Gnash Reference Manual

Tarballs of official releases can be found in the download area of the project's GNU Savannah page at http://savannah.gnu.org/projects/gnash or under http://ftp.gnu.org/gnu/gnash

The latest Gnash development sources are available via git. Use the following commands to check them out:

	mkdir gnash
	cd gnash
	git clone git://git.sv.gnu.org/gnash.git
	

At any time, other temporary development branches may also be available. Replace trunk with the branch name to check these out. You can update your copy from the main repository using:

	  cd trunk
	  git pull
	

If you only have access to the internet via a web proxy, you will find daily source snapshots of the latest CVS tree in http://www.gnashdev.org/dev_snapshots

Some switches can be used during configuration to enable or disable features of Gnash. Some of the most important configuration options are:

A complete list of available features follows.

By default, none of these options should be required unless you want Gnash to use a specific version of a development package, or if the configure test fails to find a component. Please report the problem if a configure test fails.

The following custom path options are available:

The easiest way to run Gnash's test suite is to install DejaGnu. After installing DejaGnu, run:

	  make check
	

	    make check RUNTESTFLAGS="-v -a"
	  

	    make -C testsuite Dejagnu.swf 
	  

	    make -C testsuite/samples clip_as_button2-TestRunner 
	    cd testsuite/samples && ./clip_as_button2-TestRunner
	  

	    make -C testsuite/movies.all check
	  

You may also run test cases by hand, which can be useful if you want to see all the debugging output from the test case. Often the messages which come from deep within Gnash are most useful for development.

The first step is to compile the test case, which can be done with make XML-v#.swf where the '#' is replaced with the target SWF version or versions. For example:

	  make XML-v{5,6,7,8}.swf
	

	    gnash -v XML-v6.swf
	  

	    gprocessor -v XML-v6.swf
	  

Now that Gnash has been compiled and tested, use the following command to install it:

      make install
    

The above command installs the standalone player. If the correct files were found by configure and if the --disable-plugin option was not specified, the Gnash browser plugin is also installed.

Gnash installs a number of libraries, namely: libgnashbase, libgnashamf, libgnashmedia, libserver, and libgnashplugin. Executables consist of the (optional) plugin, gprocessor, cygnal, dumpshm, soldumper, and gnash. Documentation may also be installed. The installation location is controlled with the --prefix configure option, except for plugins, which are explicitly set with --plugin-dir.

Note that if you are using a single file-system NFS mounted to multiple platforms, the configuration option --exec-prefix may be used to specify where platform-dependent executables and libraries are installed.

To cross configure and compile Gnash, begin by building a target system on your workstation. This includes cross compilers for the target architecture, and some system headers. You will also need to cross compile all the dependencies normally needed to build Gnash. This can on occasion be a daunting process, as not all libraries will cross configure and cross compile. There is more information about cross compiling all the dependant packages on the http://www.gnashdev.org web site.

If you need to build your own tool chain, that is beyond the scope of this manual. There are various resources on the web for howto's on building GCC based cross toolchains. Two popular sites are http://frank.harvard.edu/~coldwell/toolchain/ and http://www.kegel.com/crosstool/. This can also be a very time consuming and frustrating process, even for experienced developers.

Because the process of building your own cross tool chain can be harder than one may wish, there are several other cross development environments that simulate a native environment to make it easier to develop. These also let you develop for both native and cross builds. Several popular ones are Access Linux Platform, Scratchbox, Open Embedded, Maemo.

To build for an ARM based system on an x86 based systems, configure like this using the traditional style cross toolchain, configure like this:

    ../../gnash/configure --build=i686-pc-linux-gnu
    --host=arm-linux --prefix=/usr/local/arm/oe --disable-nsapi
    --disable-kparts --enable-gui=fb --enable-renderer=agg
    --disable-shared --disable-menus
    
  

The important configuration options are the ones which specify the architecture for the build:

The following example of configure builds for an ARM system on an x86 system. It was run after an ARM system was built in /usr/arm and other required libraries were cross compiled.

      ./configure -target=arm-unknown-linux-gnu --prefix=/usr/arm \
      --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu --disable-plugin
    

There are currently a few standalone programs in Gnash, which serve either to assist with Gnash development or to play SWF movies.

The plugin is designed to work within Mozilla or Firefox, although there is Konqueror support as well. The plugin uses the Mozilla plugin API (NPAPI) to be cross platform, and is portable, as well as being well integrated into Mozilla based browsers.

