Gnash Reference Manual
**********************

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.

1.1 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.

1.2 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
(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.

2 Building from Source
**********************

2.1 Overview
============

The typical process of building from source will involve getting the
source (see Getting The Source), build dependencies (see Code Dependencies),
configuration (see Configuring Gnash), compilation
(see Compiling the Code), testing (see Running the Tests), and
installation (see 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.

2.2 Getting The Source
======================

2.2.1 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
(http://savannah.gnu.org/projects/gnash) or under
http://ftp.gnu.org/gnu/gnash (http://ftp.gnu.org/gnu/gnash)

2.2.2 Git Access
----------------

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

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

You can then update your copy from the main repository using:

     	  git pull

   At any time, other temporary development branches may also be
available. Replace _exp_ with the branch name to check these out.

     	  git checkout -b exp origin/exp

   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
(http://www.gnashdev.org/dev_snapshots/)

2.3 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.

*Code Dependency Table*

Name       Level      Version    DescriptionExplanationapt-get    RPM/Yum
                                                       package    packageBSD
                                                                  package
Boost      Required   1.32 or     Boost is  In Gnash,  `libboost-thread-dev,`
                      higher     a library  Boost      libboost-date-time-devlibboost-thread-devel,
                                 of         libraries  libboost-devlibboost-date-time-devel
                                 portable   are used   '          '`
                                 C++        extensively,           boost-headers,
                                 classes    primarily             boost-libs,
                                 and        boost-gthread           or just
                                 templates. and                   boost '
                                            boost-date-time.
                                            Boost is
                                            used for
                                            thread
                                            and mutext
                                            handling.
AGG        Possibly   2.4 or      AGG is    Gnash      `libagg-dev'`agg-devel'`agg'
           Required   higher     the        requires
                                 AntiGrain  the
                                 low-level  installation
                                 2D         of at
                                 graphics   least one
                                 library.   renderer.
                                            AGG is
                                            considered
                                            the _best
                                            supported_
                                            renderer
                                            for Gnash.
OpenGL     Possibly               OpenGL    Gnash      `libgl1-mesa-dev'`libmesa-devel'`mesa'
           Required              is a       requires
                                 standard   the
                                 specificationinstallation
                                 defining a of at
                                 cross-languageleast one
                                 cross-platformrenderer.
                                 API for    If you
                                 writing    don't
                                 applicationshave a
                                 which      hardware
                                 produce    accelerated
                                 3D and 2D  driver,
                                 graphics.  you're
                                 It         better
                                 supports   off using
                                 hardware   AGG for
                                 acceleration.the
                                 You can    renderer.
                                 download
                                 a free
                                 implementation
                                 from
                                 http://www.mesa3d.org
                                 (http://www.mesa3d.org),
                                 although
                                 it
                                 doesn't
                                 support
                                 hardware
                                 acceleration.
Cairo      Possibly               Cairo is  Gnash      `libcairo2-dev'`cairo-devel'`cairo'
           Required              a 2D       requires
                                 graphics   the
                                 library    installation
                                 with       of at
                                 support    least one
                                 for        renderer.
                                 multiple   Cairo is
                                 output     considered
                                 devices.   the
                                 It will    _least
                                 automaticallysupported_
                                 use        renderer
                                 graphic    for Gnash.
                                 card
                                 acceleration
                                 when
                                 available,
                                 and has
                                 an
                                 experimental
                                 OpenGL
                                 backend.
GTK        Possibly   2.2 or      GTK is    Gnash      `libgtk2.0-dev'`gtk-devel'`gtk+2'
           Required   higher     the GIMP   requires
                                 Toolkit    the
                                 GUI        installation
                                 library    of at
                                 used by    least one
                                 the GNOME  GUI
                                 desktop.   library.
                                 It uses    GTK is
                                 Cairo      considered
                                 internally.to be the
                                 Gtk        _best
                                 enables    supported_
                                 better     GUI
                                 integrationlibrary
                                 with       option
                                 Firefox,   for Gnash.
                                 as well
                                 as better
                                 event
                                 handling
                                 and
                                 higher
                                 level GUI
                                 constructs
                                 like
                                 menus and
                                 dialog
                                 boxes.
GtkGlExt   Possibly               GtkGlExt  This       `libgtkglext1-dev'`gtkglext-devel'`gtkglext'
           Required              integrates library
                                 OpenGL     is
                                 into GTK.  required
                                            in order
                                            to use
                                            the GTK
                                            GUI
                                            library
                                            in
                                            conjunction
                                            with the
                                            OpenGL
                                            renderer.
SDL        Possibly               The       Gnash      `libsdl1.2-dev'`SDL-devel'`SDL-1.2'
           Required              Simple     requires
                                 DirectMediathe
                                 Layer is   installation
                                 a          of at
                                 cross-platformleast one
                                 multimedia GUI
                                 library    library.
                                 which      SDL may
                                 provides   also be
                                 abstractionused as a
                                 for        sound
                                 audio,     handler
                                 graphics,  regardless
                                 sound and  of
                                 input      whether
                                 APIs.      it is
                                 SDL is     employed
                                 available  as a GUI
                                 from       library.
                                 http://www.libsdl.orgThe GUI
                                 (http://www.libsdl.org).library
                                            is
                                            _poorly
                                            supported_
                                            in Gnash,
                                            but the
                                            sound
                                            handler
                                            is the
                                            _best
                                            supported_
                                            in Gnash.
FLTK       Possibly   2.0 or      The Fast  Gnash      No         No
           Required   higher     Light      requires   distributiondistribution
                                 ToolKit    the        packages   packages
                                 is a       installationare        are
                                 portable   of at      available. available.No
                                 GUI        least one             distribution
                                 library    GUI                   packages
                                 which is   library.              are
                                 intended   FLTK may              available.
                                 as a       be used
                                 replacementin
                                 for the    conjunction
                                 SDL GUI.   with the
                                            Cairo and
                                            AGG
                                            renderers.
KDE        Possibly               Kdelibs   Gnash      `kdelibs3-dev,`kdelibs-devel,
           Required              is a       requires   kdebase-dev'kdebase-devel'`kdelibs,
                                 collection the                   kdebase'
                                 of         installation
                                 libraries  of at
                                 needed to  least one
                                 compile    GUI
                                 KDE        library.
                                 applications.Kdelibs
                                            is also
                                            required
                                            for the
                                            Kpart
                                            plugin
                                            for
                                            Konqueror.
Gstreamer  Optional               Gstreamer If you     `libgstreamer0.8-dev'`gstreamer-devel'`gstreamer-0.10'
                                 is a       would
                                 video      like
                                 handler.   video
                                            playback,
                                            you must
                                            install
                                            one of
                                            the video
                                            handlers.
gst-ffmpeg Possibly               gst-ffmpegThis       `gstreamer0.8-ffmpeg-dev'`gstreamer-ffmpeg-devel'`gstreamer-ffmpeg'
           Required              allows     package
                                 you to     is
                                 use the    required
                                 FFmpeg     if you
                                 decoder    would
                                 with       like to
                                 Gstreamer. use
                                            Gstreamer
                                            as a
                                            video
                                            handler.
FFmpeg     Possibly               FFmpeg    If you     `ffmpeg-dev'`ffmpeg-devel'`ffmpeg'
           Required              is a       would
                                 video      like
                                 handler.   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.
JPEG       Required              JPEG       This       `libjpeg62-dev'`libjpeg'`jpeg'
                                 (http://www.ijg.org/)library
                                 is a       is used
                                 lossy      for
                                 image      reading
                                 format     external
                                 which is   JPEGs and
                                 heavily    JPEG data
                                 used for   embedded
                                 images.    in SWF
                                            files.
PNG        Required              PNG        This       `libpng12-dev'`libpng'`png'
                                 (http://www.libpng.org/pub/png/)library
                                 is a       is used
                                 patent-freefor
                                 image      loading
                                 format     external
                                 which is   PNG
                                 comparable images
                                 to _GIF_.  (part of
                                            the SWF8
                                            specification)
                                            and for
                                            writing
                                            images in
                                            the PNG
                                            format.
GIF        Required              GIF is a   This       `libungif-dev'`libungif-devel'`gif'
                                 common     library
                                 image      is used
                                 format     for
                                 that       loading
                                 should now external
                                 be free    GIF
                                 of patent  images
                                 restrictions.(part of
                                 _GIF_.     the SWF8
                                            specification).
libcurl    Optional               libcurl   This       `libcurl4-gnutls'`libcurl'`curl'
                                 is the     library
                                 multiprotocalis used
                                 file       for URL
                                 transfer   downloading.
                                 library.
Glib2      Optional               Glib2 is  This       `glib2-dev'`glib2-devel'`glib2'
                                 a          library
                                 dependency is used
                                 of Gtk,    for
                                 and is a   convenience.
                                 collection
                                 of
                                 commonly
                                 used
                                 functions.
Atk        Optional               Atk is a  This       `atk-dev'  `atk-devel'`atk'
                                 dependency library
                                 of Gtk,    is used
                                 and is     for
                                 used for   accessiblity..
                                 accessibility
                                 support.
Pango      Optional               Pango is  This       `pango-dev'`pango-devel'`pango'
                                 a          library
                                 dependency is used
                                 of Gtk,    for font
                                 and is     handling.
                                 used for
                                 font
                                 handling.
automake   Possibly   1.6.0       Automake  This       `automake' `automake'`automake'
           Required              is a tool  package
                                 for        is
                                 generating required
                                 _Makefile.in_to run
                                 files.     _autogen.sh_,
                                            which is
                                            a
                                            requirement
                                            if you
                                            are using
                                            the
                                            development
                                            source
                                            from CVS.
autoconf   Possibly   2.59        Autoconf  This       `autoconf' `autoconf'`autoconf'
           Required              is a       package
                                 package    is
                                 for        required
                                 generating to run
                                 configure  _autogen.sh_,
                                 scripts.   which is
                                            a
                                            requirement
                                            if you
                                            are using
                                            the
                                            development
                                            source
                                            from CVS.
gettext    Possibly   0.14.6      Gettext   This       `gettext'  `gettext'`gettext'
           Required              is part    package
                                 of the     is
                                 GNU        required
                                 Translationto run
                                 Project.   _autogen.sh_,
                                            which is
                                            a
                                            requirement
                                            if you
                                            are using
                                            the
                                            development
                                            source
                                            from CVS.
libtool    Possibly   1.5.22      This is   This       `libtool'  `libtool'`libtool'
           Required              a generic  package
                                 library    is
                                 support    required
                                 script.    to run
                                            _autogen.sh_,
                                            which is
                                            a
                                            requirement
                                            if you
                                            are using
                                            the
                                            development
                                            source
                                            from CVS.
libltdl    Required              GNU        This       libltdl-devlibtool-ltdl-devellibtool
                                 Libtool    package
                                 Dynamic    is used
                                 Module     to load
                                 Loader     gnash
                                            extensions
Xulrunner  optional              Xulrunner  This       `xulrunner-dev'`xulrunner-devel'`xulrunner-devel'
SDK                              SDK is     package
                                 needed to  is
                                 develop    required
                                 plugins    to build
                                 for        npapi
                                 Firefox    plugin

2.4 Testing Dependencies
========================

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

*Testing Dependency Table*

Name       Level      Version    DescriptionExplanationapt-get    RPM/Yum
                                                       package    packageBSD
                                                                  package
Ming       Optional   0.4.0_beta4 Ming is   Ming is    No         No
                      or higher  an         the        distributiondistribution
                                 ActionScriptprimary    packages   packages
                                 compiler.  compiler   are        are
                                            for        available. available.No
                                            ActionScript           distribution
                                            testcases.            packages
                                                                  are
                                                                  available.
Mtasc      Optional   1.12 or     Mtasc is  Mtasc is   `mtasc'    No
                      higher     an         used in               distribution
                                 ActionScriptsome                  packages
                                 compiler.  tests.                are
                                                                  available.No
                                                                  distribution
                                                                  packages
                                                                  are
                                                                  available.
swfc       Optional   part of     Swfc is   Swfc is    No         No
                      swftools   an swf     used in    distributiondistribution
                      0.8.1      compiler.  some       packages   packages
                                            testcases. are        are
                                                       available. available.No
                                                                  distribution
                                                                  packages
                                                                  are
                                                                  available.
swfmill    Optional   0.2.12      Swfmill   Swfmill    No         No
                                 is an      is used    distributiondistribution
                                 XML-based  in some    packages   packages
                                 SWF        testcases. are        are
                                 (Shockwave            available. available.No
                                 Flash)                           distribution
                                 processing                       packages
                                 tool.                            are
                                                                  available.
Python     Optional   2.4 or      Python    Python is  `python'   `python'`python'
                      higher     is a       used by
                                 scripting  part of
                                 language.  the
                                            testing
                                            framework.
DejaGnu    Optional   1.4 or      DejaGnu   DejaGnu    `dejagnu'  `dejagnu'`dejagnu'
                      higher     is a       is used
                                 testing    to run
                                 framework. multiple
                                            tests in
                                            an
                                            automated
                                            fashion.

2.5 Documentation Dependencies
==============================

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

*Documentation Dependency Table*

Name       Level      Version    DescriptionExplanationapt-get    RPM/Yum
                                                       package    packageBSD
                                                                  package
Docbook    Required              Docbook    Gnash      `docbook-utils'`docbook-dtd41-sgml'
                                 (http://http://docbook.sourceforge.net/)documentationand        and
                                 is is an   is         `docbook-dsssl'`docbook-style-dsssl'docbook
                                 industry-standardwritten
                                 XML        in
                                 format     Docbook.
                                 for
                                 technical
                                 documentation.
                                 You can
                                 download
                                 it from
                                 http://sourceforge.net/project/showfiles.php?group_id=21935#files
                                 (http://sourceforge.net/project/showfiles.php?group_id=21935#files).
DocBook2X  Optional               This      DocBook2X  `docbook2x'`docbook2x'`docbook2x'
                                 software   is
                                 package    required
                                 converts   to
                                 Docbook    produce
                                 documents  HTML and
                                 to the     Texinfo
                                 traditionalformats.
                                 man page
                                 format,
                                 GNU
                                 Texinfo
                                 format,
                                 and HTML
                                 (via
                                 Texinfo)
                                 format.
                                 It is
                                 available
                                 at
                                 http://docbook2x.sourceforge.net/
                                 (http://docbook2x.sourceforge.net/).
DocBook-utilsOptional               This      DocBook-utils`docbook-utils'`docbook-utils'`docbook-utils'
                                 software   is
                                 package    required
                                 converts   to
                                 Docbook    produce
                                 documents  HTML and
                                 to the     Texinfo
                                 traditionalformats.
                                 man page
                                 format,
                                 GNU
                                 Texinfo
                                 format,
                                 and HTML
                                 (via
                                 Texinfo)
                                 format.
Texinfo    Possibly               Texinfo   Texinfo    `texinfo'  `texinfo'`texinfo'
           Required              can be     is
                                 used to    required
                                 convert    if you
                                 DocBook2X  wish to
                                 output     produce
                                 into GNU   GNU info
                                 info       pages.
                                 pages.
                                 You can
                                 download
                                 it from
                                 http://ftp.gnu.org/gnu/texinfo/
                                 (http://ftp.gnu.org/gnu/texinfo/).
FOP        Optional   0.20.5      FormattingFOP is     `fop'      `fop'`fop'
                                 Objects    required
                                 Processor  for PDF
                                 is a       output.
                                 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/
                                 (http://xmlgraphics.apache.org/fop/).
Java       Possibly               FOP       Sun's      Download   Download
(j2re)     Required              requires   Java       the        the
                                 Sun's      runtime    package    package
                                 Java       (j2re) is  from Sun   from Sun
                                 runtime    required   (http://java.sun.com).(http://java.sun.com).
                                 (GCJ does  to use
                                 not work   FOP.
                                 with
                                 FOP).
                                 You can
                                 download
                                 it from
                                 http://java.sun.com
                                 (http://java.sun.com).
JAI        Possibly               Sun's     JAI is     Download   Download
           Required              Java       required   the        the
                                 Advanced   if you     package    package
                                 Imaging    wish to    from Sun   from Sun
                                 API can    include    (http://java.sun.com/products/java-media/jai/iio.html).(http://java.sun.com/products/java-media/jai/iio.html).
                                 be         graphics
                                 downloaded in a PDF
                                 from       file being
                                 http://java.sun.com/products/java-media/jai/iio.htmlgenerated
                                 (http://java.sun.com/products/java-media/jai/iio.html).with FOP.

   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.

2.6 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
(http://www.gnu.org/software/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 (see Code Dependencies) for
autogen.

   All the standard `configure' options are available.  In addition,
Gnash has two types of options: those that enable or disable features
(see Features), and those that specify custom paths for development
packages (see Specifying Custom Paths) 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.

2.6.1 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.

*Configuration Options - Features*

Option                               Function
`--enable-debugger'                  Enable 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).?
                                     [undisplayable block object]
`--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.  ?
                                     [undisplayable block object] 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-write'                     Makes the Mozilla plugin write the
                                     currently playing SWF movie to
                                     `/tmp'.
`--disable-sa-launcher'              Drops 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.

2.6.2 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
(see Reporting Bugs) if a configure test fails.

   The following custom path options are available:

*Custom Path Options*

Option                               Function
`--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_.

2.7 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

2.8 Creating the Documentation
==============================

By default, documentation is not built when you install (see
Installation) Gnash.  This is because there are a number of
dependencies for the documentation (see Documentation Dependencies).
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 (see Features) `--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
(http://www.stack.nl/~dimitri/doxygen/index.html) 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

2.9 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 (see Reporting Bugs).

2.9.1 Using DejaGnu
-------------------

The easiest way to run Gnash's test suite is to install _DejaGnu
(http://www.gnu.org/software/dejagnu)_.  After installing DejaGnu, run:

     	  make check

2.9.1.1 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"

2.9.1.2 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

2.9.2 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

2.9.2.1 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

2.9.2.2 ActionScript Unit Tests
...............................

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

     	    gprocessor -v XML-v6.swf

2.9.3 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 (see Libraries), namely:
_libgnashbase_, _libgnashamf_, _libgnashmedia_, _libserver_, and
_libgnashplugin_.  Executables (see Executables) consist of the
(optional) plugin, `gprocessor', `cygnal',  `dumpshm', `soldumper', and
`gnash'.  Documentation (see Documentation) may also be installed.
The installation location is controlled with the _-prefix_ configure
option (see Specifying Custom Paths), 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 (see Specifying Custom Paths)
_-exec-prefix_ may be used to specify where platform-dependent
executables and libraries are installed.

2.9.3.1 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.

2.9.3.2 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 (see Specifying Custom Paths).

   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'.

2.9.3.3 Documentation
.....................

Documentation is not built by default; please refer to the section on
documentation (see Creating the 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 (see Specifying Custom Paths) 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.

2.9.4 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 (see Documentation 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 (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/
(http://frank.harvard.edu/~coldwell/toolchain/) and
http://www.kegel.com/crosstool/ (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
(http://www.access-company.com/products/linux/alp.html), Scratchbox
(http://www.scratchbox.org/), Open Embedded
(http://www.openembedded.org/), Maemo (http://maemo.org/).

   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

3 Software Internals
********************

3.1 A Tour of Gnash
===================

The top level of Gnash has several libraries, _libgnashbase_,
_libgnashcore_, _libgnashmedia_, _libgnashamf_ and _libgnashrender_.
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.

3.1.1 The Libraries
-------------------

3.1.1.1 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.

3.1.1.2 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.

3.1.1.3 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.

3.1.1.4 libgnashsound
.....................

This library handles sound output and manages sound objects.

3.1.1.5 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.

3.1.1.6 libgnashbackend
.......................

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

3.1.1.7 libgnashplugin
......................

Libgnashplugin is the Mozilla/Firefox plugin.

3.1.1.8 libklashpart
....................

Libklashpart is the Konqueror plugin.

3.1.2 The Applications
----------------------

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

3.1.2.1 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.

3.1.2.2 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.

3.1.2.3 SOLdumper
.................

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

3.1.2.4 Dumpshm
...............

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

3.1.3 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.

3.1.3.1 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.

3.1.3.2 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.

3.1.3.3 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.

3.1.4 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.

3.1.4.1 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.

3.1.4.2 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.

3.2 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.

3.2.1 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.

3.2.2 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.

3.2.3 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.

3.2.4 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...

3.2.5 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.

3.2.6 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.

3.3 Testing
===========

Instructions on running tests (see Running the Tests) can be found
in the section on building Gnash.

3.3.1 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 (http://ming.sf.net).
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
(http://www.gnu.org/software/dejagnu) is used to run multiple test
cases in an automated manner. _DejaGnu_ is used by many other GNU
(http://www.gnu.org) projects like GCC (http://gcc.gnu.org) and Samba
(http://www.samba.org).

3.3.2 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.

3.3.3 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

3.3.4 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 (see Using Ming-based test generators facilities)
provided by the Gnash testing framework to easily run tests.

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

3.3.4.1 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 (see
Using Ming-based test generators 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 (see Writing Test Runners) for
information about writing SWF test runners.

3.3.5 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 (see Writing Test Runners) for
information about writing a test runners for your self-contained tests.

3.3.6 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.

3.3.6.1 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.

3.3.6.2 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.

3.4 Adding New ActionScript Classes
===================================

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.

3.4.1 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.

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

3.4.3
-----

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.

4 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.

4.1 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
(http://www.getgnash.org/packages/).

4.2 Determine if the bug was previously reported
================================================

Search the Gnash bug tracker
(https://savannah.gnu.org/bugs/?group=gnash) 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.

4.3 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.

4.4 Filing a bug report
=======================

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

5 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.

5.1 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.

5.1.1 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 = createObject(gl);

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

5.2 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

5.3 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.

5.3.1 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.

5.3.2 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.

5.3.3 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.

6 RTMP Protocol
***************

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
(http://www.osflash.org/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.

Image of the RTMP protocol.

   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.

6.1 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.

7 Mozilla/Firefox NPAPI Plugin
******************************

The Mozilla SDK has two API layers for plugins. The older layer is
documented in the Geeko Plugin API Reference
(http://www.gnu.org/software/gnash/manual/plugin.pdf), 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.

7.1 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.

7.2 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

7.3 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.

7.4 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_

8 Appendix
**********

8.1 Code Style
==============

I know any discussion of coding styles leads to strong opinions, so
I'll state simply I follow the GNU Coding Standards
(http://www.gnu.org/prep/standards/standards.html). 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 (http://www.doxygen.org) 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.

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 <gnash-dev@gnu.org>. Past and sometimes current
developers are Tomas Groth and Markus Gothe.

   Gnash was initially derived from GameSWF.  GameSWF is maintained by
Thatcher Ulrich <tu@tulrich.com>.  The following people contributed to
GameSWF: Mike Shaver, Thierry Berger-Perrin, Ignacio Castan~o, Willem
Kokke, Vitaly Alexeev, Alexander Streit, and Rob Savoye.

Appendix A GNU Free Documentation License
*****************************************

A.1 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.

A.2 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 (see fdl-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 (see
fdl-secondary) whose titles are designated, as being those of
Invariant Sections, in the notice that says that the Document (see
fdl-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 (see fdl-document) is released under this
License.

   A "Transparent" copy of the  Document (see fdl-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.

A.3 2. VERBATIM COPYING
=======================

You may copy and distribute the Document (see fdl-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 (see 3_ COPYING IN QUANTITY).

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

A.4 3. COPYING IN QUANTITY
==========================

If you publish printed copies of the Document (see fdl-document)
numbering more than 100, and the Document's license notice requires
Cover Texts (see fdl-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
(see fdl-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 (see fdl-transparent) copies
of the Document (see fdl-document) numbering more than 100, you
must either include a machine-readable Transparent (see
fdl-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 (see fdl-document) well before redistributing any
large number of copies, to give them a chance to provide you with an
updated version of the Document.

A.5 4. MODIFICATIONS
====================

You may copy and distribute a Modified Version (see fdl-modified)
of the Document (see fdl-document) under the conditions of sections
2 (see 2_ VERBATIM COPYING) and 3 (see 3_ COPYING IN QUANTITY)
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 (see fdl-title-page) (and on the
     covers, if any) a title distinct from that of the Document (see
     fdl-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 (see fdl-title-page), as authors,
     one or more persons or entities responsible for authorship of the
     modifications in the Modified Version (see fdl-modified),
     together with at least five of the principal authors of the
     Document (see fdl-document) (all of its principal authors, if
     it has less than five).

   * *C. * State on the Title Page (see fdl-title-page) the name of
     the publisher of the Modified Version (see fdl-modified), as
     the publisher.

   * *D. * Preserve all the copyright notices of the Document (see
     fdl-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
     (see fdl-modified) 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 (see fdl-invariant) and required Cover Texts (see
     fdl-cover-texts) given in the Document's (see fdl-document)
     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  (see fdl-modified)as
     given on the Title Page (see fdl-title-page).  If there is no
     section entitled "History" in the Document (see fdl-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
     (see fdl-document) for public access to a Transparent (see
     fdl-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 (see fdl-invariant)
     of the Document (see fdl-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 (see fdl-modified).

   * *N. * Do not retitle any existing section as "Endorsements" or to
     conflict in title with any Invariant Section (see
     fdl-invariant).

   If the Modified Version (see fdl-modified) includes new
front-matter sections or appendices that qualify as Secondary Sections
(see fdl-secondary) 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 (see fdl-invariant) 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 (see
fdl-modified) 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
(see fdl-cover-texts), and a passage of up to 25 words as a
Back-Cover Text (see fdl-cover-texts), to the end of the list of
Cover Texts (see fdl-cover-texts) in the Modified Version (see
fdl-modified).  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 (see fdl-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 (see
fdl-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  (see fdl-modified).

A.6 5. COMBINING DOCUMENTS
==========================

You may combine the Document (see fdl-document) with other
documents released under this License, under the terms defined in
section 4 (see 4_ MODIFICATIONS) above for modified versions,
provided that you include in the combination all of the Invariant
Sections (see fdl-invariant) 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 (see fdl-invariant) 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."

A.7 6. COLLECTIONS OF DOCUMENTS
===============================

You may make a collection consisting of the Document (see
fdl-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.

A.8 7. AGGREGATION WITH INDEPENDENT WORKS
=========================================

A compilation of the Document (see fdl-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 (see fdl-modified) 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 (see
fdl-cover-texts) requirement of section 3 (see 3_ COPYING IN QUANTITY)
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.

A.9 8. TRANSLATION
==================

Translation is considered a kind of modification, so you may distribute
translations of the Document (see fdl-document) under the terms of
section 4 (see 4_ MODIFICATIONS). Replacing  Invariant Sections
(see fdl-invariant) 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.

A.10 9. TERMINATION
===================

You may not copy, modify, sublicense, or distribute the Document (see
fdl-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.

A.11 10. FUTURE REVISIONS OF THIS LICENSE
=========================================

The Free Software Foundation (http://www.gnu.org/fsf/fsf.html) 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/
(http://www.gnu.org/copyleft).

   Each version of the License is given a distinguishing version
number. If the Document (see fdl-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.

A.12 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 (see fdl-invariant),
     with no Front-Cover Texts (see fdl-cover-texts), and with no
     Back-Cover Texts (see fdl-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
(http://www.gnu.org/copyleft/gpl.html), to permit their use in free
software.