Gnash Reference Manual

This manual describes version 0.8.8 of Gnash.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find a copy of the GFDL at this link or in the file COPYING-DOCS distributed with this manual.

Revision History
Revision Gnash User Manual version 0.4Jan 2010

Rob Savoye The end user parts of the manual have been pulled out of the original version of the manual, and rewritten. This is now a reference manual only.

Open Media Now! Foundation


Table of Contents

1. Introduction
Audience
What Is Supported?
2. Building from Source
Overview
Getting The Source
Releases
Git Access
Code Dependencies
Testing Dependencies
Documentation Dependencies
Configuring Gnash
Compiling the Code
Creating the Documentation
Running the Tests
Using DejaGnu
Running The Tests Manually
3. Software Internals
A Tour of Gnash
The Libraries
The Applications
The Plugin
The Message Logging System
Sound handling in Gnash
Sound types
Sound parsing
Sound playback
The SDL sound backend
The Gstreamer backend
Detailed description of the Gstreamer backend
Testing
Testing Tools
Test Cases
Writing ActionScript Tests
Writing Ming-based self-contained SWF tests
Writing self-contained SWF tests with other compilers
Writing Test Runners
5. Reporting Bugs
Get a Fresh Binary Package
Determine if the bug was previously reported
Review the bug writing guidelines
Filing a bug report
6. Gnash Extensions
Creating A New Extension
Debugging An Extension
Included Extensions
7. RTMP Protocol
AMF Format
8. Mozilla/Firefox NPAPI Plugin
Plugin C API
Plugin C++ API
OpenGL and Threads
Plugin Event Handling
9. Authors
A. GNU Free Documentation License
0. PREAMBLE
1. APPLICABILITY AND DEFINITIONS
2. VERBATIM COPYING
3. COPYING IN QUANTITY
4. MODIFICATIONS
5. COMBINING DOCUMENTS
6. COLLECTIONS OF DOCUMENTS
7. AGGREGATION WITH INDEPENDENT WORKS
8. TRANSLATION
9. TERMINATION
10. FUTURE REVISIONS OF THIS LICENSE
Addendum

List of Tables

2.1. Code Dependency Table
2.2. Testing Dependency Table
2.3. Documentation Dependency Table
2.4. Configuration Options - Features
2.5. Custom Path Options

Chapter 1. Introduction

Gnash is a free SWF movie player. It is available as a stand-alone application or as a plugin for several popular web browsers. It supports playing media from a disk or streaming over a network connection. Some popular video sharing sites like YouTube are supported on a wide variety of devices from embedded ones to modern desktops.

Gnash has a better focus on security, allowing the user tight control of all network or disk based I/O. Gnash also supports extending ActionScript by creating your own classes. You can write wrappers for any development library, and import them into the player much like Perl or Python does.

Audience

This manual is primarily focused on users interested in how to get Gnash installed from a package, and basic usage as a web browser plugin. For more technical details, please refer to the Gnash Reference manual.

What Is Supported?

Gnash is known to compile for most any POSIX and ANSI C++ conforming system if you have all the dependent libraries installed. Systems we test on, and which Gnash is known to run on are Ubuntu, Fedora, Debian, Mandriva, OpenBSD, NetBSD, FreeBSD, Win32, and Darwin (OSX) primarily. Occasionally other platforms are built, primarily by those distribution maintainers. This includes BeOS, Haiku, Syllable, OS/2, Solaris, Slackware, and Gentoo.

Gnash is capable of reading up to SWF v9 files and opcodes, but primarily supports SWF v7, with better SWF v8 and v9 support under heavy development. Since the 0.8.2 release, Gnash includes initial parser support for SWF v8 and v9. Not all ActionScript 2 classes are implemented yet, but all of the most heavily used ones are. Many ActionScript 2 classes are partially implemented; there is support for all of the commonly used methods of each class.

Gnash has implemented about 80% of ActionScript v2.0, and has begun implementing ActionScript v3.0. Gnash supports the majority of Flash opcodes up to SWF v9, and a wide sampling of ActionScript classes for SWF v8.

As ActionScript 3 is a more developed version of ActionScript 2, many of the same classes work for both. Support has been added to Gnash's ActionScript library to support the new ActionScript 3 filters, which get applied to every class. Implementing ActionScript classes is often the easiest way for new Gnash developers to make a contribution without a deep internal knowledge of Gnash.

Gnash has included video support since early 2007, but this is an ever changing field of reverse engineering. Many of the popular video sharing sites use SWF v8 or v9, which Gnash supports imperfectly. This is improving all the time, so often builds from a development snapshot will work when using the older release packaged in your distribution doesn't. You can find daily snapshots of the latest CVS tree at: http://www.gnashdev.org/dev_snapshots.

Gnash uses FFmpeg for codecs, so any file supported by Mplayer should work with Gnash. Gnash supports the loading of patent free codecs like Ogg Vorbis or Theora from disk based files, while work is being done to support these codecs when embedded in a SWF file. FFmpeg contains the codecs used by the current SWF defintion, FLV, VP6 (ON2), H.263, H.264, and MP3.

Chapter 2. Building from Source

Overview

The typical process of building from source will involve getting the source, build dependencies, configuration, compilation, testing, and installation. A simplified overview of the process would be:

        ./autogen.sh
        ./configure 
        make
        make check
        make install
      

If you are compiling with GCC you will need to use a machine with at least 128 megabytes of physical RAM; 64MB is not enough for a couple of the files, even with swap enabled and optimisation turned off. With less than 512 megabytes available, many build combinations can still be a long and painful experience.

At present the Gnash source is about 30 MB extracted and configured and requires a total of about 125 megabytes to compile it.

Continue reading for detailed step-by-step instructions of the entire procedure.

Getting The Source

Releases

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

Git Access

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

Code Dependencies

Gnash has a number of dependencies on other packages. If you install the dependencies using a package manager, be certain to install the development versions of the packages. The normal versions often lack the headers Gnash needs to compile.

Some dependencies have other dependencies: for instance, GTK also needs glib2, atk, and pango to produce a fully linked executable. Different distributions also use differing dependencies, sometimes a package will depend on libxml2 on one system, but libexpat on another.

Table 2.1. Code Dependency Table