Gnash's common message logging system uses a printf() style format. Despite the C-like appearance, however, Gnash's LogFile class by default does not use printf() for formatting the messages at all.

All logging calls are converted using templated functions to use boost::format. This uses a similar syntax to printf(), but additionally guarantees type-safety and allows more advanced substition using positional identifiers besides the traditional printf() type identifiers. The conversion templates mean that the logging API remains exactly the same, regardless of which method is used to format the log output.

The templates for conversion are generated using Boost.Preprocessor. Currently, they allow for a maximum of 16 arguments (more than enough for all current usage), but that can be expanded or reduced by changing #define ARG_NUMBER in libbase/log.h.

If a filename is not specified before the log file is needed, a default name of gnash-dbg.log is used. If Gnash is started from the command line, the debug log will be created in the current directory. When executing Gnash from a launcher under GNOME or KDE the debug file goes in your home directory, since that's considered the current directory. A file name can be specified using either gnashrc or a call to the LogFile instance itself.

log_error(const char* fmt, ...)

Sounds can be divided into two groups: event-sounds and soundstreams. Event-sounds are contained in a single SWF frame, but the playtime can span multiple frames. Soundstreams can be (and normally are) divided between the SWF frames the soundstreams spans. This means that if a gotoframe-action jumps to a frame which contains data for a soundstream, playback of the stream can be picked up from there.

When Gnash 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 SWF-file has been parsed. But since the entire soundstream doesn't need to be present when playback starts, it is not necessary to wait.

When a sound is about to be played Gnash 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 means that we have to trust both the graphic backend and the audio backend to play at correct speed.

The current SDL sound backend has replaced the original sound handler, based on SDL_mixer, which by design had some limitations, 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 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 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. The advantages of the SDL sound handler is speed, and ease of use, while its only real disadvantage is that it has to be compiled with MP3 support, which some Linux distributions will probably not like...

The Gstreamer backend, though not complete, supports both soundstreams and event-sounds. When receiving sound data it stores it compressed, unless if it's ADPCM event-sounds, which it decodes by the parser. When the playback starts, the backend sets up a Gstreamer bin containing a decoder (and other things needed) and places it in a Gstreamer pipeline, which plays the audio. All the sound data is not passed at once, but in small chunks, and via callbacks the pipeline gets fed. The advantages of the Gstreamer backend is that it supports both kinds of sound, it avoids all the legal MP3-stuff, and it should be relatively easy to add VORBIS support. The drawbacks are that it has longer "reply delay" when starting the playback of a sound, and it suffers under some bugs in Gstreamer that are yet to be fixed.

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:

	 ___
	|Bin|_
	|___| \
	 ___   \ _____       ____________
	|Bin|___|Adder|_____|Audio output|
	|___|   |_____|     |____________|
	 ___   /
	|Bin|_/
	|___|

      

There is one bin for each sound which is being played. If a sound is played more the once at the same time, multiple bins will be made. The bins contains:

	|source|---|capsfilter|---|decoder|---|aconverter|---|aresampler|---|volume|

      

In the source element we place parts of the undecoded sound data, and when playing the pipeline will pull the data from the element. Via callbacks it is refilled if needed. In the capsfilter the data is labeled with the format of the data. The decoder (surprise!) decodes the data. The audioconverter converts the now raw sound data into a format accepted by the adder, all input to the adder must in the same format. The audio re-sampler re-samples the raw sound data into a sample accepted by the adder, all input to the adder must in the same sample rate. The volume element makes it possible to control the volume of each sound.

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, 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 entire pipeline to stop playing when unlinking an element from the pipeline; so far no fix is known.

Gstreamer also contains a bug concerning linking multiple elements to the adder in rapid succession, which causes to adder to "die" and stop the playback.

Currently Gnash 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 specific features, and to see how the features operate.

The primary compiler used at this time is Ming. Since release 0.3, Ming includes a command-line compiler, makeswf. This allows test case development to be done entirely with free tools.

The other tools are optional. DejaGnu is used to run multiple test cases in an automated manner. DejaGnu is used by many other GNU projects like GCC and Samba.

ActionScript test cases are located under testsuite/actionscript.all/; these are organized in one file for the ActionScript class. Other Ming-generated tests are under testsuite/ming-misc.all/; these are typically used to test specific tag types. Full movies are located in testsuite/movies.all/ and sample movies are found in testsuite/samples/. Other directories in testsuite/ are (or shall be) used for other kind of tests.

