<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Gnash Reference Manual</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><meta name="description" content="Gnash Documentation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="Gnash Reference Manual"><div class="titlepage"><div><div><h1 class="title"><a name="index"></a>Gnash Reference Manual</h1></div><div><p class="releaseinfo">
      This manual describes version 0.8.9 of Gnash.
    </p></div><div><p class="copyright">Copyright © 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation</p></div><div><div class="legalnotice" title="Legal Notice"><a name="legalnotice"></a><p>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the <a class="link" href="#fdl" title="Appendix A. GNU Free Documentation License"><em class="citetitle">GNU
    Free Documentation License</em></a>, Version 1.1 or any later
    version published by the Free Software Foundation with no Invariant
    Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find
    a copy of the GFDL at this 
    <a class="link" href="#fdl" title="Appendix A. GNU Free Documentation License">link</a> or in the file COPYING-DOCS
    distributed with this manual.
   </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision Gnash User Manual version 0.4</td><td align="left">Jan 2010</td></tr><tr><td align="left" colspan="2"> 
      <p class="author">Rob Savoye
      <code class="email">&lt;<a class="email" href="mailto:rob@openmedianow.org">rob@openmedianow.org</a>&gt;</code>
      The end user parts of the manual have been pulled out of
      the original version of the manual, and rewritten. This
      is now a reference manual only.
      </p>
      
      <p class="publisher">Open Media Now! Foundation</p>
    </td></tr></table></div></div><div><div class="abstract" title="Abstract"><p class="title"><b>Abstract</b></p><p>Gnash Documentation</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#intro">1. Introduction</a></span></dt><dd><dl><dt><span class="sect1"><a href="#audience">Audience</a></span></dt><dt><span class="sect1"><a href="#runs-on">What Is Supported?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#build">2. Building from Source</a></span></dt><dd><dl><dt><span class="sect1"><a href="#building_overview">Overview</a></span></dt><dt><span class="sect1"><a href="#gettingsource">Getting The Source</a></span></dt><dd><dl><dt><span class="sect2"><a href="#sourcereleases">Releases</a></span></dt><dt><span class="sect2"><a href="#sourcecvs">Git Access</a></span></dt></dl></dd><dt><span class="sect1"><a href="#dependencies">Code Dependencies</a></span></dt><dt><span class="sect1"><a href="#testdep">Testing Dependencies</a></span></dt><dt><span class="sect1"><a href="#docdepend">Documentation Dependencies</a></span></dt><dt><span class="sect1"><a href="#configure">Configuring Gnash</a></span></dt><dt><span class="sect1"><a href="#compile">Compiling the Code</a></span></dt><dt><span class="sect1"><a href="#processdoc">Creating the Documentation</a></span></dt><dt><span class="sect1"><a href="#runtests">Running the Tests</a></span></dt><dd><dl><dt><span class="sect2"><a href="#dejagnu">Using DejaGnu</a></span></dt><dt><span class="sect2"><a href="#manually">Running The Tests Manually</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#internals">3. Software Internals</a></span></dt><dd><dl><dt><span class="sect1"><a href="#tour">A Tour of <span class="application">Gnash</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="#The%20Libraries">The Libraries</a></span></dt><dt><span class="sect2"><a href="#apps">The Applications</a></span></dt><dt><span class="sect2"><a href="#plugin">The Plugin</a></span></dt><dt><span class="sect2"><a href="#logging">The Message Logging System</a></span></dt></dl></dd><dt><span class="sect1"><a href="#soundhandlers">Sound handling in <span class="application">Gnash</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="#soundtypes">Sound types</a></span></dt><dt><span class="sect2"><a href="#soundparsing">Sound parsing</a></span></dt><dt><span class="sect2"><a href="#soundplayback">Sound playback</a></span></dt><dt><span class="sect2"><a href="#sdlsound">The SDL sound backend</a></span></dt><dt><span class="sect2"><a href="#gstreamer">The Gstreamer backend</a></span></dt><dt><span class="sect2"><a href="#gstreamer-details">Detailed description of the Gstreamer backend</a></span></dt></dl></dd><dt><span class="sect1"><a href="#testing">Testing </a></span></dt><dd><dl><dt><span class="sect2"><a href="#testtools">Testing Tools</a></span></dt><dt><span class="sect2"><a href="#testcases">Test Cases</a></span></dt><dt><span class="sect2"><a href="#writeastests">Writing ActionScript Tests</a></span></dt><dt><span class="sect2"><a href="#writemingtests">Writing Ming-based self-contained SWF tests</a></span></dt><dt><span class="sect2"><a href="#writing_dejagnu_so_tests">Writing self-contained SWF tests with other compilers</a></span></dt><dt><span class="sect2"><a href="#writing_test_runners">Writing Test Runners</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#bugreport">5. Reporting Bugs</a></span></dt><dd><dl><dt><span class="sect1"><a href="#bugstep_package">Get a Fresh Binary Package</a></span></dt><dt><span class="sect1"><a href="#bugstep_search">Determine if the bug was previously reported</a></span></dt><dt><span class="sect1"><a href="#bugstep_guidelines">Review the bug writing guidelines</a></span></dt><dt><span class="sect1"><a href="#bugstep_file">Filing a bug report</a></span></dt></dl></dd><dt><span class="chapter"><a href="#extensions">6. <span class="application">Gnash</span> Extensions</a></span></dt><dd><dl><dt><span class="sect1"><a href="#newext">Creating A New Extension</a></span></dt><dt><span class="sect1"><a href="#debuext">Debugging An Extension</a></span></dt><dt><span class="sect1"><a href="#inclext">Included Extensions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#rtmp">7. RTMP Protocol</a></span></dt><dd><dl><dt><span class="sect1"><a href="#amf">AMF Format</a></span></dt></dl></dd><dt><span class="chapter"><a href="#nsapi">8. Mozilla/Firefox NPAPI Plugin</a></span></dt><dd><dl><dt><span class="sect1"><a href="#plugincapi">Plugin C API</a></span></dt><dt><span class="sect1"><a href="#plugincppapi">Plugin C++ API</a></span></dt><dt><span class="sect1"><a href="#glthread">OpenGL and Threads</a></span></dt><dt><span class="sect1"><a href="#eventhandle">Plugin Event Handling</a></span></dt></dl></dd><dt><span class="chapter"><a href="#authors">9. Authors</a></span></dt><dt><span class="appendix"><a href="#fdl">A. GNU Free Documentation License</a></span></dt><dd><dl><dt><span class="sect1"><a href="#fdl-preamble">0. PREAMBLE</a></span></dt><dt><span class="sect1"><a href="#fdl-section1">1. APPLICABILITY AND DEFINITIONS</a></span></dt><dt><span class="sect1"><a href="#fdl-section2">2. VERBATIM COPYING</a></span></dt><dt><span class="sect1"><a href="#fdl-section3">3. COPYING IN QUANTITY</a></span></dt><dt><span class="sect1"><a href="#fdl-section4">4. MODIFICATIONS</a></span></dt><dt><span class="sect1"><a href="#fdl-section5">5. COMBINING DOCUMENTS</a></span></dt><dt><span class="sect1"><a href="#fdl-section6">6. COLLECTIONS OF DOCUMENTS</a></span></dt><dt><span class="sect1"><a href="#fdl-section7">7. AGGREGATION WITH INDEPENDENT WORKS</a></span></dt><dt><span class="sect1"><a href="#fdl-section8">8. TRANSLATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section9">9. TERMINATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section10">10. FUTURE REVISIONS OF THIS LICENSE</a></span></dt><dt><span class="sect1"><a href="#fdl-using">Addendum</a></span></dt></dl></dd></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="#codedeps">Code Dependency Table</a></dt><dt>2.2. <a href="#testdeps">Testing Dependency Table</a></dt><dt>2.3. <a href="#docdeps">Documentation Dependency Table</a></dt><dt>2.4. <a href="#tb-config-features">Configuration Options - Features</a></dt><dt>2.5. <a href="#tb-configure-paths">Custom Path Options</a></dt></dl></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#audience">Audience</a></span></dt><dt><span class="sect1"><a href="#runs-on">What Is Supported?</a></span></dt></dl></div><p>
    <span class="application">Gnash</span> 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.
  </p><p>
    <span class="application">Gnash</span> 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.
  </p><div class="sect1" title="Audience"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="audience"></a>Audience</h2></div></div></div><p>
      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.
    </p></div><div class="sect1" title="What Is Supported?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="runs-on"></a>What Is Supported?</h2></div></div></div><p>
      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.
    </p><p>
      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.
    </p><p>
      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.
    </p><p>
      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.
    </p><p>
      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: <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/" target="_top">
      http://www.gnashdev.org/dev_snapshots</a>.
    </p><p>
      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.
    </p></div></div><div class="chapter" title="Chapter 2. Building from Source"><div class="titlepage"><div><div><h2 class="title"><a name="build"></a>Chapter 2. Building from Source</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#building_overview">Overview</a></span></dt><dt><span class="sect1"><a href="#gettingsource">Getting The Source</a></span></dt><dd><dl><dt><span class="sect2"><a href="#sourcereleases">Releases</a></span></dt><dt><span class="sect2"><a href="#sourcecvs">Git Access</a></span></dt></dl></dd><dt><span class="sect1"><a href="#dependencies">Code Dependencies</a></span></dt><dt><span class="sect1"><a href="#testdep">Testing Dependencies</a></span></dt><dt><span class="sect1"><a href="#docdepend">Documentation Dependencies</a></span></dt><dt><span class="sect1"><a href="#configure">Configuring Gnash</a></span></dt><dt><span class="sect1"><a href="#compile">Compiling the Code</a></span></dt><dt><span class="sect1"><a href="#processdoc">Creating the Documentation</a></span></dt><dt><span class="sect1"><a href="#runtests">Running the Tests</a></span></dt><dd><dl><dt><span class="sect2"><a href="#dejagnu">Using DejaGnu</a></span></dt><dt><span class="sect2"><a href="#manually">Running The Tests Manually</a></span></dt></dl></dd></dl></div><div class="sect1" title="Overview"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="building_overview"></a>Overview</h2></div></div></div><p>
      The typical process of building from source will involve 
      <a class="link" href="#gettingsource" title="Getting The Source">getting the source</a>,
      <a class="link" href="#dependencies" title="Code Dependencies">build dependencies</a>,
      <a class="link" href="#configure" title="Configuring Gnash">configuration</a>, 
      <a class="link" href="#compile" title="Compiling the Code">compilation</a>,
      <a class="link" href="#runtests" title="Running the Tests">testing</a>, and
      <a class="link" href="#install" title="Installation">installation</a>.
      A simplified overview of the process would be:
      </p><pre class="programlisting">
        ./autogen.sh
        ./configure 
        make
        make check
        make install
      </pre><p>
    </p><p>
      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.
    </p><p>
      At present the <span class="application">Gnash</span> source is about 30 MB extracted and configured
      and requires a total of about 125 megabytes to compile it.
    </p><p>
      Continue reading for detailed step-by-step instructions 
      of the entire procedure.
    </p></div><div class="sect1" title="Getting The Source"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="gettingsource"></a>Getting The Source</h2></div></div></div><div class="sect2" title="Releases"><div class="titlepage"><div><div><h3 class="title"><a name="sourcereleases"></a>Releases</h3></div></div></div><p>
	Tarballs of official releases can be found in the download area
	of the project's GNU Savannah page at
	<a class="ulink" href="http://savannah.gnu.org/projects/gnash" target="_top">
		    http://savannah.gnu.org/projects/gnash
	</a> 
	or under
	<a class="ulink" href="http://ftp.gnu.org/gnu/gnash" target="_top">
		    http://ftp.gnu.org/gnu/gnash
	</a> 
      </p></div><div class="sect2" title="Git Access"><div class="titlepage"><div><div><h3 class="title"><a name="sourcecvs"></a>Git Access</h3></div></div></div><p>
	The latest <span class="application">Gnash</span> development sources are available via git.
	Use the following commands to check them out:
	</p><pre class="programlisting">
	mkdir gnash
	cd gnash
	git clone git://git.sv.gnu.org/gnash.git
	</pre><p>
	At any time, other temporary development branches may also
	be available. Replace <span class="emphasis"><em>trunk</em></span> with the
	branch name to check these out.
	You can update your copy from the main 
	repository using:
	</p><pre class="programlisting">
	  cd trunk
	  git pull
	</pre><p>
      </p><p>
	If you only have access to the internet via a web proxy,
	you will find daily source snapshots of the latest CVS tree in
	<a class="ulink" href="http://www.gnashdev.org/dev_snapshots/" target="_top">
		    http://www.gnashdev.org/dev_snapshots
	</a> 
      </p></div></div><div class="sect1" title="Code Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dependencies"></a>Code Dependencies</h2></div></div></div><p>
    <span class="application">Gnash</span> 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 <span class="application">Gnash</span> needs to compile.
  </p><p>
    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.
  </p><div class="table"><a name="codedeps"></a><p class="title"><b>Table 2.1. Code Dependency Table</b></p><div class="table-contents"><table summary="Code Dependency Table" border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th align="left">Name</th><th align="left">Level</th><th align="left">Version</th><th align="left">Description</th><th align="left">Explanation</th><th align="left">apt-get package</th><th align="left">RPM/Yum package</th><th align="left">BSD package</th></tr></thead><tbody><tr><td align="left">Boost</td><td align="left">Required</td><td align="left">1.32 or higher</td><td align="left">
	    Boost is a library of portable C++ classes and
	    templates.
	  </td><td align="left">
	    In <span class="application">Gnash</span>, Boost libraries are used extensively, primarily
	    boost-gthread and boost-date-time. Boost is used for thread and mutext 
	    handling. 
	  </td><td align="left">
	    <code class="filename">libboost-thread-dev, libboost-date-time-dev libboost-dev
	    </code>
	  </td><td align="left">
	    <code class="filename">
	      libboost-thread-devel, libboost-date-time-devel
	  </code>
	  </td><td align="left">
	    <code class="filename">
	      boost-headers, boost-libs, or just boost
	  </code></td></tr><tr><td align="left">AGG</td><td align="left">Possibly Required</td><td align="left">2.4 or higher</td><td align="left">
	    AGG is the AntiGrain low-level 2D graphics
	    library.  
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    renderer.  AGG is considered the <span class="emphasis"><em>best
	    supported</em></span> renderer for <span class="application">Gnash</span>.
	  </td><td align="left"><code class="filename">libagg-dev</code></td><td align="left"><code class="filename">agg-devel</code></td><td align="left"><code class="filename">agg</code></td></tr><tr><td align="left">OpenGL</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    OpenGL is a standard specification defining a
	    cross-language cross-platform API for writing
	    applications which produce 3D and 2D graphics.
	    It supports hardware acceleration.
	    You can download a free implementation from
	    <a class="ulink" href="http://www.mesa3d.org" target="_top">http://www.mesa3d.org</a>,
	    although it doesn't support hardware acceleration.
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    renderer. If you don't have a hardware accelerated driver,
	    you're better off using AGG for the renderer.
	  </td><td align="left"><code class="filename">libgl1-mesa-dev</code></td><td align="left"><code class="filename">libmesa-devel</code></td><td align="left"><code class="filename">mesa</code></td></tr><tr><td align="left">Cairo</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    Cairo is a 2D graphics library with support for
	    multiple output devices.  It will automatically use
	    graphic card acceleration when available, and has
	    an experimental OpenGL backend.  
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    renderer.  Cairo is considered
	    the <span class="emphasis"><em>least supported</em></span> renderer
	    for <span class="application">Gnash</span>.
	  </td><td align="left"><code class="filename">libcairo2-dev</code></td><td align="left"><code class="filename">cairo-devel</code></td><td align="left"><code class="filename">cairo</code></td></tr><tr><td align="left">GTK</td><td align="left">Possibly Required</td><td align="left">2.2 or higher</td><td align="left">
	    GTK is the GIMP Toolkit GUI library used by the GNOME
	    desktop. It uses Cairo internally. Gtk enables better
	    integration with Firefox, as well as better event handling
	    and higher level GUI constructs like menus and dialog
	    boxes.
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    GUI library.  GTK is considered to be the
	    <span class="emphasis"><em>best supported</em></span> GUI library
	    option for <span class="application">Gnash</span>.
	  </td><td align="left"><code class="filename">libgtk2.0-dev</code></td><td align="left"><code class="filename">gtk-devel</code></td><td align="left"><code class="filename">gtk+2</code></td></tr><tr><td align="left">GtkGlExt</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    GtkGlExt integrates OpenGL into GTK.
	  </td><td align="left">
	    This library is required in order to use
	    the GTK GUI library in conjunction with the
	    OpenGL renderer.
	  </td><td align="left"><code class="filename">libgtkglext1-dev</code></td><td align="left"><code class="filename">gtkglext-devel</code></td><td align="left"><code class="filename">gtkglext</code></td></tr><tr><td align="left">SDL</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    The Simple DirectMedia Layer is a cross-platform
	    multimedia library which provides abstraction for
	    audio, graphics, sound and input APIs.  
	    SDL is available from
	    <a class="ulink" href="http://www.libsdl.org" target="_top">
	      http://www.libsdl.org</a>.  
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    GUI library.  SDL may also be used as a sound
	    handler regardless of whether it is employed as
	    a GUI library.  The GUI
	    library is <span class="emphasis"><em>poorly supported</em></span>
	    in <span class="application">Gnash</span>, but the sound handler is the
	    <span class="emphasis"><em>best supported</em></span> in <span class="application">Gnash</span>.
	  </td><td align="left"><code class="filename">libsdl1.2-dev</code></td><td align="left"><code class="filename">SDL-devel</code></td><td align="left"><code class="filename">SDL-1.2</code></td></tr><tr><td align="left">FLTK</td><td align="left">Possibly Required</td><td align="left">2.0 or higher</td><td align="left">
	    The Fast Light ToolKit is a portable GUI library
	    which is intended as a replacement for the SDL GUI.
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    GUI library.  FLTK may be used in conjunction with
	    the Cairo and AGG renderers.
	  </td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td></tr><tr><td align="left">KDE</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    Kdelibs is a collection of libraries needed to
	    compile KDE applications.
	  </td><td align="left">
	    <span class="application">Gnash</span> requires the installation of at least one
	    GUI library.  Kdelibs is also required for the
	    Kpart plugin for Konqueror.
	  </td><td align="left"><code class="filename">kdelibs3-dev, kdebase-dev</code></td><td align="left"><code class="filename">kdelibs-devel, kdebase-devel</code></td><td align="left"><code class="filename">kdelibs, kdebase</code></td></tr><tr><td align="left">Gstreamer</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    Gstreamer is a video handler.
	  </td><td align="left">
	    If you would like video playback, you must
	    install one of the video handlers.
	  </td><td align="left"><code class="filename">libgstreamer0.8-dev</code></td><td align="left"><code class="filename">gstreamer-devel</code></td><td align="left"><code class="filename">gstreamer-0.10</code></td></tr><tr><td align="left">gst-ffmpeg</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    gst-ffmpeg allows you to use the FFmpeg decoder
	    with Gstreamer.
	  </td><td align="left">
	    This package is required if you would like to
	    use Gstreamer as a video handler.
	  </td><td align="left"><code class="filename">gstreamer0.8-ffmpeg-dev</code></td><td align="left"><code class="filename">gstreamer-ffmpeg-devel</code></td><td align="left"><code class="filename">gstreamer-ffmpeg</code></td></tr><tr><td align="left">FFmpeg</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    FFmpeg is a video handler.
	  </td><td align="left">
	    If you would like video playback, you must
	    install one of the video handlers. When using the
	    gstreamer-ffmpeg plugin, ffmpeg doesn't need to be
	    installed, as it's part of the plugin. For systems
	    without Gstreamer support, FFmpeg can be used directly.
	  </td><td align="left"><code class="filename">ffmpeg-dev</code></td><td align="left"><code class="filename">ffmpeg-devel</code></td><td align="left"><code class="filename">ffmpeg</code></td></tr><tr><td align="left">JPEG</td><td align="left">Required</td><td align="left"> </td><td align="left">
	    <a class="ulink" href="http://www.ijg.org/" target="_top">JPEG</a>
	    is a lossy image format which is heavily used for images.
	  </td><td align="left">
		  This library is used for reading external JPEGs and JPEG
		  data embedded in SWF files.
	  </td><td align="left"><code class="filename">libjpeg62-dev</code></td><td align="left"><code class="filename">libjpeg</code></td><td align="left"><code class="filename">jpeg</code></td></tr><tr><td align="left">PNG</td><td align="left">Required</td><td align="left"> </td><td align="left">
	    <a class="ulink" href="http://www.libpng.org/pub/png/" target="_top">PNG</a> is
	    a patent-free image format which is comparable to
	    <span class="emphasis"><em>GIF</em></span>.
	  </td><td align="left">
		  This library is used for loading external PNG
		  images (part of the SWF8 specification) and for writing
		  images in the PNG format.
	  </td><td align="left"><code class="filename">libpng12-dev</code></td><td align="left"><code class="filename">libpng</code></td><td align="left"><code class="filename">png</code></td></tr><tr><td align="left">GIF</td><td align="left">Required</td><td align="left"> </td><td align="left">GIF is a common image format that should now
		      be free of patent restrictions.
               <span class="emphasis"><em>GIF</em></span>.
                </td><td align="left">
                This library is used for loading external GIF
                images (part of the SWF8 specification).
	        </td><td align="left"><code class="filename">libungif-dev</code></td><td align="left"><code class="filename">libungif-devel</code></td><td align="left"><code class="filename">gif</code></td></tr><tr><td align="left">libcurl</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    libcurl is the multiprotocal file transfer library.
	  </td><td align="left">
	    This library is used for URL downloading.
	  </td><td align="left"><code class="filename">libcurl4-gnutls</code></td><td align="left"><code class="filename">libcurl</code></td><td align="left"><code class="filename">curl</code></td></tr><tr><td align="left">Glib2</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    Glib2 is a dependency of Gtk, and is a collection of
	    commonly used functions.
	  </td><td align="left">
	    This library is used for convenience.
	  </td><td align="left"><code class="filename">glib2-dev</code></td><td align="left"><code class="filename">glib2-devel</code></td><td align="left"><code class="filename">glib2</code></td></tr><tr><td align="left">Atk</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    Atk is a dependency of Gtk, and is used for accessibility
	    support.
	  </td><td align="left">
	    This library is used for accessiblity..
	  </td><td align="left"><code class="filename">atk-dev</code></td><td align="left"><code class="filename">atk-devel</code></td><td align="left"><code class="filename">atk</code></td></tr><tr><td align="left">Pango</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    Pango is a dependency of Gtk, and is used for font handling.
	  </td><td align="left">
	    This library is used for font handling.
	  </td><td align="left"><code class="filename">pango-dev</code></td><td align="left"><code class="filename">pango-devel</code></td><td align="left"><code class="filename">pango</code></td></tr><tr><td align="left">automake</td><td align="left">Possibly Required</td><td align="left">1.6.0</td><td align="left">
	    Automake is a tool for generating
	    <span class="emphasis"><em>Makefile.in</em></span> files.
	  </td><td align="left">
	    This package is required to run
	    <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
	    if you are using the development source from CVS.
	  </td><td align="left"><code class="filename">automake</code></td><td align="left"><code class="filename">automake</code></td><td align="left"><code class="filename">automake</code></td></tr><tr><td align="left">autoconf</td><td align="left">Possibly Required</td><td align="left">2.59</td><td align="left">
	    Autoconf is a package for generating configure
	    scripts.
	  </td><td align="left">
	    This package is required to run
	    <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
	    if you are using the development source from CVS.
	  </td><td align="left"><code class="filename">autoconf</code></td><td align="left"><code class="filename">autoconf</code></td><td align="left"><code class="filename">autoconf</code></td></tr><tr><td align="left">gettext</td><td align="left">Possibly Required</td><td align="left">0.14.6</td><td align="left">
	    Gettext is part of the GNU Translation Project.
	  </td><td align="left">
	    This package is required to run
	    <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
	    if you are using the development source from CVS.
	  </td><td align="left"><code class="filename">gettext</code></td><td align="left"><code class="filename">gettext</code></td><td align="left"><code class="filename">gettext</code></td></tr><tr><td align="left">libtool</td><td align="left">Possibly Required</td><td align="left">1.5.22</td><td align="left">
	    This is a generic library support script.
	  </td><td align="left">
	    This package is required to run
	    <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
	    if you are using the development source from CVS.
	  </td><td align="left"><code class="filename">libltdl3-dev</code></td><td align="left"><code class="filename">libtool</code></td><td align="left"><code class="filename">libtool</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect1" title="Testing Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="testdep"></a>Testing Dependencies</h2></div></div></div><p>
    <span class="application">Gnash</span> tries to run as many tests as possible, but will
    silentl skip tests if the tools to run them are unavailable.
  </p><div class="table"><a name="testdeps"></a><p class="title"><b>Table 2.2. Testing Dependency Table</b></p><div class="table-contents"><table summary="Testing Dependency Table" border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th align="left">Name</th><th align="left">Level</th><th align="left">Version</th><th align="left">Description</th><th align="left">Explanation</th><th align="left">apt-get package</th><th align="left">RPM/Yum package</th><th align="left">BSD package</th></tr></thead><tbody><tr><td align="left">Ming</td><td align="left">Optional</td><td align="left">0.4.0_beta4 or higher</td><td align="left">
	    Ming is an ActionScript compiler.
	  </td><td align="left">
	    Ming is the primary compiler for ActionScript testcases.
	  </td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td></tr><tr><td align="left">Mtasc</td><td align="left">Optional</td><td align="left">1.12 or higher</td><td align="left">
	    Mtasc is an ActionScript compiler.
	  </td><td align="left">
	    Mtasc is used in some tests.
	  </td><td align="left"><code class="filename">mtasc</code></td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td></tr><tr><td align="left">swfc</td><td align="left">Optional</td><td align="left">part of swftools 0.8.1</td><td align="left">
	    Swfc is an swf compiler.
	  </td><td align="left">
	    Swfc is used in some testcases.
	  </td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td></tr><tr><td align="left">swfmill</td><td align="left">Optional</td><td align="left"> 0.2.12</td><td align="left">
	    Swfmill is an XML-based SWF (Shockwave Flash) processing tool.
	  </td><td align="left">
	    Swfmill is used in some testcases.
	  </td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td><td align="left">No distribution packages are available.</td></tr><tr><td align="left">Python</td><td align="left">Optional</td><td align="left">2.4 or higher</td><td align="left">
	    Python is a scripting language.
	  </td><td align="left">
	    Python is used by part of the testing framework.
	  </td><td align="left"><code class="filename">python</code></td><td align="left"><code class="filename">python</code></td><td align="left"><code class="filename">python</code></td></tr><tr><td align="left">DejaGnu</td><td align="left">Optional</td><td align="left">1.4 or higher</td><td align="left">
	    DejaGnu is a testing framework.
	  </td><td align="left">
	    DejaGnu is used to run multiple tests in an
	    automated fashion.
	  </td><td align="left"><code class="filename">dejagnu</code></td><td align="left"><code class="filename">dejagnu</code></td><td align="left"><code class="filename">dejagnu</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect1" title="Documentation Dependencies"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="docdepend"></a>Documentation Dependencies</h2></div></div></div><p>
    The following packages are used to build <span class="application">Gnash</span>'s documentation.
  </p><div class="table"><a name="docdeps"></a><p class="title"><b>Table 2.3. Documentation Dependency Table</b></p><div class="table-contents"><table summary="Documentation Dependency Table" border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th align="left">Name</th><th align="left">Level</th><th align="left">Version</th><th align="left">Description</th><th align="left">Explanation</th><th align="left">apt-get package</th><th align="left">RPM/Yum package</th><th align="left">BSD package</th></tr></thead><tbody><tr><td align="left">Docbook</td><td align="left">Required</td><td align="left"> </td><td align="left">
	    <a class="ulink" href="http://http://docbook.sourceforge.net/" target="_top">Docbook</a> is
	    is an industry-standard XML format for technical
	    documentation.  You can download it from
	    <a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=21935#files" target="_top">http://sourceforge.net/project/showfiles.php?group_id=21935#files</a>.
	  </td><td align="left">
	    <span class="application">Gnash</span> documentation is written in Docbook.
	  </td><td align="left">
	    <code class="filename">docbook-utils</code> and <code class="filename">docbook-dsssl</code>
	  </td><td align="left">
	    <code class="filename">docbook-dtd41-sgml</code> and <code class="filename">docbook-style-dsssl</code>
	  </td><td align="left">docbook</td></tr><tr><td align="left">DocBook2X</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    This software package converts Docbook documents to
	    the traditional man page format, GNU Texinfo
	    format, and HTML (via Texinfo) format.  
	    It is available at <a class="ulink" href="http://docbook2x.sourceforge.net/" target="_top">http://docbook2x.sourceforge.net/</a>.
	  </td><td align="left">
	    DocBook2X is required to produce HTML and Texinfo
	    formats.
	  </td><td align="left"><code class="filename">docbook2x</code></td><td align="left"><code class="filename">docbook2x</code></td><td align="left"><code class="filename">docbook2x</code></td></tr><tr><td align="left">DocBook-utils</td><td align="left">Optional</td><td align="left"> </td><td align="left">
	    This software package converts Docbook documents to
	    the traditional man page format, GNU Texinfo
	    format, and HTML (via Texinfo) format.  
	  </td><td align="left">
	    DocBook-utils is required to produce HTML and Texinfo
	    formats.
	  </td><td align="left"><code class="filename">docbook-utils</code></td><td align="left"><code class="filename">docbook-utils</code></td><td align="left"><code class="filename">docbook-utils</code></td></tr><tr><td align="left">Texinfo</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    Texinfo can be used to convert DocBook2X output
	    into GNU info pages.  You can download it from
	    <a class="ulink" href="http://ftp.gnu.org/gnu/texinfo/" target="_top">http://ftp.gnu.org/gnu/texinfo/</a>.
	  </td><td align="left">
	    Texinfo is required if you wish to produce GNU info
	    pages.
	  </td><td align="left"><code class="filename">texinfo</code></td><td align="left"><code class="filename">texinfo</code></td><td align="left"><code class="filename">texinfo</code></td></tr><tr><td align="left">FOP</td><td align="left">Optional</td><td align="left">0.20.5</td><td align="left">
	    Formatting Objects Processor is a print formatter
	    driven by XSL formatting objects.  It is a Java
	    application which can output PDF, PCL, PS, SVG, XML,
	    Print, AWT, MIF, and Text.  It is available at
	    <a class="ulink" href="http://xmlgraphics.apache.org/fop/" target="_top">http://xmlgraphics.apache.org/fop/</a>.
	  </td><td align="left">
	    FOP is required for PDF output.
	  </td><td align="left"><code class="filename">fop</code></td><td align="left"><code class="filename">fop</code></td><td align="left"><code class="filename">fop</code></td></tr><tr><td align="left">Java (j2re)</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    FOP requires Sun's Java runtime (GCJ does not work with
	    FOP).  You can download it from
	    <a class="ulink" href="http://java.sun.com" target="_top">http://java.sun.com</a>.
	  </td><td align="left">
	    Sun's Java runtime (j2re) is required to use FOP.  
	  </td><td align="left">
	    Download the package from <a class="ulink" href="http://java.sun.com" target="_top">Sun</a>.
	  </td><td align="left">
	    Download the package from <a class="ulink" href="http://java.sun.com" target="_top">Sun</a>.
	  </td><td align="left"> </td></tr><tr><td align="left">JAI</td><td align="left">Possibly Required</td><td align="left"> </td><td align="left">
	    Sun's Java Advanced Imaging API can be downloaded from
	    <a class="ulink" href="http://java.sun.com/products/java-media/jai/iio.html" target="_top">http://java.sun.com/products/java-media/jai/iio.html</a>.
	  </td><td align="left">
	    JAI is required
	    if you wish to include graphics in a PDF file being
	    generated with FOP.
	  </td><td align="left">
	    Download the package from <a class="ulink" href="http://java.sun.com/products/java-media/jai/iio.html" target="_top">Sun</a>.
	  </td><td align="left">
	    Download the package from <a class="ulink" href="http://java.sun.com/products/java-media/jai/iio.html" target="_top">Sun</a>.
	  </td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break"><p>
    If you install j2re, set the <span class="emphasis"><em>JAVA_HOME</em></span>
    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
    <span class="emphasis"><em>CLASSPATH</em></span> environment variable.
  </p></div><div class="sect1" title="Configuring Gnash"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configure"></a>Configuring Gnash</h2></div></div></div><p>
    <span class="application">Gnash</span>, 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 <a class="ulink" href="http://www.gnu.org/software/autoconf/" target="_top">GNU Autoconf</a>
    for configuration.
  </p><p>
    If you opted to download the development snapshot
    of <span class="application">Gnash</span>, the <span class="emphasis"><em>configure</em></span> script will
    not be included.  It can be created by running 
    <span class="emphasis"><em>autogen.sh</em></span> from the source root directory:
    </p><pre class="programlisting">
      ./autogen.sh
    </pre><p>
    Note that there are some 
    <a class="link" href="#dependencies" title="Code Dependencies">dependencies</a> for
    autogen.
  </p><p>
    All the standard <span class="command"><strong>configure</strong></span> options
    are available.  In addition, <span class="application">Gnash</span> has two types of
    options: those that <a class="link" href="#configfeatures" title="Features">enable or disable 
    features</a>, and
    those that <a class="link" href="#custompath" title="Specifying Custom Paths">specify custom paths for 
    development packages</a>
    which are not found during the default search.  A complete
    list of <span class="emphasis"><em>all</em></span> configuration options, including
    standard ones, can be seen by typing:
    </p><pre class="programlisting">
      ./configure --help | less
    </pre><p>
    Read further for a more detailed explanation of <span class="application">Gnash</span>-specific
    options.
  </p><p>
    The syntax for running <span class="emphasis"><em>configure</em></span> is as follows:
    </p><pre class="programlisting">
      configure <em class="replaceable"><code>&lt;options&gt;</code></em>
    </pre><p>
    The example below shows the <span class="command"><strong>configure</strong></span> options
    which create the smallest working standalone version of <span class="application">Gnash</span>.  In
    this example, <span class="command"><strong>configure</strong></span> is being run from the
    source root directory:
  </p><pre class="programlisting">
    ./configure --disable-debugger --disable-cygnal \
    --disable-plugin --enable-media=ffmpeg --enable-gui=sdl
  </pre><p>
    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.
  </p><p>
    Being highly portable, <span class="application">Gnash</span> has many configuration options
    available, and not all are supposed to work together. A common
    mistake when configuring <span class="application">Gnash</span> is to supply too many options,
    overdriving <span class="application">Gnash</span>'s ability to do the right thing.
  </p><div class="sect1" title="Features"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configfeatures"></a>Features</h2></div></div></div><p>
    Some switches can be used during configuration to enable or disable
    features of <span class="application">Gnash</span>. Some of the most important configuration options
    are:
  </p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p>
	<code class="option">--enable-gui</code> lets you specify your GUI of choice.
	The default option is GTK.
      </p></li><li class="listitem" style="list-style-type: circle"><p>
	<code class="option">--enable-renderer</code> allows a renderer to be
	chosen.  The default renderer is AGG.
      </p></li><li class="listitem" style="list-style-type: circle"><p>
	<code class="option">--enable-media</code> permits a media handler to be
	selected.  The default is Gstreamer. 
      </p></li></ul></div><p>
    A complete list of available features follows.
  </p><div class="table"><a name="tb-config-features"></a><p class="title"><b>Table 2.4. Configuration Options - Features</b></p><div class="table-contents"><table summary="Configuration Options - Features" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Option</th><th align="left">Function</th></tr></thead><tbody><tr><td align="left"><code class="option">--enable-debugger</code></td><td align="left">Enable support for the Flash debugger. The debugger is
	  mainly of interest to Flash developers, and is still under development.</td></tr><tr><td align="left"><code class="option">--enable-lirc</code></td><td align="left">
	    Enable support for the LIRC remote control protocol.
	  </td></tr><tr><td align="left"><code class="option">--enable-cygnal</code></td><td align="left">
	    Build the Cygnal streaming media server.
	  </td></tr><tr><td align="left"><code class="option">--disable-menus</code></td><td align="left">
	    Disable building all the menus for the GUI. THis is used
	    by mobile devices without as much screen space.
	  </td></tr><tr><td align="left"> <code class="option">--enable-docbook</code></td><td align="left">  Enable the generation of HTML, INFO, and MAN
	  versions of the documentation from the Docbook XML. You will
	  then be able to use <span class="command"><strong>make html</strong></span>,
	  <span class="command"><strong>make info</strong></span>, and <span class="command"><strong>make
	  man</strong></span> commands. By default, man,info and html pages
	  are generated.</td></tr><tr><td align="left"><code class="option">--enable-gui=gtk|sdl|kde|fltk|fb|hildon|alp</code></td><td align="left"><p>Select the Graphic User Interface to use (choose one).</p>
	  <div class="variablelist"><dl><dt><span class="term">GTK</span></dt><dd><p>
		  The GTK+ toolkit, which is the default GUI.
		  Said to interwork particularly well with firefox.
		</p></dd><dt><span class="term">Hildon</span></dt><dd><p>
		  The Hildon toolkist is based on GTK+, and is use by
		  some mobile devices.
		</p></dd><dt><span class="term">ALP</span></dt><dd><p>
		  The ALP "Hiker" GUI is used for the Access Linux platform.
		</p></dd><dt><span class="term">SDL</span></dt><dd><p>
		  Simple DirectMedia Layer, a simple and portable GUI.
		  Its sound facilities are used when --enable-media=ffmpeg
		  regardless of whether it is also in charge of the GUI.
		</p></dd><dt><span class="term">KDE</span></dt><dd><p>
		  An interface adapted to the KDE Desktop Environment.
		  This must be selected when building the Konqueror plugin
		  "klash". Furthermore, the only renderer that currently
		  works with KDE is opengl.
		</p></dd><dt><span class="term">FLTK</span></dt><dd><p>
		  Fast Light ToolKit, low on resource usage.
		  Since all builds using fltk are now broken, we declare it
		  "for developers".
		</p></dd><dt><span class="term">FB</span></dt><dd><p>
		  The Linux Frame Buffer, also known as /dev/fb0.
		  AGG is the only renderer that can currently be used
		  with the framebuffer GUI.
		</p></dd></dl></div>
	  </td></tr><tr><td align="left"><code class="option">--enable-i810-lod-bias</code>
	  </td><td align="left">Enable fix for Intel 810 LOD bias problem. Older versions
	  of libMesa on the Intel i810 or i815 graphics processor
	  need this flag or Gnash will core dump. This has been
	  fixed in newer versions (summer 2005) of libMesa.</td></tr><tr><td align="left"><code class="option">--enable-media=ffmpeg|gst|none</code>
	  </td><td align="left">  <p>
	    Select the specified media decoder and sound engine.
	    FFmpeg uses the SDL sound engine; GST uses its own.
	    <code class="option">GST</code> is the default decoder.
	  </p>
	  <p>
	    You should only select one media decoder.
	  </p></td></tr><tr><td align="left">
	    <code class="option">--disable-nsapi</code>
	    <code class="option">--enable-nsapi</code>
	  </td><td align="left">Force disable/enable building the NPAPI plugin.
	  By default the Mozilla plugin is built if the GTK gui 
	  is selected.  Specify the 
	  <code class="option">--with-npapi-plugindir=</code> option to specify where the
	  plugin should be installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--disable-kparts</code>
	    <code class="option">--enable-kparts</code>
	  </td><td align="left">Force disable/enable building the KPARTS plugin. By default the
	  KDE plugin is built if the kde gui is selected. 
	  Specify the <code class="option">--with-kde-plugindir=</code> and
	  <code class="option">--with-kde-servicesdir=</code> options (or more generally
	  the <code class="option">--with-kde-pluginprefix=</code> one) to specify where the
	  plugin should be installed. The default installation dir is extracted
	  from kde-config.
	  </td></tr><tr><td align="left">
	    <code class="option">--disable-plugins</code>
	  </td><td align="left">Disable build of both kparts and npapi plugins</td></tr><tr><td align="left"><code class="option">--enable-renderer=opengl|cairo|agg</code>
	  </td><td align="left">Enable support for a graphics backend. Currently
	  only <code class="option">opengl</code> and
	  <code class="option">agg</code> 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.</td></tr><tr><td align="left"><code class="option">--enable-sdk-install</code>
	  </td><td align="left">Enable installing the libraries and headers as an SDK.
	  </td></tr><tr><td align="left"><code class="option">--disable-shared</code>
	  </td><td align="left">Enable installing the shared libraries and headers.
	  Note that the extensions mechanism may not work if shared
	  libraries are disabled.</td></tr><tr><td align="left"><code class="option">--enable-strict</code>
	  </td><td align="left">Turn verbose GCC compiler warnings. By default only
	  <code class="option">-Wall</code> is used with GCC.</td></tr><tr><td align="left"><code class="option">--enable-fps-debug</code>
	  </td><td align="left">Enable FPS debugging code. When this feature is compiled in you can use the -f switch of <span class="application">Gnash</span>
	  to have FPS printed at regular intervals.</td></tr><tr><td align="left"><code class="option">--enable-write</code></td><td align="left">Makes the Mozilla plugin write the currently playing SWF movie to <code class="filename">/tmp</code>.
	  </td></tr><tr><td align="left"><code class="option">--disable-sa-launcher</code></td><td align="left">Drops the NPAPI plugin support for writing a standalone executable launcher script for the currently playing SWF movie to <code class="filename">/tmp</code>. 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.
	  </td></tr><tr><td align="left"><code class="option">--disable-mit-shm</code>
	  </td><td align="left">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.
	  </td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect1" title="Specifying Custom Paths"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="custompath"></a>Specifying Custom Paths</h2></div></div></div><p>
    By default, none of these options should be required
    unless you want <span class="application">Gnash</span> to use a specific version of a
    development package, or if the configure test fails to
    find a component.  Please <a class="link" href="#bugreport" title="Chapter 5. Reporting Bugs">report the problem</a> if a
    configure test fails.
  </p><p>
    The following custom path options are available:
  </p><div class="table"><a name="tb-configure-paths"></a><p class="title"><b>Table 2.5. Custom Path Options</b></p><div class="table-contents"><table summary="Custom Path Options" border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Option</th><th align="left">Function</th></tr></thead><tbody><tr><td align="left">
	    <code class="option">--x-includes=DIR</code>
	  </td><td align="left">
	    X include files are in DIR.
	  </td></tr><tr><td align="left">
	    <code class="option">--x-libraries=DIR</code>
	  </td><td align="left">
	    X library files are in DIR.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-docbook=DIR</code>
	  </td><td align="left">
	    Directory where the DocBook style-sheets are installed.        
	  </td></tr><tr><td align="left">
	    <code class="option">--with-sdl-prefix=PFX</code>
	  </td><td align="left">
	    Prefix where SDL is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-zlib-incl</code>
	  </td><td align="left">
	    Directory where zlib header is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-zlib-lib</code>
	  </td><td align="left">
	    Directory where zlib library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-jpeg-incl</code>
	  </td><td align="left">
	    Directory where jpeg header is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-jpeg-lib</code>
	  </td><td align="left">
	    Directory where jpeg library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-png-incl</code>
	  </td><td align="left">
	    Directory where png header is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-png-lib</code>
	  </td><td align="left">
	    Directory where png library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-qt-dir</code>
	  </td><td align="left">
	    Directory where QT is installed. This is only used by
	    the Klash plugin.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-qt-includes</code>
	  </td><td align="left">
	    Directory where the QT header files are installed. This
	    is only used by the Klash plugin.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-qt-libraries</code>
	  </td><td align="left">
	    Directory where the QT libraries are installed. This is
	    only used by the Klash plugin.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-plugins-install=user|system|prefix</code>
	  </td><td align="left">
	    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.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-npapi-install=user|system|prefix</code>
	  </td><td align="left">
	    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.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-npapi-plugindir</code>
	  </td><td align="left">
	    This is the directory to install the NPAPI (Mozilla) plugin in.
	    By default it goes to ~/.mozilla/plugins.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-kparts-install=user|system|prefix</code>
	  </td><td align="left">
	    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
            <code class="option">--with-kde-pluginprefix</code>
            or the fine-tuned options.
            The default at time of writing (2008-05-18) is 'user'.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-kde-pluginprefix</code>
	  </td><td align="left">
	    This option sets the default install dir for all KPARTS (kde) files.
	    The plugin will be installed in PREFIX/lib/kde3, use
	    <code class="option">-with-kde-plugindir</code> to override. The service file in 
	    PREFIX/share/services, use <code class="option">--with-kde-servicesdir</code> to
	    override. The config file in PREFIX/share/config, use
	    <code class="option">--with-kde-configdir</code> to override. The
	    appdata file in PREFIX/share/apps/klash, use
	    <code class="option">--with-kde-appsdatadir</code> to override. 
	  </td></tr><tr><td align="left">
	    <code class="option">--with-kde-plugindir</code>
	  </td><td align="left">
	    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.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-kde-servicesdir</code>
	  </td><td align="left">
	    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.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-kde-configdir</code>
	  </td><td align="left">
	    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.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-kde-appsdatadir</code>
	  </td><td align="left">
	    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.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-ming</code>
	  </td><td align="left">
	    Ming is used to build test cases, but not by the Gnash
	    player itself.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-ogg_incl</code>
	  </td><td align="left">
	    Directory where the libogg headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-ogg_lib</code>
	  </td><td align="left">
	    Directory where the libogg library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-gstreamer-incl</code>
	  </td><td align="left">
	    Directory where the Gstreamer headers are
	    installed. Gstreamer version 0.10 or greater must be used.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-gstreamer-lib</code>
	  </td><td align="left">
	    Directory where the Gstreamer library is
	    installed. Gstreamer version 0.10 or greater must be used.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-opengl-includes</code>
	  </td><td align="left">
	    Directory where OpenGL (libMesa) headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-opengl-lib</code>
	  </td><td align="left">
	    Directory where the OpenGL (libMesa) library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-glext-incl</code>
	  </td><td align="left">
	    Directory where GtkGlExt headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-glext-lib</code>
	  </td><td align="left">
	    Directory where the GtkGlExt library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-gtk2-incl</code>
	  </td><td align="left">
	    Directory where the Gtk2 headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-gtk2-lib</code>
	  </td><td align="left">
	    Directory where the Gtk2 library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-cairo_incl</code>
	  </td><td align="left">
	    Directory where the Cairo headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-cairo-lib</code>
	  </td><td align="left">
	    Directory where the Cairo library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-glib-incl</code>
	  </td><td align="left">
	    Directory where the Glib headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-glib-lib</code>
	  </td><td align="left">
	    Directory where the Glib library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-pango-incl</code>
	  </td><td align="left">
	    Directory where the Pango headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-pango-lib</code>
	  </td><td align="left">
	    Directory where the Pango library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-atk-incl</code>
	  </td><td align="left">
	    Directory where the ATK headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-atk-lib</code>
	  </td><td align="left">
	    Directory where the ATK library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-pthread-incl</code>
	  </td><td align="left">
	    Directory where the Pthread headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-pthread-lib</code>
	  </td><td align="left">
	    Directory where the Pthread library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-agg-incl</code>
	  </td><td align="left">
	    Directory where the AGG (Antigrain) headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-agg-lib</code>
	  </td><td align="left">
	    Directory where the AGG (Antigrain) library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-ffmpeg-incl</code>
	  </td><td align="left">
	    Directory where the FFMPEG headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-ffmpeg-lib</code>
	  </td><td align="left">
	    Directory where the FFMPEG library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-boost-incl</code>
	  </td><td align="left">
	    Directory where the Boost headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-boost-lib</code>
	  </td><td align="left">
	    Directory where the Boost library is installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-curl-incl</code>
	  </td><td align="left">
	    Directory where the libCurl headers are installed.
	  </td></tr><tr><td align="left">
	    <code class="option">--with-curl-lib</code>
	  </td><td align="left">
	    Directory where the libCurl library is installed.
	  </td></tr></tbody></table></div></div><br class="table-break"></div></div><p>
    Once you have <span class="application">Gnash</span> configured, you are ready to build the code.  <span class="application">Gnash</span> is built using
    <span class="emphasis"><em>GNU make</em></span>.
  </p><div class="sect1" title="Compiling the Code"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="compile"></a>Compiling the Code</h2></div></div></div><p>
      The most basic way to compile code is simply:
      </p><pre class="programlisting">
	make
      </pre><p>
      If the compilation ends with an error, check the output of 
      <span class="emphasis"><em>configure</em></span> and ensure that you are not missing 
      any required prerequisites.  The output of <span class="command"><strong>make</strong></span> can be verbose; you may wish to pipe the output to a file.
    </p><p>
      The variables used by <span class="command"><strong>make</strong></span> can be redefined when
      the program is invoked, if you desire it.   The most interesting flags
      are <span class="emphasis"><em>CFLAGS</em></span> and <span class="emphasis"><em>CXXFLAGS</em></span>,
      which are often used to enable debugging or turn of optimization.
      The default value for both of these variables is
      <span class="emphasis"><em>-O2 -g</em></span>.  A list of influential 
      environment variables can be seen in the configuration help:
    </p><pre class="programlisting">./configure --help</pre><p>
      In the following example, debugging is enabled and optimization is
      disabled:
    </p><pre class="programlisting">make CFLAGS=-g CXXFLAGS=-g</pre></div><div class="sect1" title="Creating the Documentation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="processdoc"></a>Creating the Documentation</h2></div></div></div><p>
      By default, documentation is not built when you
      <a class="link" href="#install" title="Installation">install</a> <span class="application">Gnash</span>.  This is because
      there are a number of <a class="link" href="#docdepend" title="Documentation Dependencies">dependencies 
      for the documentation</a>.  Documentation is built when it
      is specified with a specific target in the generated 
      <span class="command"><strong>Makefile</strong></span> in the <code class="filename">doc/C</code>
      sub-directory.  If you type <span class="command"><strong>make install</strong></span> in
      this directory, all documents will be built.
    </p><p>
      You must specify a target output format when you wish to create
      documentation.  The available output formats are: <span class="command"><strong>html</strong></span>,
      <span class="command"><strong>pdf</strong></span>, <span class="command"><strong>info</strong></span>, 
      <span class="command"><strong>man</strong></span>, and <span class="command"><strong>alldocs</strong></span>.  
      It is also possible to output <span class="command"><strong>GNOME help</strong></span> if
      the <a class="link" href="#configfeatures" title="Features">configure option</a>
      <code class="option">--enable-ghelp</code> was used.  
      The <span class="command"><strong>alldocs</strong></span> target will build all output formats
      except <span class="emphasis"><em>GNOME help</em></span>.
      For example, to create HTML output, type:
      </p><pre class="programlisting">
	make html
      </pre><p>
    </p><p>
      <span class="application">Gnash</span> also uses <a class="ulink" href="http://www.stack.nl/~dimitri/doxygen/index.html" target="_top">Doxygen</a> to produce <span class="emphasis"><em>HTML</em></span>
      documentation of <span class="application">Gnash</span> internals.  You must have Doxygen installed
      to produce this documentation, which is built from the
      <code class="filename">doc</code> directory with the command (documents
      will be placed in the subdirectory <code class="filename">apidoc/html</code>):
      </p><pre class="programlisting">
	make apidoc
      </pre><p>
    </p></div><div class="sect1" title="Running the Tests"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="runtests"></a>Running the Tests</h2></div></div></div><p>
      Before beginning the potentially lengthy install, it is wise to
      test the installation.  If a test fails, please report it by
      following the <a class="link" href="#bugreport" title="Chapter 5. Reporting Bugs">instructions for
      reporting a bug</a>. 
    </p><div class="sect2" title="Using DejaGnu"><div class="titlepage"><div><div><h3 class="title"><a name="dejagnu"></a>Using DejaGnu</h3></div></div></div><p>
	
	The easiest way to run <span class="application">Gnash</span>'s test suite is to install
	<span class="emphasis"><em><a class="ulink" href="http://www.gnu.org/software/dejagnu" target="_top">DejaGnu</a></em></span>.
	After installing DejaGnu, run:
	</p><pre class="programlisting">
	  make check
	</pre><p>
      </p><div class="sect4" title="Increasing Verbosity"><div class="titlepage"><div><div><h5 class="title"><a name="testing_verbosity"></a>Increasing Verbosity</h5></div></div></div><p>
	  If you encounter a problem with a test, increasing the
	  verbosity may make the issue easier to spot.
	  Additional details are visible when 
	  <span class="emphasis"><em>RUNTESTFLAGS</em></span> are used to add the 
	  <span class="emphasis"><em>verbose</em></span> and <span class="emphasis"><em>all</em></span> options.
	  The <code class="option">verbose</code> option prints more information about the testing process, while
	  the <code class="option">all</code> option includes details on passing tests.  
	  </p><pre class="programlisting">
	    make check RUNTESTFLAGS="-v -a"
	  </pre><p>
	</p></div><div class="sect4" title="Running Some Tests"><div class="titlepage"><div><div><h5 class="title"><a name="running_some_tests"></a>Running Some Tests</h5></div></div></div><p>
	  It is possible to run just a single test, or 
	  a subdirectory of tests, by specifying the directory or 
	  compiled test file.
	</p><p>
	  Some tests rely on <span class="emphasis"><em>testsuite/Dejagnu.swf</em></span>,
	  which in turn relies on <span class="emphasis"><em>Ming</em></span>.
	  This file is created when you run <span class="command"><strong>make check</strong></span> for the entire
	  testsuite, and can also be created on demand:
	  </p><pre class="programlisting">
	    make -C testsuite Dejagnu.swf 
	  </pre><p>
	</p><p>
	  In this example, the <span class="command"><strong>clip_as_button2</strong></span> test is compiled and
	  run:
	  </p><pre class="programlisting">
	    make -C testsuite/samples clip_as_button2-TestRunner 
	    cd testsuite/samples &amp;&amp; ./clip_as_button2-TestRunner
	  </pre><p>
	  This creates and runs all the tests in the directory
	  <code class="filename">movies.all</code>:
	  </p><pre class="programlisting">
	    make -C testsuite/movies.all check
	  </pre><p>
	</p></div></div><div class="sect2" title="Running The Tests Manually"><div class="titlepage"><div><div><h3 class="title"><a name="manually"></a>Running The Tests Manually</h3></div></div></div><p>
	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 <span class="application">Gnash</span> are most useful for
	development.
      </p><p>
	The first step is to compile the test case, which can be done
	with <code class="filename">make XML-v#.swf</code> where the '#' is replaced
	with the <span class="emphasis"><em>target</em></span> SWF version or versions.  
	For example:
	</p><pre class="programlisting">
	  make XML-v{5,6,7,8}.swf
	</pre><p>
      </p><div class="sect4" title="Movie tests"><div class="titlepage"><div><div><h5 class="title"><a name="manual_compiled_tests"></a>Movie tests</h5></div></div></div><p>
	  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 <span class="application">Gnash</span>:
	  </p><pre class="programlisting">
	    gnash -v XML-v6.swf
	  </pre><p>
	</p></div><div class="sect4" title="ActionScript Unit Tests"><div class="titlepage"><div><div><h5 class="title"><a name="manual_actionscript_tests"></a>ActionScript Unit Tests</h5></div></div></div><p>
	  Unit tests for ActionScript classes in <span class="command"><strong>testsuite/actionscript.all</strong></span>
	  are run without a graphical display:
	  </p><pre class="programlisting">
	    gprocessor -v XML-v6.swf
	  </pre><p>
	</p></div></div><div class="sect1" title="Installation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install"></a>Installation</h2></div></div></div><p>
    Now that <span class="application">Gnash</span> has been compiled and tested, use the following command to install it:
    </p><pre class="programlisting">
      make install
    </pre><p>
    The above command installs the standalone player.  If the correct
    files were found by <span class="command"><strong>configure</strong></span> and if the
    <code class="option">--disable-plugin</code> option was not specified, the
    <span class="application">Gnash</span> browser plugin is also installed. 
  </p><p>
    <span class="application">Gnash</span> installs a number of <a class="link" href="#libinstall" title="Libraries">libraries</a>,
    namely: <span class="emphasis"><em>libgnashbase</em></span>,
    <span class="emphasis"><em>libgnashamf</em></span>, <span class="emphasis"><em>libgnashmedia</em></span>,
    <span class="emphasis"><em>libserver</em></span>, and <span class="emphasis"><em>libgnashplugin</em></span>.
    <a class="link" href="#appinstall" title="Executables">Executables</a>
    consist of the (optional) plugin, <code class="filename">gprocessor</code>,
    <code class="filename">cygnal</code>,  <code class="filename">dumpshm</code>,
    <code class="filename">soldumper</code>, and <code class="filename">gnash</code>.
    <a class="link" href="#docinstall" title="Documentation">Documentation</a> may also be installed.
    The installation location is controlled with the
    <span class="emphasis"><em>--prefix</em></span> <a class="link" href="#custompath" title="Specifying Custom Paths">configure
    option</a>, except for plugins, which are explicitly set with
    <span class="emphasis"><em>--plugin-dir</em></span>.
  </p><p>
    Note that if you are using a single file-system <span class="emphasis"><em>NFS</em></span>
    mounted to multiple platforms, the 
    <a class="link" href="#custompath" title="Specifying Custom Paths">configuration option</a> 
    <span class="emphasis"><em>--exec-prefix</em></span> may be used to specify where
    platform-dependent executables and libraries are installed.
  </p><div class="sect2" title="Libraries"><div class="titlepage"><div><div><h3 class="title"><a name="libinstall"></a>Libraries</h3></div></div></div><p>
      Installed libraries are located in 
      <code class="filename">/usr/local/lib</code> by default.
      If the <span class="emphasis"><em>--prefix</em></span> option was used during the
      configuration step, the libraries will
      be installed in the directory <code class="filename">lib</code> 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.
    </p><p>
      The traditional way to do this on UNIX
      platforms is to set the <span class="emphasis"><em>LD_LIBRARY_PATH</em></span> variable
      to the path plus <code class="filename">/lib</code>.  For example, if you
      installed in <code class="filename">/home/gnash</code>, the 
      <span class="emphasis"><em>LD_LIBRARY_PATH</em></span> path would be
      <code class="filename">/home/gnash/lib</code>.  Multiple paths are delimited
      with a colon (':').
    </p><p>
      GNU/Linux allows the custom path to be added to
      <code class="filename">/etc/ld.so.conf</code>.  After adding the path,
      run <span class="emphasis"><em>ldconfig</em></span> as root to update the runtime
      cache.
    </p></div><div class="sect2" title="Executables"><div class="titlepage"><div><div><h3 class="title"><a name="appinstall"></a>Executables</h3></div></div></div><p>
      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 <code class="filename">~/.mozilla/plugins/</code>. To enable
      the plugin for other users, copy the file <code class="filename">libgnashplugin.so</code>
      to <code class="filename">.mozilla/plugins/</code> in their home directory.
      You may also specify the plugin installation directory by using the 
      <code class="option">--with-plugindir</code> <a class="link" href="#custompath" title="Specifying Custom Paths">option 
      at configuration time</a>.
    </p><p>
      These defaults are likely to change in future versions of Gnash.
    </p><p>
      The remaining executables are installed in the <code class="filename">bin</code>
      subdirectory of the directory specified by during configuration.
      If no path was specified, the default is 
      <code class="filename">/usr/local/bin</code>.
    </p></div><div class="sect2" title="Documentation"><div class="titlepage"><div><div><h3 class="title"><a name="docinstall"></a>Documentation</h3></div></div></div><p>
      Documentation is not built by default; please refer to the 
      <a class="link" href="#processdoc" title="Creating the Documentation">section on documentation</a> for
      more information on building documentation.
    </p><p>
      <span class="command"><strong>man</strong></span> and <span class="command"><strong>info</strong></span> 
      are installed in <code class="filename">/usr/local/share/man</code>
      and <code class="filename">/usr/local/share/info</code> respectively, unless
      the <code class="option">--mandir</code> or <code class="option">--infodir</code>
      <a class="link" href="#custompath" title="Specifying Custom Paths">configuration options</a> are used.
    </p><p>
      <span class="emphasis"><em>GNOME help</em></span> documentation uses the directory
      <code class="filename">/usr/local/share/gnash/doc/gnash/C/</code> by default.
      A configuration file in the <span class="application">Gnash</span> source tree,
      <code class="filename">doc/C/gnash.omf</code> is used to specify under
      which menu item <span class="application">Gnash</span> appears in the <span class="emphasis"><em>GNOME help</em></span>
      system.
    </p></div></div><div class="sect1" title="Cross Configuring"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cross"></a>Cross Configuring</h2></div></div></div><p>
    To cross configure and compile <span class="application">Gnash</span>, 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 <a class="link" href="#docdepend" title="Documentation Dependencies">dependencies  
    </a> 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 <a class="ulink" href="http://www.gnashdev.org" target="_top">http://www.gnashdev.org</a> web
    site.
  </p><p>
    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
    <a class="ulink" href="http://frank.harvard.edu/~coldwell/toolchain/" target="_top">http://frank.harvard.edu/~coldwell/toolchain/</a>
    and <a class="ulink" href="http://www.kegel.com/crosstool/" target="_top">http://www.kegel.com/crosstool/</a>. This
    can also be a very time consuming and frustrating process, even
    for experienced developers.
  </p><p>
    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 
    <a class="ulink" href="http://www.access-company.com/products/linux/alp.html" target="_top">
    Access Linux Platform</a>, 
    <a class="ulink" href="http://www.scratchbox.org/" target="_top">
    Scratchbox</a>, 
    <a class="ulink" href="http://www.openembedded.org/" target="_top">
    Open Embedded</a>, 
    <a class="ulink" href="http://maemo.org/" target="_top">
    Maemo</a>.
  </p><p>
    To build for an ARM based system on an x86 based systems,
    configure like this using the traditional style cross toolchain,
    configure like this:
  </p><pre class="programlisting">
    ../../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
    
  </pre><p>
    The important configuration options are the ones which specify the
    architecture for the build:
  </p><div class="variablelist"><dl><dt><span class="term">--target</span></dt><dd><p>
	  The target architecture, where the final executables are expected
	  to run.
	</p></dd><dt><span class="term">--host</span></dt><dd><p>
	  The host architecture, where the executables are expected
	  to run.  Usually this is the same as the <span class="emphasis"><em>--target</em></span>,
	  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, <span class="emphasis"><em>--target</em></span> would
	  be 'arm-unknown-linux-gnu', while <span class="emphasis"><em>--host</em></span> would 
	  be 'win32'.
	</p></dd><dt><span class="term">--build</span></dt><dd><p>
	  This is the system the build is running on.
	</p></dd></dl></div><p>
    The following example of <span class="emphasis"><em>configure</em></span> builds for an
    ARM system on an x86 system.  It was run after an ARM system was built
    in <code class="filename">/usr/arm</code> and other required libraries were 
    cross compiled.
    </p><pre class="programlisting">
      ./configure -target=arm-unknown-linux-gnu --prefix=/usr/arm \
      --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu --disable-plugin
    </pre><p>
  </p></div></div></div><div class="chapter" title="Chapter 3. Software Internals"><div class="titlepage"><div><div><h2 class="title"><a name="internals"></a>Chapter 3. Software Internals</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#tour">A Tour of <span class="application">Gnash</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="#The%20Libraries">The Libraries</a></span></dt><dt><span class="sect2"><a href="#apps">The Applications</a></span></dt><dt><span class="sect2"><a href="#plugin">The Plugin</a></span></dt><dt><span class="sect2"><a href="#logging">The Message Logging System</a></span></dt></dl></dd><dt><span class="sect1"><a href="#soundhandlers">Sound handling in <span class="application">Gnash</span></a></span></dt><dd><dl><dt><span class="sect2"><a href="#soundtypes">Sound types</a></span></dt><dt><span class="sect2"><a href="#soundparsing">Sound parsing</a></span></dt><dt><span class="sect2"><a href="#soundplayback">Sound playback</a></span></dt><dt><span class="sect2"><a href="#sdlsound">The SDL sound backend</a></span></dt><dt><span class="sect2"><a href="#gstreamer">The Gstreamer backend</a></span></dt><dt><span class="sect2"><a href="#gstreamer-details">Detailed description of the Gstreamer backend</a></span></dt></dl></dd><dt><span class="sect1"><a href="#testing">Testing </a></span></dt><dd><dl><dt><span class="sect2"><a href="#testtools">Testing Tools</a></span></dt><dt><span class="sect2"><a href="#testcases">Test Cases</a></span></dt><dt><span class="sect2"><a href="#writeastests">Writing ActionScript Tests</a></span></dt><dt><span class="sect2"><a href="#writemingtests">Writing Ming-based self-contained SWF tests</a></span></dt><dt><span class="sect2"><a href="#writing_dejagnu_so_tests">Writing self-contained SWF tests with other compilers</a></span></dt><dt><span class="sect2"><a href="#writing_test_runners">Writing Test Runners</a></span></dt></dl></dd></dl></div><div class="sect1" title="A Tour of Gnash"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tour"></a>A Tour of <span class="application">Gnash</span></h2></div></div></div><p>
      The top level of <span class="application">Gnash</span> has several libraries, <span class="emphasis"><em>libgnashbase</em></span>,
      <span class="emphasis"><em>libgnashcore</em></span>,
      <span class="emphasis"><em>libgnashmedia</em></span>,
      <span class="emphasis"><em>libgnashamf</em></span> and
      <span class="emphasis"><em>libgnashrender</em></span>. 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.
    </p><div class="sect2" title="The Libraries"><div class="titlepage"><div><div><h3 class="title"><a name="The%20Libraries"></a>The Libraries</h3></div></div></div><div class="sect3" title="libgnashbase"><div class="titlepage"><div><div><h4 class="title"><a name="libbase"></a>libgnashbase</h4></div></div></div><p>
	  Libgnashbase contains support classes used by the rest of the
	  code.This library has no dependencies on any of the other
	  <span class="application">Gnash</span> libraries.
	</p><p>
	  <span class="application">Gnash</span> makes heavy use of smart pointers, so memory allocations
	  are freed up automatically by the interpreter. Both STL and
	  Boost smart pointers are used.
	</p></div><div class="sect3" title="libgnashcore"><div class="titlepage"><div><div><h4 class="title"><a name="libgnashcore"></a>libgnashcore</h4></div></div></div><p>
	  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.
	</p></div><div class="sect3" title="libgnashmedia"><div class="titlepage"><div><div><h4 class="title"><a name="libgnashmedia"></a>libgnashmedia</h4></div></div></div><p>
        Libgnashmedia handles <span class="application">Gnash</span>'s decoding of video and audio,
        including both streamed and embedded media.
		Besides the standard SWF formats
		FLV, MPEG4, Nellymoser, ADPCM, MP3 and RAW, <span class="application">Gnash</span> can 
		decode other formats supports by Gstreamer or FFmpeg, 
		including the free OGG container and free codecs.
	</p></div><div class="sect3" title="libgnashsound"><div class="titlepage"><div><div><h4 class="title"><a name="libgnashsound"></a>libgnashsound</h4></div></div></div><p>
        This library handles sound output and manages sound objects.
	</p></div><div class="sect3" title="libgnashamf"><div class="titlepage"><div><div><h4 class="title"><a name="libgnashamf"></a>libgnashamf</h4></div></div></div><p>
	  AMF is the data format used internally by SWF files. This is
	  <span class="application">Gnash</span>'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.
	</p></div><div class="sect3" title="libgnashbackend"><div class="titlepage"><div><div><h4 class="title"><a name="libgnashbackend"></a>libgnashbackend</h4></div></div></div><p>
	  Libgnashbackend is a library containing the rendering
	  code that glues this display to the <span class="application">Gnash</span>. Supported
	  rendering backends are OpenGL, Cairo, and AGG.
	</p></div><div class="sect3" title="libgnashplugin"><div class="titlepage"><div><div><h4 class="title"><a name="libgnashpluin"></a>libgnashplugin</h4></div></div></div><p>
	  Libgnashplugin is the Mozilla/Firefox plugin.
	</p></div><div class="sect3" title="libklashpart"><div class="titlepage"><div><div><h4 class="title"><a name="libklashpart"></a>libklashpart</h4></div></div></div><p>
	  Libklashpart is the Konqueror plugin.
	</p></div></div><div class="sect2" title="The Applications"><div class="titlepage"><div><div><h3 class="title"><a name="apps"></a>The Applications</h3></div></div></div><p>
	    There are currently a few standalone programs in <span class="application">Gnash</span>,
        which serve either to assist with <span class="application">Gnash</span> development or to play SWF
        movies.
      </p><div class="sect3" title="The Standalone Player"><div class="titlepage"><div><div><h4 class="title"><a name="Gnash"></a>The Standalone Player</h4></div></div></div><p>
	  This is the standalone OpenGL backend used to play
	  movies. There are several command line options and keyboard
	  control keys used by <span class="application">Gnash</span>.
	</p></div><div class="sect3" title="Gprocessor"><div class="titlepage"><div><div><h4 class="title"><a name="processor"></a>Gprocessor</h4></div></div></div><p>
	  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 <span class="emphasis"><em>.gsc</em></span>
	  files that <span class="application">Gnash</span> uses to cache data, thereby speeding up the
	  loading of files.
	</p></div><div class="sect3" title="SOLdumper"><div class="titlepage"><div><div><h4 class="title"><a name="soldumper"></a>SOLdumper</h4></div></div></div><p>
	  SOLDumper is a utility program used to find and dump the
	  content of <span class="emphasis"><em>Local Shared Objects</em></span>, also
	  called "Flash Cookies" by some.
	</p></div><div class="sect3" title="Dumpshm"><div class="titlepage"><div><div><h4 class="title"><a name="dumpshm"></a>Dumpshm</h4></div></div></div><p>
	  Dumpshm is a program used to find and dump the contents of
	  the <span class="emphasis"><em>LocalConnection</em></span> shared memory segment.
	</p></div></div><div class="sect2" title="The Plugin"><div class="titlepage"><div><div><h3 class="title"><a name="plugin"></a>The Plugin</h3></div></div></div><p>
	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.
      </p><div class="sect3" title="Current Implementation"><div class="titlepage"><div><div><h4 class="title"><a name="pluginstatus"></a>Current Implementation</h4></div></div></div><p>
	  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 <span class="application">Gnash</span>
	  itself is not thread safe at this time.
	</p></div><div class="sect3" title="GUI Support"><div class="titlepage"><div><div><h4 class="title"><a name="gui"></a>GUI Support</h4></div></div></div><p>
	  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.
	</p><p>
	  <span class="application">Gnash</span> can use either several different GUI toolkits to create the window,
	  and to handle events for the standalone player.
	</p><p>
	  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. <span class="application">Gnash</span> 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.
	</p><p>
	  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. 
	</p><p>
	  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.
	</p><p>
	  GTK also allows <span class="application">Gnash</span> 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.
	</p></div><div class="sect3" title="Klash"><div class="titlepage"><div><div><h4 class="title"><a name="Klash"></a>Klash</h4></div></div></div><p>
	  Klash is MozPlugger type support for KDE's Konqueror web
	  browser. Klash makes <span class="application">Gnash</span> a <span class="emphasis"><em>kpart</em></span>, so it's
	  integrated into KDE better than when using MozPlugger. Klash
	  uses the standalone player, utilizing <span class="application">Gnash</span>'s "-x" window
	  plugin command line option.
	</p><p>
	  By default, Klash is not built. To enable building Klash,
	  use the <span class="emphasis"><em>--enable-klash</em></span> option when
	  configuring. Other than installing, there is nothing else
	  that needs to be done to install Klash.
	</p></div></div><div class="sect2" title="The Message Logging System"><div class="titlepage"><div><div><h3 class="title"><a name="logging"></a>The Message Logging System</h3></div></div></div><p>
    <span class="application">Gnash</span>'s common message logging system uses a <span class="emphasis"><em>printf()</em></span>
    style format. Despite the C-like appearance, however, <span class="application">Gnash</span>'s LogFile class
    by default does not use <span class="emphasis"><em>printf()</em></span> for formatting the
    messages at all.
  </p><p>
    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.
  </p><p>
    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 
    <span class="emphasis"><em>#define ARG_NUMBER</em></span> in <span class="emphasis"><em>libbase/log.h</em></span>.
  </p><p>
    If a filename is not specified before the log file is needed, a
    default name of <span class="emphasis"><em>gnash-dbg.log</em></span> 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
    <span class="emphasis"><em>GNOME</em></span> or <span class="emphasis"><em>KDE</em></span> the debug file goes in your
    home directory, since that's considered the current directory. A file name
    can be specified using either <span class="emphasis"><em>gnashrc</em></span> or a 
    call to the LogFile instance itself.
  </p><div class="sect3" title="Logging System API"><div class="titlepage"><div><div><h4 class="title"><a name="api"></a>Logging System API</h4></div></div></div><p>
        <span class="application">Gnash</span> provides 9 specialized logging calls, each using the <span class="emphasis"><em>printf()</em></span>-style
        call similar to this:
        </p><pre class="programlisting">log_error(const char* fmt, ...)</pre><p>
        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.
    </p><div class="variablelist"><dl><dt><span class="term">log_error</span></dt><dd><p>
	    Display an error message if verbose output is enabled. This is
	    always printed at a verbosity level of 1 or more.
	  </p></dd><dt><span class="term">log_unimpl</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">log_trace</span></dt><dd><p>
	    Used only for the output of the ActionScript <span class="emphasis"><em>trace()</em></span>
	     function. This is
	    always printed at a verbosity level of 1 or more.
	  </p></dd><dt><span class="term">log_debug</span></dt><dd><p>
	    Logs debug information. This is printed at a verbosity level of 2 or more.
	  </p></dd><dt><span class="term">log_action</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">log_parse</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">log_swferror</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">log_aserror</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">log_abc</span></dt><dd><p>
		Extremely verbose logging related to AVM2/ABC execution.
		This is printed at verbosity level 3.
	  </p></dd></dl></div></div><div class="sect3" title="The LogFile Instance"><div class="titlepage"><div><div><h4 class="title"><a name="logfileinstance"></a>The LogFile Instance</h4></div></div></div><p>
      This is the main API for initializing and manipulating the logging output.
      By default, the log will be written to <span class="emphasis"><em>gnash-dbg.log</em></span>
      file whenever a verbose option is
      supplied.
    </p><div class="variablelist"><dl><dt><span class="term">getDefaultInstance()</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">setLogFilename(const std::string&amp; filename)</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">closeLog()</span></dt><dd><p>
	    Close a debug log. The disk file remains.
	  </p></dd><dt><span class="term">removeLog()</span></dt><dd><p>
	    Delete the debug log file from disk.
	  </p></dd><dt><span class="term">setVerbosity()</span></dt><dd><p>
	    Increment the verbosity level.
	  </p></dd><dt><span class="term">setVerbosity(int level)</span></dt><dd><p>
	    Set the verbosity level to a specified level.
	  </p></dd><dt><span class="term">setStamp(bool flag)</span></dt><dd><p>
	    If <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>true</em></span>, then print a
	    timestamp prefixed to every output line. If
	    <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>false</em></span>, then don't print
	    a timestamp.
	  </p></dd><dt><span class="term">setWriteDisk(bool flag)</span></dt><dd><p>
	    If <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>true</em></span>, then create the
	    disk file. If <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>false</em></span>,
	    then don't create the disk file.
	  </p></dd></dl></div></div></div></div><div class="sect1" title="Sound handling in Gnash"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="soundhandlers"></a>Sound handling in <span class="application">Gnash</span></h2></div></div></div><p>
        Sound in <span class="application">Gnash</span> is handled by libgnashsound. This library takes
        care of interfacing with a sound handler.
    </p><p>
      There are two different settings related to sound support:
      <span class="emphasis"><em>pluginsound</em></span> and <span class="emphasis"><em>sound</em></span>. 
      This was done in order to allow the plugin to be independently 
      configured, for instance to block sound from advertisements.
    </p><div class="sect2" title="Sound types"><div class="titlepage"><div><div><h3 class="title"><a name="soundtypes"></a>Sound types</h3></div></div></div><p>
        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. 
      </p></div><div class="sect2" title="Sound parsing"><div class="titlepage"><div><div><h3 class="title"><a name="soundparsing"></a>Sound parsing</h3></div></div></div><p>
        When <span class="application">Gnash</span> 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. 
      </p></div><div class="sect2" title="Sound playback"><div class="titlepage"><div><div><h3 class="title"><a name="soundplayback"></a>Sound playback</h3></div></div></div><p>
	When a sound is about to be played <span class="application">Gnash</span> 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. 
      </p></div><div class="sect2" title="The SDL sound backend"><div class="titlepage"><div><div><h3 class="title"><a name="sdlsound"></a>The SDL sound backend</h3></div></div></div><p>
	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 <span class="application">Gnash</span>'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 <span class="application">Gnash</span> 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...
      </p></div><div class="sect2" title="The Gstreamer backend"><div class="titlepage"><div><div><h3 class="title"><a name="gstreamer"></a>The Gstreamer backend</h3></div></div></div><p>
	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. 
      </p></div><div class="sect2" title="Detailed description of the Gstreamer backend"><div class="titlepage"><div><div><h3 class="title"><a name="gstreamer-details"></a>Detailed description of the Gstreamer backend</h3></div></div></div><p>
	Gstreamer uses pipelines, bins and elements. Pipelines are the
	main bin, where all other bins or elements are places. Visually the
	audio pipeline in <span class="application">Gnash</span> looks like this: 
      </p><pre class="programlisting">
	 ___
	|Bin|_
	|___| \
	 ___   \ _____       ____________
	|Bin|___|Adder|_____|Audio output|
	|___|   |_____|     |____________|
	 ___   /
	|Bin|_/
	|___|

      </pre><p>
	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: 
      </p><pre class="programlisting">

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

      </pre><p>
	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. 
      </p><p>
	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 <span class="application">Gnash</span> 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. 
      </p><p>
	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. 
      </p></div></div><div class="sect1" title="Testing"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="testing"></a>Testing </h2></div></div></div><p>
       <a class="link" href="#runtests" title="Running the Tests">Instructions on running tests</a>
       can be found in the section on building <span class="application">Gnash</span>.
     </p><div class="sect2" title="Testing Tools"><div class="titlepage"><div><div><h3 class="title"><a name="testtools"></a>Testing Tools</h3></div></div></div><p>
	Currently <span class="application">Gnash</span> 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 <span class="application">Gnash</span> to test
	specific features, and to see how the features operate.
      </p><p>
	The primary compiler used at this time is <a class="ulink" href="http://ming.sf.net" target="_top">Ming</a>. Since release 0.3,
	<span class="emphasis"><em>Ming</em></span> includes a command-line compiler,
	<span class="emphasis"><em>makeswf</em></span>. This allows test case development
        to be done entirely with free tools.
      </p><p>
        The other tools are optional.  
	<a class="ulink" href="http://www.gnu.org/software/dejagnu" target="_top">DejaGnu</a>
	is used to run multiple test cases in an automated
	manner. <span class="emphasis"><em>DejaGnu</em></span> is used by many other <a class="ulink" href="http://www.gnu.org" target="_top">GNU</a> projects like 
	<a class="ulink" href="http://gcc.gnu.org" target="_top">GCC</a> and 
	<a class="ulink" href="http://www.samba.org" target="_top">Samba</a>.
      </p></div><div class="sect2" title="Test Cases"><div class="titlepage"><div><div><h3 class="title"><a name="testcases"></a>Test Cases</h3></div></div></div><p>
	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.
      </p></div><div class="sect2" title="Writing ActionScript Tests"><div class="titlepage"><div><div><h3 class="title"><a name="writeastests"></a>Writing ActionScript Tests</h3></div></div></div><p>
	Writing ActionScript tests is very simple. The
	<span class="emphasis"><em>makeswf</em></span> 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.
      </p><p>
	Each test unit sets an <span class="emphasis"><em>rcsid</em></span> variable, includes the
	<span class="emphasis"><em>check.as</em></span> file and performs some checks using
	the provided macros. Here is an example:
	
	</p><pre class="programlisting">

	  // 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 ...
	</pre><p>
      </p><p>
	The check(expr) macro will <span class="emphasis"><em>trace</em></span> PASSED or FAILED
	together with the expression being evaluated and the line number
	of the check. This is the format expected by DejaGnu.
      </p><p>
	The <span class="emphasis"><em>check_equals(obtained, expected)</em></span> macro uses equality operator
	<span class="emphasis"><em>==</em></span> to check for equality. When possible, use of the
	<span class="emphasis"><em>check_equals()</em></span> macro is preferred over <span class="emphasis"><em>check()</em></span>
	because it shows what the actual result was in case of a failure. 
      </p><p>
	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.
      </p><p>
	Test units are built by running <span class="emphasis"><em>make TestName-v#.swf</em></span>.
	This will use TestName.as as source and the value of # as target version.
	Allowed target version are from 5 to 8 (inclusive).
      </p><p>
	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
	<span class="emphasis"><em>TestName.as.pp</em></span> or <span class="emphasis"><em>TestName-v#.swf.frame#.pp</em></span>
	(depending on Ming version) and it's not thrown away by
	<span class="emphasis"><em>makeswf</em></span> to make debugging easier.
      </p><p>
	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:

	</p><pre class="programlisting">

	  #if OUTPUT_VERSION &gt;= 7
	  check(_root.getSWFVersion == OUTPUT_VERSION);
	  #endif
	  
	</pre><p>
      </p></div><div class="sect2" title="Writing Ming-based self-contained SWF tests"><div class="titlepage"><div><div><h3 class="title"><a name="writemingtests"></a>Writing Ming-based self-contained SWF tests</h3></div></div></div><p>
	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.
      </p><p>
	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 <a class="link" href="#ming_testgenerator_facilities" title="Using Ming-based test generators facilities">facilities</a>
	provided by the <span class="application">Gnash</span> testing framework to easily run tests.
      </p><p>
	For generic Ming API documentation, see <a class="ulink" href="http://www.libming.org/" target="_top">http://www.libming.org</a>. 
      </p><div class="sect3" title="Using Ming-based test generators facilities"><div class="titlepage"><div><div><h4 class="title"><a name="ming_testgenerator_facilities"></a>Using Ming-based test generators facilities</h4></div></div></div><p>
	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.
      </p><p>
	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.
      </p><p>
        You will <span class="emphasis"><em>not</em></span> need to directly invoke the
	TestState object created by the 'add_dejagnu_functions()' routine,
	rather you will be using C macros hiding its complexity:
	
	</p><pre class="programlisting">

	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.
	</pre><p>
	
      </p><p>
	Test cases generated using Ming and the provided
	<a class="link" href="#ming_testgenerator_facilities" title="Using Ming-based test generators facilities">facilities</a>
	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
	<span class="application">Gnash</span> use them as tests.
      </p><p>
	See section <a class="link" href="#writing_test_runners" title="Writing Test Runners">Writing Test Runners</a>
	for information about writing SWF test runners.
      </p></div></div><div class="sect2" title="Writing self-contained SWF tests with other compilers"><div class="titlepage"><div><div><h3 class="title"><a name="writing_dejagnu_so_tests"></a>Writing self-contained SWF tests with other compilers</h3></div></div></div><p>
	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 <span class="application">Gnash</span> testsuite
	to let your test consistent with the rest of the suite.
      </p><p>
	The loadable module is called <span class="emphasis"><em>Dejagnu.swf</em></span> and is built during
	<span class="emphasis"><em>make check</em></span> 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 <span class="emphasis"><em>dejagnu_module_initialized</em></span> variable, which will
	be set to 'true' when all initialization actions contained in the
	<span class="emphasis"><em>Dejagnu.swf</em></span> file are executed. 
      </p><p>
	Once the module is loaded you will be able to invoke the following functions,
	all registered against the <span class="emphasis"><em>_root</em></span> sprite (effects of <span class="emphasis"><em>_lockroot</em></span>
	untested):
	</p><pre class="programlisting">
	  
	  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.
	  
	</pre><p>
      </p><p>
	Visual traces are lines of text pushed to a textarea defined
	by the <span class="emphasis"><em>Dejagnu.swf</em></span> module. The textarea is
	initially placed at <span class="emphasis"><em>0, 50</em></span> and is
	<span class="emphasis"><em>600x800</em></span> 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
	<span class="emphasis"><em>debugging</em></span> trace (call to the trace
	function). The latter will be used by the testing framework. 
      </p><p>
	See section <a class="link" href="#writing_test_runners" title="Writing Test Runners">Writing Test Runners</a>
	for information about writing a test runners for your self-contained tests.
      </p></div><div class="sect2" title="Writing Test Runners"><div class="titlepage"><div><div><h3 class="title"><a name="writing_test_runners"></a>Writing Test Runners</h3></div></div></div><p>
	Test runners are executables that run one or more tests,
	writing results in Dejagnu form to standard output.
      </p><p>
	The Dejagnu form uses a standard set of labels when printing test 
	results.  These are:
	</p><div class="informaltable"><table border="1" width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
		  <p>Label</p>
		</th><th valign="top">
		  <p>Meaning</p>
		</th></tr></thead><tbody><tr><td align="left" valign="top">
		  <p>PASSED</p>
		</td><td align="left" valign="top">
		  <p>The test succeeded.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>FAILED</p>
		</td><td align="left" valign="top">
		  <p>The test failed.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>XPASSED</p>
		</td><td align="left" valign="top">
		  <p>The test succeeded, but was expected to fail.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>XFAILED</p>
		</td><td align="left" valign="top">
		  <p>The test failed, and was expected to fail.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>UNRESOLVED</p>
		</td><td align="left" valign="top">
		  <p>The results of the test could not be automatically 
		  parsed.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>UNTESTED</p>
		</td><td align="left" valign="top">
		  <p>This test case is not complete.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>UNSUPPORTED</p>
		</td><td align="left" valign="top">
		  <p>The test case relies on a conditional feature which 
		  is not present in your environment.</p>
		</td></tr></tbody></table></div><p>
      </p><p>
	The following labels may also appear:
	</p><div class="informaltable"><table border="1" width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
		  <p>Label</p>
		</th><th valign="top">
		  <p>Meaning</p>
		</th></tr></thead><tbody><tr><td align="left" valign="top">
		  <p>ERROR</p>
		</td><td align="left" valign="top">
		  <p>There was a serious error in running the test. </p>
		</td></tr><tr><td align="left" valign="top">
		  <p>WARNING</p>
		</td><td align="left" valign="top">
		  <p>There may have been a problem with running the
		  test.</p>
		</td></tr><tr><td align="left" valign="top">
		  <p>NOTE</p>
		</td><td align="left" valign="top">
		  <p>There was some additional information given about
		  the test.</p>
		</td></tr></tbody></table></div><p>
      </p><div class="sect3" title="Using the generic test runner for self-contained SWF tests"><div class="titlepage"><div><div><h4 class="title"><a name="generic_test_runner"></a>Using the generic test runner for self-contained SWF tests</h4></div></div></div><p>
	  The simplest test runner is one that simply invokes <span class="application">Gnash</span>
	  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 <span class="application">Gnash</span> in verbose mode this movie will behave
	  as a compliant "Test Runner".
	</p><p>
	  A generator for simple test runners can be found in
	  <span class="emphasis"><em>testsuite/generic-testrunner.sh</em></span>.
	  The script can be invoked by passing it <span class="emphasis"><em>$(top_builddir)</em></span>
	  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:
	  </p><pre class="programlisting">
	    MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
	    sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf &gt; $@
	    chmod +x $@
	  </pre><p>
	</p><p>
	  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:
	  </p><pre class="programlisting">
	    MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
	    sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir) MyTest.swf &gt; $@
	    chmod +x $@
	  </pre><p>
	</p><p>
	  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.
	  </p><pre class="programlisting">
	    MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
	    sh $(srcdir)/../generic-testrunner.sh -f10 $(top_builddir) MyTest.swf &gt; $@
	    chmod +x $@
	  </pre><p>
	  When both -f and -r are given, the first exit condition reached will take effect.
	</p></div><div class="sect3" title="Writing Movie testers"><div class="titlepage"><div><div><h4 class="title"><a name="writing_movie_testers"></a>Writing Movie testers</h4></div></div></div><p>
	  There are some parts of <span class="application">Gnash</span> that can NOT be tested
	  by only using ActionScript tests. Examples include: frame
	  advancements, actual actions execution, gui events and so on.
	</p><p>
	  In this case you might want to use the MovieTester class to
	  implement a C++ test runner. Be aware that you can <span class="emphasis"><em>mix</em></span> tests in
	  the MovieTester-based class with <span class="emphasis"><em>self-contained</em></span>
	  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.
	</p><p>
	  Movie testers are executables which load an SWF, generate events
	  (both user or system) on it, and check its state using
	  a standard interface.
	</p><p>
	  To help this process a MovieTester class is defined in the
	  testsuite/MovieTester.{h,cpp} files; see Doxygen documentation
	  for more information.
	</p><p>
	  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.
	</p></div></div></div><div class="chapter" title="Chapter 4. Adding New ActionScript Classes"><div class="titlepage"><div><div><h2 class="title"><a name="newclass"></a>Chapter 4. Adding New ActionScript Classes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#prototype">Prototype</a></span></dt><dt><span class="sect1"><a href="#constructor">Constructor</a></span></dt><dt><span class="sect1"><a href="#properties"></a></span></dt></dl></div><p>
      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.
  </p><p>
      A genuine ActionScript 2.0 class comprises a constructor function
      and a prototype object. Classes may have native type information,
      but most do not.
  </p><div class="sect1" title="Prototype"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="prototype"></a>Prototype</h2></div></div></div><p>
      In ActionScript, a prototype is an object that contains
      all the methods that an instantiated object will inherit.
    </p><p>
        In Gnash, the prototype of an ActionScript class, like all other
        objects, is implemented as an <span class="emphasis"><em>as_object</em></span>.
        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:
      </p><pre class="programlisting">
        void
        attachBooleanInterface(as_object&amp; o)
        {
            Global_as&amp; gl = getGlobal(o);
            o.init_member("toString", gl.createFunction(boolean_tostring));
            o.init_member("valueOf", gl.createFunction(boolean_valueof));
        }
      </pre><p>
    </p><p>
      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.
    </p></div><div class="sect1" title="Constructor"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="constructor"></a>Constructor</h2></div></div></div><p>
        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.
    </p><p>
        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.
    </p><p>
        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.
    </p><pre class="programlisting">
        as_value
        movieclip_ctor(const fn_call&amp; fn)
        {
        }
        
        as_value
        class_ctor(const fn_call&amp; fn)
        {
            as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);

            if (fn.nargs) {
                string_table&amp; st = getStringTable(fn);
                this_ptr-&gt;set_member(st.find("property"), fn.arg(0));
            }
            return as_value();
        }
    </pre><p>
        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.
    </p><p>
        Native typing can be accessed in ActionScript callback functions using the
        ensure&lt;&gt; function template:
    </p><pre class="programlisting">
          as_value
          boolean_toString(const fn_call&amp; fn)
          {
              // This ensures that the function can only be called as a
              // member function of a genuine Boolean_as object.
              Boolean_as* b = ensure&lt;IsNativeType&lt;Boolean_as&gt; &gt;(fn);

              return as_value(b.value());
          }
      </pre></div><div class="sect1"><div class="titlepage"></div><p>
        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.
    </p></div></div></div><div class="chapter" title="Chapter 5. Reporting Bugs"><div class="titlepage"><div><div><h2 class="title"><a name="bugreport"></a>Chapter 5. Reporting Bugs</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#bugstep_package">Get a Fresh Binary Package</a></span></dt><dt><span class="sect1"><a href="#bugstep_search">Determine if the bug was previously reported</a></span></dt><dt><span class="sect1"><a href="#bugstep_guidelines">Review the bug writing guidelines</a></span></dt><dt><span class="sect1"><a href="#bugstep_file">Filing a bug report</a></span></dt></dl></div><p>
    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
    <a class="ulink" href="http://savannah.gnu.org" target="_top">http://savannah.gnu.org</a> to manage these reports.
  </p><p>
    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.
  </p><div class="sect1" title="Get a Fresh Binary Package"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bugstep_package"></a>Get a Fresh Binary Package</h2></div></div></div><p>
      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. 
    </p><p>
      You can get a fresh binary package of Gnash, as well as recent 
      source packages from
      <a class="ulink" href="http://www.getgnash.org/packages/" target="_top">
	http://www.getgnash.org/packages
      </a>. 
    </p></div><div class="sect1" title="Determine if the bug was previously reported"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bugstep_search"></a>Determine if the bug was previously reported</h2></div></div></div><p>
      Search the <a class="ulink" href="https://savannah.gnu.org/bugs/?group=gnash" target="_top">Gnash
      bug tracker</a> to see if the bug has already been identified.
    </p><p>
      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.
    </p></div><div class="sect1" title="Review the bug writing guidelines"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bugstep_guidelines"></a>Review the bug writing guidelines</h2></div></div></div><p>
      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:
    </p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p>
	  An overview of the problem;
	</p></li><li class="listitem" style="list-style-type: circle"><p>
	  Instructions on how to replicate the bug;
	</p></li><li class="listitem" style="list-style-type: circle"><p>
	  A description of what happened when you performed the steps
	  to replicate the bug, and what you expected to happen;
	</p></li><li class="listitem" style="list-style-type: circle"><p>
	  Your system information: operating system name and version, as
	  well as the versions of major development dependencies;
	</p></li><li class="listitem" style="list-style-type: circle"><p>
	  The release number or checkout timestamp for the version of Gnash
	  where you observe the problem;
	</p></li><li class="listitem" style="list-style-type: circle"><p>
	  The file <code class="filename">config.log</code>, which should be
	  attached as a file;
	</p></li><li class="listitem" style="list-style-type: circle"><p>
	  A descriptive title.
	</p></li></ul></div><p>
      Include any additional information that you feel might be useful
      to the developers.
    </p></div><div class="sect1" title="Filing a bug report"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bugstep_file"></a>Filing a bug report</h2></div></div></div><p>
      After following the steps described above, you can file a bug report at 
      <a class="ulink" href="https://savannah.gnu.org/bugs/?group=gnash" target="_top">https://savannah.gnu.org/bugs/?group=gnash</a>.
    </p></div></div><div class="chapter" title="Chapter 6. Gnash Extensions"><div class="titlepage"><div><div><h2 class="title"><a name="extensions"></a>Chapter 6. <span class="application">Gnash</span> Extensions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#newext">Creating A New Extension</a></span></dt><dt><span class="sect1"><a href="#debuext">Debugging An Extension</a></span></dt><dt><span class="sect1"><a href="#inclext">Included Extensions</a></span></dt></dl></div><p>
    <span class="application">Gnash</span> supports the creation of custom extensions to ActionScript. This
    allows you to integrate any conceivable system or library function into
    ActionScript execution.
  </p><p>
      Extensions do not represent a general alteration of the ActionScript
      language. They are designed to allow <span class="application">Gnash</span> to be more
      flexible and powerful where it is required. They allow you to
      customize <span class="application">Gnash</span> 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.
  </p><p>
      Some extensions are distributed with <span class="application">Gnash</span>, mainly to serve
      as an example. Extensions are not enabled by default, both for
      security and compatibility reasons.
  </p><div class="sect1" title="Creating A New Extension"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="newext"></a>Creating A New Extension</h2></div></div></div><p>
      Each new extension should live in its own directory. The
      extensions included in <span class="application">Gnash</span> are all in the
      <span class="emphasis"><em>gnash/extensions</em></span> directory. Creating an extension
      requires a Makefile.am,
    </p><p>
      If you are adding this extension to the <span class="application">Gnash</span> 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
      <span class="emphasis"><em>configure.ac</em></span> so the new directory will be
      configured along with the rest of <span class="application">Gnash</span>.
    </p><p>
      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 <span class="emphasis"><em>check_PROGRAMS</em></span>
      variable so that "make check" works.
    </p><p>
      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 <span class="application">Gnash</span>.
    </p><div class="sect1" title="Crafting an Extension"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="craftext"></a>Crafting an Extension</h2></div></div></div><p>
          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.
      </p><p>
          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:
      </p><pre class="programlisting">
	      void extension_init(as_object&amp; where, const ObjectURI&amp; uri);
      </pre><p>
          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.
      </p><p>
          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:
      </p><pre class="programlisting">
          void
          extension_init(as_object&amp; where, const ObjectURI&amp; uri) 
          {
              // Get a reference to the global object.
              Global_as&amp; gl = getGlobal(where);

              // Create a prototype object
              as_object* proto = createObject(gl);

              // Create the class
              as_object* cl = gl.createClass(&amp;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);
          }
      </pre><p>
          You will notice three functions in the example above that need
          definition. The first two are attachInterface() and
          attachStaticInterface(). This is a convention
          in <span class="application">Gnash</span> 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:
      </p><pre class="programlisting">
          void
          attachInterface(as_object&amp; obj)
          {
              Global_as&amp; gl = getGlobal(obj);
              obj.init_member("ext1", gl.createFunction(&amp;extension_ext1));
          }
      </pre><p>
          This attaches a function called ext1 to the Extension class
          prototype. When ext1 is called in ActionScript, <span class="application">Gnash</span> 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.
      </p><p>
          The attachStaticInterface() function looks identical:
      </p><pre class="programlisting">
          void
          attachStaticInterface(as_object&amp; obj)
          {
              Global_as&amp; gl = getGlobal(obj);
              obj.init_member("static1", gl.createFunction(&amp;extension_static1));
          }
      </pre><p>
          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:
      </p><pre class="programlisting">
          Extension.static();
      </pre><p>
          The other undefined function is extension_ctor. Like extension_ext1,
          this is an ActionScript callback function. Such functions have the
          signature:
      </p><pre class="programlisting">
          as_value extension_ctor(const fn_call&amp; fn);
      </pre><p>
          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.
      </p><p>
          The function extension_static is the simplest function. A possible
          implementation is as follows:
      </p><pre class="programlisting">
          as_value
          extension_static(const fn_call&amp; 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);
          }
      </pre><p>
          The member function implementation extension_ext1 is barely more
          complex. It could look like this:
      </p><pre class="programlisting">
          as_value extension_ext1(const fn_call&amp; 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&lt;ValidThis&gt;(fn);

              // Reject any calls with no arguments.
              if (!fn.nargs) return as_value();

              const as_value&amp; arg0 = fn.arg(0);

              // The string table manages all strings; we refer to strings
              // by their index in the table.
              string_table&amp; st = getStringTable(fn);

              // Set a member named "property" on the object to the value of
              // the first argument.
              this_ptr-&gt;set_member(st.find("property"), arg0);

              // This is the return value of the function.
              return as_value("return value");
          }
      </pre><p>
          It is not a very useful function. In ActionScript, this definition
          will have the following effect:
      </p><pre class="programlisting">
          var e = new Extension();
          var i = e.ext1(8);
          trace(e.property) // traces "8"
          trace(i) // traces "return value"
      </pre><p>
          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.
      </p><pre class="programlisting">
          as_value
          extension_ctor(const fn_call&amp; fn)
          {
              // When called as a constructor, there is always a "this" object
              as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);

              // The init_member function will never replace an existing
              // property.
              this_ptr-&gt;init_member("myProperty", true);

              // A constructor function must not return anything.
              return as_value();
          }
      </pre><p>
          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):
      </p><pre class="programlisting">
          as_value extension_ctor(const fn_call&amp; fn)
          {
          }
      </pre><p>
          If you have defined all the callback functions in the way
          described above, you can simplify the class registration. <span class="application">Gnash</span>
          provides a convenience function to register a built-in class. In
          this case, your entry function would look like this:
      </p><pre class="programlisting">
          void
          extension_init(as_object&amp; where, const ObjectURI&amp; uri) 
          {
              string_table&amp; st = getStringTable(where);
              registerBuiltinClass(where, extension_ctor, attachInterface,
                  0, st.find("Extension"));
          }
      </pre><p>
          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:
      </p><pre class="programlisting">
          #include "Relay.h"
          #include &lt;complex&gt;

          class Complex : public Relay
          {
          public:
              typedef std::complex&lt;double&gt; type;
              Complex(type c = type()) : _c(c) {}
              type _c;
          };
      </pre><p>
          Using this Relay involves two steps: attaching it, and accessing
          it. Relays must be attached in the constructor:
      </p><pre class="programlisting">
          as_value extension_ctor(const fn_call&amp; fn)
          {
              as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);
              this_ptr-&gt;setRelay(new Complex())
          }
      </pre><p>
          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:
      </p><pre class="programlisting">
          as_value
          extension_toString(const fn_call&amp; fn)
          {
              // This ensures that the function can only be called as a
              // member function of a genuine Complex object.
              Complex* c = ensure&lt;IsNativeType&lt;Complex&gt; &gt;(fn);

              std::ostringstream s;
              s &lt;&lt; "real:" &lt;&lt; c.real() &lt;&lt; ",imag: &lt;&lt; c.imag();
              // This is the return value of the function.
              return as_value(s.str());
          }
      </pre></div></div><div class="sect1" title="Debugging An Extension"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="debuext"></a>Debugging An Extension</h2></div></div></div><p>
      You can resort to the time honored technique of creating a
      loop before the point you want to set a breakpoint for. <span class="application">Gnash</span>
      will stop playing the movie at this point, and then you can
      externally attach GDB to the running process, or type
      <span class="emphasis"><em>^C</em></span> to drop into the GDB command console.
    </p><pre class="programlisting">
      bool stall = true;
      while (stall) {
          sleep 1;
      }
    </pre><p>
      Once you have set the breakpoints you want, reset the value of
      the <span class="emphasis"><em>stall</em></span> variable to break out of the
      loop, and the SWF movie will then continue playing.
    </p><pre class="programlisting">
      (gdb) set variable stall = false;
      continue
    </pre></div><div class="sect1" title="Included Extensions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="inclext"></a>Included Extensions</h2></div></div></div><p>
      <span class="application">Gnash</span> has some extensions included in the distribution. This is
      mostly because they were written by the <span class="application">Gnash</span> team. Extensions
      can be external to gnash, <span class="application">Gnash</span> needs no compiled in knowledge
      to load an extension file.
    </p><div class="sect3" title="Gtk Extension"><div class="titlepage"><div><div><h4 class="title"><a name="gtkext"></a>Gtk Extension</h4></div></div></div><p>
    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.
  </p><div class="variablelist"><dl><dt><span class="term">window_new</span></dt><dd><p>
	  Create a new window.
	</p></dd><dt><span class="term">signal_connect</span></dt><dd><p>
	  Add an event handler to a widget.
	</p></dd><dt><span class="term">container_set_border_width</span></dt><dd><p>
	  Set the width of the window border.
	</p></dd><dt><span class="term">button_new_with_label</span></dt><dd><p>
	  Create a new button and give it the specified label.
	</p></dd><dt><span class="term">signal_connect_swapped</span></dt><dd><p>
	  Swap signals. Commonly used for <span class="emphasis"><em>delete</em></span> event handling.
	</p></dd><dt><span class="term">container_add</span></dt><dd><p>
	      Add one widget to another as a child.
	    </p></dd><dt><span class="term">widget_show</span></dt><dd><p>
	  Display the widget on the screen.
	</p></dd><dt><span class="term">main</span></dt><dd><p>
	  Start the main GTK event loop. This function does not return.
	</p></dd></dl></div></div><div class="sect3" title="File I/O Extension"><div class="titlepage"><div><div><h4 class="title"><a name="fileioext"></a>File I/O Extension</h4></div></div></div><p>
    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.
  </p><div class="variablelist"><dl><dt><span class="term">fopen</span></dt><dd><p>
	  Open the file.
	</p></dd><dt><span class="term">fread</span></dt><dd><p>
	  Read a series of bytes from the opened file.
	</p></dd><dt><span class="term">fgetc</span></dt><dd><p>
	  Read a single byte from the opened file.
	</p></dd><dt><span class="term">fgets</span></dt><dd><p>
	  Read a single line until a Carriage Return from the opened file.
	</p></dd><dt><span class="term">gets</span></dt><dd><p>
	  Read a single line from the standard in.
	</p></dd><dt><span class="term">getchar</span></dt><dd><p>
	  Read a single character from the standard in.
	</p></dd><dt><span class="term">fwrite</span></dt><dd><p>
	</p></dd><dt><span class="term">fputc</span></dt><dd><p>
	  Write a single character to the opened file.
	</p></dd><dt><span class="term">fputs</span></dt><dd><p>
	  Write a single line to the opened file.
	</p></dd><dt><span class="term">puts</span></dt><dd><p>
	  Write a single line to standard out..
	</p></dd><dt><span class="term">putchar</span></dt><dd><p>
	  Write a single character to standard out..
	</p></dd><dt><span class="term">fflush</span></dt><dd><p>
	  Flush the current opened file to disk.
	</p></dd><dt><span class="term">fseek</span></dt><dd><p>
	  Seek to a location within the opened file.
	</p></dd><dt><span class="term">ftell</span></dt><dd><p>
	  Report the current position within the opened file.
	</p></dd><dt><span class="term">fclose</span></dt><dd><p>
	  Close the opened file.
	</p></dd></dl></div></div><div class="sect3" title="MySQL Extension"><div class="titlepage"><div><div><h4 class="title"><a name="mysqlext"></a>MySQL Extension</h4></div></div></div><p>
    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.
  </p><div class="variablelist"><dl><dt><span class="term">connect</span></dt><dd><p>
	  Connect to a MySQL database.
	</p></dd><dt><span class="term">qetData</span></dt><dd><p>
	  Get data from the database.
	</p></dd><dt><span class="term">disconnect</span></dt><dd><p>
	  Disconnect from a MySQL database.
	</p></dd><dt><span class="term">query</span></dt><dd><p>
	  Execute an SQL query to the database.
	</p></dd><dt><span class="term">fetch_row</span></dt><dd><p>
	  Fetch a row from the query results.
	</p></dd><dt><span class="term">num_fields</span></dt><dd><p>
	</p></dd><dt><span class="term">free_result</span></dt><dd><p>
	  Free the results of a query.
	</p></dd><dt><span class="term">store_results</span></dt><dd><p>
	  Store the results of a query.
	</p></dd></dl></div></div></div></div><div class="chapter" title="Chapter 7. RTMP Protocol"><div class="titlepage"><div><div><h2 class="title"><a name="rtmp"></a>Chapter 7. RTMP Protocol</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#amf">AMF Format</a></span></dt></dl></div><p>
    This document is based mostly on my own reverse engineering of the
    RTMP protocol and AMF format. <span class="emphasis"><em>tcpdump</em></span> and
    <span class="emphasis"><em>ethereal</em></span> are your friend. Some additional info that got
    me started was from the <a class="ulink" href="http://www.osflash.org/red5" target="_top">Red5</a>
    project. <span class="emphasis"><em>Red5</em></span> 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.
  </p><p>
    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.
  </p><p>
    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.
  </p><p>
    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.
  </p><p>
    The basics of the RTMP protocol are as follows. All communications
    are initiated by the client.
    </p><div class="mediaobject" align="center"><img src="images/rtmp.png" align="middle"></div><p>
  </p><p>
    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.
  </p><p>
    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.
  </p><p>
    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.
  </p><p>
    The first AMF packet sent to the server contains the
    <span class="emphasis"><em>connect</em></span> 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.
  </p><p>
    The second packet is the <span class="emphasis"><em>NetConnection</em></span> object from
    the client. This ActionScript class is used by the SWF movie to
    create the network connection to the server.
  </p><p>
    The third packet is the <span class="emphasis"><em>NetStream</em></span> object from the
    client. This is the ActionScript class used to specify the file to
    be streamed by the server.
  </p><p>
    The RTMP packet for our example looks like this:
   
    </p><pre class="programlisting">
      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
    </pre><p>
    
    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.
  </p><p>
    The RTMP header is first, followed by the connect message as an
    ASCII string as the message body. The following AMF packet is the
    <span class="emphasis"><em>NetConnection</em></span> 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.
  </p><p>
    The third packet is the one from <span class="emphasis"><em>NetStream</em></span>, which
    specifies the URL used for the movie, followed by the user name
    for a semblance of security.
  </p><p>
    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.
  </p><p>
    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.

    </p><div class="variablelist"><dl><dt><span class="term">00</span></dt><dd><p>
 	    This specifies the header contains 12 bytes, including
	    this one.
	  </p></dd><dt><span class="term">01</span></dt><dd><p>
 	    This specifies the header contains 8 bytes, including this
	    one.
	  </p></dd><dt><span class="term">02</span></dt><dd><p>
 	    This specifies the header contains 4 bytes, including this
	    one.
	  </p></dd><dt><span class="term">03</span></dt><dd><p>
 	    This specifies the header contains 1 byte, so this is the
	    complete header.
	  </p></dd></dl></div><p>
  </p><p>
    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.
  </p><p>
    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.
  </p><p>
    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.
  </p><p>
    For messages with an 8 byte or larger header, the next byte is the
    type of the AMF object.
    
    </p><div class="variablelist"><dl><dt><span class="term">0x3</span></dt><dd><p>
	    This specifies the content type of the RTMP packet is the
	    number of bytes read. This is used to start the RTMP
	    connection.
	  </p></dd><dt><span class="term">0x4</span></dt><dd><p>
	    This specifies the content type of the RTMP message is a
	    <span class="emphasis"><em>ping</em></span> packet.
	  </p></dd><dt><span class="term">0x5</span></dt><dd><p>
	    This specifies the content type of the RTMP message is
	    server response of some type.
	  </p></dd><dt><span class="term">0x6</span></dt><dd><p>
	    This specifies the content type of the RTMP packet is
	    client request of some type.
	  </p></dd><dt><span class="term">0x8</span></dt><dd><p>
	    This specifies the content type of the RTMP packet is an
	    audio message.
	  </p></dd><dt><span class="term">0x9</span></dt><dd><p>
	    This specifies the content type of the RTMP message is a
	    video packet.
	  </p></dd><dt><span class="term">0x12</span></dt><dd><p>
	    This specifies the content type of the RTMP message is
	    notify. 
	  </p></dd><dt><span class="term">0x13</span></dt><dd><p>
	    This specifies the content type of the RTMP message is
	    shared object.
	  </p></dd><dt><span class="term">0x14</span></dt><dd><p>
	    This specifies the content type of the RTMP message is
	    remote procedure call. This invokes the method of a SWF
	    class remotely.
	  </p></dd></dl></div><p>     
  
  </p><p>
    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.
  </p><p>
    The values of the initial type byte are:
    </p><div class="variablelist"><dl><dt><span class="term">0x0</span></dt><dd><p>
	    This specifies the data in the AMF packet is a numeric
	    value. All numeric values in SWF are 64 bit,
	    <span class="emphasis"><em>big-endian</em></span>.
	  </p></dd><dt><span class="term">0x1</span></dt><dd><p>
	    This specifies the data in the AMF packet is a boolean
	    value.
	  </p></dd><dt><span class="term">0x2</span></dt><dd><p>
	    This specifies the data in the AMF packet is an
	    <span class="emphasis"><em>ASCII</em></span> string. 
	  </p></dd><dt><span class="term">0x3</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">0x4</span></dt><dd><p>
	    This specifies the data in the AMF packet is a SWF
	    movie, ie. another SWF movie.
	  </p></dd><dt><span class="term">0x5</span></dt><dd><p>
	    This specifies the data in the AMF packet is a NULL
	    value. NULL is often used as the return code from calling
	    SWF functions.
	  </p></dd><dt><span class="term">0x6</span></dt><dd><p>
	    This specifies the data in the AMF packet is a
	    undefined. This is also used as the return code from
	    calling SWF functions.
	  </p></dd><dt><span class="term">0x7</span></dt><dd><p>
	    This specifies the data in the AMF packet is a reference.
	  </p></dd><dt><span class="term">0x8</span></dt><dd><p>
	    This specifies the data in the AMF packet is a ECMA
	    array.
	  </p></dd><dt><span class="term">0x9</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">0xa</span></dt><dd><p>
	    This specifies the data in the AMF packet is a Strict
	    array.
	  </p></dd><dt><span class="term">0xb</span></dt><dd><p>
	    This specifies the data in the AMF packet is a date.
	  </p></dd><dt><span class="term">0xc</span></dt><dd><p>
	    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 <span class="emphasis"><em>ASCII</em></span>
	    fonts.
	  </p></dd><dt><span class="term">0xd</span></dt><dd><p>
	    This specifies the data in the AMF packet is a an
	    unsupported feature.
	  </p></dd><dt><span class="term">0xe</span></dt><dd><p>
	    This specifies the data in the AMF packet is a record
	    set.
	  </p></dd><dt><span class="term">0xf</span></dt><dd><p>
	    This specifies the data in the AMF packet is a AML
	    object. XML objects are then parsed by the
	    <span class="emphasis"><em>XML</em></span> ActionScript class.
	  </p></dd><dt><span class="term">0x10</span></dt><dd><p>
	    This specifies the data in the AMF packet is a typed object.
	  </p></dd></dl></div><p>
    
  </p><p>
    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. 
  </p><p>
    Multiple AMF streams can be contained in a single RTMP messages,
    so it's important to check the index of each AMF packet.
  </p><p>
    An example RTMP header might look like this. (spaces added between
    fields for clarity) All the numbers are in hex.

    </p><pre class="screen">
      03 000019 0000c9 14 000000000
    </pre><p>
    
    </p><div class="variablelist"><dl><dt><span class="term">03</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">000019</span></dt><dd><p>
	    These 3 bytes currently have an unknown purpose.
	  </p></dd><dt><span class="term">000c9</span></dt><dd><p>
	    Since this example has a 12 byte header, this is the size
	    of the RTMP message, in this case 201 bytes.
	  </p></dd><dt><span class="term">14</span></dt><dd><p>
	    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).
	  </p></dd><dt><span class="term">00000000</span></dt><dd><p>
	    The source is the NetConnection object used to start this
	    connection.
	  </p></dd></dl></div><p>

  </p><div class="sect1" title="AMF Format"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="amf"></a>AMF Format</h2></div></div></div><p>
    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.
  </p><p>
    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.
  </p><p>
    The body of an AMF packet may look something like this
    example. The spaces have been added for clarity.
    
    </p><pre class="screen">
      02  0007 636f6e6e656374
    </pre><p>

    </p><div class="variablelist"><dl><dt><span class="term">02</span></dt><dd><p>
	    This is a single byte header. The value of the first 2
	    bits is 0x3, and the AMF index is also 0x3.
	  </p></dd><dt><span class="term">0007</span></dt><dd><p>
	    This is the length in bytes of the string.
	  </p></dd><dt><span class="term">63 6f 6e 6e 65 63 74</span></dt><dd><p>
	    This is the string. Note that there is no null terminator
	    since the length is specified.
	  </p></dd></dl></div><p>

  </p></div></div><div class="chapter" title="Chapter 8. Mozilla/Firefox NPAPI Plugin"><div class="titlepage"><div><div><h2 class="title"><a name="nsapi"></a>Chapter 8. Mozilla/Firefox NPAPI Plugin</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#plugincapi">Plugin C API</a></span></dt><dt><span class="sect1"><a href="#plugincppapi">Plugin C++ API</a></span></dt><dt><span class="sect1"><a href="#glthread">OpenGL and Threads</a></span></dt><dt><span class="sect1"><a href="#eventhandle">Plugin Event Handling</a></span></dt></dl></div><p>
    The Mozilla SDK has two API layers for plugins. The older layer is
    documented in the <a class="ulink" href="http://www.gnu.org/software/gnash/manual/plugin.pdf" target="_top">
    Geeko Plugin API Reference</a>, 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.
  </p><p>
    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.
  </p><p>
    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.
  </p><div class="sect1" title="Plugin C API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="plugincapi"></a>Plugin C API</h2></div></div></div><p>
      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 <span class="emphasis"><em>plugin/mozilla-sdk</em></span>. 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.
    </p><p>
      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.
    </p><div class="variablelist"><dl><dt><span class="term">NS_PluginInitialize</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">NS_NewPluginInstance</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">NS_DestroyPluginInstance</span></dt><dd><p>
	    This destroys our instantiated object when the browser is
	    done.
	  </p></dd><dt><span class="term">NS_PluginShutdown</span></dt><dd><p>
	    This is called when a plugin is shut down, so this is
	    where all the one time only shutdown stuff goes.
	  </p></dd><dt><span class="term">NPP_GetMIMEDescription</span></dt><dd><p>
	    This is called to get the MIME types the plugin supports.
	  </p></dd><dt><span class="term">NS_PluginGetValue</span></dt><dd><p>
	    This is used by Firefox to query information from the
	    plugin, like the supported MIME type, the version number,
	    and a description.
	  </p></dd></dl></div></div><div class="sect1" title="Plugin C++ API"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="plugincppapi"></a>Plugin C++ API</h2></div></div></div><p>
      The higher level layer is the one we are most concerned
      with. This is an instantiation of the
      <span class="emphasis"><em>nsPluginInstanceBase</em></span> 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.
    </p><p>
      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, <span class="emphasis"><em>nsPluginInstance::init()</em></span> and
      <span class="emphasis"><em>nsPluginInstance::SetWindow()</em></span> are called more than
      once, so the plugin must protect against actions that could be
      destructive.
    </p><div class="variablelist"><dl><dt><span class="term">nsPluginInstance::nsPluginInstance</span></dt><dd><p>
	    Create a new plugin object.
	  </p></dd><dt><span class="term">nsPluginInstance::init</span></dt><dd><p>
	    This methods initializes the plugin object, and is
	    called for every movie which gets played. This is where
	    the thread-specific information goes.
	  </p></dd><dt><span class="term">nsPluginInstance::SetWindow</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">nsPluginInstance::NewStream</span></dt><dd><p>
	    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/&amp;shickwave=http%3a//www.sickwave.com&amp;gblst=http%3a//gbst.sickwave.com/gb/gbHome.jsp&amp;known=0 ../flash/gui.swf?ip_addr=foobar.com&amp;ip_port=3660&amp;show_cursor=true&amp;path_prefix=../flash/&amp;trapallkeys=true"
	    So this is where we parse the URL to get all the options
	    passed in when invoking the plugin.
	  </p></dd><dt><span class="term">nsPluginInstance::Write</span></dt><dd><p>
	    Read the data stream from Mozilla/Firefox.  For now we
	    read the bytes and write them to a disk file.
	  </p></dd><dt><span class="term">nsPluginInstance::WriteReady</span></dt><dd><p>
	    Return how many bytes we can read into the buffer.
	  </p></dd><dt><span class="term">nsPluginInstance::DestroyStream</span></dt><dd><p>
	    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.
	  </p></dd><dt><span class="term">nsPluginInstance::shut</span></dt><dd><p>
	    This is where the movie playing specific shutdown emphasis goes.
	  </p></dd><dt><span class="term">nsPluginInstance::~nsPluginInstance</span></dt><dd><p>
	    This destroys our plugin object.
	  </p></dd><dt><span class="term">NS_PluginInitialize::initGL</span></dt><dd><p>
	    This is a Gnash internal function that sets up OpenGL.
	  </p></dd><dt><span class="term">NS_PluginInitialize::destroyContext</span></dt><dd><p>
	    This is a Gnash internal function that destroys a GLX
	    context. 
	  </p></dd><dt><span class="term">nsPluginInstance::getVersion</span></dt><dd><p>
	    This returns the version of Mozilla this plugin supports.
	  </p></dd><dt><span class="term">nsPluginInstance::GetValue</span></dt><dd><p>
	    This returns information to the browser about the plugin's
	    name and description.
	  </p></dd><dt><span class="term">nsPluginInstance::URLNotify</span></dt><dd><p>
	  </p></dd></dl></div></div><div class="sect1" title="OpenGL and Threads"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="glthread"></a>OpenGL and Threads</h2></div></div></div><p>
      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.
    </p><p>
      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 <span class="emphasis"><em>XLockDisplay()</em></span> and
      <span class="emphasis"><em>XUnlockDisplay()</em></span>. A connection to the X11
      server is opened for every instantiation of the plugin using
      <span class="emphasis"><em>XOpenDisplay()</em></span>.
    </p><p>
      The <span class="emphasis"><em>GLX Context</em></span> 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 <span class="emphasis"><em>glXCreateContext()</em></span>,
      and then later destroyed by using <span class="emphasis"><em>glXDestroyContext()</em></span>.
      When swapping threads, the context is changed using
      <span class="emphasis"><em>glXMakeCurrent()</em></span>.
    </p><p>
      All the emphasis that directly accesses a GLX context or the X11
      display must be wrapped with a mutex.
    </p></div><div class="sect1" title="Plugin Event Handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eventhandle"></a>Plugin Event Handling</h2></div></div></div><p>
      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.
    </p><p>
      It is also possible to disable the <span class="emphasis"><em>GTK</em></span> support so
      only the older <span class="emphasis"><em>SDL</em></span> 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
      <span class="emphasis"><em>--disable-glext</em></span>
    </p><p>
      
    </p></div></div><div class="sect1" title="Appendix"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="appendix"></a>Appendix</h2></div></div></div><div class="sect2" title="Code Style"><div class="titlepage"><div><div><h3 class="title"><a name="codestyle"></a>Code Style</h3></div></div></div><p>
      I know any discussion of coding styles leads to strong opinions,
      so I'll state simply I follow the <a class="ulink" href="http://www.gnu.org/prep/standards/standards.html" target="_top">GNU
      Coding Standards</a>. Where there is some flexibility as to
      the location of braces, I prefer mine on the end of a line when
      using an <span class="emphasis"><em>if</em></span>, <span class="emphasis"><em>while</em></span>, or <span class="emphasis"><em>do</em></span>
      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 <span class="emphasis"><em>if</em></span> statements, even if they're one
      liners.
    </p><p>
      Here's my tweaked style settings for <span class="emphasis"><em>Emacs</em></span>, the one
      true editor to rule them all.

      </p><pre class="programlisting">
      (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&amp;comma-criteria
		 'c-semi&amp;comma-no-newlines-before-nonblanks)
    (add-to-list 'c-hanging-semi&amp;comma-criteria
		 'c-semi&amp;comma-no-newlines-for-oneline-inliners)
;    (knr-argdecl-intro . -)
    (c-echo-syntactic-information-p . t)
    )
  "My GNU Programming Style")
    </pre><p>

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

      </p><pre class="programlisting">
	counter++;		// increment counter
      </pre><p>
      
      Gnash also uses <a class="ulink" href="http://www.doxygen.org" target="_top">Doxygen</a> 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.
    </p><p>
      <span class="emphasis"><em>Doxygen</em></span> style comments for <span class="emphasis"><em>C++</em></span> code involves
      simply using three slashes <span class="emphasis"><em>///</em></span> instead of the
      standard two slashes <span class="emphasis"><em>//</em></span> used for C++
      comments. Here's a short comment block for the
      <span class="emphasis"><em>XML::cloneNode()</em></span> method:

      </p><pre class="programlisting">
	/// \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 &amp;
	XML::cloneNode(XMLNode &amp;newnode, bool deep) {
	...
	}
      </pre><p> 
    </p><p>
      The <span class="emphasis"><em>\brief</em></span> 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.
    </p></div></div><div class="chapter" title="Chapter 9. Authors"><div class="titlepage"><div><div><h2 class="title"><a name="authors"></a>Chapter 9. Authors</h2></div></div></div><p>
        <span class="application">Gnash</span> 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
        <code class="email">&lt;<a class="email" href="mailto:gnash-dev@gnu.org">gnash-dev@gnu.org</a>&gt;</code>. Past and sometimes current
        developers are Tomas Groth and Markus Gothe.
    </p><p>
        <span class="application">Gnash</span> was initially derived from <span class="application">GameSWF</span>.
        <span class="application">GameSWF</span> is maintained by
        Thatcher Ulrich <code class="email">&lt;<a class="email" href="mailto:tu@tulrich.com">tu@tulrich.com</a>&gt;</code>.  The following
        people contributed to <span class="application">GameSWF</span>:
        Mike Shaver, Thierry Berger-Perrin,
	Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit, 
        and Rob Savoye.
    </p></div><div class="appendix" title="Appendix A. GNU Free Documentation License"><div class="titlepage"><div><div><h2 class="title"><a name="fdl"></a>Appendix A. GNU Free Documentation License</h2></div><div><p class="releaseinfo">
      Version 1.1, March 2000
    </p></div><div><p class="copyright">Copyright © 2000 Free Software Foundation, Inc.</p></div><div><div class="legalnotice" title="Legal Notice"><a name="fdl-legalnotice"></a><p>
	</p><div class="address"><p>Free Software Foundation, Inc. <span class="street">59 Temple Place, <br>
        Suite 330</span>, <span class="city">Boston</span>, <span class="state">MA</span>  <br>
        <span class="postcode">02111-1307</span>  <span class="country">USA</span></p></div><p> 
	Everyone is permitted to copy and distribute verbatim copies of this 
        license document, but changing it is not allowed.
      </p></div></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#fdl-preamble">0. PREAMBLE</a></span></dt><dt><span class="sect1"><a href="#fdl-section1">1. APPLICABILITY AND DEFINITIONS</a></span></dt><dt><span class="sect1"><a href="#fdl-section2">2. VERBATIM COPYING</a></span></dt><dt><span class="sect1"><a href="#fdl-section3">3. COPYING IN QUANTITY</a></span></dt><dt><span class="sect1"><a href="#fdl-section4">4. MODIFICATIONS</a></span></dt><dt><span class="sect1"><a href="#fdl-section5">5. COMBINING DOCUMENTS</a></span></dt><dt><span class="sect1"><a href="#fdl-section6">6. COLLECTIONS OF DOCUMENTS</a></span></dt><dt><span class="sect1"><a href="#fdl-section7">7. AGGREGATION WITH INDEPENDENT WORKS</a></span></dt><dt><span class="sect1"><a href="#fdl-section8">8. TRANSLATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section9">9. TERMINATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section10">10. FUTURE REVISIONS OF THIS LICENSE</a></span></dt><dt><span class="sect1"><a href="#fdl-using">Addendum</a></span></dt></dl></div><div class="sect1" title="0. PREAMBLE"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-preamble"></a>0. PREAMBLE</h2></div></div></div><p>
      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.
    </p><p>
      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.
    </p><p>
      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.
    </p></div><div class="sect1" title="1. APPLICABILITY AND DEFINITIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section1"></a>1. APPLICABILITY AND DEFINITIONS</h2></div></div></div><p><a name="fdl-document"></a>
      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".
    </p><p><a name="fdl-modified"></a>
      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.
    </p><p><a name="fdl-secondary"></a>
      A "Secondary Section" is a named appendix or a
      front-matter section of the <a class="link" href="#fdl-document">Document</a> 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.
    </p><p><a name="fdl-invariant"></a>
      The "Invariant Sections" are certain <a class="link" href="#fdl-secondary"> Secondary Sections</a> whose titles
      are designated, as being those of Invariant Sections, in the
      notice that says that the <a class="link" href="#fdl-document">Document</a> is released under this
      License.
    </p><p><a name="fdl-cover-texts"></a>
      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 <a class="link" href="#fdl-document">Document</a> is released under this
      License.
    </p><p><a name="fdl-transparent"></a>
      A "Transparent" copy of the <a class="link" href="#fdl-document"> Document</a> 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".
    </p><p>
      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.
    </p><p><a name="fdl-title-page"></a>
      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.
    </p></div><div class="sect1" title="2. VERBATIM COPYING"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section2"></a>2. VERBATIM COPYING</h2></div></div></div><p>
      You may copy and distribute the <a class="link" href="#fdl-document">Document</a> 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 <a class="link" href="#fdl-section3" title="3. COPYING IN QUANTITY">section 3</a>.
    </p><p>
      You may also lend copies, under the same conditions stated
      above, and you may publicly display copies.
    </p></div><div class="sect1" title="3. COPYING IN QUANTITY"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section3"></a>3. COPYING IN QUANTITY</h2></div></div></div><p>
      If you publish printed copies of the <a class="link" href="#fdl-document">Document</a> numbering more than 100,
      and the Document's license notice requires <a class="link" href="#fdl-cover-texts">Cover Texts</a>, 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
      <a class="link" href="#fdl-document">Document</a> and satisfy these
      conditions, can be treated as verbatim copying in other
      respects.
    </p><p>
      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.
    </p><p>
      If you publish or distribute <a class="link" href="#fdl-transparent">Opaque</a> copies of the <a class="link" href="#fdl-document">Document</a> numbering more than 100,
      you must either include a machine-readable <a class="link" href="#fdl-transparent">Transparent</a> 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.
    </p><p>
      It is requested, but not required, that you contact the authors
      of the <a class="link" href="#fdl-document">Document</a> well before
      redistributing any large number of copies, to give them a chance
      to provide you with an updated version of the Document.
    </p></div><div class="sect1" title="4. MODIFICATIONS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section4"></a>4. MODIFICATIONS</h2></div></div></div><p>
      You may copy and distribute a <a class="link" href="#fdl-modified">Modified Version</a> of the <a class="link" href="#fdl-document">Document</a> under the conditions of
      sections <a class="link" href="#fdl-section2" title="2. VERBATIM COPYING">2</a> and <a class="link" href="#fdl-section3" title="3. COPYING IN QUANTITY">3</a> 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:
    </p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p title="A"><b>A. </b>
	    Use in the <a class="link" href="#fdl-title-page">Title
	    Page</a> (and on the covers, if any) a title distinct
	    from that of the <a class="link" href="#fdl-document">Document</a>, 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.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="B"><b>B. </b>
	    List on the <a class="link" href="#fdl-title-page">Title
	    Page</a>, as authors, one or more persons or entities
	    responsible for authorship of the modifications in the
	    <a class="link" href="#fdl-modified">Modified Version</a>,
	    together with at least five of the principal authors of
	    the <a class="link" href="#fdl-document">Document</a> (all of
	    its principal authors, if it has less than five).
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="C"><b>C. </b>
	    State on the <a class="link" href="#fdl-title-page">Title
	    Page</a> the name of the publisher of the <a class="link" href="#fdl-modified">Modified Version</a>, as the
	    publisher.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="D"><b>D. </b>
	    Preserve all the copyright notices of the <a class="link" href="#fdl-document">Document</a>.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="E"><b>E. </b>
	    Add an appropriate copyright notice for your modifications
	    adjacent to the other copyright notices.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="F"><b>F. </b>
	    Include, immediately after the copyright notices, a
	    license notice giving the public permission to use the
	    <a class="link" href="#fdl-modified">Modified Version</a> under
	    the terms of this License, in the form shown in the
	    Addendum below.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="G"><b>G. </b>
	    Preserve in that license notice the full lists of <a class="link" href="#fdl-invariant"> Invariant Sections</a> and
	    required <a class="link" href="#fdl-cover-texts">Cover
	    Texts</a> given in the <a class="link" href="#fdl-document">Document's</a> license notice.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="H"><b>H. </b>
	    Include an unaltered copy of this License.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="I"><b>I. </b>
	    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 <a class="link" href="#fdl-modified">Modified Version </a>as given on
	    the <a class="link" href="#fdl-title-page">Title Page</a>.  If
	    there is no section entitled "History" in the
	    <a class="link" href="#fdl-document">Document</a>, 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.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="J"><b>J. </b>
	    Preserve the network location, if any, given in the <a class="link" href="#fdl-document">Document</a> for public access
	    to a <a class="link" href="#fdl-transparent">Transparent</a>
	    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.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="K"><b>K. </b>
	    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.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="L"><b>L. </b>
	    Preserve all the <a class="link" href="#fdl-invariant">Invariant
	    Sections</a> of the <a class="link" href="#fdl-document">Document</a>, unaltered in their
	    text and in their titles.  Section numbers or the
	    equivalent are not considered part of the section titles.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="M"><b>M. </b>
	    Delete any section entitled
	    "Endorsements". Such a section may not be
	    included in the <a class="link" href="#fdl-modified">Modified
	    Version</a>.
	  </p></li><li class="listitem" style="list-style-type: circle"><p title="N"><b>N. </b>
	    Do not retitle any existing section as
	    "Endorsements" or to conflict in title with
	    any <a class="link" href="#fdl-invariant">Invariant
	    Section</a>.
	  </p></li></ul></div><p>
      If the <a class="link" href="#fdl-modified">Modified Version</a>
      includes new front-matter sections or appendices that qualify as
      <a class="link" href="#fdl-secondary">Secondary Sections</a> 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 <a class="link" href="#fdl-invariant">Invariant Sections</a> in the
      Modified Version's license notice.  These titles must be
      distinct from any other section titles.
    </p><p>
      You may add a section entitled "Endorsements",
      provided it contains nothing but endorsements of your <a class="link" href="#fdl-modified">Modified Version</a> 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.
    </p><p>
      You may add a passage of up to five words as a <a class="link" href="#fdl-cover-texts">Front-Cover Text</a>, and a passage
      of up to 25 words as a <a class="link" href="#fdl-cover-texts">Back-Cover Text</a>, to the end of
      the list of <a class="link" href="#fdl-cover-texts">Cover Texts</a>
      in the <a class="link" href="#fdl-modified">Modified Version</a>.
      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 <a class="link" href="#fdl-document">Document</a>
      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.
    </p><p>
      The author(s) and publisher(s) of the <a class="link" href="#fdl-document">Document</a> do not by this License
      give permission to use their names for publicity for or to
      assert or imply endorsement of any <a class="link" href="#fdl-modified">Modified Version </a>.
    </p></div><div class="sect1" title="5. COMBINING DOCUMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section5"></a>5. COMBINING DOCUMENTS</h2></div></div></div><p>
      You may combine the <a class="link" href="#fdl-document">Document</a>
      with other documents released under this License, under the
      terms defined in <a class="link" href="#fdl-section4" title="4. MODIFICATIONS">section 4</a>
      above for modified versions, provided that you include in the
      combination all of the <a class="link" href="#fdl-invariant">Invariant
      Sections</a> of all of the original documents, unmodified,
      and list them all as Invariant Sections of your combined work in
      its license notice.
    </p><p>
      The combined work need only contain one copy of this License,
      and multiple identical <a class="link" href="#fdl-invariant">Invariant
      Sections</a> 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.
    </p><p>
      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."
    </p></div><div class="sect1" title="6. COLLECTIONS OF DOCUMENTS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section6"></a>6. COLLECTIONS OF DOCUMENTS</h2></div></div></div><p>
      You may make a collection consisting of the <a class="link" href="#fdl-document">Document</a> 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.
    </p><p>
      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.
    </p></div><div class="sect1" title="7. AGGREGATION WITH INDEPENDENT WORKS"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section7"></a>7. AGGREGATION WITH INDEPENDENT WORKS</h2></div></div></div><p>
      A compilation of the <a class="link" href="#fdl-document">Document</a> 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 <a class="link" href="#fdl-modified">Modified Version</a>
      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 <a class="link" href="#fdl-cover-texts">Cover Text</a> requirement of <a class="link" href="#fdl-section3" title="3. COPYING IN QUANTITY">section 3</a> 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.
    </p></div><div class="sect1" title="8. TRANSLATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section8"></a>8. TRANSLATION</h2></div></div></div><p>
      Translation is considered a kind of modification, so you may
      distribute translations of the <a class="link" href="#fdl-document">Document</a> under the terms of <a class="link" href="#fdl-section4" title="4. MODIFICATIONS">section 4</a>. Replacing <a class="link" href="#fdl-invariant"> Invariant Sections</a> 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.
    </p></div><div class="sect1" title="9. TERMINATION"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section9"></a>9. TERMINATION</h2></div></div></div><p>
      You may not copy, modify, sublicense, or distribute the <a class="link" href="#fdl-document">Document</a> 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.
    </p></div><div class="sect1" title="10. FUTURE REVISIONS OF THIS LICENSE"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-section10"></a>10. FUTURE REVISIONS OF THIS LICENSE</h2></div></div></div><p>
      The <a class="ulink" href="http://www.gnu.org/fsf/fsf.html" target="_top">Free Software
      Foundation</a> 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 <a class="ulink" href="http://www.gnu.org/copyleft" target="_top">http://www.gnu.org/copyleft/</a>.
    </p><p>
      Each version of the License is given a distinguishing version
      number. If the <a class="link" href="#fdl-document">Document</a>
      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.
    </p></div><div class="sect1" title="Addendum"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="fdl-using"></a>Addendum</h2></div></div></div><p>
      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:
    </p><div class="blockquote"><blockquote class="blockquote"><p>
	Copyright 2008, Free Software Foundation.
      </p><p>
	Permission is granted to copy, distribute and/or modify this
	document under the terms of the GNU Free Documentation
	License, Version 1.1 or any later version published by the
	Free Software Foundation; with no<a class="link" href="#fdl-invariant">Invariant Sections</a>, with no <a class="link" href="#fdl-cover-texts">Front-Cover Texts</a>,
	and with no <a class="link" href="#fdl-cover-texts">Back-Cover
	Texts</a>. A copy of the license is included in
	the section entitled "GNU Free Documentation License".
      </p></blockquote></div><p>
      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 <a class="ulink" href="http://www.gnu.org/copyleft/gpl.html" target="_top"> GNU General Public
      License</a>, to permit their use in free software.
    </p></div></div></div></body></html>
