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 anonymous CVS. Use the following commands to check them out (just hit return when you are prompted for the password):

	  export CVS_RSH=ssh
	  cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/gnash co gnash
	

You will then be able to update your copy from the repository using

	  cd gnash
	  cvs update -d
	

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 flash movies.

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

	    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
	  

Gnash supports a debug logging system which supports both C and C++ natively. This means you can use both printf() style debug messages and C++ iostreams style, where you can print C++ objects directly as you would when using cout.

In the beginning, Gnash only supported the C API for debug logging, so it is the most heavily used in Gnash. This API was used in the log_msg() and log_error() functions, and used a callback to set them up.

If a filename is not specified at object construction time, 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.

There is common functionality between using the C or C++ API. Optional output is based on flags that can be set or unset. Multiple levels of verbosity are supported, so you can get more output by supplying multiple -v options on the command line. You can also disable the creation of the debug log.

Currently the use of the C++ API for logging is discouraged, do to performance issues.and the generic log_msg() has been replaced by more spcific function calls to allow more control of what gets displayed and logged.

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 either FFMPEG or LIBMAD. 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.

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.

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 Flash 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 flash 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 $@