Writing ActionScript tests is very simple. The makeswf compiler makes use of the C preprocessor, thus allowing the inclusion of definitions for macros and external files. We use these feature to provide common utilities for test units.

Each test unit sets an rcsid variable, includes the check.as file and performs some checks using the provided macros. Here is an example:

	  // This variable will be used by check.as
	  // to show testcase info as part of the test runs.
	  rcsid="Name and version of this testcase, usually the RCS id";
	  
	  #include "check.as"
	  
	  // Test object creation
	  check(new Object() instanceOf Object);
	  
	  // Test parseInt
	  check(isNaN(parseInt('none')));

	  // Test assignment
	  var a = 1;
	  check_equals(a, 1);
	  
	  // .. your tests here ...
	

The check(expr) macro will trace PASSED or FAILED together with the expression being evaluated and the line number of the check. This is the format expected by DejaGnu.

The check_equals(obtained, expected) macro uses equality operator == to check for equality. When possible, use of the check_equals() macro is preferred over check() because it shows what the actual result was in case of a failure.

Additionally, the check.as file provides a transparent way to send results to a TextField rather then using trace. This is very useful when you use a SWF player without tracing support.

Test units are built by running make TestName-v#.swf. This will use TestName.as as source and the value of # as target version. Allowed target version are from 5 to 8 (inclusive).

Note that if you get a syntax error from the compiler, the line number will refer to the pre-processed file. This file is called TestName.as.pp or TestName-v#.swf.frame#.pp (depending on Ming version) and it's not thrown away by makeswf to make debugging easier.

Sometimes an expression is only supported by a specific SWF version, or it's evaluated differently by different SWF versions. For this purpose the framework provides an OUTPUT_VERSION macro that you can use to switch code based on output version. For example:

	  #if OUTPUT_VERSION >= 7
	  check(_root.getSWFVersion == OUTPUT_VERSION);
	  #endif
	  
	

Ming-based test cases are located in testsuite/misc-ming.all and contain a test generator and a test runner. The test generator (usually a C program) is used to produce the SWF file, while the test runner (a C++ program) will run it using a MovieTester class. Note that only the test generator needs Ming, not the test runner, so if Ming isn't installed on the user's host, the test cases can still be run as long as SWF has been distributed.

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 facilities provided by the Gnash testing framework to easily run tests.

For generic Ming API documentation, see http://www.libming.org.

	check(SWFMovie mo, const char* expr)

		Evaluate an ActionScript expression.

	xcheck(SWFMovie mo, const char* expr)

		Evaluate an ActionScript expression.
		A failure is expected
		(for cases where the call exposes a known bug).

	check_equals(SWFMovie mo, const char* obtained, const char* expected)

		Evaluate an ActionScript expression against an expected output.

	xcheck_equals(SWFMovie mo, const char* obtained, const char* expected)

		Evaluate an ActionScript expression against an expected output.
		A failure is expected (for cases where the call exposes a known bug).

	print_tests_summary(SWFMovie mo)

                This will print a summary of tests run, and should be
		called as the last step in your SWF generator.
	

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 to let your test consistent with the rest of the suite.

The loadable module is called Dejagnu.swf and is built during make check under testsuite/misc-ming.all. In order to use it you will need to load it into your SWF. We currently load it with an IMPORT tag for our ActionScript based test cases, but you can probably also use loadMovie or whatever works in the target SWF you're generating. Just make sure that the module is initialized before using it. You can check this by inspecting the dejagnu_module_initialized variable, which will be set to 'true' when all initialization actions contained in the Dejagnu.swf file are executed.

Once the module is loaded you will be able to invoke the following functions, all registered against the _root sprite (effects of _lockroot untested):

	  
	  check(expression, [message]);
	  
	  Evaluate the expression.
	  Trace result (PASSED: expression / FAILED: expression).
	  If fails, *visually* trace the failure.
	  If second argument is given, it will be used instead of
	  'expression' for printing results.
	  
	  check_equals(obtained, expected)
	  
	  Evaluate an expression against an expected output.
	  Trace result (PASSED: obtained == expected / FAILED: expected X, obtained Y)
	  If fails, *visually* trace the failure.
	  
	  xcheck(expression, [message]);
	  
	  Evaluate the expression.
	  Trace result (XPASSED: expression / XFAILED: expression).
	  If fails, *visually* trace the failure.
	  If second argument is given, it will be used instead of
	  'expression' for printing results.
	  
	  xcheck_equals(obtained, expected)
	  
	  Evaluate an expression against an expected output.
	  Trace result (XPASSED: obtained == expected / XFAILED: expected X, obtained Y)
	  If fails, *visually* trace the failure.
	  
	  note(string)
	  
	  Print string, both as debugging and *visual* trace.
	  
	  totals()
	  
	  Print a summary of tests run, both as debugging and *visual* traces.
	  
	