NameLevelVersionDescriptionExplanationapt-get packageRPM/Yum packageBSD package
BoostRequired1.32 or higher Boost is a library of portable C++ classes and templates. In Gnash, Boost libraries are used extensively, primarily boost-gthread and boost-date-time. Boost is used for thread and mutext handling. libboost-thread-dev, libboost-date-time-dev libboost-dev libboost-thread-devel, libboost-date-time-devel boost-headers, boost-libs, or just boost
AGGPossibly Required2.4 or higher AGG is the AntiGrain low-level 2D graphics library. Gnash requires the installation of at least one renderer. AGG is considered the best supported renderer for Gnash. libagg-devagg-develagg
OpenGLPossibly Required  OpenGL is a standard specification defining a cross-language cross-platform API for writing applications which produce 3D and 2D graphics. It supports hardware acceleration. You can download a free implementation from http://www.mesa3d.org, although it doesn't support hardware acceleration. Gnash requires the installation of at least one renderer. If you don't have a hardware accelerated driver, you're better off using AGG for the renderer. libgl1-mesa-devlibmesa-develmesa
CairoPossibly Required  Cairo is a 2D graphics library with support for multiple output devices. It will automatically use graphic card acceleration when available, and has an experimental OpenGL backend. Gnash requires the installation of at least one renderer. Cairo is considered the least supported renderer for Gnash. libcairo2-devcairo-develcairo
GTKPossibly Required2.2 or higher GTK is the GIMP Toolkit GUI library used by the GNOME desktop. It uses Cairo internally. Gtk enables better integration with Firefox, as well as better event handling and higher level GUI constructs like menus and dialog boxes. Gnash requires the installation of at least one GUI library. GTK is considered to be the best supported GUI library option for Gnash. libgtk2.0-devgtk-develgtk+2
GtkGlExtPossibly Required  GtkGlExt integrates OpenGL into GTK. This library is required in order to use the GTK GUI library in conjunction with the OpenGL renderer. libgtkglext1-devgtkglext-develgtkglext
SDLPossibly Required  The Simple DirectMedia Layer is a cross-platform multimedia library which provides abstraction for audio, graphics, sound and input APIs. SDL is available from http://www.libsdl.org. Gnash requires the installation of at least one GUI library. SDL may also be used as a sound handler regardless of whether it is employed as a GUI library. The GUI library is poorly supported in Gnash, but the sound handler is the best supported in Gnash. libsdl1.2-devSDL-develSDL-1.2
FLTKPossibly Required2.0 or higher The Fast Light ToolKit is a portable GUI library which is intended as a replacement for the SDL GUI. Gnash requires the installation of at least one GUI library. FLTK may be used in conjunction with the Cairo and AGG renderers. No distribution packages are available.No distribution packages are available.No distribution packages are available.
KDEPossibly Required  Kdelibs is a collection of libraries needed to compile KDE applications. Gnash requires the installation of at least one GUI library. Kdelibs is also required for the Kpart plugin for Konqueror. kdelibs3-dev, kdebase-devkdelibs-devel, kdebase-develkdelibs, kdebase
GstreamerOptional  Gstreamer is a video handler. If you would like video playback, you must install one of the video handlers. libgstreamer0.8-devgstreamer-develgstreamer-0.10
gst-ffmpegPossibly Required  gst-ffmpeg allows you to use the FFmpeg decoder with Gstreamer. This package is required if you would like to use Gstreamer as a video handler. gstreamer0.8-ffmpeg-devgstreamer-ffmpeg-develgstreamer-ffmpeg
FFmpegPossibly Required  FFmpeg is a video handler. If you would like video playback, you must install one of the video handlers. When using the gstreamer-ffmpeg plugin, ffmpeg doesn't need to be installed, as it's part of the plugin. For systems without Gstreamer support, FFmpeg can be used directly. ffmpeg-devffmpeg-develffmpeg
JPEGRequired  JPEG is a lossy image format which is heavily used for images. This library is used for reading external JPEGs and JPEG data embedded in SWF files. libjpeg62-devlibjpegjpeg
PNGRequired  PNG is a patent-free image format which is comparable to GIF. This library is used for loading external PNG images (part of the SWF8 specification) and for writing images in the PNG format. libpng12-devlibpngpng
GIFRequired GIF is a common image format that should now be free of patent restrictions. GIF. This library is used for loading external GIF images (part of the SWF8 specification). libungif-devlibungif-develgif
libcurlOptional  libcurl is the multiprotocal file transfer library. This library is used for URL downloading. libcurl4-gnutlslibcurlcurl
Glib2Optional  Glib2 is a dependency of Gtk, and is a collection of commonly used functions. This library is used for convenience. glib2-devglib2-develglib2
AtkOptional  Atk is a dependency of Gtk, and is used for accessibility support. This library is used for accessiblity.. atk-devatk-develatk
PangoOptional  Pango is a dependency of Gtk, and is used for font handling. This library is used for font handling. pango-devpango-develpango
automakePossibly Required1.6.0 Automake is a tool for generating Makefile.in files. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. automakeautomakeautomake
autoconfPossibly Required2.59 Autoconf is a package for generating configure scripts. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. autoconfautoconfautoconf
gettextPossibly Required0.14.6 Gettext is part of the GNU Translation Project. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. gettextgettextgettext
libtoolPossibly Required1.5.22 This is a generic library support script. This package is required to run autogen.sh, which is a requirement if you are using the development source from CVS. libltdl3-devlibtoollibtool

Testing Dependencies

Gnash tries to run as many tests as possible, but will silentl skip tests if the tools to run them are unavailable.

Table 2.2. Testing Dependency Table

NameLevelVersionDescriptionExplanationapt-get packageRPM/Yum packageBSD package
MingOptional0.4.0_beta4 or higher Ming is an ActionScript compiler. Ming is the primary compiler for ActionScript testcases. No distribution packages are available.No distribution packages are available.No distribution packages are available.
MtascOptional1.12 or higher Mtasc is an ActionScript compiler. Mtasc is used in some tests. mtascNo distribution packages are available.No distribution packages are available.
swfcOptionalpart of swftools 0.8.1 Swfc is an swf compiler. Swfc is used in some testcases. No distribution packages are available.No distribution packages are available.No distribution packages are available.
swfmillOptional 0.2.12 Swfmill is an XML-based SWF (Shockwave Flash) processing tool. Swfmill is used in some testcases. No distribution packages are available.No distribution packages are available.No distribution packages are available.
PythonOptional2.4 or higher Python is a scripting language. Python is used by part of the testing framework. pythonpythonpython
DejaGnuOptional1.4 or higher DejaGnu is a testing framework. DejaGnu is used to run multiple tests in an automated fashion. dejagnudejagnudejagnu

Documentation Dependencies

The following packages are used to build Gnash's documentation.

Table 2.3. Documentation Dependency Table

NameLevelVersionDescriptionExplanationapt-get packageRPM/Yum packageBSD package
DocbookRequired  Docbook is is an industry-standard XML format for technical documentation. You can download it from http://sourceforge.net/project/showfiles.php?group_id=21935#files. Gnash documentation is written in Docbook. docbook-utils and docbook-dsssl docbook-dtd41-sgml and docbook-style-dsssl docbook
DocBook2XOptional  This software package converts Docbook documents to the traditional man page format, GNU Texinfo format, and HTML (via Texinfo) format. It is available at http://docbook2x.sourceforge.net/. DocBook2X is required to produce HTML and Texinfo formats. docbook2xdocbook2xdocbook2x
DocBook-utilsOptional  This software package converts Docbook documents to the traditional man page format, GNU Texinfo format, and HTML (via Texinfo) format. DocBook-utils is required to produce HTML and Texinfo formats. docbook-utilsdocbook-utilsdocbook-utils
TexinfoPossibly Required  Texinfo can be used to convert DocBook2X output into GNU info pages. You can download it from http://ftp.gnu.org/gnu/texinfo/. Texinfo is required if you wish to produce GNU info pages. texinfotexinfotexinfo
FOPOptional0.20.5 Formatting Objects Processor is a print formatter driven by XSL formatting objects. It is a Java application which can output PDF, PCL, PS, SVG, XML, Print, AWT, MIF, and Text. It is available at http://xmlgraphics.apache.org/fop/. FOP is required for PDF output. fopfopfop
Java (j2re)Possibly Required  FOP requires Sun's Java runtime (GCJ does not work with FOP). You can download it from http://java.sun.com. Sun's Java runtime (j2re) is required to use FOP. Download the package from Sun. Download the package from Sun.  
JAIPossibly Required  Sun's Java Advanced Imaging API can be downloaded from http://java.sun.com/products/java-media/jai/iio.html. JAI is required if you wish to include graphics in a PDF file being generated with FOP. Download the package from Sun. Download the package from Sun.  

If you install j2re, set the JAVA_HOME environment variable to the top directory of the j2re installation. If you encounter problems with the Java installation, you may also need to add this path to the CLASSPATH environment variable.

Configuring Gnash

Gnash, like most GNU projects, allows a user to select various options before compiling its source code. These options include selecting from the available features, specifying custom paths for installation, and cross compiling support uses GNU Autoconf for configuration.

If you opted to download the development snapshot of Gnash, the configure script will not be included. It can be created by running autogen.sh from the source root directory:

      ./autogen.sh
    

Note that there are some dependencies for autogen.

All the standard configure options are available. In addition, Gnash has two types of options: those that enable or disable features, and those that specify custom paths for development packages which are not found during the default search. A complete list of all configuration options, including standard ones, can be seen by typing:

      ./configure --help | less
    

Read further for a more detailed explanation of Gnash-specific options.

The syntax for running configure is as follows:

      configure <options>
    

The example below shows the configure options which create the smallest working standalone version of Gnash. In this example, configure is being run from the source root directory:

    ./configure --disable-debugger --disable-cygnal \
    --disable-plugin --enable-media=ffmpeg --enable-gui=sdl
  

