[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnash-commit] /srv/bzr/gnash/trunk r11896: Update documentation. Extens
|
From: |
Benjamin Wolsey |
|
Subject: |
[Gnash-commit] /srv/bzr/gnash/trunk r11896: Update documentation. Extensions documentation is completely updated. |
|
Date: |
Thu, 04 Feb 2010 11:02:27 +0100 |
|
User-agent: |
Bazaar (2.0.2) |
------------------------------------------------------------
revno: 11896 [merge]
committer: Benjamin Wolsey <address@hidden>
branch nick: trunk
timestamp: Thu 2010-02-04 11:02:27 +0100
message:
Update documentation. Extensions documentation is completely updated.
ActionScript class documentation no longer has out-dated information,
but is not completely replaced with correct information.
modified:
doc/C/refmanual/extensions/extensions.xml
doc/C/refmanual/internals.xml
doc/C/refmanual/logging.xml
doc/C/refmanual/new_as_class.xml
=== modified file 'doc/C/refmanual/extensions/extensions.xml'
--- a/doc/C/refmanual/extensions/extensions.xml 2008-09-12 21:18:45 +0000
+++ b/doc/C/refmanual/extensions/extensions.xml 2010-02-04 10:01:37 +0000
@@ -1,241 +1,337 @@
<chapter id="extensions">
- <title>Gnash Extensions</title>
-
- <para>
- Gnash supports extending the SWF specification by creating
- custom ActionScript classes that are compiled code, as opposed to
- the existing method of defining custom classes as
- ActionScript. Executing compiled code has many performance
- benefits over having to interpret the byte stream of the
- ActionScript opcodes.
- </para>
-
- <para>
- I can already hear people complaining now about the concept of
- extending SWF, so this in no way affects Gnash's ability to play
- SWF movies when functioning as a browser plugin.
- Gnash's goal is still to function in a way that is compatible
- with the current proprietary Flash player.
- </para>
-
- <para>
- But at the same time, we see SWF as the ideal scripting language
- for a digital multi-media streaming environment. There are many
- resources for SWF movie creators for widgets, higher level APIs,
- all sorts of desirable things. But for those of use committed to
- using free software tools for SWF, our options are very
- limited.
- </para>
-
- <para>
- Rather than launching a multi-year project to duplicate all
- classes in the commercial Flash IDE, it's much more efficient to
- use existing development libraries much like Python or Perl
- do. The extension mechanism in Gnash allows wrappers to be created
- for any C or C++ development library. Unlike the proprietary Flash
- IDE, which compiles all the extension libraries into byte codes
- from ActionScript, the support is moved to the player side. Movies
- with all of the goodies of the proprietary IDE in them play in
- Gnash just fine, as it's all just byte codes by then.
- </para>
-
- <para>
- This trick works because until SWF version 9, all the
- ActionScript class names and methods are passed as ASCII strings
- into the SWF movie. So the Gnash Virtual Machine just loads the
- extension file if that class name is invoked in the movie. All
- extension files specify the class name and methods it implements
- in an identical style as adding any new ActionScript class. The
- advantage is the class itself is compiled code, and runs much
- faster than the equivalent byte codes which all have to be
- interpreted..
- </para>
-
+ <title>&app; Extensions</title>
+
+ <para>
+ &app; supports the creation of custom extensions to ActionScript. This
+ allows you to integrate any conceivable system or library function into
+ ActionScript execution.
+ </para>
+ <para>
+ Extensions do not represent a general alteration of the ActionScript
+ language. They are designed to allow &app; to be more
+ flexible and powerful where it is required. They allow you to
+ customize &app; for your own purposes and to distribute those changes
+ to other users who need them. They are not intended for use in
+ normal SWF execution or internet browsing, but rather for
+ executing SWFs designed to use those extensions under controlled
+ conditions.
+ </para>
+ <para>
+ Some extensions are distributed with &app;, mainly to serve
+ as an example. Extensions are not enabled by default, both for
+ security and compatibility reasons.
+ </para>
+
<sect1 id="newext">
<title>Creating A New Extension</title>
<para>
- Each new extension should live in it's own directory. The
- extensions included in Gnash are all in the
+ Each new extension should live in its own directory. The
+ extensions included in &app; are all in the
<emphasis>gnash/extensions</emphasis> directory. Creating an extension
requires a Makefile.am,
</para>
<para>
- If you are adding this extension to the Gnash source tree
+ If you are adding this extension to the &app; source tree
itself, then you need to make two changes to add the new
- extension.
- </para>
-
- <para>
- The first change is to add the directory to the list in
+ extension. The first change is to add the directory to the list in
extensions/Makefile.am. This can be done either by adding the
new directory to the SUBDIRS setting, or by wrapping it in a
- conditional test.
- </para>
-
- <para>
- The other change is to add it to the AC_OUTPUT list in
+ conditional test. The other change is to add it to the AC_OUTPUT list in
<emphasis>configure.ac</emphasis> so the new directory will be
- configured along with the rest of Gnash.
+ configured along with the rest of &app;.
</para>
<para>
Each extension should have an ActionScript source file included
that tests the new class, and this file should be referenced in
the new Makefile.am in the <emphasis>check_PROGRAMS</emphasis>
- variable so that "make check" works.
+ variable so that "make check" works.
</para>
<para>
When creating an extension that is a wrapper for an existing
development library API, it's often better to make this a thin
- layer, than to get carried away with creating beautiful
+ layer than to get carried away with creating beautiful
abstractions. Higher-level classes that offer a lot of new
- functionality are fine, but is different than wrapping a library
- so it can be used from within Gnash.
+ functionality are fine, but this is different from wrapping a library
+ so it can be used from within &app;.
</para>
- <sect2 id="craftext">
+ <sect1 id="craftext">
<title>Crafting an Extension</title>
<para>
- All extensions have the same requirements, namely setting up a
- few defined function callbacks, which the Gnash VM then uses
- to do the right thing. The initial two function callbacks are
- for handling the interface of the newly created object so that
- Gnash can find and use it.
- </para>
-
- <para>
- The first function is commonly called
- <emphasis>attachInterface</emphasis>, and this sets the other
- function callbacks for all the methods this class
- supports. The method callbacks are attached to the parent
- class by using <emphasis>init_member()</emphasis> to set a C
- function pointer to the string value used in the SWF movie.
- </para>
-
- <programlisting>
- // Attach DummyClass 'func1' and 'func2' methods to the given object
- static void
- attachInterface(as_object& obj) {
- obj.init_member("func1", &ext_func1);
- obj.init_member("func2", &ext_func2);
- }
- </programlisting>
-
- <para>
- The second function is commonly called
- <emphasis>getInterface()</emphasis>, and this returns a
- pointer to a static prototype of the class.
- Gnash uses garbage collection for ActionScript objects
- so you need to register the static with the VM to give it
- a chance to be marked as reachable.
- </para>
- <programlisting>
- static as_object*
- getInterface()
- {
- static boost::intrusive_ptr<as_object> o;
- if (o == NULL) {
- o = new as_object();
- VM::get().addStatic(o);
- attachInterface(*o);
- }
- return o.get();
- }
- </programlisting>
-
- <para>
- This is the callback that gets executed when constructing a
- new object for the VM. In this example we'll assume the new
- ActionScript class is called <emphasis>DummyExt</emphasis>,
- and has two methods, <emphasis>func1</emphasis> and
- <emphasis>func2</emphasis>.
- </para>
- <programlisting>
- static as_value
- dummyext_ctor(const fn_call& fn)
- {
- DummyExt *obj = new DummyExt(); // will setup prototypes
-
- return as_value(obj);
- }
- </programlisting>
-
- <para>
- The trick for the above simple constructor to work is that
- class appartenence is setup in the C++ DummyExt constructor
- itself, which should derive from as_object and construct the
- base passing it the interface (prototype) of it's class.
- </para>
-
- <programlisting>
- class DummyExt : public as_object
- {
- public:
- DummyExt()
- :
- as_object(getInterface()) // returns the static prototype
- {}
-
- };
- </programlisting>
-
- <para>
- Initialize the extension. This is looked for by the extension
- handling code in each extension, and is executed when the
- extension is loaded. This is the main entry point into the
- extension. This function can be found because the prefix of
- <emphasis>dummyext</emphasis>, which also matches the file
- name of the extension. Gnash uses the name of the extension
- file itself when looking for the init function.
- </para>
- <programlisting>
- extern "C" {
- void
- dummyext_class_init(as_object &obj)
- {
- static builtin_function* cl=NULL;
- if (!cl)
- {
- // Create a builtin function using the given constructor
- // to instanciate objects and exporting the given interface
- cl = new builtin_function(&dummyext_ctor,
getInterface());
- VM::get().addStatic(cl); // will forbid to collect the class
- }
-
- obj.init_member("DummyExt", cl);
- }
- } // end of extern C
- </programlisting>
-
- <para>
- The callbacks are all C functions. Like all the other code
- that implements ActionScript, parameters to the function are
- passed in using the <emphasis>fn_call</emphasis> data
- structure. The return code, if any, is also returned using
- this data structure. <emphasis>this_ptr</emphasis> is the
- object that the method is a member of.
- </para>
- <programlisting>
- // Creates a new button with the label as the text.
- as_value func1(const fn_call& fn) {
- // Following line will ensure 'func1' is called for a DummyExt
instance,
- // or would throw an exception which should behave as if we
returned the
- // undefined value.
- boost::intrusive_ptr<DummyExt> ptr =
ensureType<DummyExt>(fn.this_ptr);
-
- if (fn.nargs > 0) {
- std::string label = fn.arg(0).to_string();
- bool ret = ptr->dummy_text_label(label);
- return as_value(ret);
- }
- }
- </programlisting>
-
- </sect2>
+ An extension defines a built-in type of ActionScript object.
+ An ActionScript object may have native type information known
+ as a Relay. This adds an extra layer of complexity and runtime
+ cost, so avoid using it unless necessary.
+ </para>
+ <para>
+ ActionScript classes consist of a constructor function and a
+ prototype object. The constructor function is called when an
+ instance of your extension class is created. The prototype object
+ contains the properties inherited by instances of the extension
+ class. To create an extension class, you must provide an entry
+ function with the following signature:
+ </para>
+ <programlisting>
+ void extension_init(as_object& where, const ObjectURI&
uri);
+ </programlisting>
+ <para>
+ This will be called during initialization. The first argument
+ is the object to which your class will be attached. For extensions,
+ this is the Global object, known as _global in ActionScript 2.0.
+ The second argument is ignored for extension classes.
+ </para>
+ <para>
+ Our extension class will imaginatively be called
+ "Extension". Our extension_init function takes care of
+ attaching the prototype and constructor function to the passed object
+ object. One way to do this is as follows:
+ </para>
+ <programlisting>
+ void
+ extension_init(as_object& where, const ObjectURI& uri)
+ {
+ // Get a reference to the global object.
+ Global_as& gl = getGlobal(where);
+
+ // Create a prototype object
+ as_object* proto = gl.createObject();
+
+ // Create the class
+ as_object* cl = gl.createClass(&extension_ctor, proto);
+
+ // Attach the class's functions to the prototype object.
+ attachInterface(*proto);
+
+ // Attach static properties to the class itself
+ attachStaticInterface(*cl);
+
+ // Attach the class to the passed object.
+ where.init_member("Extension", cl);
+ }
+ </programlisting>
+ <para>
+ You will notice three functions in the example above that need
+ definition. The first two are attachInterface() and
+ attachStaticInterface(). This is a convention
+ in &app; to separate ActionScript interface creation from the
+ registration of our Extension class. We will see why this is
+ useful later. The attachInterface function may be defined
+ as follows:
+ </para>
+ <programlisting>
+ void
+ attachInterface(as_object& obj)
+ {
+ Global_as& gl = getGlobal(obj);
+ obj.init_member("ext1",
gl.createFunction(&extension_ext1));
+ }
+ </programlisting>
+ <para>
+ This attaches a function called ext1 to the Extension class
+ prototype. When ext1 is called in ActionScript, &app; will
+ execute the C++ function named extension_ext1. This is known as
+ a ActionScript callback function and must have the correct signature.
+ We will deal with this next. The member function function will be
+ inherited by all instances of Extension.
+ </para>
+ <para>
+ The attachStaticInterface() function looks identical:
+ </para>
+ <programlisting>
+ void
+ attachStaticInterface(as_object& obj)
+ {
+ Global_as& gl = getGlobal(obj);
+ obj.init_member("static1",
gl.createFunction(&extension_static1));
+ }
+ </programlisting>
+ <para>
+ This does exactly the same as the previous function, but it
+ attaches "static" properties to the class. Such functions
can
+ be called directly, that is, without requiring an instance of
+ Extension:
+ </para>
+ <programlisting>
+ Extension.static();
+ </programlisting>
+ <para>
+ The other undefined function is extension_ctor. Like extension_ext1,
+ this is an ActionScript callback function. Such functions have the
+ signature:
+ </para>
+ <programlisting>
+ as_value extension_ctor(const fn_call& fn);
+ </programlisting>
+ <para>
+ The fn_call type contains information about the ActionScript function
+ call, including the number of arguments, the "this" object
+ (if
+ present), the VM and the Global object. With one small exception,
+ the constructor function extension_ctor, and the ext1 function
+ implementation, extension_ext1, do the same thing.
+ </para>
+ <para>
+ The function extension_static is the simplest function. A possible
+ implementation is as follows:
+ </para>
+ <programlisting>
+ as_value
+ extension_static(const fn_call& fn)
+ {
+ // Reject any calls with no arguments. We must ensure that
+ // we do not access out-of-range arguments.
+ if (!fn.nargs) return as_value();
+
+ // Convert the first argument to a double.
+ const double d = fn.arg(0).to_number();
+
+ // This is the return value of the function.
+ return as_value(d * 6);
+ }
+ </programlisting>
+ <para>
+ The member function implementation extension_ext1 is barely more
+ complex. It could look like this:
+ </para>
+ <programlisting>
+ as_value extension_ext1(const fn_call& fn)
+ {
+ // This ensures that the function can only be called as a
+ // member function of an object. If not, execution of the
+ // function ends at this point.
+ as_object* this_ptr = ensure<ValidThis>(fn);
+
+ // Reject any calls with no arguments.
+ if (!fn.nargs) return as_value();
+
+ const as_value& arg0 = fn.arg(0);
+
+ // The string table manages all strings; we refer to strings
+ // by their index in the table.
+ string_table& st = getStringTable(fn);
+
+ // Set a member named "property" on the object to the
value of
+ // the first argument.
+ this_ptr->set_member(st.find("property"), arg0);
+
+ // This is the return value of the function.
+ return as_value("return value");
+ }
+ </programlisting>
+ <para>
+ It is not a very useful function. In ActionScript, this definition
+ will have the following effect:
+ </para>
+ <programlisting>
+ var e = new Extension();
+ var i = e.ext1(8);
+ trace(e.property) // traces "8"
+ trace(i) // traces "return value"
+ </programlisting>
+ <para>
+ The constructor function is very similar, but has a different
+ purpose. When the actionscript "new Extension" is called,
+ this extension_ctor function will be called with a newly-created
+ object as the "this" object. Its job is to attach
properties
+ to the "this" object. Unlike the class prototype's
propertes
+ that we attached in the attachInterface function, any properties
+ attached here belong directly to the new object.
+ </para>
+ <programlisting>
+ as_value
+ extension_ctor(const fn_call& fn)
+ {
+ // When called as a constructor, there is always a
"this" object
+ as_object* this_ptr = ensure<ValidThis>(fn);
+
+ // The init_member function will never replace an existing
+ // property.
+ this_ptr->init_member("myProperty", true);
+
+ // A constructor function must not return anything.
+ return as_value();
+ }
+ </programlisting>
+ <para>
+ You may not want to do anything in your constructor. It is perfectly
+ valid to use the following as a constructor function (and indeed
+ this is recommended unless you need more complex behaviour):
+ </para>
+ <programlisting>
+ as_value extension_ctor(const fn_call& fn)
+ {
+ }
+ </programlisting>
+ <para>
+ If you have defined all the callback functions in the way
+ described above, you can simplify the class registration. &app;
+ provides a convenience function to register a built-in class. In
+ this case, your entry function would look like this:
+ </para>
+ <programlisting>
+ void
+ extension_init(as_object& where, const ObjectURI& uri)
+ {
+ string_table& st = getStringTable(where);
+ registerBuiltinClass(where, extension_ctor, attachInterface,
+ 0, st.find("Extension"));
+ }
+ </programlisting>
+ <para>
+ For more advanced extensions, you may want to store extra information
+ in an object. You can do this using a Relay. This imposes type
+ restrictions when using the object in ActionScript. A Relay is
+ a C++ class that could look like this:
+ </para>
+ <programlisting>
+ #include "Relay.h"
+ #include <complex>
+
+ class Complex : public Relay
+ {
+ public:
+ typedef std::complex<double> type;
+ Complex(type c = type()) : _c(c) {}
+ type _c;
+ };
+ </programlisting>
+ <para>
+ Using this Relay involves two steps: attaching it, and accessing
+ it. Relays must be attached in the constructor:
+ </para>
+ <programlisting>
+ as_value extension_ctor(const fn_call& fn)
+ {
+ as_object* this_ptr = ensure<ValidThis>(fn);
+ this_ptr->setRelay(new Complex())
+ }
+ </programlisting>
+ <para>
+ To access this information in ActionScript callback functions, we
+ must ensure that the object has the correct type of Relay attached.
+ A toString function (which must also be attached to the prototype!)
+ could look like this:
+ </para>
+ <programlisting>
+ as_value
+ extension_toString(const fn_call& fn)
+ {
+ // This ensures that the function can only be called as a
+ // member function of a genuine Complex object.
+ Complex* c = ensure<IsNativeType<Complex> >(fn);
+
+ std::ostringstream s;
+ s << "real:" << c.real() <<
",imag: << c.imag();
+ // This is the return value of the function.
+ return as_value(s.str());
+ }
+ </programlisting>
+ </sect1>
</sect1>
@@ -243,34 +339,8 @@
<title>Debugging An Extension</title>
<para>
- As extensions are loaded dynamically at runtime, debugging one
- can be difficult. You can use GDB, but you have the problem of
- not being able to set a breakpoint in Gnash until
- <emphasis>after</emphasis> the extension has been loaded into
- Gnash's VM. The easy solution is to use the Gnash debugger.
- </para>
-
- <para>
- You can insert these few lines in any file that you wish to
- manually start the debugger. Once at the console, you can attach
- GDB to the process. Then you can set breakpoints, etc... and you
- are at the point of execution where the console was started. To
- then continue playing the movie, type the <emphasis>c</emphasis>
- (for continue) command to the Gnash console.
- </para>
- <programlisting>
- // Get the debugger instance
- static Debugger& debugger = Debugger::getDefaultInstance();
-
- // Enable the debugger
- debugger.enabled(true);
- // Stop and drop into a console
- debugger.console();
- </programlisting>
-
- <para>
- You can also resort to the time honored technique of creating a
- loop before the point you want to set a breakpoint for. Gnash
+ You can resort to the time honored technique of creating a
+ loop before the point you want to set a breakpoint for. &app;
will stop playing the movie at this point, and then you can
externally attach GDB to the running process, or type
<emphasis>^C</emphasis> to drop into the GDB command console.
@@ -298,9 +368,9 @@
<title>Included Extensions</title>
<para>
- Gnash has some extensions included in the distribution. This is
- mostly because they were written by the Gnash team. Extensions
- can be external to gnash, Gnash needs no compiled in knowledge
+ &app; has some extensions included in the distribution. This is
+ mostly because they were written by the &app; team. Extensions
+ can be external to gnash, &app; needs no compiled in knowledge
to load an extension file.
</para>
=== modified file 'doc/C/refmanual/internals.xml'
--- a/doc/C/refmanual/internals.xml 2009-08-14 14:48:58 +0000
+++ b/doc/C/refmanual/internals.xml 2010-02-04 09:22:45 +0000
@@ -2,11 +2,11 @@
<title>Software Internals</title>
<sect1 id="tour">
- <title>A Tour of Gnash</title>
+ <title>A Tour of &app;</title>
<para>
- The top level of Gnash has several libraries,
<emphasis>libgnashbase</emphasis>,
- <emphasis>libgnashserver</emphasis>,
+ The top level of &app; has several libraries,
<emphasis>libgnashbase</emphasis>,
+ <emphasis>libgnashcore</emphasis>,
<emphasis>libgnashmedia</emphasis>,
<emphasis>libgnashamf</emphasis> and
<emphasis>libgnashbackend</emphasis>. There are several utility programs
@@ -34,12 +34,12 @@
</para>
</sect3>
- <sect3 id="libgnashserver">
- <title>libgnashserver</title>
+ <sect3 id="libgnashcore">
+ <title>libgnashcore</title>
<para>
- Libgnashserver is the guts of the interpreter itself. This is where
- the main code for the interpreter lives. Includes in
- libserver are the two support libraries for the parser and
+ Libgnashcore is the guts of the interpreter itself. This is where
+ the main code for the interpreter lives. Included in
+ libcore are the two support libraries for the parser and
the core of the virtual machine.
</para>
</sect3>
@@ -47,20 +47,27 @@
<sect3 id="libgnashmedia">
<title>libgnashmedia</title>
<para>
- Libgnashmedia handles Gnash's audio and video capabilities,
- dealing with streamed video and sound as well as decoding
- embedded media frames. Besides the standard SWF formats
+ Libgnashmedia handles &app;'s decoding of video and audio,
+ including both streamed and embedded media.
+ Besides the standard SWF formats
FLV, MPEG4, Nellymoser, ADPCM, MP3 and RAW, &app; can
decode other formats supports by Gstreamer or FFmpeg,
including the free OGG container and free codecs.
</para>
+</sect3>
+
+ <sect3 id="libgnashsound">
+ <title>libgnashsound</title>
+ <para>
+ This library handles sound output and manages sound objects.
+ </para>
</sect3>
<sect3 id="libgnashamf">
<title>libgnashamf</title>
<para>
AMF is the data format used internally by SWF files. This is
- Gnash's support library to handle AMF data. This is used by
+ &app;'s support library to handle AMF data. This is used by
the ActionScript classes SharedObject and
LocalConnection. This is also used by the NetStream class
when using thre RTMP streaming network protocol.
@@ -72,7 +79,7 @@
<para>
Libgnashbackend is a library containing the rendering
- code that glues this display to the Gnash. Supported
+ code that glues this display to the &app;. Supported
rendering backends are OpenGL, Cairo, and AGG.
</para>
</sect3>
@@ -99,8 +106,8 @@
<title>The Applications</title>
<para>
- There are currently a few standalone programs in Gnash,
- which serve either to assist with Gnash development or to play SWF
+ There are currently a few standalone programs in &app;,
+ which serve either to assist with &app; development or to play SWF
movies.
</para>
@@ -110,7 +117,7 @@
<para>
This is the standalone OpenGL backend used to play
movies. There are several command line options and keyboard
- control keys used by Gnash.
+ control keys used by &app;.
</para>
</sect3>
@@ -122,7 +129,7 @@
Gprocessor is used to print out the actions (using the -va
option) or the parsing (using the -vp option) of a SWF
movie. It is also used to produce the <emphasis>.gsc</emphasis>
- files that Gnash uses to cache data, thereby speeding up the
+ files that &app; uses to cache data, thereby speeding up the
loading of files.
</para>
@@ -166,13 +173,9 @@
fashion similar to MozPlugger: the standalone player
is used instead of using a thread. This gets around the
issue of having to maintain a separate player to support the
- plugin. It also gets around the other issues that Gnash
+ plugin. It also gets around the other issues that &app;
itself is not thread safe at this time.
</para>
- <para>
- As of Jan, 2007, streaming video, ala "YouTube"
- works, along with other video sharing sites.
- </para>
</sect3>
<sect3 id="gui">
@@ -187,7 +190,7 @@
</para>
<para>
- Gnash can use either several different GUI toolkits to create the
window,
+ &app; can use either several different GUI toolkits to create the
window,
and to handle events for the standalone player.
</para>
@@ -196,7 +199,7 @@
platforms, including win32. It has no support for event
handling, which means mouse clicks, keyboard presses, and
window resizing doesn't work. I personally find the default
- event handler slow and unresponsive. Gnash has support to
+ event handler slow and unresponsive. &app; has support to
use fast events, (currently not enabled) which is an SDL
hack using a background thread to pump events into the SDL
event queue at a much higher rate.
@@ -218,7 +221,7 @@
</para>
<para>
- GTK also allows Gnash to have menus and dialog
+ GTK also allows &app; to have menus and dialog
boxes. Currently this is only being utilized in a limited
fashion for now. There is a right mouse button menu that
allows the user to control the movie being player the same
@@ -227,73 +230,13 @@
</sect3>
- <sect3 id="mozplugger">
- <title>Mozplugger</title>
-
- <para>
- <ulink type="http"
- url="http://mozplugger.mozdev.org/";>Mozplugger</ulink> is a
- <emphasis>Mozilla/Firefox</emphasis> plugin that uses external
- programs to play video, audio, and other multimedia content
- in the browser. With some support added to the external
- application, it's possible to force the external program to
- use the internal window in the browser where this plugin is
- supposed to display. This enables one to then run the
- standalone player and display its output in the browser.
- </para>
-
- <para>
- While this is not an optimal solution, it does enable one to
- use Gnash as the SWF player when browsing. The main issue
- appears to be that the SWF movie being played doesn't get
- any mouse or keyboard input. That may be a mozplugger
- configuration issue, however.
- </para>
-
- <para>
- Use of MozPlugger is obsolete now that the Gnash plugin
- works. Still, this may be useful still on some platforms.
- </para>
-
- <para>
- Add this to your <emphasis>$(HOME)/.mozilla/mozpluggerrc</emphasis>
- file to enable this:
-
- <programlisting>
- application/x-shockwave-flash:swf:Shockwave Gnash
- nokill embed noisy ignore_errors hidden fill swallow(Gnash) loop:
gnash -v "$file" -x $window
- : gnash -v "$file" -x $window
- </programlisting>
- </para>
-
- <para>
- Once this is added, you must delete the
- <emphasis>$(HOME)/.mozilla/firefox/pluginreg.dat</emphasis> file to
- force Firefox to register the plugins again. This is an
- ASCII text file, so if the patch has been added correctly,
- you'll see an entry for <emphasis>swf</emphasis> files after it is
- recreated. You will need to restart Firefox to recreate this
- file.
- </para>
-
- <para>
- This file is not recreated immediately when restarting
- Firefox, but waits till the first time a plugin is used. You
- can force creation of this file by typing
- <emphasis>about:plugins</emphasis> into the URL entry of the browser
- window. The output will also contain information about the
- mozplugger. You should see an entry for Gnash now.
- </para>
-
- </sect3>
-
<sect3 id="Klash">
<title>Klash</title>
<para>
Klash is MozPlugger type support for KDE's Konqueror web
- browser. Klash makes Gnash a <emphasis>kpart</emphasis>, so it's
+ browser. Klash makes &app; a <emphasis>kpart</emphasis>, so it's
integrated into KDE better than when using MozPlugger. Klash
- uses the standalone player, utilizing Gnash's "-x" window
+ uses the standalone player, utilizing &app;'s "-x" window
plugin command line option.
</para>
@@ -312,12 +255,11 @@
</sect1>
<sect1 id="soundhandlers">
- <title>Sound handling in Gnash</title>
+ <title>Sound handling in &app;</title>
<para>
- When a SWF-file contains audio Gnash uses its sound handlers to play it.
- At the moment there are two sound handlers, but it is likely that more
- will be made.
+ Sound in &app; is handled by libgnashsound. This library takes
+ care of interfacing with a sound handler.
</para>
<para>
@@ -342,7 +284,7 @@
<sect2 id="soundparsing">
<title>Sound parsing</title>
<para>
- When Gnash parses a SWF-file, it creates a sound handler if possible
+ When &app; parses a SWF-file, it creates a sound handler if possible
and hands over the sounds to it. Since the event-sounds are contained
in one frame, the entire event-sound is retrieved at once, while a
soundstream maybe not be completely retrieved before the entire
@@ -354,7 +296,7 @@
<sect2 id="soundplayback">
<title>Sound playback</title>
<para>
- When a sound is about to be played Gnash calls the sound handler, which
+ When a sound is about to be played &app; calls the sound handler, which
then starts to play the sound and return. All the playing is done by
threads (in both SDL and Gstreamer), so once
started the audio and graphics are not sync'ed with each other, which
@@ -371,13 +313,13 @@
making it difficult to implement needed features such as support
for soundstreams.
The SDL sound backend supports both event-sounds and soundstreams,
- using Gnash's internal ADPCM, and optionally MP3 support, using
+ using &app;'s internal ADPCM, and optionally MP3 support, using
FFMPEG.
When it receives sound data it is stored without being decoded, unless
it is ADPCM, which is decoded in the parser. When playing, backend
relies on a function callback for retrieving output sound, which is
decoded and re-sampled if needed, and all sound output is mixed
together.
- The current SDL sound backend was made since Gnash needed a working
+ The current SDL sound backend was made since &app; needed a working
sound backend as soon as possible, and since the gstreamer backend at
the time suffered from bugs and/or lack of features in gstreamer. The
result was the most complete and best sound handler so far.
@@ -405,22 +347,12 @@
</para>
</sect2>
- <sect2 id="audio-future">
- <title>Future audio backends</title>
- <para>
- It would probably be desirable to make more backends in the future,
- either because other and better backend systems are brought to our
- attention, or perhaps because an internal sound handling is better
- suited for embedded platform with limited software installed.
- </para>
- </sect2>
-
<sect2 id="gstreamer-details">
<title>Detailed description of the Gstreamer backend</title>
<para>
Gstreamer uses pipelines, bins and elements. Pipelines are the
main bin, where all other bins or elements are places. Visually the
- audio pipeline in Gnash looks like this:
+ audio pipeline in &app; looks like this:
</para>
<programlisting>
@@ -465,7 +397,7 @@
When a sound is done being played it emits a End-Of-Stream-signal
(EOS), which is caught by an event-handler-callback, which then makes
sure that the bin in question is removed from the pipeline. When a
- sound is told by Gnash to stop playback before it has ended playback,
+ sound is told by &app; to stop playback before it has ended playback,
we do something (not yet finally implemented), which makes the bin emit
an EOS, and the event-handler-callback will remove the sound from the
pipeline. Unfortunately Gstreamer currently has a bug which causes the
@@ -488,16 +420,16 @@
<para>
<link linkend="runtests">Instructions on running tests</link>
- can be found in the section on building Gnash.
+ can be found in the section on building &app;.
</para>
<sect2 id="testtools">
<title>Testing Tools</title>
<para>
- Currently Gnash uses three other tools to help with
+ Currently &app; uses three other tools to help with
testing. Two of these are free compilers for the SWF
- format. This lets us write simple test cases for Gnash to test
+ format. This lets us write simple test cases for &app; to test
specific features, and to see how the features operate.
</para>
@@ -643,7 +575,7 @@
Producing tests using Ming has the advantage that you can easily see
and modify the full source code for the SWF movie, and you can use
some <link linkend="ming_testgenerator_facilities">facilities</link>
- provided by the Gnash testing framework to easily run tests.
+ provided by the &app; testing framework to easily run tests.
</para>
<para>
@@ -712,7 +644,7 @@
by simply running them with whatever Player you might have.
Any 'check' or 'check_equals' result will be both traced and
printed in a textfield. You can use 'gprocessor -v' to have
- Gnash use them as tests.
+ &app; use them as tests.
</para>
<para>
@@ -728,7 +660,7 @@
<para>
If you want/need to use a different compiler for your test cases
(there's
plenty of open source tools for generating SWF out there), you can still
- make use of a loadable SWF utility provided as part of the Gnash
testsuite
+ make use of a loadable SWF utility provided as part of the &app;
testsuite
to let your test consistent with the rest of the suite.
</para>
@@ -946,11 +878,11 @@
<title>Using the generic test runner for self-contained SWF
tests</title>
<para>
- The simplest test runner is one that simply invokes Gnash
+ The simplest test runner is one that simply invokes &app;
in verbose mode against a self-contained SWF test movie.
Self-contained SWF test movies are the ones that print
the PASSED/FAILED etc. lines using ActionScript (traces).
- By invoking Gnash in verbose mode this movie will behave
+ By invoking &app; in verbose mode this movie will behave
as a compliant "Test Runner".
</para>
@@ -1000,7 +932,7 @@
<title>Writing Movie testers</title>
<para>
- There are some parts of Gnash that can NOT be tested
+ There are some parts of &app; that can NOT be tested
by only using ActionScript tests. Examples include: frame
advancements, actual actions execution, gui events and so on.
</para>
=== modified file 'doc/C/refmanual/logging.xml'
--- a/doc/C/refmanual/logging.xml 2008-05-08 10:33:04 +0000
+++ b/doc/C/refmanual/logging.xml 2010-02-04 09:22:45 +0000
@@ -115,15 +115,6 @@
</listitem>
</varlistentry>
<varlistentry>
- <term>log_security</term>
- <listitem>
- <para>
- Display a message with security related information. This is always
- printed at a verbosity level of 1 or more.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
<term>log_swferror</term>
<listitem>
<para>
@@ -140,7 +131,7 @@
</varlistentry>
<varlistentry>
- <term>void log_aserror</term>
+ <term>log_aserror</term>
<listitem>
<para>
This indicates an erroneous actionscript request such as
@@ -155,6 +146,15 @@
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>log_abc</term>
+ <listitem>
+ <para>
+ Extremely verbose logging related to AVM2/ABC execution.
+ This is printed at verbosity level 3.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</sect3>
=== modified file 'doc/C/refmanual/new_as_class.xml'
--- a/doc/C/refmanual/new_as_class.xml 2008-03-01 21:14:04 +0000
+++ b/doc/C/refmanual/new_as_class.xml 2010-02-04 09:57:25 +0000
@@ -1,218 +1,120 @@
<chapter id="newclass">
- <title>Adding New ActionScript Class</title>
-
- <para>
- In this document, the term 'ActionScript class' refers to the
- C++ class which is instantiated by Gnash when some ActionScript
- code instantiates a corresponding class. The C++ class
- stores instance data and implements the methods which are
- called on the object in the ActionScript code.
- </para>
-
- <para>
- Adding a new ActionScript class is relatively simple, but the
- process is complicated by the fact that the interface has evolved
- over time and the current code base represents several different
- formats. This document describes the current interface. The
- Boolean class should be considered the authoritative example of
- a modern ActionScript class.
- </para>
-
- <para>
- ActionScript classes contain a header file and a C++
- implementation. The name is usually the name of the
- class as it is called in the ActionScript specifications;
- for instance <emphasis>Boolean.cpp</emphasis> for the Boolean class.
- </para>
-
+ <title>Adding New ActionScript Classes</title>
+
+ <para>
+ An ActionScript 2.0 class refers to two different kinds of objects:
+ a genuine class that can be used to construct instances of that class,
+ and a simple singleton object. Examples of the simple object classes
+ are Mouse and Stage. This chapter is mainly concerned with genuine
+ classes.
+ </para>
+ <para>
+ A genuine ActionScript 2.0 class comprises a constructor function
+ and a prototype object. Classes may have native type information,
+ but most do not.
+ </para>
+
+
<sect1 id="prototype">
<title>Prototype</title>
<para>
- In ActionScript, a prototype is a base object which contains
- all the methods that an instantiated object will contain.
- In short, it contains every part of the class except for
- the portions dealing with the storage of instance data.
- </para>
- <para>
- In Gnash, the prototype of an ActionScript object is
- implemented as an <emphasis>as_object</emphasis>.
- At startup, the methods and properties of the ActionScript class
- are attached to the <emphasis>as_object</emphasis>. The
- following example demonstrates how methods can be attached:
- <programlisting>
- static void
- attachBooleanInterface(as_object& o) {
- o.init_member("toString", new builtin_function(boolean_tostring));
- o.init_member("valueOf", new builtin_function(boolean_valueof));
- }
- </programlisting>
- </para>
- <para>
- Static properties can also be added to the ActionScript prototype
- (<link linkend="properties">dynamic properties</link>
- are addressed later). They are attached in a similar way:
- <programlisting>
- o.init_member("myProperty", as_value("HelloWorld"));
- </programlisting>
- </para>
- <para>
- Properties which have been added in this manner can be
- directly accessed in ActionScript code without a function
- call, as this piece of ActionScript code compiled by Ming's
- <emphasis>makeswf</emphasis> compiler demonstrates:
- <programlisting>
- // Get the value of the myProperty property
- if (node.myProperty == "HelloWorld") {
- trace("MATCHED");
- }
- </programlisting>
- </para>
- </sect1>
-
- <sect1 id="declaration">
- <title>Declaration</title>
-
- <para>
- A new class should derive from <emphasis>as_object</emphasis>,
- which is the base class of every ActionScript object in Gnash.
- </para>
- </sect1>
-
- <sect1 id="instantiation">
- <title>Instantiation</title>
-
- <para>
- When a new object is needed, instance data is added to
- the methods and properties inherited from the prototype.
- </para>
- <para>
- The init method should be called in the constructor in
- <emphasis>Global.cpp</emphasis>, where all other ActionScript
- classes are similarly referenced. This method constructs a
- prototype, which is implemented as an
- <emphasis>as_object</emphasis>. In addition, the method
- registers the constructor to be used for future object creation,
- and attaches methods and properties to the prototype.
- </para>
- </sect1>
-
- <sect1 id="methods">
- <title>Methods</title>
-
- <para>
- Every method you implement and
- <link linkend="prototype">attach</link> will receive an
- &fn_call; data structure as an argument when it is called.
- </para>
-
- <sect3 id="arguments">
- <title>Accessing Arguments</title>
- <para>
- The arguments stored in &fn_call;
- should be accessed using <emphasis>arg()</emphasis>. For
- instance, the first element can be popped with
- <emphasis>fn.arg(0)</emphasis>.
- </para>
- <para>
- The element popped off the stack is an
- <link linkend="as_value"><emphasis>as_value</emphasis>
- object</link>.
- </para>
- </sect3>
-
- <sect3 id="return">
- <title>Returning a Value to ActionScript</title>
- <para>
- The return value should be an
- <link linkend="as_value"><emphasis>as_value</emphasis>
- object</link>. For example:
- <programlisting>
- return as_value('Goodbye, cruel world.');
- </programlisting>
- </para>
- </sect3>
-
- <sect3 id="additional_fn_call">
- <title>Additional &fn_call; Members</title>
- <para>
- There are two other useful members of the &fn_call;
- structure, namely <emphasis>this_ptr</emphasis> and
- <emphasis>nargs</emphasis>. The former points to the
- class which is invoking this method, while the latter
- is a count of the number of
- <link linkend="arguments">arguments in the stack</link>.
- </para>
- <para>
- You may also see instances of the <emphasis>env</emphasis>
- pointer being used. This is being deprecated. Instances
- which could be replaced with
- <link linkend="arguments"><emphasis>arg()</emphasis></link>
- are already deprecated; other uses will be deprecated
- in the near future.
- </para>
- <para>
- Beyond the <emphasis><link
- linkend="arguments">arg()</link></emphasis> method, there
- is one method of note. <emphasis>dump_args()</emphasis>
- can be used in debugging to output the entire argument
- stack.
- </para>
- </sect3>
- </sect1>
-
- <sect1 id="properties">
- <title>Dynamic Properties</title>
- <para>
- This section describes accessors to dynamic properties.
- Read-only properties are described
- in the <link linkend="prototype">prototype</link> section.
- </para>
- <para>
- Accessors should be written as a single get/set method.
- Previously this was done by overriding
- <emphasis>get_member()</emphasis> and
- <emphasis>set_member()</emphasis>, but this practice
- is deprecated.
- </para>
- <para>
- The accessor is written so that it sets the property
- if it is called with an argument, and puts the property in
- the <link linkend="methods">&fn_call;</link>
- <link linkend="return">result pointer</link>. For instance:
- <programlisting>
- void
- MyClass::myProperty_getset(const fn_call& fn) {
- boost::intrusive_ptr<MyClass> ptr =
ensureType<MyClass>(fn.this_ptr);
-
- // setter
- if ( fn.nargs > 0 ) {
- bool h = fn.arg(0).to_bool();
- ptr->MyMethod(h);
- return;
- }
-
- // getter
- bool h = ptr->MyMethod();
- fn.result->set_bool(h);
- }
- </programlisting>
- </para>
- <para>
- It has not yet been decided whether properties should be set
- in the <link linkend="prototype">exported interface</link>
- or attached to instances of the class. A property is attached
- in the following manner:
- <programlisting>
- boost::intrusive_ptr<builtin_function> gettersetter;
- gettersetter = new builtin_function(&MyClass::myProperty_getset,
NULL);
- o.init_property("myProperty", *gettersetter, *gettersetter);
- </programlisting>
- </para>
- </sect1>
-
- &asvalue;
- &object;
-
+ In ActionScript, a prototype is an object that contains
+ all the methods that an instantiated object will inherit.
+ </para>
+ <para>
+ In Gnash, the prototype of an ActionScript class, like all other
+ objects, is implemented as an <emphasis>as_object</emphasis>.
+ When the class is initialized, the class interface - its
+ inheritable properties - are attached to the prototype as_object.
+ The following example demonstrates how methods can be attached:
+ <programlisting>
+ void
+ attachBooleanInterface(as_object& o)
+ {
+ Global_as& gl = getGlobal(o);
+ o.init_member("toString", gl.createFunction(boolean_tostring));
+ o.init_member("valueOf", gl.createFunction(boolean_valueof));
+ }
+ </programlisting>
+ </para>
+ <para>
+ Classes may also have static properties. These are functions or
+ data members attached directly to the class. They do not require
+ an instance of the class to be used. These are attached in exactly
+ the same way, but attached to the class (that is, the constructor
+ function), not the prototype object.
+ </para>
+ </sect1>
+
+ <sect1 id="constructor">
+ <title>Constructor</title>
+ <para>
+ A constructor function is an ActionScript callback function that
+ is called when an instance of a class is created. The "this" object
+ during the call is a new object.
+ </para>
+ <para>
+ Constructor functions may do tasks such as attaching properties or
+ type information to the new object. They may also do absolutely
+ nothing. Anything attached to the object during the constructor
+ call is an "own property" of the new object, not an inherited property.
+ </para>
+ <para>
+ The following examples are valid constructors. A constructor should
never return anything
+ other than as_value() (an undefined value). Exceptions to this rule
are the
+ basic types String, Boolean, and Number. These have constructor
functions that can
+ also be called as conversion functions. They have a special
implementation that
+ behaves differently depending on the calling context.
+ </para>
+ <programlisting>
+ as_value
+ movieclip_ctor(const fn_call& fn)
+ {
+ }
+
+ as_value
+ class_ctor(const fn_call& fn)
+ {
+ as_object* this_ptr = ensure<ValidThis>(fn);
+
+ if (fn.nargs) {
+ string_table& st = getStringTable(fn);
+ this_ptr->set_member(st.find("property"), fn.arg(0));
+ }
+ return as_value();
+ }
+ </programlisting>
+ <para>
+ Native typing is added using a Relay subclass. This only applies to a
small number of
+ classes. The native typing is added during the constructor function
using the
+ as_object::setRelay() function. All Relay types must inherit from the
Relay base class.
+ </para>
+ <para>
+ Native typing can be accessed in ActionScript callback functions using
the
+ ensure<> function template:
+ </para>
+ <programlisting>
+ as_value
+ boolean_toString(const fn_call& fn)
+ {
+ // This ensures that the function can only be called as a
+ // member function of a genuine Boolean_as object.
+ Boolean_as* b = ensure<IsNativeType<Boolean_as>
>(fn);
+
+ return as_value(b.value());
+ }
+ </programlisting>
+</sect1>
+
+<sect1 id="properties">
+ <para>
+ There are three kinds of property: simple data members, functions, and
getter-setters.
+ All three kinds may be inherited. Getter-setters are attached using the
+ init_property() function. Functions and data members using the
init_member() function.
+ </para>
+</sect1>
+
+
</chapter>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gnash-commit] /srv/bzr/gnash/trunk r11896: Update documentation. Extensions documentation is completely updated.,
Benjamin Wolsey <=