Visual traces are lines of text pushed to a textarea defined by the Dejagnu.swf module. The textarea is initially placed at 0, 50 and is 600x800 in size. You can resize/move the clip after loading it. Also, you can completely make the clip invisible if that bothers you. The important thing is the debugging trace (call to the trace function). The latter will be used by the testing framework.

See section Writing Test Runners for information about writing a test runners for your self-contained tests.

Test runners are executables that run one or more tests, writing results in Dejagnu form to standard output.

The Dejagnu form uses a standard set of labels when printing test results. These are:

The following labels may also appear:

	    MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
	    sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf > $@
	    chmod +x $@
	  

	    MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
	    sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir) MyTest.swf > $@
	    chmod +x $@
	  

	    MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
	    sh $(srcdir)/../generic-testrunner.sh -f10 $(top_builddir) MyTest.swf > $@
	    chmod +x $@
	  

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.

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:

	      void extension_init(as_object& where, const ObjectURI& uri);
      

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.

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:

          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);
          }
      

You will notice three functions in the example above that need definition. The first two are attachInterface() and attachStaticInterface(). This is a convention in Gnash 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:

          void
          attachInterface(as_object& obj)
          {
              Global_as& gl = getGlobal(obj);
              obj.init_member("ext1", gl.createFunction(&extension_ext1));
          }
      

This attaches a function called ext1 to the Extension class prototype. When ext1 is called in ActionScript, Gnash 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.

The attachStaticInterface() function looks identical:

          void
          attachStaticInterface(as_object& obj)
          {
              Global_as& gl = getGlobal(obj);
              obj.init_member("static1", gl.createFunction(&extension_static1));
          }
      

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:

          Extension.static();
      

The other undefined function is extension_ctor. Like extension_ext1, this is an ActionScript callback function. Such functions have the signature:

          as_value extension_ctor(const fn_call& fn);
      

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.

The function extension_static is the simplest function. A possible implementation is as follows:

          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);
          }
      

The member function implementation extension_ext1 is barely more complex. It could look like this:

          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");
          }
      

It is not a very useful function. In ActionScript, this definition will have the following effect:

          var e = new Extension();
          var i = e.ext1(8);
          trace(e.property) // traces "8"
          trace(i) // traces "return value"
      

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.

          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();
          }
      

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):

          as_value extension_ctor(const fn_call& fn)
          {
          }
      

If you have defined all the callback functions in the way described above, you can simplify the class registration. Gnash provides a convenience function to register a built-in class. In this case, your entry function would look like this:

          void
          extension_init(as_object& where, const ObjectURI& uri) 
          {
              string_table& st = getStringTable(where);
              registerBuiltinClass(where, extension_ctor, attachInterface,
                  0, st.find("Extension"));
          }
      

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:

          #include "Relay.h"
          #include <complex>

          class Complex : public Relay
          {
          public:
              typedef std::complex<double> type;
              Complex(type c = type()) : _c(c) {}
              type _c;
          };
      

Using this Relay involves two steps: attaching it, and accessing it. Relays must be attached in the constructor:

          as_value extension_ctor(const fn_call& fn)
          {
              as_object* this_ptr = ensure<ValidThis>(fn);
              this_ptr->setRelay(new Complex())
          }
      

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:

          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());
          }
      

The GTK ActionScript class follows the same API as Gtk2, even down to the same arguments to the same function names. This means you're actually programming GTK,you're just using ActionScript instead of python, perl, or C. This extension makes it possible to write Flash movies that use the Gtk2 widgets for user interface components.

Flash movies are traditionally forbidden from accessing the filesystem, but this may be necessary for some embedded applications. Especially in the case of a user console, currently there is no way to get input into a Flash movie but through a TextField.

The MySQL ActionScript class follows the same API as MySQL, even down to the same arguments to the same function names. This enables a Flash movie to have direct access to a MySQL database. Traditionally Flash movies have had no database support, they either had to use arrays, or use XML to communicate to an application specific external database daemon.