By default, you shouldn't need to supply any options to configure. The configure script will attempt to determine what to build based on the development libraries you have installed. The default configuration for Gnash is both GTK and KDE GUIs, the AGG renderer, and Gstreamer for multimedia support, with no extensions built.

Being highly portable, Gnash has many configuration options available, and not all are supposed to work together. A common mistake when configuring Gnash is to supply too many options, overdriving Gnash's ability to do the right thing.

Features

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

  • --enable-gui lets you specify your GUI of choice. The default option is GTK.

  • --enable-renderer allows a renderer to be chosen. The default renderer is AGG.

  • --enable-media permits a media handler to be selected. The default is Gstreamer.

A complete list of available features follows.

Table 2.4. Configuration Options - Features

OptionFunction
--enable-debuggerEnable support for the Flash debugger. The debugger is mainly of interest to Flash developers, and is still under development.
--enable-lirc Enable support for the LIRC remote control protocol.
--enable-cygnal Build the Cygnal streaming media server.
--disable-menus Disable building all the menus for the GUI. THis is used by mobile devices without as much screen space.
--enable-docbook Enable the generation of HTML, INFO, and MAN versions of the documentation from the Docbook XML. You will then be able to use make html, make info, and make man commands. By default, man,info and html pages are generated.
--enable-gui=gtk|sdl|kde|fltk|fb|hildon|alp

Select the Graphic User Interface to use (choose one).

GTK

The GTK+ toolkit, which is the default GUI. Said to interwork particularly well with firefox.

Hildon

The Hildon toolkist is based on GTK+, and is use by some mobile devices.

ALP

The ALP "Hiker" GUI is used for the Access Linux platform.

SDL

Simple DirectMedia Layer, a simple and portable GUI. Its sound facilities are used when --enable-media=ffmpeg regardless of whether it is also in charge of the GUI.

KDE

An interface adapted to the KDE Desktop Environment. This must be selected when building the Konqueror plugin "klash". Furthermore, the only renderer that currently works with KDE is opengl.

FLTK

Fast Light ToolKit, low on resource usage. Since all builds using fltk are now broken, we declare it "for developers".

FB

The Linux Frame Buffer, also known as /dev/fb0. AGG is the only renderer that can currently be used with the framebuffer GUI.

--enable-i810-lod-bias Enable fix for Intel 810 LOD bias problem. Older versions of libMesa on the Intel i810 or i815 graphics processor need this flag or Gnash will core dump. This has been fixed in newer versions (summer 2005) of libMesa.
--enable-media=ffmpeg|gst|none

Select the specified media decoder and sound engine. FFmpeg uses the SDL sound engine; GST uses its own. GST is the default decoder.

You should only select one media decoder.

--disable-nsapi --enable-nsapi Force disable/enable building the NPAPI plugin. By default the Mozilla plugin is built if the GTK gui is selected. Specify the --with-npapi-plugindir= option to specify where the plugin should be installed.
--disable-kparts --enable-kparts Force disable/enable building the KPARTS plugin. By default the KDE plugin is built if the kde gui is selected. Specify the --with-kde-plugindir= and --with-kde-servicesdir= options (or more generally the --with-kde-pluginprefix= one) to specify where the plugin should be installed. The default installation dir is extracted from kde-config.
--disable-plugins Disable build of both kparts and npapi plugins
--enable-renderer=opengl|cairo|agg Enable support for a graphics backend. Currently only opengl and agg work sufficiently. Use OpenGL when you have hardware accelerated graphics. Use AGG when you do not have hardware accelerated graphics or when you are building for a wide audience. Typically most desktop machines have OpenGL support, and most embedded systems do not. AGG is the default when building Gnash, although the speed of OpenGL's rendering is currently superior to AGG.
--enable-sdk-install Enable installing the libraries and headers as an SDK.
--disable-shared Enable installing the shared libraries and headers. Note that the extensions mechanism may not work if shared libraries are disabled.
--enable-strict Turn verbose GCC compiler warnings. By default only -Wall is used with GCC.
--enable-fps-debug Enable FPS debugging code. When this feature is compiled in you can use the -f switch of Gnash to have FPS printed at regular intervals.
--enable-writeMakes the Mozilla plugin write the currently playing SWF movie to /tmp.
--disable-sa-launcherDrops the NPAPI plugin support for writing a standalone executable launcher script for the currently playing SWF movie to /tmp. Note that you'll still need to add a 'writelauncher' string to your GNASH_OPTIONS environment variable for the script to be created, even if the compile-time support is enabled.
--disable-mit-shm Disable support for the MIT-SHM X extensions. Currently support is only available using GTK gui and AGG renderer. Keeping it enabled is not a problem as it will not be used if not available in the current X session.

Specifying Custom Paths

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:

Table 2.5. Custom Path Options

OptionFunction
--x-includes=DIR X include files are in DIR.
--x-libraries=DIR X library files are in DIR.
--with-docbook=DIR Directory where the DocBook style-sheets are installed.
--with-sdl-prefix=PFX Prefix where SDL is installed.
--with-zlib-incl Directory where zlib header is installed.
--with-zlib-lib Directory where zlib library is installed.
--with-jpeg-incl Directory where jpeg header is installed.
--with-jpeg-lib Directory where jpeg library is installed.
--with-png-incl Directory where png header is installed.
--with-png-lib Directory where png library is installed.
--with-qt-dir Directory where QT is installed. This is only used by the Klash plugin.
--with-qt-includes Directory where the QT header files are installed. This is only used by the Klash plugin.
--with-qt-libraries Directory where the QT libraries are installed. This is only used by the Klash plugin.
--with-plugins-install=user|system|prefix This option sets the install policy for NPAPI (mozilla) and KPARTS (kde) plugins. Policy 'user' means plugin will be installed only for the configuring user. Policy 'system' will try to find a systemwide place for plugins (to enable for all). Policy 'prefix' will install under ${prefix} (npapi/kparts subdirs); WARNING: if 'prefix' policy is given, plugins won't be found w/out further enabling procudures. The default policy is 'user', can be overridden for specific plugins.
--with-npapi-install=user|system|prefix This option sets the install policy for NPAPI plugin. Policy 'user' means plugin will be installed in ~/.mozilla/plugins; 'system' will try to find an existing system-wide mozilla plugin dir (or bail out if not found); 'prefix' will install under ${prefix}/npapi.
--with-npapi-plugindir This is the directory to install the NPAPI (Mozilla) plugin in. By default it goes to ~/.mozilla/plugins.
--with-kparts-install=user|system|prefix This option sets the install policy for all KPARTS (kde) files. Policy 'user' means plugin will be installed in ~/.kde; 'system' will find out using kde-config (or bail out if not found); 'prefix' will install under ${prefix}/kparts. The actual prefix can be overridden using --with-kde-pluginprefix or the fine-tuned options. The default at time of writing (2008-05-18) is 'user'.
--with-kde-pluginprefix This option sets the default install dir for all KPARTS (kde) files. The plugin will be installed in PREFIX/lib/kde3, use -with-kde-plugindir to override. The service file in PREFIX/share/services, use --with-kde-servicesdir to override. The config file in PREFIX/share/config, use --with-kde-configdir to override. The appdata file in PREFIX/share/apps/klash, use --with-kde-appsdatadir to override.
--with-kde-plugindir This is the directory to install the KPARTS (kde) plugin in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install module --expandvars, or $(prefix)/share/services if kde-config is not found.
--with-kde-servicesdir This is the directory to install the KPARTS (kde) service in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install services --expandvars, or $(libdir)/kde3 if kde-config is not found.
--with-kde-configdir This is the directory to install the KPARTS (kde) config files in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install config --expandvars, or $(prefix)/share/config if kde-config is not found.
--with-kde-appsdatadir This is the directory to install the KPARTS (kde) application data files in. By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install data --expandvars, or $(prefix)/share/apps if kde-config is not found.
--with-ming Ming is used to build test cases, but not by the Gnash player itself.
--with-ogg_incl Directory where the libogg headers are installed.
--with-ogg_lib Directory where the libogg library is installed.
--with-gstreamer-incl Directory where the Gstreamer headers are installed. Gstreamer version 0.10 or greater must be used.
--with-gstreamer-lib Directory where the Gstreamer library is installed. Gstreamer version 0.10 or greater must be used.
--with-opengl-includes Directory where OpenGL (libMesa) headers are installed.
--with-opengl-lib Directory where the OpenGL (libMesa) library is installed.
--with-glext-incl Directory where GtkGlExt headers are installed.
--with-glext-lib Directory where the GtkGlExt library is installed.
--with-gtk2-incl Directory where the Gtk2 headers are installed.
--with-gtk2-lib Directory where the Gtk2 library is installed.
--with-cairo_incl Directory where the Cairo headers are installed.
--with-cairo-lib Directory where the Cairo library is installed.
--with-glib-incl Directory where the Glib headers are installed.
--with-glib-lib Directory where the Glib library is installed.
--with-pango-incl Directory where the Pango headers are installed.
--with-pango-lib Directory where the Pango library is installed.
--with-atk-incl Directory where the ATK headers are installed.
--with-atk-lib Directory where the ATK library is installed.
--with-pthread-incl Directory where the Pthread headers are installed.
--with-pthread-lib Directory where the Pthread library is installed.
--with-agg-incl Directory where the AGG (Antigrain) headers are installed.
--with-agg-lib Directory where the AGG (Antigrain) library is installed.
--with-ffmpeg-incl Directory where the FFMPEG headers are installed.
--with-ffmpeg-lib Directory where the FFMPEG library is installed.
--with-boost-incl Directory where the Boost headers are installed.
--with-boost-lib Directory where the Boost library is installed.
--with-curl-incl Directory where the libCurl headers are installed.
--with-curl-lib Directory where the libCurl library is installed.

Once you have Gnash configured, you are ready to build the code. Gnash is built using GNU make.

Compiling the Code

The most basic way to compile code is simply:

	make
      

If the compilation ends with an error, check the output of configure and ensure that you are not missing any required prerequisites. The output of make can be verbose; you may wish to pipe the output to a file.

The variables used by make can be redefined when the program is invoked, if you desire it. The most interesting flags are CFLAGS and CXXFLAGS, which are often used to enable debugging or turn of optimization. The default value for both of these variables is -O2 -g. A list of influential environment variables can be seen in the configuration help:

./configure --help

In the following example, debugging is enabled and optimization is disabled:

make CFLAGS=-g CXXFLAGS=-g

Creating the Documentation

By default, documentation is not built when you install Gnash. This is because there are a number of dependencies for the documentation. Documentation is built when it is specified with a specific target in the generated Makefile in the doc/C sub-directory. If you type make install in this directory, all documents will be built.

You must specify a target output format when you wish to create documentation. The available output formats are: html, pdf, info, man, and alldocs. It is also possible to output GNOME help if the configure option --enable-ghelp was used. The alldocs target will build all output formats except GNOME help. For example, to create HTML output, type:

	make html
      

Gnash also uses Doxygen to produce HTML documentation of Gnash internals. You must have Doxygen installed to produce this documentation, which is built from the doc directory with the command (documents will be placed in the subdirectory apidoc/html):

	make apidoc
      

Running the Tests

Before beginning the potentially lengthy install, it is wise to test the installation. If a test fails, please report it by following the instructions for reporting a bug.

Using DejaGnu

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

	  make check
	

Increasing Verbosity

If you encounter a problem with a test, increasing the verbosity may make the issue easier to spot. Additional details are visible when RUNTESTFLAGS are used to add the verbose and all options. The verbose option prints more information about the testing process, while the all option includes details on passing tests.

	    make check RUNTESTFLAGS="-v -a"
	  

Running Some Tests

It is possible to run just a single test, or a subdirectory of tests, by specifying the directory or compiled test file.

Some tests rely on testsuite/Dejagnu.swf, which in turn relies on Ming. This file is created when you run make check for the entire testsuite, and can also be created on demand:

	    make -C testsuite Dejagnu.swf 
	  

In this example, the clip_as_button2 test is compiled and run:

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

This creates and runs all the tests in the directory movies.all:

	    make -C testsuite/movies.all check
	  

Running The Tests Manually

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
	

Movie tests

This creates a SWF movie version of the test case, which can be run with a standalone SWF player. For instance, the target for SWF version 6 could be run with Gnash:

	    gnash -v XML-v6.swf
	  

ActionScript Unit Tests

Unit tests for ActionScript classes in testsuite/actionscript.all are run without a graphical display:

	    gprocessor -v XML-v6.swf
	  

Installation

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.

Libraries

Installed libraries are located in /usr/local/lib by default. If the --prefix option was used during the configuration step, the libraries will be installed in the directory lib inside the path you specified. If the libraries are stored in a non-standard location, you must identify the path in one of two ways.

The traditional way to do this on UNIX platforms is to set the LD_LIBRARY_PATH variable to the path plus /lib. For example, if you installed in /home/gnash, the LD_LIBRARY_PATH path would be /home/gnash/lib. Multiple paths are delimited with a colon (':').

GNU/Linux allows the custom path to be added to /etc/ld.so.conf. After adding the path, run ldconfig as root to update the runtime cache.

Executables

The Mozilla plugin is built from headers (the Mozilla SDK) provided with Gnash and does not need extra development packages to be installed. By default, the plugin is installed to ~/.mozilla/plugins/. To enable the plugin for other users, copy the file libgnashplugin.so to .mozilla/plugins/ in their home directory. You may also specify the plugin installation directory by using the --with-plugindir option at configuration time.

These defaults are likely to change in future versions of Gnash.

The remaining executables are installed in the bin subdirectory of the directory specified by during configuration. If no path was specified, the default is /usr/local/bin.

Documentation

Documentation is not built by default; please refer to the section on documentation for more information on building documentation.

man and info are installed in /usr/local/share/man and /usr/local/share/info respectively, unless the --mandir or --infodir configuration options are used.

GNOME help documentation uses the directory /usr/local/share/gnash/doc/gnash/C/ by default. A configuration file in the Gnash source tree, doc/C/gnash.omf is used to specify under which menu item Gnash appears in the GNOME help system.

Cross Configuring

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:

--target

The target architecture, where the final executables are expected to run.

--host

The host architecture, where the executables are expected to run. Usually this is the same as the --target, except when building a compiler as a Canadian Cross. In this case, you might build a cross compiler on a UNIX system which runs on a win32 machine, producing code for a third architecture, such as ARM. In this example, --target would be 'arm-unknown-linux-gnu', while --host would be 'win32'.

--build

This is the system the build is running on.

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
    

Chapter 3. Software Internals

A Tour of Gnash

The top level of Gnash has several libraries, libgnashbase, libgnashcore, libgnashmedia, libgnashamf and libgnashbackend. There are several utility programs included for debug parsing and processing of SWF movie files, and other useful utilities for examining local Shared Objects and sniffing LocalConnections.

The Libraries

libgnashbase

Libgnashbase contains support classes used by the rest of the code.This library has no dependencies on any of the other Gnash libraries.

Gnash makes heavy use of smart pointers, so memory allocations are freed up automatically by the interpreter. Both STL and Boost smart pointers are used.

libgnashcore

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.

libgnashmedia

Libgnashmedia handles Gnash's decoding of video and audio, including both streamed and embedded media. Besides the standard SWF formats FLV, MPEG4, Nellymoser, ADPCM, MP3 and RAW, Gnash can decode other formats supports by Gstreamer or FFmpeg, including the free OGG container and free codecs.

libgnashsound

This library handles sound output and manages sound objects.

libgnashamf

AMF is the data format used internally by SWF files. This is Gnash'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.

libgnashbackend

Libgnashbackend is a library containing the rendering code that glues this display to the Gnash. Supported rendering backends are OpenGL, Cairo, and AGG.

libgnashplugin

Libgnashplugin is the Mozilla/Firefox plugin.

libklashpart

Libklashpart is the Konqueror plugin.

The Applications

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

The Standalone Player

This is the standalone OpenGL backend used to play movies. There are several command line options and keyboard control keys used by Gnash.

Gprocessor

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 .gsc files that Gnash uses to cache data, thereby speeding up the loading of files.

SOLdumper

SOLDumper is a utility program used to find and dump the content of Local Shared Objects, also called "Flash Cookies" by some.

Dumpshm

Dumpshm is a program used to find and dump the contents of the LocalConnection shared memory segment.

The Plugin

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.

Current Implementation

The plugin works in a 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 itself is not thread safe at this time.

GUI Support

Any plugin that wants to display in a browser window needs to be tied into the windowing system of the platform being used. On GNU/Linux systems, Firefox is a GTK2+ application. There is also KDE support through the use of the Klash plugin.

Gnash can use either several different GUI toolkits to create the window, and to handle events for the standalone player.

The SDL version is more limited, but runs on all 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 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.

There are a variety of development libraries that build a GUI widget system on top of SDL and OpenGL. The use of these to add menus and dialog boxes to the SDL version is being considered.

The GTK support is currently the most functional, and the best integrated into Firefox. The performance of this version is better than the SDL version because of the more efficient event handling within GTK. For the best end user experience, use the GTK enabled version.

GTK also allows Gnash 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 way the existing keyboard commands do.

Klash

Klash is MozPlugger type support for KDE's Konqueror web browser. Klash makes Gnash a kpart, so it's integrated into KDE better than when using MozPlugger. Klash uses the standalone player, utilizing Gnash's "-x" window plugin command line option.

By default, Klash is not built. To enable building Klash, use the --enable-klash option when configuring. Other than installing, there is nothing else that needs to be done to install Klash.

The Message Logging System

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.

Logging System API

Gnash provides 9 specialized logging calls, each using the printf()-style call similar to this:

log_error(const char* fmt, ...)

The different calls and their purposes are described below. The output to stdout and to disk are always identical, although writing the log to disk can be separately disabled.

log_error

Display an error message if verbose output is enabled. This is always printed at a verbosity level of 1 or more.

log_unimpl

Displays a warning to the user about missing Gnash features. We expect all calls to this function to disappear over time, as we implement those features of Flash. This is always printed at a verbosity level of 1 or more.

log_trace

Used only for the output of the ActionScript trace() function. This is always printed at a verbosity level of 1 or more.

log_debug

Logs debug information. This is printed at a verbosity level of 2 or more.

log_action

Log action execution information. Wrap all calls to this function (and other related statements) into an IF_VERBOSE_ACTION macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if action logging is enabled.

log_parse

Log SWF parsing Wrap all calls to this function (and other related statements) into an IF_VERBOSE_PARSE macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if parser logging is enabled.

log_swferror

This indicates an error in how the binary SWF file was constructed, i.e.probably a bug in the tools used to build the SWF file. Wrap all calls to this function (and other related statements) into an IF_VERBOSE_MALFORMED_SWF macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if malformed SWF logging is enabled.

log_aserror

This indicates an erroneous actionscript request such as an incorrect number of arguments or an invalid argument. Wrap all calls to this function (and other related statements) into an IF_VERBOSE_ASCODING_ERRORS macro, so to allow completely removing all the overhead at compile time and reduce it at runtime. This is printed at a verbosity level of 1 or more only if AS coding error logging is enabled.

log_abc

Extremely verbose logging related to AVM2/ABC execution. This is printed at verbosity level 3.

The LogFile Instance

This is the main API for initializing and manipulating the logging output. By default, the log will be written to gnash-dbg.log file whenever a verbose option is supplied.

getDefaultInstance()

This allows the construction of a LogFile on the first call, so ensuring that it the logfile is always initialised before use. It is the only way to access a LogFile instance. The logfile itself is never opened until it is needed.

setLogFilename(const std::string& filename)

Use this to set a different name for the disk-based log file. This setting can be overridden by a directive in gnashrc. If the log file is already open, a call to setLogFilename() will close it; a file with the new name will be opened when it is next needed.

closeLog()

Close a debug log. The disk file remains.

removeLog()

Delete the debug log file from disk.

setVerbosity()

Increment the verbosity level.

setVerbosity(int level)

Set the verbosity level to a specified level.

setStamp(bool flag)

If flag is true, then print a timestamp prefixed to every output line. If flag is false, then don't print a timestamp.

setWriteDisk(bool flag)

If flag is true, then create the disk file. If flag is false, then don't create the disk file.

Sound handling in Gnash

Sound in Gnash is handled by libgnashsound. This library takes care of interfacing with a sound handler.

There are two different settings related to sound support: pluginsound and sound. This was done in order to allow the plugin to be independently configured, for instance to block sound from advertisements.

Sound types

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.

Sound parsing

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.

Sound playback

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 SDL sound backend

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

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.

Detailed description of the Gstreamer backend

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.

Testing

Instructions on running tests can be found in the section on building Gnash.

Testing Tools

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.

Test Cases

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

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
	  
	

Writing Ming-based self-contained SWF tests

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.

Using Ming-based test generators facilities

Ming-based test generator facilities, which might be moved into a loadable SWF in the future, can be currently used by your test generator by including the ming_utils.h file and calling the appropriate functions.

The most useful facility provided for Ming-based SWF test generators is a Dejagnu-like TestState ActionScript class. In order to use this facility you must call 'add_dejagnu_functions()' right after Movie creation. The function takes an SWFMovie object and some parameters specifying depth and location of the "visual" trace textfield; it instantiates a global 'TestState' ActionScript object to keep track of test's state.

You will not need to directly invoke the TestState object created by the 'add_dejagnu_functions()' routine, rather you will be using C macros hiding its complexity:


	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.
	

Test cases generated using Ming and the provided facilities will be self-contained, which means they can be used as tests 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.

See section Writing Test Runners for information about writing SWF test runners.

Writing self-contained SWF tests with other compilers

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.

Writing Test Runners

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:

Label

Meaning

PASSED

The test succeeded.

FAILED

The test failed.

XPASSED

The test succeeded, but was expected to fail.

XFAILED

The test failed, and was expected to fail.

UNRESOLVED

The results of the test could not be automatically parsed.

UNTESTED

This test case is not complete.

UNSUPPORTED

The test case relies on a conditional feature which is not present in your environment.

The following labels may also appear:

Label

Meaning

ERROR

There was a serious error in running the test.

WARNING

There may have been a problem with running the test.

NOTE

There was some additional information given about the test.

Using the generic test runner for self-contained SWF tests

The simplest test runner is one that simply invokes Gnash 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 as a compliant "Test Runner".

A generator for simple test runners can be found in testsuite/generic-testrunner.sh. The script can be invoked by passing it $(top_builddir) as the first argument and the name of the SWF file (without the path) as the second argument. This will create a specific runner for your test in the current build directory. A simple Makefile.am rule for doing this follows:

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

By default, the generated test runner will play the movie up to the last frame. If you want the movie to be played more then once (maybe because you're exactly testing loop features) you can use the -r switch to the generic-testrunner.sh call. The following will create a runner playing the movie twice:

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

In case your test movie stops before the last frame, or you want to control the exact number of times to call the frame advancement routine, you can use the -f switch to control that.

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

When both -f and -r are given, the first exit condition reached will take effect.

Writing Movie testers

There are some parts of Gnash that can NOT be tested by only using ActionScript tests. Examples include: frame advancements, actual actions execution, gui events and so on.

In this case you might want to use the MovieTester class to implement a C++ test runner. Be aware that you can mix tests in the MovieTester-based class with self-contained tests in the SWF file as long as you activate verbosity for the debug logfile. This is done, for example, for the DefineEditTextVariableNameTest.swf file. The corresponding test runner (DefineEditTextVariableNameTest-Runner) is a C++ runner based on MovieTester class. If you run the runner you see two kinds of test results: the ones coming from the ActionScript engine, and the ones coming from the test runner. You can distinguish between the two because the former contains an additional timestamp and the latter does not. Also, you'll see two final summaries for the two test sets. The 'make check' rule, which uses the testsuite/simple.exp output parser as its work-horse, will count test results from both test sets.

Movie testers are executables which load an SWF, generate events (both user or system) on it, and check its state using a standard interface.

To help this process a MovieTester class is defined in the testsuite/MovieTester.{h,cpp} files; see Doxygen documentation for more information.

Note that you do NOT need access to the SWF source code in order to implement a Movie tester for it. Some knowledge about the expected behavior suffices.

Chapter 4. Adding New ActionScript Classes

Table of Contents

Prototype
Constructor

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.

A genuine ActionScript 2.0 class comprises a constructor function and a prototype object. Classes may have native type information, but most do not.

Prototype

In ActionScript, a prototype is an object that contains all the methods that an instantiated object will inherit.

In Gnash, the prototype of an ActionScript class, like all other objects, is implemented as an as_object. 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:

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

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.

Constructor

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.

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.

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.

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

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.

Native typing can be accessed in ActionScript callback functions using the ensure<> function template:

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

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.

Chapter 5. Reporting Bugs

The Gnash project relies on the community of Gnash users to test the player. Feedback is critical to any successful project. Not only does it let us know that people use Gnash, but it helps us understand the community's needs. Gnash uses a bug tracker on http://savannah.gnu.org to manage these reports.

When filing a report, please follow the guidelines below. The better your bug report is, the easier it will be for the developers to address the issue. Bug reports without enough information will be asked to provide this information anyway. Adding critical details, like the Operating System you are on, its version, and any relevant error messages from Gnash that you get.

Get a Fresh Binary Package

For starters, it's a good idea to obtain a copy of the latest snapshot. Although Gnash is primarily released as source, the Gnash build infrastructure allows the automated building of binary packages. Often the version of Gnash as packaged by a GNU/Linux or BSD distribution is based on the last official release, which could be months out of date. It helps us, if this is the case, for you to try a newer packaged build of Gnash.

You can get a fresh binary package of Gnash, as well as recent source packages from http://www.getgnash.org/packages .

Determine if the bug was previously reported

Search the Gnash bug tracker to see if the bug has already been identified.

If the issue has already been reported, you should not file a bug report. However, you may add some additional information to the ticket if you feel that it will be beneficial to the developers. For instance, if someone reported a memory issue on Ubuntu GNU/Linux, and you noticed the same problem on OpenBSD, your stacktrace would be useful. Conversely, adding a "me too" note to a feature request is not helpful.

Review the bug writing guidelines

A good bug report should be precise, explicit, and discrete. This means that there should be just one bug per ticket, and that a ticket should contain the following information:

  • An overview of the problem;

  • Instructions on how to replicate the bug;

  • A description of what happened when you performed the steps to replicate the bug, and what you expected to happen;

  • Your system information: operating system name and version, as well as the versions of major development dependencies;

  • The release number or checkout timestamp for the version of Gnash where you observe the problem;

  • The file config.log, which should be attached as a file;

  • A descriptive title.

Include any additional information that you feel might be useful to the developers.

Filing a bug report

After following the steps described above, you can file a bug report at https://savannah.gnu.org/bugs/?group=gnash.

Chapter 6. Gnash Extensions

Gnash supports the creation of custom extensions to ActionScript. This allows you to integrate any conceivable system or library function into ActionScript execution.

Extensions do not represent a general alteration of the ActionScript language. They are designed to allow Gnash to be more flexible and powerful where it is required. They allow you to customize Gnash 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.

Some extensions are distributed with Gnash, mainly to serve as an example. Extensions are not enabled by default, both for security and compatibility reasons.

Creating A New Extension

Each new extension should live in its own directory. The extensions included in Gnash are all in the gnash/extensions directory. Creating an extension requires a Makefile.am,

If you are adding this extension to the Gnash source tree itself, then you need to make two changes to add the new 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. The other change is to add it to the AC_OUTPUT list in configure.ac so the new directory will be configured along with the rest of Gnash.

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 check_PROGRAMS variable so that "make check" works.

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 abstractions. Higher-level classes that offer a lot of new functionality are fine, but this is different from wrapping a library so it can be used from within Gnash.

Crafting an Extension

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

Debugging An Extension

You can resort to the time honored technique of creating a loop before the point you want to set a breakpoint for. Gnash will stop playing the movie at this point, and then you can externally attach GDB to the running process, or type ^C to drop into the GDB command console.

      bool stall = true;
      while (stall) {
          sleep 1;
      }
    

Once you have set the breakpoints you want, reset the value of the stall variable to break out of the loop, and the SWF movie will then continue playing.

      (gdb) set variable stall = false;
      continue
    

Included Extensions

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 to load an extension file.

Gtk Extension

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.

window_new

Create a new window.

signal_connect

Add an event handler to a widget.

container_set_border_width

Set the width of the window border.

button_new_with_label

Create a new button and give it the specified label.

signal_connect_swapped

Swap signals. Commonly used for delete event handling.

container_add

Add one widget to another as a child.

widget_show

Display the widget on the screen.

main

Start the main GTK event loop. This function does not return.

File I/O Extension

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.

fopen

Open the file.

fread

Read a series of bytes from the opened file.

fgetc

Read a single byte from the opened file.

fgets

Read a single line until a Carriage Return from the opened file.

gets

Read a single line from the standard in.

getchar

Read a single character from the standard in.

fwrite

fputc

Write a single character to the opened file.

fputs

Write a single line to the opened file.

puts

Write a single line to standard out..

putchar

Write a single character to standard out..

fflush

Flush the current opened file to disk.

fseek

Seek to a location within the opened file.

ftell

Report the current position within the opened file.

fclose

Close the opened file.

MySQL Extension

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.

connect

Connect to a MySQL database.

qetData

Get data from the database.

disconnect

Disconnect from a MySQL database.

query

Execute an SQL query to the database.

fetch_row

Fetch a row from the query results.

num_fields

free_result

Free the results of a query.

store_results

Store the results of a query.

Chapter 7. RTMP Protocol

Table of Contents

AMF Format

This document is based mostly on my own reverse engineering of the RTMP protocol and AMF format. tcpdump and ethereal are your friend. Some additional info that got me started was from the Red5 project. Red5 is the only other open source SWF server. So some details are still vague, but as the implementation appears to work, we'll figure out what they are later.

The Real Time Messaging Protocol was created by MacroMedia (now Adobe) for delivering SWF objects and video over a network connection. Currently the only servers which support this format are the MacroMedia Media sever, and the Open Source Red5 project.

This is a simple protocol, optimized for poor bandwidth connections. It can support up to 64 concurrent streams over the same network connection. Part of each AMF packet header contains the index number of the stream. A single RTMP message can contain multiple AMF packets.

An RTMP connection uses Tcp/ip port 1935. It is also possible to tunnel RTMP over an HTTP connection using port 80. Each AMF packet is 128 bytes long except for streaming audio, which has 64 byte packets.

The basics of the RTMP protocol are as follows. All communications are initiated by the client.

The client starts the RTMP connection by sending a single byte with a value of 0x3. This byte is followed by a data block of 1536 bytes. The format if this data block is unknown, but it appears to not be actually used by the protocol except as a handshake.

The server receives this packet, stores the 1536 byte data block, and then send a single byte with the value of 0x3, followed by two 1536 data blocks. The second data block is the full contents of the original data block as sent by the client.

The client receives the 1536 byte data block, and if they match, the connection is established. After the handshake process is done, there are three other messages that the client sends to the sever to start the data flowing.

The first AMF packet sent to the server contains the connect packet. This doesn't appear to do much but notify the server the client is happy with the handshake, and ready to start reading packets.

The second packet is the NetConnection object from the client. This ActionScript class is used by the SWF movie to create the network connection to the server.

The third packet is the NetStream object from the client. This is the ActionScript class used to specify the file to be streamed by the server.

The RTMP packet for our example looks like this:

      030000190000c91400000000020007connect00?f0000000000000030003app0200#
      software/gnash/tests/1153948634.flv0008flashVer02000cLNX 6,0,82,0 0006
      swfUrl02001dfile:///file|%2Ftmp%2Fout.swfc30005tcUrl\002\0004
      rtmp://localhost/software/gnash/tests/1153948634.flv\000\000\t
      \002\000\005userx
    

We'll take this apart in a bit, but you can see how all three AMF packets are in the same message. The message is received in several 128 byte blocks, with the last one being less than that. The total size of the RTMP message is in the header, so the reader can tell if the entire message was read or not.

The RTMP header is first, followed by the connect message as an ASCII string as the message body. The following AMF packet is the NetConnection one, which specifies that this is coming from a SWF application. This also contains the file path the server can use to find the file to stream. This is then followed by the version number, which I assume is the version of the SWF player, so the server knows what it is talking to.

The third packet is the one from NetStream, which specifies the URL used for the movie, followed by the user name for a semblance of security.

For the next level of detail, we'll explain the format of AMF. AMF is used by the RTMP protocol to transfer data. Each SWF object is encapsulated in an AMF packet, including streaming audio or video.

The first byte of the RTMP header determines two things about the rest of the message. The first 2 bits of this byte signify the total size of the RTMP header. The RTMP header is of a variable size, so this is important.

00

This specifies the header contains 12 bytes, including this one.

01

This specifies the header contains 8 bytes, including this one.

02

This specifies the header contains 4 bytes, including this one.

03

This specifies the header contains 1 byte, so this is the complete header.

The other 6 bits in this byte represent the AMF index. As a single RTMP connection can support multiple data streams, this signifies which stream this packet is for. Once an AMF object is fully received by the client, the AMF index may be reused.

For messages with headers of at least 4 bytes, the next 3 bytes are used by audio and video data packets, but at this time the meaning of this field is unknown.

For messages with a 8 byte or larger header, the next 3 bytes determine the size of the RTMP message being transmitted. Messages with a 1 byte or 4 byte header use a standard size, 128 bytes for video, and 64 bytes for audio.

For messages with an 8 byte or larger header, the next byte is the type of the AMF object.

0x3

This specifies the content type of the RTMP packet is the number of bytes read. This is used to start the RTMP connection.

0x4

This specifies the content type of the RTMP message is a ping packet.

0x5

This specifies the content type of the RTMP message is server response of some type.

0x6

This specifies the content type of the RTMP packet is client request of some type.

0x8

This specifies the content type of the RTMP packet is an audio message.

0x9

This specifies the content type of the RTMP message is a video packet.

0x12

This specifies the content type of the RTMP message is notify.

0x13

This specifies the content type of the RTMP message is shared object.

0x14

This specifies the content type of the RTMP message is remote procedure call. This invokes the method of a SWF class remotely.

There are two sets of data types to consider. One set is used by the to specify the content type of the AMF object, the other is an ActionScript data type tag used to denote which type of object is being transferred.

The values of the initial type byte are:

0x0

This specifies the data in the AMF packet is a numeric value. All numeric values in SWF are 64 bit, big-endian.

0x1

This specifies the data in the AMF packet is a boolean value.

0x2

This specifies the data in the AMF packet is an ASCII string.

0x3

This specifies the data in the AMF packet is a SWF object. The SWF object data type field further along in the message specifies which type of ActionScript object it is.

0x4

This specifies the data in the AMF packet is a SWF movie, ie. another SWF movie.

0x5

This specifies the data in the AMF packet is a NULL value. NULL is often used as the return code from calling SWF functions.

0x6

This specifies the data in the AMF packet is a undefined. This is also used as the return code from calling SWF functions.

0x7

This specifies the data in the AMF packet is a reference.

0x8

This specifies the data in the AMF packet is a ECMA array.

0x9

This specifies the data in the AMF packet is the end of an object definition. As an object is transmitted with multiple AMF packets, this lets the server know when the end of the object is reached.

0xa

This specifies the data in the AMF packet is a Strict array.

0xb

This specifies the data in the AMF packet is a date.

0xc

This specifies the data in the AMF packet is a multi-byte string. Multi-byte strings are used for international language support to represent non ASCII fonts.

0xd

This specifies the data in the AMF packet is a an unsupported feature.

0xe

This specifies the data in the AMF packet is a record set.

0xf

This specifies the data in the AMF packet is a AML object. XML objects are then parsed by the XML ActionScript class.

0x10

This specifies the data in the AMF packet is a typed object.

For messages with a 12 byte header, the last 4 bytes are the routing of the message. If the destination is the server, this value is the NetStream object source. If the destination is the client, this is the NetStream object for this RTMP message. A value of 0x00000000 appears to be reserved for the NetConnection object.

Multiple AMF streams can be contained in a single RTMP messages, so it's important to check the index of each AMF packet.

An example RTMP header might look like this. (spaces added between fields for clarity) All the numbers are in hex.

      03 000019 0000c9 14 000000000
    

03

The first two bits of this byte are the size of the header, which in this example is 00, for a 12 byte header. The next 6 bits is the AMF stream index number, which in this example is 0x3.

000019

These 3 bytes currently have an unknown purpose.

000c9

Since this example has a 12 byte header, this is the size of the RTMP message, in this case 201 bytes.

14

This is the content type of the RTMP message, which in this case is to invoke a remote function call. (which we later see is the connect function).

00000000

The source is the NetConnection object used to start this connection.

AMF Format

The AMF format is used in the LocalConnection, SharedObject, NetConnection, and NetStream ActionScript classes. This is a means of binary data interchange between SWF movies, or between a SWF player and a SWF server.

Like the RTMP messages, an AMF packet header can be of a variable size. The size is either the same as the initial header of the RTMP message, or a 1 byte header, which is commonly used for streaming audio or video data.

The body of an AMF packet may look something like this example. The spaces have been added for clarity.

      02  0007 636f6e6e656374
    

02

This is a single byte header. The value of the first 2 bits is 0x3, and the AMF index is also 0x3.

0007

This is the length in bytes of the string.

63 6f 6e 6e 65 63 74

This is the string. Note that there is no null terminator since the length is specified.

Chapter 8. Mozilla/Firefox NPAPI Plugin

The Mozilla SDK has two API layers for plugins. The older layer is documented in the Geeko Plugin API Reference, and the newer layer doesn't appear to be documented. The new API is simpler, and is portable across multiple versions of Mozilla or Firefox. The new API is just a layer on top of the older one, so this manual still applies.

Most of the programming of a plugin is filling in real emphasis for the standard API functions and methods. Firefox uses these to create the plugin, and to send it data.

When initializing or destroying a plugin, no matter how many instances are being used, the C API is used. These functions are typically called once for each plugin that is loaded.

Plugin C API

The lower layer is a C based API which is used by Firefox to initialize and destroy a plugin. This is so a plugin can be portable across multiple systems, since C++ emphasis is not portable between most C++ compilers. This is where most of the behind the scenes work is done in a plugin. For Gnash, the sources this lower layer are in plugin/mozilla-sdk. They were added to the Gnash source tree so it wouldn't be necessary to have the Mozilla development packages installed to compile the Gnash plugin.

This is also the older API used for plugins, so is usually the one used if you dig around for plugin examples on the web. These are the main functions which have to be implemented in a plugin for it to be recognized by the browser, and to be initialized and destroyed.

NS_PluginInitialize

This C function gets called once when the plugin is loaded, regardless of how many instantiations there are actually playing movies. So this is where all the one time only initialization stuff goes that is shared by all the threads.

NS_NewPluginInstance

This instantiates a new object for the browser. Returning a pointer to the C++ plugin object is what ties the C++ and C emphasis parts of the API together.

NS_DestroyPluginInstance

This destroys our instantiated object when the browser is done.

NS_PluginShutdown

This is called when a plugin is shut down, so this is where all the one time only shutdown stuff goes.

NPP_GetMIMEDescription

This is called to get the MIME types the plugin supports.

NS_PluginGetValue

This is used by Firefox to query information from the plugin, like the supported MIME type, the version number, and a description.

Plugin C++ API

The higher level layer is the one we are most concerned with. This is an instantiation of the nsPluginInstanceBase class, as defined by the Mozilla SDK, for our plugin. With this API, a plugin is mostly defining the standard entry points for Firefox, and the emphasis that implements the glue between the Firefox and our plugin.

These are called for each instantiation of plugin. If there are three Flash movies on a web page, then three instances are created. Unfortunately for plugin programmers, these functions may randomly be called more than once, so it's good to use initialization flags for things that should only be done one per thread. For instance, nsPluginInstance::init() and nsPluginInstance::SetWindow() are called more than once, so the plugin must protect against actions that could be destructive.

nsPluginInstance::nsPluginInstance

Create a new plugin object.

nsPluginInstance::init

This methods initializes the plugin object, and is called for every movie which gets played. This is where the thread-specific information goes.

nsPluginInstance::SetWindow

This sets up the window the plugin is supposed to render into. This calls passes in various information used by the plugin to setup the window. This may get called multiple times by each instantiated object, so it can't do much but window specific setup here. This is where the main emphasis is that sets up the window for the plugin.

nsPluginInstance::NewStream

Opens a new incoming data stream, which is the flash movie we want to play. A URL can be pretty ugly, like in this example: http://www.sickwave.com/swf/navbar/navbar_sw.swf?atfilms=http%3a//www.atm.com/af/home/&shickwave=http%3a//www.sickwave.com&gblst=http%3a//gbst.sickwave.com/gb/gbHome.jsp&known=0 ../flash/gui.swf?ip_addr=foobar.com&ip_port=3660&show_cursor=true&path_prefix=../flash/&trapallkeys=true" So this is where we parse the URL to get all the options passed in when invoking the plugin.

nsPluginInstance::Write

Read the data stream from Mozilla/Firefox. For now we read the bytes and write them to a disk file.

nsPluginInstance::WriteReady

Return how many bytes we can read into the buffer.

nsPluginInstance::DestroyStream

Destroy the data stream we've been reading. For Gnash, when the stream is destroyed means we've grabbed the entire movie. So we signal the thread to start reading and playing the movie.

nsPluginInstance::shut

This is where the movie playing specific shutdown emphasis goes.

nsPluginInstance::~nsPluginInstance

This destroys our plugin object.

NS_PluginInitialize::initGL

This is a Gnash internal function that sets up OpenGL.

NS_PluginInitialize::destroyContext

This is a Gnash internal function that destroys a GLX context.

nsPluginInstance::getVersion

This returns the version of Mozilla this plugin supports.

nsPluginInstance::GetValue

This returns information to the browser about the plugin's name and description.

nsPluginInstance::URLNotify

OpenGL and Threads

Neither OpenGL nor X11 has any built-in support for threads. Most actions aren't even atomic, so care has to be made to not corrupt any internal data. While it is difficult to render OpenGL from multiple threads, it can be done with the proper locking. The downside is the locking adds a performance hit, since all the threads will have to have the access synchronized by using mutexes.

The X11 context is maintained one per instantiation of the plugin. It is necessary to lock access to the X11 context when using threads by using XLockDisplay() and XUnlockDisplay(). A connection to the X11 server is opened for every instantiation of the plugin using XOpenDisplay().

The GLX Context is maintained one per instantiation of the plugin for a web page. If there are more than one Flash movie, there is more than one GLX Context. A GLX context can be created by using glXCreateContext(), and then later destroyed by using glXDestroyContext(). When swapping threads, the context is changed using glXMakeCurrent().

All the emphasis that directly accesses a GLX context or the X11 display must be wrapped with a mutex.

Plugin Event Handling

Firefox on most UNIX systems is a GTK+ application, so it is possible to have the plugin hook into the X11 event handling via GLX or GTK. Since Firefox uses GTK, so does Gnash. This also allows the addition of a right-click mouse menu for controlling the player. The GTK build of Gnash offers the best browsing experience as it's more functional than the SDL version.

It is also possible to disable the GTK support so only the older SDL support is used. In this case Gnash can't support event handling within the browser. This means that when using the SDL of the plugin, mouse clicks and keys pressed get ignored. Windows also can't be resized, and sometimes they overrun their boundaries as well. To disable the GTK support and force SDL to be used anyway, configure with --disable-glext

Appendix

Code Style

I know any discussion of coding styles leads to strong opinions, so I'll state simply I follow the GNU Coding Standards. Where there is some flexibility as to the location of braces, I prefer mine on the end of a line when using an if, while, or do statement. I find this more compact style easier to read and parse by eye. I'm also a big fan of always using braces around if statements, even if they're one liners.

Here's my tweaked style settings for Emacs, the one true editor to rule them all.

      (defconst my-style
          '((c-tab-always-indent   . t)
           (c-auto-newline	   . t)
           (c-hanging-braces-alist . (
				   (brace-list-intro)
				   (namespace-open)
				   (inline-open)
				   (block-open)
				   (brace-list-open)
				   (brace-list-close)
				   (brace-entry-open)
				   (brace-else-brace)
				   (brace-elseif-brace)
				   (class-open after)
				   (class-close)
				   (defun-open after)
				   (defun-close)
				   (extern-lang-open)
				   (inexpr-class-open)
				   (statement-open)
				   (substatement-open)
				   (inexpr-class-close)))
            (c-hanging-colons-alist . ((member-init-intro before)
                                   (inher-intro)
                                   (case-label after)
                                   (label after)
                                   (access-label after)))
            (c-offsets-alist	. (
				   (innamespace . 0)
                                   (case-label  . 2)
				   ))
            (c-cleanup-list	. (
				   (scope-operator)
				   (empty-defun-braces)
				   (brace-else-brace)
				   (brace-elseif-brace)
				   (defun-close-semi)
				   (list-close-comma)
				   )
				)
    ;; no automatic newlines after ';' if following line non-blank or inside
    ;; one-line inline methods
    (add-to-list 'c-hanging-semi&comma-criteria
		 'c-semi&comma-no-newlines-before-nonblanks)
    (add-to-list 'c-hanging-semi&comma-criteria
		 'c-semi&comma-no-newlines-for-oneline-inliners)
;    (knr-argdecl-intro . -)
    (c-echo-syntactic-information-p . t)
    )
  "My GNU Programming Style")
    

Another coding consideration: comments are good! Over commenting isn't good. Here is an over commented example:

	counter++;		// increment counter
      

Gnash also uses Doxygen style comments. These are processed by Doxygen when building a cross reference of all the classes, and is a good way to help push internals documentation from the depths of the code into documentation where it can be seen by others.

Doxygen style comments for C++ code involves simply using three slashes /// instead of the standard two slashes // used for C++ comments. Here's a short comment block for the XML::cloneNode() method:

	/// \brief copy a node
	///
	/// Method; constructs and returns a new XML node of the same type,
	/// name, value, and attributes as the specified XML object. If deep
	/// is set to true, all child nodes are recursively cloned, resulting
	/// in an exact copy of the original object's document tree.
	XMLNode &
	XML::cloneNode(XMLNode &newnode, bool deep) {
	...
	}
      

The \brief keyword means that the text becomes associated when listing all the classes on the generated web pages. The text after the blank link becomes the detailed description which appears on the generated web page for that class and method.

Chapter 9. Authors

Gnash is maintained by Rob Savoye. Other active developers are: Sandro Santilli, Bastiaan Jacques, Udo Giacomozzi, Chad Musick, Benjamin Wolsey, Zou Lunkai, and Russ Nelson. Please send all comments and suggestions to . Past and sometimes current developers are Tomas Groth and Markus Gothe.

Gnash was initially derived from GameSWF. GameSWF is maintained by Thatcher Ulrich . The following people contributed to GameSWF: Mike Shaver, Thierry Berger-Perrin, Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit, and Rob Savoye.

Appendix A. GNU Free Documentation License

Version 1.1, March 2000

Free Software Foundation, Inc. 59 Temple Place, 
        Suite 330
BostonMA  
        02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or non-commercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

  • A.  Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  • B.  List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

  • C.  State on the Title Page the name of the publisher of the Modified Version, as the publisher.

  • D.  Preserve all the copyright notices of the Document.

  • E.  Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  • F.  Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

  • G.  Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  • H.  Include an unaltered copy of this License.

  • I.  Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  • J.  Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  • K.  In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  • L.  Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  • M.  Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

  • N.  Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version .

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

Addendum

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright 2008, Free Software Foundation.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with noInvariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.