doc/C/preformatted/gnashref.html.in

   1 <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">
   2       This manual describes version 0.8.9 of Gnash.
   3     </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>
   4     Permission is granted to copy, distribute and/or modify this document
   5     under the terms of the <a class="link" href="#fdl" title="Appendix A. GNU Free Documentation License"><em class="citetitle">GNU
   6     Free Documentation License</em></a>, Version 1.1 or any later
   7     version published by the Free Software Foundation with no Invariant
   8     Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find
   9     a copy of the GFDL at this
  10     <a class="link" href="#fdl" title="Appendix A. GNU Free Documentation License">link</a> or in the file COPYING-DOCS
  11     distributed with this manual.
  12    </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">
  13       <p class="author">Rob Savoye
  14       <code class="email">&lt;<a class="email" href="mailto:rob@openmedianow.org">rob@openmedianow.org</a>&gt;</code>
  15       The end user parts of the manual have been pulled out of
  16       the original version of the manual, and rewritten. This
  17       is now a reference manual only.
  18       </p>
  19
  20       <p class="publisher">Open Media Now! Foundation</p>
  21     </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>
  22     <span class="application">Gnash</span> is a free SWF movie player.  It is available as a
  23     stand-alone application or as a plugin for several popular
  24     web browsers. It supports playing media from a disk or streaming
  25     over a network connection. Some popular video sharing sites like
  26     YouTube are supported on a wide variety of devices from
  27     embedded ones to modern desktops.
  28   </p><p>
  29     <span class="application">Gnash</span> has a better focus on security, allowing the user tight
  30     control of all network or disk based I/O. Gnash also supports
  31     extending ActionScript by creating your own classes. You can write
  32     wrappers for any development library, and import them into the
  33     player much like Perl or Python does.
  34   </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>
  35       This manual is primarily focused on users interested in how to
  36       get Gnash installed from a package, and basic usage as a web
  37       browser plugin. For more technical details, please refer to the
  38       Gnash Reference manual.
  39     </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>
  40       Gnash is known to compile for most any POSIX and ANSI C++
  41       conforming system if you have all the dependent libraries
  42       installed. Systems we test on, and which Gnash is known to
  43       run on are Ubuntu, Fedora, Debian, Mandriva, OpenBSD, NetBSD, FreeBSD,
  44       Win32, and Darwin (OSX) primarily. Occasionally other platforms
  45       are built, primarily by those distribution maintainers. This
  46       includes BeOS, Haiku, Syllable, OS/2, Solaris, Slackware, and
  47       Gentoo.
  48     </p><p>
  49       Gnash is capable of reading up to SWF v9 files and opcodes,
  50       but primarily supports SWF v7, with better SWF v8 and v9
  51       support under heavy development. Since the 0.8.2 release,
  52       Gnash includes initial parser support for SWF v8 and v9.
  53       Not all ActionScript 2 classes are implemented yet, but all of the
  54       most heavily used ones are. Many ActionScript 2 classes are
  55       partially implemented; there is support for all of the
  56       commonly used methods of each class.
  57     </p><p>
  58       Gnash has implemented about 80% of ActionScript v2.0, and has
  59       begun implementing ActionScript v3.0. Gnash supports the
  60       majority of Flash opcodes up to SWF v9, and a wide
  61       sampling of ActionScript classes for SWF v8.
  62     </p><p>
  63       As ActionScript 3 is a more developed version of
  64       ActionScript 2, many of the same classes work for
  65       both. Support has been added to Gnash's ActionScript library
  66       to support the new ActionScript 3 filters, which get applied
  67       to every class. Implementing ActionScript classes is often the
  68       easiest way for new Gnash developers to make a contribution
  69       without a deep internal knowledge of Gnash.
  70     </p><p>
  71       Gnash has included video support since early 2007, but this is
  72       an ever changing field of reverse engineering. Many of the
  73       popular video sharing sites use SWF v8 or v9, which Gnash
  74       supports imperfectly. This is improving all the
  75       time, so often builds from a development snapshot will work
  76       when using the older release packaged in your distribution
  77       doesn't. You can find daily snapshots of the latest CVS tree
  78       at: <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/" target="_top">
  79       http://www.gnashdev.org/dev_snapshots</a>.
  80     </p><p>
  81       Gnash uses FFmpeg for codecs, so any file supported by Mplayer
  82       should work with Gnash. Gnash supports the loading of patent
  83       free codecs like Ogg Vorbis or Theora from disk based files,
  84       while work is being done to support these codecs when embedded
  85       in a SWF file. FFmpeg contains the codecs used by the current
  86       SWF defintion, FLV, VP6 (ON2), H.263, H.264, and MP3.
  87     </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>
  88       The typical process of building from source will involve
  89       <a class="link" href="#gettingsource" title="Getting The Source">getting the source</a>,
  90       <a class="link" href="#dependencies" title="Code Dependencies">build dependencies</a>,
  91       <a class="link" href="#configure" title="Configuring Gnash">configuration</a>,
  92       <a class="link" href="#compile" title="Compiling the Code">compilation</a>,
  93       <a class="link" href="#runtests" title="Running the Tests">testing</a>, and
  94       <a class="link" href="#install" title="Installation">installation</a>.
  95       A simplified overview of the process would be:
  96       </p><pre class="programlisting">
  97         ./autogen.sh
  98         ./configure
  99         make
 100         make check
 101         make install
 102       </pre><p>
 103     </p><p>
 104       If you are compiling with GCC you will need to use a machine
 105       with at least 128 megabytes of physical RAM; 64MB is not enough for a
 106       couple of the files, even with swap enabled and optimisation turned off.
 107       With less than 512 megabytes available, many build combinations can
 108       still be a long and painful experience.
 109     </p><p>
 110       At present the <span class="application">Gnash</span> source is about 30 MB extracted and configured
 111       and requires a total of about 125 megabytes to compile it.
 112     </p><p>
 113       Continue reading for detailed step-by-step instructions
 114       of the entire procedure.
 115     </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>
 116         Tarballs of official releases can be found in the download area
 117         of the project's GNU Savannah page at
 118         <a class="ulink" href="http://savannah.gnu.org/projects/gnash" target="_top">
 119                     http://savannah.gnu.org/projects/gnash
 120         </a>
 121         or under
 122         <a class="ulink" href="http://ftp.gnu.org/gnu/gnash" target="_top">
 123                     http://ftp.gnu.org/gnu/gnash
 124         </a>
 125       </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>
 126         The latest <span class="application">Gnash</span> development sources are available via git.
 127         Use the following commands to check them out:
 128         </p><pre class="programlisting">
 129         mkdir gnash
 130         cd gnash
 131         git clone git://git.sv.gnu.org/gnash.git
 132         </pre><p>
 133         At any time, other temporary development branches may also
 134         be available. Replace <span class="emphasis"><em>trunk</em></span> with the
 135         branch name to check these out.
 136         You can update your copy from the main
 137         repository using:
 138         </p><pre class="programlisting">
 139           cd trunk
 140           git pull
 141         </pre><p>
 142       </p><p>
 143         If you only have access to the internet via a web proxy,
 144         you will find daily source snapshots of the latest CVS tree in
 145         <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/" target="_top">
 146                     http://www.gnashdev.org/dev_snapshots
 147         </a>
 148       </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>
 149     <span class="application">Gnash</span> has a number of dependencies on other packages.
 150     If you install the dependencies using a package
 151     manager, be certain to install the development versions
 152     of the packages.  The normal versions often lack
 153     the headers <span class="application">Gnash</span> needs to compile.
 154   </p><p>
 155     Some dependencies have other dependencies: for instance, GTK also needs
 156     glib2, atk, and pango to produce a fully linked
 157     executable. Different distributions also use differing
 158     dependencies, sometimes a package will depend on libxml2 on one
 159     system, but libexpat on another.
 160   </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">
 161             Boost is a library of portable C++ classes and
 162             templates.
 163           </td><td align="left">
 164             In <span class="application">Gnash</span>, Boost libraries are used extensively, primarily
 165             boost-gthread and boost-date-time. Boost is used for thread and mutext
 166             handling.
 167           </td><td align="left">
 168             <code class="filename">libboost-thread-dev, libboost-date-time-dev libboost-dev
 169             </code>
 170           </td><td align="left">
 171             <code class="filename">
 172               libboost-thread-devel, libboost-date-time-devel
 173           </code>
 174           </td><td align="left">
 175             <code class="filename">
 176               boost-headers, boost-libs, or just boost
 177           </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">
 178             AGG is the AntiGrain low-level 2D graphics
 179             library.
 180           </td><td align="left">
 181             <span class="application">Gnash</span> requires the installation of at least one
 182             renderer.  AGG is considered the <span class="emphasis"><em>best
 183             supported</em></span> renderer for <span class="application">Gnash</span>.
 184           </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">
 185             OpenGL is a standard specification defining a
 186             cross-language cross-platform API for writing
 187             applications which produce 3D and 2D graphics.
 188             It supports hardware acceleration.
 189             You can download a free implementation from
 190             <a class="ulink" href="http://www.mesa3d.org" target="_top">http://www.mesa3d.org</a>,
 191             although it doesn't support hardware acceleration.
 192           </td><td align="left">
 193             <span class="application">Gnash</span> requires the installation of at least one
 194             renderer. If you don't have a hardware accelerated driver,
 195             you're better off using AGG for the renderer.
 196           </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">
 197             Cairo is a 2D graphics library with support for
 198             multiple output devices.  It will automatically use
 199             graphic card acceleration when available, and has
 200             an experimental OpenGL backend.
 201           </td><td align="left">
 202             <span class="application">Gnash</span> requires the installation of at least one
 203             renderer.  Cairo is considered
 204             the <span class="emphasis"><em>least supported</em></span> renderer
 205             for <span class="application">Gnash</span>.
 206           </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">
 207             GTK is the GIMP Toolkit GUI library used by the GNOME
 208             desktop. It uses Cairo internally. Gtk enables better
 209             integration with Firefox, as well as better event handling
 210             and higher level GUI constructs like menus and dialog
 211             boxes.
 212           </td><td align="left">
 213             <span class="application">Gnash</span> requires the installation of at least one
 214             GUI library.  GTK is considered to be the
 215             <span class="emphasis"><em>best supported</em></span> GUI library
 216             option for <span class="application">Gnash</span>.
 217           </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">
 218             GtkGlExt integrates OpenGL into GTK.
 219           </td><td align="left">
 220             This library is required in order to use
 221             the GTK GUI library in conjunction with the
 222             OpenGL renderer.
 223           </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">
 224             The Simple DirectMedia Layer is a cross-platform
 225             multimedia library which provides abstraction for
 226             audio, graphics, sound and input APIs.
 227             SDL is available from
 228             <a class="ulink" href="http://www.libsdl.org" target="_top">
 229               http://www.libsdl.org</a>.
 230           </td><td align="left">
 231             <span class="application">Gnash</span> requires the installation of at least one
 232             GUI library.  SDL may also be used as a sound
 233             handler regardless of whether it is employed as
 234             a GUI library.  The GUI
 235             library is <span class="emphasis"><em>poorly supported</em></span>
 236             in <span class="application">Gnash</span>, but the sound handler is the
 237             <span class="emphasis"><em>best supported</em></span> in <span class="application">Gnash</span>.
 238           </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">
 239             The Fast Light ToolKit is a portable GUI library
 240             which is intended as a replacement for the SDL GUI.
 241           </td><td align="left">
 242             <span class="application">Gnash</span> requires the installation of at least one
 243             GUI library.  FLTK may be used in conjunction with
 244             the Cairo and AGG renderers.
 245           </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">
 246             Kdelibs is a collection of libraries needed to
 247             compile KDE applications.
 248           </td><td align="left">
 249             <span class="application">Gnash</span> requires the installation of at least one
 250             GUI library.  Kdelibs is also required for the
 251             Kpart plugin for Konqueror.
 252           </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">
 253             Gstreamer is a video handler.
 254           </td><td align="left">
 255             If you would like video playback, you must
 256             install one of the video handlers.
 257           </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">
 258             gst-ffmpeg allows you to use the FFmpeg decoder
 259             with Gstreamer.
 260           </td><td align="left">
 261             This package is required if you would like to
 262             use Gstreamer as a video handler.
 263           </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">
 264             FFmpeg is a video handler.
 265           </td><td align="left">
 266             If you would like video playback, you must
 267             install one of the video handlers. When using the
 268             gstreamer-ffmpeg plugin, ffmpeg doesn't need to be
 269             installed, as it's part of the plugin. For systems
 270             without Gstreamer support, FFmpeg can be used directly.
 271           </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">
 272             <a class="ulink" href="http://www.ijg.org/" target="_top">JPEG</a>
 273             is a lossy image format which is heavily used for images.
 274           </td><td align="left">
 275                   This library is used for reading external JPEGs and JPEG
 276                   data embedded in SWF files.
 277           </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">
 278             <a class="ulink" href="http://www.libpng.org/pub/png/" target="_top">PNG</a> is
 279             a patent-free image format which is comparable to
 280             <span class="emphasis"><em>GIF</em></span>.
 281           </td><td align="left">
 282                   This library is used for loading external PNG
 283                   images (part of the SWF8 specification) and for writing
 284                   images in the PNG format.
 285           </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
 286                       be free of patent restrictions.
 287                <span class="emphasis"><em>GIF</em></span>.
 288                 </td><td align="left">
 289                 This library is used for loading external GIF
 290                 images (part of the SWF8 specification).
 291                 </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">
 292             libcurl is the multiprotocal file transfer library.
 293           </td><td align="left">
 294             This library is used for URL downloading.
 295           </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">
 296             Glib2 is a dependency of Gtk, and is a collection of
 297             commonly used functions.
 298           </td><td align="left">
 299             This library is used for convenience.
 300           </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">
 301             Atk is a dependency of Gtk, and is used for accessibility
 302             support.
 303           </td><td align="left">
 304             This library is used for accessiblity..
 305           </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">
 306             Pango is a dependency of Gtk, and is used for font handling.
 307           </td><td align="left">
 308             This library is used for font handling.
 309           </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">
 310             Automake is a tool for generating
 311             <span class="emphasis"><em>Makefile.in</em></span> files.
 312           </td><td align="left">
 313             This package is required to run
 314             <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
 315             if you are using the development source from CVS.
 316           </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">
 317             Autoconf is a package for generating configure
 318             scripts.
 319           </td><td align="left">
 320             This package is required to run
 321             <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
 322             if you are using the development source from CVS.
 323           </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">
 324             Gettext is part of the GNU Translation Project.
 325           </td><td align="left">
 326             This package is required to run
 327             <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
 328             if you are using the development source from CVS.
 329           </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">
 330             This is a generic library support script.
 331           </td><td align="left">
 332             This package is required to run
 333             <span class="emphasis"><em>autogen.sh</em></span>, which is a requirement
 334             if you are using the development source from CVS.
 335           </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>
 336     <span class="application">Gnash</span> tries to run as many tests as possible, but will
 337     silentl skip tests if the tools to run them are unavailable.
 338   </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">
 339             Ming is an ActionScript compiler.
 340           </td><td align="left">
 341             Ming is the primary compiler for ActionScript testcases.
 342           </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">
 343             Mtasc is an ActionScript compiler.
 344           </td><td align="left">
 345             Mtasc is used in some tests.
 346           </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">
 347             Swfc is an swf compiler.
 348           </td><td align="left">
 349             Swfc is used in some testcases.
 350           </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">
 351             Swfmill is an XML-based SWF (Shockwave Flash) processing tool.
 352           </td><td align="left">
 353             Swfmill is used in some testcases.
 354           </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">
 355             Python is a scripting language.
 356           </td><td align="left">
 357             Python is used by part of the testing framework.
 358           </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">
 359             DejaGnu is a testing framework.
 360           </td><td align="left">
 361             DejaGnu is used to run multiple tests in an
 362             automated fashion.
 363           </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>
 364     The following packages are used to build <span class="application">Gnash</span>'s documentation.
 365   </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">
 366             <a class="ulink" href="http://http://docbook.sourceforge.net/" target="_top">Docbook</a> is
 367             is an industry-standard XML format for technical
 368             documentation.  You can download it from
 369             <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>.
 370           </td><td align="left">
 371             <span class="application">Gnash</span> documentation is written in Docbook.
 372           </td><td align="left">
 373             <code class="filename">docbook-utils</code> and <code class="filename">docbook-dsssl</code>
 374           </td><td align="left">
 375             <code class="filename">docbook-dtd41-sgml</code> and <code class="filename">docbook-style-dsssl</code>
 376           </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">
 377             This software package converts Docbook documents to
 378             the traditional man page format, GNU Texinfo
 379             format, and HTML (via Texinfo) format.
 380             It is available at <a class="ulink" href="http://docbook2x.sourceforge.net/" target="_top">http://docbook2x.sourceforge.net/</a>.
 381           </td><td align="left">
 382             DocBook2X is required to produce HTML and Texinfo
 383             formats.
 384           </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">
 385             This software package converts Docbook documents to
 386             the traditional man page format, GNU Texinfo
 387             format, and HTML (via Texinfo) format.
 388           </td><td align="left">
 389             DocBook-utils is required to produce HTML and Texinfo
 390             formats.
 391           </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">
 392             Texinfo can be used to convert DocBook2X output
 393             into GNU info pages.  You can download it from
 394             <a class="ulink" href="http://ftp.gnu.org/gnu/texinfo/" target="_top">http://ftp.gnu.org/gnu/texinfo/</a>.
 395           </td><td align="left">
 396             Texinfo is required if you wish to produce GNU info
 397             pages.
 398           </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">
 399             Formatting Objects Processor is a print formatter
 400             driven by XSL formatting objects.  It is a Java
 401             application which can output PDF, PCL, PS, SVG, XML,
 402             Print, AWT, MIF, and Text.  It is available at
 403             <a class="ulink" href="http://xmlgraphics.apache.org/fop/" target="_top">http://xmlgraphics.apache.org/fop/</a>.
 404           </td><td align="left">
 405             FOP is required for PDF output.
 406           </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">
 407             FOP requires Sun's Java runtime (GCJ does not work with
 408             FOP).  You can download it from
 409             <a class="ulink" href="http://java.sun.com" target="_top">http://java.sun.com</a>.
 410           </td><td align="left">
 411             Sun's Java runtime (j2re) is required to use FOP.
 412           </td><td align="left">
 413             Download the package from <a class="ulink" href="http://java.sun.com" target="_top">Sun</a>.
 414           </td><td align="left">
 415             Download the package from <a class="ulink" href="http://java.sun.com" target="_top">Sun</a>.
 416           </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">
 417             Sun's Java Advanced Imaging API can be downloaded from
 418             <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>.
 419           </td><td align="left">
 420             JAI is required
 421             if you wish to include graphics in a PDF file being
 422             generated with FOP.
 423           </td><td align="left">
 424             Download the package from <a class="ulink" href="http://java.sun.com/products/java-media/jai/iio.html" target="_top">Sun</a>.
 425           </td><td align="left">
 426             Download the package from <a class="ulink" href="http://java.sun.com/products/java-media/jai/iio.html" target="_top">Sun</a>.
 427           </td><td align="left"> </td></tr></tbody></table></div></div><br class="table-break"><p>
 428     If you install j2re, set the <span class="emphasis"><em>JAVA_HOME</em></span>
 429     environment variable to the top directory of the j2re
 430     installation.  If you encounter problems with the Java
 431     installation, you may also need to add this path to the
 432     <span class="emphasis"><em>CLASSPATH</em></span> environment variable.
 433   </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>
 434     <span class="application">Gnash</span>, like most GNU projects, allows a user to select various
 435     options before compiling its source code. These options include
 436     selecting from the available features, specifying custom paths for
 437     installation, and cross compiling support uses <a class="ulink" href="http://www.gnu.org/software/autoconf/" target="_top">GNU Autoconf</a>
 438     for configuration.
 439   </p><p>
 440     If you opted to download the development snapshot
 441     of <span class="application">Gnash</span>, the <span class="emphasis"><em>configure</em></span> script will
 442     not be included.  It can be created by running
 443     <span class="emphasis"><em>autogen.sh</em></span> from the source root directory:
 444     </p><pre class="programlisting">
 445       ./autogen.sh
 446     </pre><p>
 447     Note that there are some
 448     <a class="link" href="#dependencies" title="Code Dependencies">dependencies</a> for
 449     autogen.
 450   </p><p>
 451     All the standard <span class="command"><strong>configure</strong></span> options
 452     are available.  In addition, <span class="application">Gnash</span> has two types of
 453     options: those that <a class="link" href="#configfeatures" title="Features">enable or disable
 454     features</a>, and
 455     those that <a class="link" href="#custompath" title="Specifying Custom Paths">specify custom paths for
 456     development packages</a>
 457     which are not found during the default search.  A complete
 458     list of <span class="emphasis"><em>all</em></span> configuration options, including
 459     standard ones, can be seen by typing:
 460     </p><pre class="programlisting">
 461       ./configure --help | less
 462     </pre><p>
 463     Read further for a more detailed explanation of <span class="application">Gnash</span>-specific
 464     options.
 465   </p><p>
 466     The syntax for running <span class="emphasis"><em>configure</em></span> is as follows:
 467     </p><pre class="programlisting">
 468       configure <em class="replaceable"><code>&lt;options&gt;</code></em>
 469     </pre><p>
 470     The example below shows the <span class="command"><strong>configure</strong></span> options
 471     which create the smallest working standalone version of <span class="application">Gnash</span>.  In
 472     this example, <span class="command"><strong>configure</strong></span> is being run from the
 473     source root directory:
 474   </p><pre class="programlisting">
 475     ./configure --disable-debugger --disable-cygnal \
 476     --disable-plugin --enable-media=ffmpeg --enable-gui=sdl
 477   </pre><p>
 478     By default, you shouldn't need to supply any options to
 479     configure. The configure script will attempt to determine what to
 480     build based on the development libraries you have installed. The
 481     default configuration for Gnash is both GTK and KDE GUIs, the AGG
 482     renderer, and Gstreamer for multimedia support, with no extensions
 483     built.
 484   </p><p>
 485     Being highly portable, <span class="application">Gnash</span> has many configuration options
 486     available, and not all are supposed to work together. A common
 487     mistake when configuring <span class="application">Gnash</span> is to supply too many options,
 488     overdriving <span class="application">Gnash</span>'s ability to do the right thing.
 489   </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>
 490     Some switches can be used during configuration to enable or disable
 491     features of <span class="application">Gnash</span>. Some of the most important configuration options
 492     are:
 493   </p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p>
 494         <code class="option">--enable-gui</code> lets you specify your GUI of choice.
 495         The default option is GTK.
 496       </p></li><li class="listitem" style="list-style-type: circle"><p>
 497         <code class="option">--enable-renderer</code> allows a renderer to be
 498         chosen.  The default renderer is AGG.
 499       </p></li><li class="listitem" style="list-style-type: circle"><p>
 500         <code class="option">--enable-media</code> permits a media handler to be
 501         selected.  The default is Gstreamer.
 502       </p></li></ul></div><p>
 503     A complete list of available features follows.
 504   </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
 505           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">
 506             Enable support for the LIRC remote control protocol.
 507           </td></tr><tr><td align="left"><code class="option">--enable-cygnal</code></td><td align="left">
 508             Build the Cygnal streaming media server.
 509           </td></tr><tr><td align="left"><code class="option">--disable-menus</code></td><td align="left">
 510             Disable building all the menus for the GUI. THis is used
 511             by mobile devices without as much screen space.
 512           </td></tr><tr><td align="left"> <code class="option">--enable-docbook</code></td><td align="left">  Enable the generation of HTML, INFO, and MAN
 513           versions of the documentation from the Docbook XML. You will
 514           then be able to use <span class="command"><strong>make html</strong></span>,
 515           <span class="command"><strong>make info</strong></span>, and <span class="command"><strong>make
 516           man</strong></span> commands. By default, man,info and html pages
 517           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>
 518           <div class="variablelist"><dl><dt><span class="term">GTK</span></dt><dd><p>
 519                   The GTK+ toolkit, which is the default GUI.
 520                   Said to interwork particularly well with firefox.
 521                 </p></dd><dt><span class="term">Hildon</span></dt><dd><p>
 522                   The Hildon toolkist is based on GTK+, and is use by
 523                   some mobile devices.
 524                 </p></dd><dt><span class="term">ALP</span></dt><dd><p>
 525                   The ALP "Hiker" GUI is used for the Access Linux platform.
 526                 </p></dd><dt><span class="term">SDL</span></dt><dd><p>
 527                   Simple DirectMedia Layer, a simple and portable GUI.
 528                   Its sound facilities are used when --enable-media=ffmpeg
 529                   regardless of whether it is also in charge of the GUI.
 530                 </p></dd><dt><span class="term">KDE</span></dt><dd><p>
 531                   An interface adapted to the KDE Desktop Environment.
 532                   This must be selected when building the Konqueror plugin
 533                   "klash". Furthermore, the only renderer that currently
 534                   works with KDE is opengl.
 535                 </p></dd><dt><span class="term">FLTK</span></dt><dd><p>
 536                   Fast Light ToolKit, low on resource usage.
 537                   Since all builds using fltk are now broken, we declare it
 538                   "for developers".
 539                 </p></dd><dt><span class="term">FB</span></dt><dd><p>
 540                   The Linux Frame Buffer, also known as /dev/fb0.
 541                   AGG is the only renderer that can currently be used
 542                   with the framebuffer GUI.
 543                 </p></dd></dl></div>
 544           </td></tr><tr><td align="left"><code class="option">--enable-i810-lod-bias</code>
 545           </td><td align="left">Enable fix for Intel 810 LOD bias problem. Older versions
 546           of libMesa on the Intel i810 or i815 graphics processor
 547           need this flag or Gnash will core dump. This has been
 548           fixed in newer versions (summer 2005) of libMesa.</td></tr><tr><td align="left"><code class="option">--enable-media=ffmpeg|gst|none</code>
 549           </td><td align="left">  <p>
 550             Select the specified media decoder and sound engine.
 551             FFmpeg uses the SDL sound engine; GST uses its own.
 552             <code class="option">GST</code> is the default decoder.
 553           </p>
 554           <p>
 555             You should only select one media decoder.
 556           </p></td></tr><tr><td align="left">
 557             <code class="option">--disable-nsapi</code>
 558             <code class="option">--enable-nsapi</code>
 559           </td><td align="left">Force disable/enable building the NPAPI plugin.
 560           By default the Mozilla plugin is built if the GTK gui
 561           is selected.  Specify the
 562           <code class="option">--with-npapi-plugindir=</code> option to specify where the
 563           plugin should be installed.
 564           </td></tr><tr><td align="left">
 565             <code class="option">--disable-kparts</code>
 566             <code class="option">--enable-kparts</code>
 567           </td><td align="left">Force disable/enable building the KPARTS plugin. By default the
 568           KDE plugin is built if the kde gui is selected.
 569           Specify the <code class="option">--with-kde-plugindir=</code> and
 570           <code class="option">--with-kde-servicesdir=</code> options (or more generally
 571           the <code class="option">--with-kde-pluginprefix=</code> one) to specify where the
 572           plugin should be installed. The default installation dir is extracted
 573           from kde-config.
 574           </td></tr><tr><td align="left">
 575             <code class="option">--disable-plugins</code>
 576           </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>
 577           </td><td align="left">Enable support for a graphics backend. Currently
 578           only <code class="option">opengl</code> and
 579           <code class="option">agg</code> work sufficiently. Use OpenGL
 580           when you have hardware accelerated graphics. Use AGG
 581           when you do not have hardware accelerated
 582           graphics or when you are building for a wide audience.
 583           Typically most desktop machines have OpenGL
 584           support, and most embedded systems do not. AGG is the
 585           default when building Gnash, although the speed of OpenGL's
 586           rendering is currently superior to AGG.</td></tr><tr><td align="left"><code class="option">--enable-sdk-install</code>
 587           </td><td align="left">Enable installing the libraries and headers as an SDK.
 588           </td></tr><tr><td align="left"><code class="option">--disable-shared</code>
 589           </td><td align="left">Enable installing the shared libraries and headers.
 590           Note that the extensions mechanism may not work if shared
 591           libraries are disabled.</td></tr><tr><td align="left"><code class="option">--enable-strict</code>
 592           </td><td align="left">Turn verbose GCC compiler warnings. By default only
 593           <code class="option">-Wall</code> is used with GCC.</td></tr><tr><td align="left"><code class="option">--enable-fps-debug</code>
 594           </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>
 595           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>.
 596           </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.
 597           </td></tr><tr><td align="left"><code class="option">--disable-mit-shm</code>
 598           </td><td align="left">Disable support for the MIT-SHM X extensions.
 599           Currently support is only available using GTK gui and AGG renderer.
 600           Keeping it enabled is not a problem as it will not be used if not
 601           available in the current X session.
 602           </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>
 603     By default, none of these options should be required
 604     unless you want <span class="application">Gnash</span> to use a specific version of a
 605     development package, or if the configure test fails to
 606     find a component.  Please <a class="link" href="#bugreport" title="Chapter 5. Reporting Bugs">report the problem</a> if a
 607     configure test fails.
 608   </p><p>
 609     The following custom path options are available:
 610   </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">
 611             <code class="option">--x-includes=DIR</code>
 612           </td><td align="left">
 613             X include files are in DIR.
 614           </td></tr><tr><td align="left">
 615             <code class="option">--x-libraries=DIR</code>
 616           </td><td align="left">
 617             X library files are in DIR.
 618           </td></tr><tr><td align="left">
 619             <code class="option">--with-docbook=DIR</code>
 620           </td><td align="left">
 621             Directory where the DocBook style-sheets are installed.
 622           </td></tr><tr><td align="left">
 623             <code class="option">--with-sdl-prefix=PFX</code>
 624           </td><td align="left">
 625             Prefix where SDL is installed.
 626           </td></tr><tr><td align="left">
 627             <code class="option">--with-zlib-incl</code>
 628           </td><td align="left">
 629             Directory where zlib header is installed.
 630           </td></tr><tr><td align="left">
 631             <code class="option">--with-zlib-lib</code>
 632           </td><td align="left">
 633             Directory where zlib library is installed.
 634           </td></tr><tr><td align="left">
 635             <code class="option">--with-jpeg-incl</code>
 636           </td><td align="left">
 637             Directory where jpeg header is installed.
 638           </td></tr><tr><td align="left">
 639             <code class="option">--with-jpeg-lib</code>
 640           </td><td align="left">
 641             Directory where jpeg library is installed.
 642           </td></tr><tr><td align="left">
 643             <code class="option">--with-png-incl</code>
 644           </td><td align="left">
 645             Directory where png header is installed.
 646           </td></tr><tr><td align="left">
 647             <code class="option">--with-png-lib</code>
 648           </td><td align="left">
 649             Directory where png library is installed.
 650           </td></tr><tr><td align="left">
 651             <code class="option">--with-qt-dir</code>
 652           </td><td align="left">
 653             Directory where QT is installed. This is only used by
 654             the Klash plugin.
 655           </td></tr><tr><td align="left">
 656             <code class="option">--with-qt-includes</code>
 657           </td><td align="left">
 658             Directory where the QT header files are installed. This
 659             is only used by the Klash plugin.
 660           </td></tr><tr><td align="left">
 661             <code class="option">--with-qt-libraries</code>
 662           </td><td align="left">
 663             Directory where the QT libraries are installed. This is
 664             only used by the Klash plugin.
 665           </td></tr><tr><td align="left">
 666             <code class="option">--with-plugins-install=user|system|prefix</code>
 667           </td><td align="left">
 668             This option sets the install policy for NPAPI (mozilla) and KPARTS (kde) plugins.
 669             Policy 'user' means plugin will be installed only for the configuring user.
 670             Policy 'system' will try to find a systemwide place for plugins (to enable for all).
 671             Policy 'prefix' will install under ${prefix} (npapi/kparts subdirs);
 672             WARNING: if 'prefix' policy is given, plugins won't be found w/out further enabling procudures.
 673             The default policy is 'user', can be overridden for specific plugins.
 674           </td></tr><tr><td align="left">
 675             <code class="option">--with-npapi-install=user|system|prefix</code>
 676           </td><td align="left">
 677             This option sets the install policy for NPAPI plugin.
 678             Policy 'user' means plugin will be installed in ~/.mozilla/plugins;
 679             'system' will try to find an existing system-wide mozilla plugin dir (or bail out if not found);
 680             'prefix' will install under ${prefix}/npapi.
 681           </td></tr><tr><td align="left">
 682             <code class="option">--with-npapi-plugindir</code>
 683           </td><td align="left">
 684             This is the directory to install the NPAPI (Mozilla) plugin in.
 685             By default it goes to ~/.mozilla/plugins.
 686           </td></tr><tr><td align="left">
 687             <code class="option">--with-kparts-install=user|system|prefix</code>
 688           </td><td align="left">
 689             This option sets the install policy for all KPARTS (kde) files.
 690             Policy 'user' means plugin will be installed in ~/.kde;
 691             'system' will find out using kde-config (or bail out if not found);
 692             'prefix' will install under ${prefix}/kparts.
 693             The actual prefix can be overridden using
 694             <code class="option">--with-kde-pluginprefix</code>
 695             or the fine-tuned options.
 696             The default at time of writing (2008-05-18) is 'user'.
 697           </td></tr><tr><td align="left">
 698             <code class="option">--with-kde-pluginprefix</code>
 699           </td><td align="left">
 700             This option sets the default install dir for all KPARTS (kde) files.
 701             The plugin will be installed in PREFIX/lib/kde3, use
 702             <code class="option">-with-kde-plugindir</code> to override. The service file in
 703             PREFIX/share/services, use <code class="option">--with-kde-servicesdir</code> to
 704             override. The config file in PREFIX/share/config, use
 705             <code class="option">--with-kde-configdir</code> to override. The
 706             appdata file in PREFIX/share/apps/klash, use
 707             <code class="option">--with-kde-appsdatadir</code> to override.
 708           </td></tr><tr><td align="left">
 709             <code class="option">--with-kde-plugindir</code>
 710           </td><td align="left">
 711             This is the directory to install the KPARTS (kde) plugin in.
 712             By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install module --expandvars,
 713             or $(prefix)/share/services if kde-config is not found.
 714           </td></tr><tr><td align="left">
 715             <code class="option">--with-kde-servicesdir</code>
 716           </td><td align="left">
 717             This is the directory to install the KPARTS (kde) service in.
 718             By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install services --expandvars,
 719             or $(libdir)/kde3 if kde-config is not found.
 720           </td></tr><tr><td align="left">
 721             <code class="option">--with-kde-configdir</code>
 722           </td><td align="left">
 723             This is the directory to install the KPARTS (kde) config files in.
 724             By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install config --expandvars,
 725             or $(prefix)/share/config if kde-config is not found.
 726           </td></tr><tr><td align="left">
 727             <code class="option">--with-kde-appsdatadir</code>
 728           </td><td align="left">
 729             This is the directory to install the KPARTS (kde) application data files in.
 730             By default it is what's set by --with-kde-pluginprefix or what's returned by kde-config --install data --expandvars,
 731             or $(prefix)/share/apps if kde-config is not found.
 732           </td></tr><tr><td align="left">
 733             <code class="option">--with-ming</code>
 734           </td><td align="left">
 735             Ming is used to build test cases, but not by the Gnash
 736             player itself.
 737           </td></tr><tr><td align="left">
 738             <code class="option">--with-ogg_incl</code>
 739           </td><td align="left">
 740             Directory where the libogg headers are installed.
 741           </td></tr><tr><td align="left">
 742             <code class="option">--with-ogg_lib</code>
 743           </td><td align="left">
 744             Directory where the libogg library is installed.
 745           </td></tr><tr><td align="left">
 746             <code class="option">--with-gstreamer-incl</code>
 747           </td><td align="left">
 748             Directory where the Gstreamer headers are
 749             installed. Gstreamer version 0.10 or greater must be used.
 750           </td></tr><tr><td align="left">
 751             <code class="option">--with-gstreamer-lib</code>
 752           </td><td align="left">
 753             Directory where the Gstreamer library is
 754             installed. Gstreamer version 0.10 or greater must be used.
 755           </td></tr><tr><td align="left">
 756             <code class="option">--with-opengl-includes</code>
 757           </td><td align="left">
 758             Directory where OpenGL (libMesa) headers are installed.
 759           </td></tr><tr><td align="left">
 760             <code class="option">--with-opengl-lib</code>
 761           </td><td align="left">
 762             Directory where the OpenGL (libMesa) library is installed.
 763           </td></tr><tr><td align="left">
 764             <code class="option">--with-glext-incl</code>
 765           </td><td align="left">
 766             Directory where GtkGlExt headers are installed.
 767           </td></tr><tr><td align="left">
 768             <code class="option">--with-glext-lib</code>
 769           </td><td align="left">
 770             Directory where the GtkGlExt library is installed.
 771           </td></tr><tr><td align="left">
 772             <code class="option">--with-gtk2-incl</code>
 773           </td><td align="left">
 774             Directory where the Gtk2 headers are installed.
 775           </td></tr><tr><td align="left">
 776             <code class="option">--with-gtk2-lib</code>
 777           </td><td align="left">
 778             Directory where the Gtk2 library is installed.
 779           </td></tr><tr><td align="left">
 780             <code class="option">--with-cairo_incl</code>
 781           </td><td align="left">
 782             Directory where the Cairo headers are installed.
 783           </td></tr><tr><td align="left">
 784             <code class="option">--with-cairo-lib</code>
 785           </td><td align="left">
 786             Directory where the Cairo library is installed.
 787           </td></tr><tr><td align="left">
 788             <code class="option">--with-glib-incl</code>
 789           </td><td align="left">
 790             Directory where the Glib headers are installed.
 791           </td></tr><tr><td align="left">
 792             <code class="option">--with-glib-lib</code>
 793           </td><td align="left">
 794             Directory where the Glib library is installed.
 795           </td></tr><tr><td align="left">
 796             <code class="option">--with-pango-incl</code>
 797           </td><td align="left">
 798             Directory where the Pango headers are installed.
 799           </td></tr><tr><td align="left">
 800             <code class="option">--with-pango-lib</code>
 801           </td><td align="left">
 802             Directory where the Pango library is installed.
 803           </td></tr><tr><td align="left">
 804             <code class="option">--with-atk-incl</code>
 805           </td><td align="left">
 806             Directory where the ATK headers are installed.
 807           </td></tr><tr><td align="left">
 808             <code class="option">--with-atk-lib</code>
 809           </td><td align="left">
 810             Directory where the ATK library is installed.
 811           </td></tr><tr><td align="left">
 812             <code class="option">--with-pthread-incl</code>
 813           </td><td align="left">
 814             Directory where the Pthread headers are installed.
 815           </td></tr><tr><td align="left">
 816             <code class="option">--with-pthread-lib</code>
 817           </td><td align="left">
 818             Directory where the Pthread library is installed.
 819           </td></tr><tr><td align="left">
 820             <code class="option">--with-agg-incl</code>
 821           </td><td align="left">
 822             Directory where the AGG (Antigrain) headers are installed.
 823           </td></tr><tr><td align="left">
 824             <code class="option">--with-agg-lib</code>
 825           </td><td align="left">
 826             Directory where the AGG (Antigrain) library is installed.
 827           </td></tr><tr><td align="left">
 828             <code class="option">--with-ffmpeg-incl</code>
 829           </td><td align="left">
 830             Directory where the FFMPEG headers are installed.
 831           </td></tr><tr><td align="left">
 832             <code class="option">--with-ffmpeg-lib</code>
 833           </td><td align="left">
 834             Directory where the FFMPEG library is installed.
 835           </td></tr><tr><td align="left">
 836             <code class="option">--with-boost-incl</code>
 837           </td><td align="left">
 838             Directory where the Boost headers are installed.
 839           </td></tr><tr><td align="left">
 840             <code class="option">--with-boost-lib</code>
 841           </td><td align="left">
 842             Directory where the Boost library is installed.
 843           </td></tr><tr><td align="left">
 844             <code class="option">--with-curl-incl</code>
 845           </td><td align="left">
 846             Directory where the libCurl headers are installed.
 847           </td></tr><tr><td align="left">
 848             <code class="option">--with-curl-lib</code>
 849           </td><td align="left">
 850             Directory where the libCurl library is installed.
 851           </td></tr></tbody></table></div></div><br class="table-break"></div></div><p>
 852     Once you have <span class="application">Gnash</span> configured, you are ready to build the code.  <span class="application">Gnash</span> is built using
 853     <span class="emphasis"><em>GNU make</em></span>.
 854   </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>
 855       The most basic way to compile code is simply:
 856       </p><pre class="programlisting">
 857         make
 858       </pre><p>
 859       If the compilation ends with an error, check the output of
 860       <span class="emphasis"><em>configure</em></span> and ensure that you are not missing
 861       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.
 862     </p><p>
 863       The variables used by <span class="command"><strong>make</strong></span> can be redefined when
 864       the program is invoked, if you desire it.   The most interesting flags
 865       are <span class="emphasis"><em>CFLAGS</em></span> and <span class="emphasis"><em>CXXFLAGS</em></span>,
 866       which are often used to enable debugging or turn of optimization.
 867       The default value for both of these variables is
 868       <span class="emphasis"><em>-O2 -g</em></span>.  A list of influential
 869       environment variables can be seen in the configuration help:
 870     </p><pre class="programlisting">./configure --help</pre><p>
 871       In the following example, debugging is enabled and optimization is
 872       disabled:
 873     </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>
 874       By default, documentation is not built when you
 875       <a class="link" href="#install" title="Installation">install</a> <span class="application">Gnash</span>.  This is because
 876       there are a number of <a class="link" href="#docdepend" title="Documentation Dependencies">dependencies
 877       for the documentation</a>.  Documentation is built when it
 878       is specified with a specific target in the generated
 879       <span class="command"><strong>Makefile</strong></span> in the <code class="filename">doc/C</code>
 880       sub-directory.  If you type <span class="command"><strong>make install</strong></span> in
 881       this directory, all documents will be built.
 882     </p><p>
 883       You must specify a target output format when you wish to create
 884       documentation.  The available output formats are: <span class="command"><strong>html</strong></span>,
 885       <span class="command"><strong>pdf</strong></span>, <span class="command"><strong>info</strong></span>,
 886       <span class="command"><strong>man</strong></span>, and <span class="command"><strong>alldocs</strong></span>.
 887       It is also possible to output <span class="command"><strong>GNOME help</strong></span> if
 888       the <a class="link" href="#configfeatures" title="Features">configure option</a>
 889       <code class="option">--enable-ghelp</code> was used.
 890       The <span class="command"><strong>alldocs</strong></span> target will build all output formats
 891       except <span class="emphasis"><em>GNOME help</em></span>.
 892       For example, to create HTML output, type:
 893       </p><pre class="programlisting">
 894         make html
 895       </pre><p>
 896     </p><p>
 897       <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>
 898       documentation of <span class="application">Gnash</span> internals.  You must have Doxygen installed
 899       to produce this documentation, which is built from the
 900       <code class="filename">doc</code> directory with the command (documents
 901       will be placed in the subdirectory <code class="filename">apidoc/html</code>):
 902       </p><pre class="programlisting">
 903         make apidoc
 904       </pre><p>
 905     </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>
 906       Before beginning the potentially lengthy install, it is wise to
 907       test the installation.  If a test fails, please report it by
 908       following the <a class="link" href="#bugreport" title="Chapter 5. Reporting Bugs">instructions for
 909       reporting a bug</a>.
 910     </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>
 911
 912         The easiest way to run <span class="application">Gnash</span>'s test suite is to install
 913         <span class="emphasis"><em><a class="ulink" href="http://www.gnu.org/software/dejagnu" target="_top">DejaGnu</a></em></span>.
 914         After installing DejaGnu, run:
 915         </p><pre class="programlisting">
 916           make check
 917         </pre><p>
 918       </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>
 919           If you encounter a problem with a test, increasing the
 920           verbosity may make the issue easier to spot.
 921           Additional details are visible when
 922           <span class="emphasis"><em>RUNTESTFLAGS</em></span> are used to add the
 923           <span class="emphasis"><em>verbose</em></span> and <span class="emphasis"><em>all</em></span> options.
 924           The <code class="option">verbose</code> option prints more information about the testing process, while
 925           the <code class="option">all</code> option includes details on passing tests.
 926           </p><pre class="programlisting">
 927             make check RUNTESTFLAGS="-v -a"
 928           </pre><p>
 929         </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>
 930           It is possible to run just a single test, or
 931           a subdirectory of tests, by specifying the directory or
 932           compiled test file.
 933         </p><p>
 934           Some tests rely on <span class="emphasis"><em>testsuite/Dejagnu.swf</em></span>,
 935           which in turn relies on <span class="emphasis"><em>Ming</em></span>.
 936           This file is created when you run <span class="command"><strong>make check</strong></span> for the entire
 937           testsuite, and can also be created on demand:
 938           </p><pre class="programlisting">
 939             make -C testsuite Dejagnu.swf
 940           </pre><p>
 941         </p><p>
 942           In this example, the <span class="command"><strong>clip_as_button2</strong></span> test is compiled and
 943           run:
 944           </p><pre class="programlisting">
 945             make -C testsuite/samples clip_as_button2-TestRunner
 946             cd testsuite/samples &amp;&amp; ./clip_as_button2-TestRunner
 947           </pre><p>
 948           This creates and runs all the tests in the directory
 949           <code class="filename">movies.all</code>:
 950           </p><pre class="programlisting">
 951             make -C testsuite/movies.all check
 952           </pre><p>
 953         </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>
 954         You may also run test cases by hand, which can be useful if you
 955         want to see all the debugging output from the test case.  Often
 956         the messages which come from deep within <span class="application">Gnash</span> are most useful for
 957         development.
 958       </p><p>
 959         The first step is to compile the test case, which can be done
 960         with <code class="filename">make XML-v#.swf</code> where the '#' is replaced
 961         with the <span class="emphasis"><em>target</em></span> SWF version or versions.
 962         For example:
 963         </p><pre class="programlisting">
 964           make XML-v{5,6,7,8}.swf
 965         </pre><p>
 966       </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>
 967           This creates a SWF movie version of the test case, which
 968           can be run with a standalone SWF player.  For instance,
 969           the target for SWF version 6 could be run with <span class="application">Gnash</span>:
 970           </p><pre class="programlisting">
 971             gnash -v XML-v6.swf
 972           </pre><p>
 973         </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>
 974           Unit tests for ActionScript classes in <span class="command"><strong>testsuite/actionscript.all</strong></span>
 975           are run without a graphical display:
 976           </p><pre class="programlisting">
 977             gprocessor -v XML-v6.swf
 978           </pre><p>
 979         </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>
 980     Now that <span class="application">Gnash</span> has been compiled and tested, use the following command to install it:
 981     </p><pre class="programlisting">
 982       make install
 983     </pre><p>
 984     The above command installs the standalone player.  If the correct
 985     files were found by <span class="command"><strong>configure</strong></span> and if the
 986     <code class="option">--disable-plugin</code> option was not specified, the
 987     <span class="application">Gnash</span> browser plugin is also installed.
 988   </p><p>
 989     <span class="application">Gnash</span> installs a number of <a class="link" href="#libinstall" title="Libraries">libraries</a>,
 990     namely: <span class="emphasis"><em>libgnashbase</em></span>,
 991     <span class="emphasis"><em>libgnashamf</em></span>, <span class="emphasis"><em>libgnashmedia</em></span>,
 992     <span class="emphasis"><em>libserver</em></span>, and <span class="emphasis"><em>libgnashplugin</em></span>.
 993     <a class="link" href="#appinstall" title="Executables">Executables</a>
 994     consist of the (optional) plugin, <code class="filename">gprocessor</code>,
 995     <code class="filename">cygnal</code>,  <code class="filename">dumpshm</code>,
 996     <code class="filename">soldumper</code>, and <code class="filename">gnash</code>.
 997     <a class="link" href="#docinstall" title="Documentation">Documentation</a> may also be installed.
 998     The installation location is controlled with the
 999     <span class="emphasis"><em>--prefix</em></span> <a class="link" href="#custompath" title="Specifying Custom Paths">configure
1000     option</a>, except for plugins, which are explicitly set with
1001     <span class="emphasis"><em>--plugin-dir</em></span>.
1002   </p><p>
1003     Note that if you are using a single file-system <span class="emphasis"><em>NFS</em></span>
1004     mounted to multiple platforms, the
1005     <a class="link" href="#custompath" title="Specifying Custom Paths">configuration option</a>
1006     <span class="emphasis"><em>--exec-prefix</em></span> may be used to specify where
1007     platform-dependent executables and libraries are installed.
1008   </p><div class="sect2" title="Libraries"><div class="titlepage"><div><div><h3 class="title"><a name="libinstall"></a>Libraries</h3></div></div></div><p>
1009       Installed libraries are located in
1010       <code class="filename">/usr/local/lib</code> by default.
1011       If the <span class="emphasis"><em>--prefix</em></span> option was used during the
1012       configuration step, the libraries will
1013       be installed in the directory <code class="filename">lib</code> inside the
1014       path you specified.  If the libraries are stored in a non-standard
1015       location, you must identify the path in one of two ways.
1016     </p><p>
1017       The traditional way to do this on UNIX
1018       platforms is to set the <span class="emphasis"><em>LD_LIBRARY_PATH</em></span> variable
1019       to the path plus <code class="filename">/lib</code>.  For example, if you
1020       installed in <code class="filename">/home/gnash</code>, the
1021       <span class="emphasis"><em>LD_LIBRARY_PATH</em></span> path would be
1022       <code class="filename">/home/gnash/lib</code>.  Multiple paths are delimited
1023       with a colon (':').
1024     </p><p>
1025       GNU/Linux allows the custom path to be added to
1026       <code class="filename">/etc/ld.so.conf</code>.  After adding the path,
1027       run <span class="emphasis"><em>ldconfig</em></span> as root to update the runtime
1028       cache.
1029     </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>
1030       The Mozilla plugin is built from headers (the Mozilla SDK) provided with Gnash and
1031       does not need extra development packages to be installed. By default, the
1032       plugin is installed to <code class="filename">~/.mozilla/plugins/</code>. To enable
1033       the plugin for other users, copy the file <code class="filename">libgnashplugin.so</code>
1034       to <code class="filename">.mozilla/plugins/</code> in their home directory.
1035       You may also specify the plugin installation directory by using the
1036       <code class="option">--with-plugindir</code> <a class="link" href="#custompath" title="Specifying Custom Paths">option
1037       at configuration time</a>.
1038     </p><p>
1039       These defaults are likely to change in future versions of Gnash.
1040     </p><p>
1041       The remaining executables are installed in the <code class="filename">bin</code>
1042       subdirectory of the directory specified by during configuration.
1043       If no path was specified, the default is
1044       <code class="filename">/usr/local/bin</code>.
1045     </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>
1046       Documentation is not built by default; please refer to the
1047       <a class="link" href="#processdoc" title="Creating the Documentation">section on documentation</a> for
1048       more information on building documentation.
1049     </p><p>
1050       <span class="command"><strong>man</strong></span> and <span class="command"><strong>info</strong></span>
1051       are installed in <code class="filename">/usr/local/share/man</code>
1052       and <code class="filename">/usr/local/share/info</code> respectively, unless
1053       the <code class="option">--mandir</code> or <code class="option">--infodir</code>
1054       <a class="link" href="#custompath" title="Specifying Custom Paths">configuration options</a> are used.
1055     </p><p>
1056       <span class="emphasis"><em>GNOME help</em></span> documentation uses the directory
1057       <code class="filename">/usr/local/share/gnash/doc/gnash/C/</code> by default.
1058       A configuration file in the <span class="application">Gnash</span> source tree,
1059       <code class="filename">doc/C/gnash.omf</code> is used to specify under
1060       which menu item <span class="application">Gnash</span> appears in the <span class="emphasis"><em>GNOME help</em></span>
1061       system.
1062     </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>
1063     To cross configure and compile <span class="application">Gnash</span>, begin by building a target system
1064     on your workstation.  This includes cross compilers for the target
1065     architecture, and some system headers.
1066     You will also need to cross compile all the <a class="link" href="#docdepend" title="Documentation Dependencies">dependencies
1067     </a> normally needed to build Gnash. This can on occasion be a
1068     daunting process, as not all libraries will cross configure and cross
1069     compile. There is more information about cross compiling all the
1070     dependant packages on the <a class="ulink" href="http://www.gnashdev.org" target="_top">http://www.gnashdev.org</a> web
1071     site.
1072   </p><p>
1073     If you need to build your own tool chain, that is beyond the scope
1074     of this manual. There are various resources on the web for howto's
1075     on building GCC based cross toolchains. Two popular sites are
1076     <a class="ulink" href="http://frank.harvard.edu/~coldwell/toolchain/" target="_top">http://frank.harvard.edu/~coldwell/toolchain/</a>
1077     and <a class="ulink" href="http://www.kegel.com/crosstool/" target="_top">http://www.kegel.com/crosstool/</a>. This
1078     can also be a very time consuming and frustrating process, even
1079     for experienced developers.
1080   </p><p>
1081     Because the process of building your own cross tool chain can be
1082     harder than one may wish, there are several other cross
1083     development environments that simulate a native environment to
1084     make it easier to develop. These also let you develop for both
1085     native and cross builds. Several popular ones are
1086     <a class="ulink" href="http://www.access-company.com/products/linux/alp.html" target="_top">
1087     Access Linux Platform</a>,
1088     <a class="ulink" href="http://www.scratchbox.org/" target="_top">
1089     Scratchbox</a>,
1090     <a class="ulink" href="http://www.openembedded.org/" target="_top">
1091     Open Embedded</a>,
1092     <a class="ulink" href="http://maemo.org/" target="_top">
1093     Maemo</a>.
1094   </p><p>
1095     To build for an ARM based system on an x86 based systems,
1096     configure like this using the traditional style cross toolchain,
1097     configure like this:
1098   </p><pre class="programlisting">
1099     ../../gnash/configure --build=i686-pc-linux-gnu
1100     --host=arm-linux --prefix=/usr/local/arm/oe --disable-nsapi
1101     --disable-kparts --enable-gui=fb --enable-renderer=agg
1102     --disable-shared --disable-menus
1103
1104   </pre><p>
1105     The important configuration options are the ones which specify the
1106     architecture for the build:
1107   </p><div class="variablelist"><dl><dt><span class="term">--target</span></dt><dd><p>
1108           The target architecture, where the final executables are expected
1109           to run.
1110         </p></dd><dt><span class="term">--host</span></dt><dd><p>
1111           The host architecture, where the executables are expected
1112           to run.  Usually this is the same as the <span class="emphasis"><em>--target</em></span>,
1113           except when building a compiler as a Canadian Cross.  In this
1114           case, you might build a cross compiler on a UNIX system which
1115           runs on a win32 machine, producing code for a third architecture,
1116           such as ARM.  In this example, <span class="emphasis"><em>--target</em></span> would
1117           be 'arm-unknown-linux-gnu', while <span class="emphasis"><em>--host</em></span> would
1118           be 'win32'.
1119         </p></dd><dt><span class="term">--build</span></dt><dd><p>
1120           This is the system the build is running on.
1121         </p></dd></dl></div><p>
1122     The following example of <span class="emphasis"><em>configure</em></span> builds for an
1123     ARM system on an x86 system.  It was run after an ARM system was built
1124     in <code class="filename">/usr/arm</code> and other required libraries were
1125     cross compiled.
1126     </p><pre class="programlisting">
1127       ./configure -target=arm-unknown-linux-gnu --prefix=/usr/arm \
1128       --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu --disable-plugin
1129     </pre><p>
1130   </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>
1131       The top level of <span class="application">Gnash</span> has several libraries, <span class="emphasis"><em>libgnashbase</em></span>,
1132       <span class="emphasis"><em>libgnashcore</em></span>,
1133       <span class="emphasis"><em>libgnashmedia</em></span>,
1134       <span class="emphasis"><em>libgnashamf</em></span> and
1135       <span class="emphasis"><em>libgnashrender</em></span>. There are several utility programs
1136       included for debug parsing and processing of SWF movie files,
1137       and other useful utilities for examining local Shared Objects and
1138       sniffing LocalConnections.
1139     </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>
1140           Libgnashbase contains support classes used by the rest of the
1141           code.This library has no dependencies on any of the other
1142           <span class="application">Gnash</span> libraries.
1143         </p><p>
1144           <span class="application">Gnash</span> makes heavy use of smart pointers, so memory allocations
1145           are freed up automatically by the interpreter. Both STL and
1146           Boost smart pointers are used.
1147         </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>
1148           Libgnashcore is the guts of the interpreter itself. This is where
1149           the main code for the interpreter lives. Included in
1150           libcore are the two support libraries for the parser and
1151           the core of the virtual machine.
1152         </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>
1153         Libgnashmedia handles <span class="application">Gnash</span>'s decoding of video and audio,
1154         including both streamed and embedded media.
1155                 Besides the standard SWF formats
1156                 FLV, MPEG4, Nellymoser, ADPCM, MP3 and RAW, <span class="application">Gnash</span> can
1157                 decode other formats supports by Gstreamer or FFmpeg,
1158                 including the free OGG container and free codecs.
1159         </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>
1160         This library handles sound output and manages sound objects.
1161         </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>
1162           AMF is the data format used internally by SWF files. This is
1163           <span class="application">Gnash</span>'s support library to handle AMF data. This is used by
1164           the ActionScript classes SharedObject and
1165           LocalConnection. This is also used by the NetStream class
1166           when using thre RTMP streaming network protocol.
1167         </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>
1168           Libgnashbackend is a library containing the rendering
1169           code that glues this display to the <span class="application">Gnash</span>. Supported
1170           rendering backends are OpenGL, Cairo, and AGG.
1171         </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>
1172           Libgnashplugin is the Mozilla/Firefox plugin.
1173         </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>
1174           Libklashpart is the Konqueror plugin.
1175         </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>
1176             There are currently a few standalone programs in <span class="application">Gnash</span>,
1177         which serve either to assist with <span class="application">Gnash</span> development or to play SWF
1178         movies.
1179       </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>
1180           This is the standalone OpenGL backend used to play
1181           movies. There are several command line options and keyboard
1182           control keys used by <span class="application">Gnash</span>.
1183         </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>
1184           Gprocessor is used to print out the actions (using the -va
1185           option) or the parsing (using the -vp option) of a SWF
1186           movie. It is also used to produce the <span class="emphasis"><em>.gsc</em></span>
1187           files that <span class="application">Gnash</span> uses to cache data, thereby speeding up the
1188           loading of files.
1189         </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>
1190           SOLDumper is a utility program used to find and dump the
1191           content of <span class="emphasis"><em>Local Shared Objects</em></span>, also
1192           called "Flash Cookies" by some.
1193         </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>
1194           Dumpshm is a program used to find and dump the contents of
1195           the <span class="emphasis"><em>LocalConnection</em></span> shared memory segment.
1196         </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>
1197         The plugin is designed to work within Mozilla or Firefox,
1198         although there is Konqueror support as well. The plugin uses
1199         the Mozilla plugin API (NPAPI) to be cross platform, and is
1200         portable, as well as being well integrated into Mozilla based
1201         browsers.
1202       </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>
1203           The plugin works in a
1204           fashion similar to MozPlugger: the standalone player
1205           is used instead of using a thread. This gets around the
1206           issue of having to maintain a separate player to support the
1207           plugin. It also gets around the other issues that <span class="application">Gnash</span>
1208           itself is not thread safe at this time.
1209         </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>
1210           Any plugin that wants to display in a browser window needs
1211           to be tied into the windowing system of the platform being
1212           used. On GNU/Linux systems, Firefox is a GTK2+ application.
1213           There is also KDE support through the use of the Klash
1214           plugin.
1215         </p><p>
1216           <span class="application">Gnash</span> can use either several different GUI toolkits to create the window,
1217           and to handle events for the standalone player.
1218         </p><p>
1219           The SDL version is more limited, but runs on all
1220           platforms, including win32. It has no support for event
1221           handling, which means mouse clicks, keyboard presses, and
1222           window resizing doesn't work. I personally find the default
1223           event handler slow and unresponsive. <span class="application">Gnash</span> has support to
1224           use fast events, (currently not enabled) which is an SDL
1225           hack using a background thread to pump events into the SDL
1226           event queue at a much higher rate.
1227         </p><p>
1228           There are a variety of development libraries that build a GUI
1229           widget system on top of SDL and OpenGL. The use of these to
1230           add menus and dialog boxes to the SDL version is being
1231           considered.
1232         </p><p>
1233           The GTK support is currently the most functional, and the
1234           best integrated into Firefox. The performance of this
1235           version is better than the SDL version because of the more
1236           efficient event handling within GTK. For the best end user
1237           experience, use the GTK enabled version.
1238         </p><p>
1239           GTK also allows <span class="application">Gnash</span> to have menus and dialog
1240           boxes. Currently this is only being utilized in a limited
1241           fashion for now. There is a right mouse button menu that
1242           allows the user to control the movie being player the same
1243           way the existing keyboard commands do.
1244         </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>
1245           Klash is MozPlugger type support for KDE's Konqueror web
1246           browser. Klash makes <span class="application">Gnash</span> a <span class="emphasis"><em>kpart</em></span>, so it's
1247           integrated into KDE better than when using MozPlugger. Klash
1248           uses the standalone player, utilizing <span class="application">Gnash</span>'s "-x" window
1249           plugin command line option.
1250         </p><p>
1251           By default, Klash is not built. To enable building Klash,
1252           use the <span class="emphasis"><em>--enable-klash</em></span> option when
1253           configuring. Other than installing, there is nothing else
1254           that needs to be done to install Klash.
1255         </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>
1256     <span class="application">Gnash</span>'s common message logging system uses a <span class="emphasis"><em>printf()</em></span>
1257     style format. Despite the C-like appearance, however, <span class="application">Gnash</span>'s LogFile class
1258     by default does not use <span class="emphasis"><em>printf()</em></span> for formatting the
1259     messages at all.
1260   </p><p>
1261     All logging calls are converted using templated functions to use boost::format.
1262     This uses a similar syntax to printf(), but additionally guarantees type-safety
1263     and allows more advanced substition using positional identifiers besides the
1264     traditional printf() type identifiers. The conversion templates mean that
1265     the logging API remains exactly the same, regardless of which method is
1266     used to format the log output.
1267   </p><p>
1268     The templates for conversion are generated using Boost.Preprocessor. Currently,
1269     they allow for a maximum of 16 arguments (more than enough for all current
1270     usage), but that can be expanded or reduced by changing
1271     <span class="emphasis"><em>#define ARG_NUMBER</em></span> in <span class="emphasis"><em>libbase/log.h</em></span>.
1272   </p><p>
1273     If a filename is not specified before the log file is needed, a
1274     default name of <span class="emphasis"><em>gnash-dbg.log</em></span> is used. If Gnash is
1275     started from the command line, the debug log will be created in
1276     the current directory. When executing Gnash from a launcher under
1277     <span class="emphasis"><em>GNOME</em></span> or <span class="emphasis"><em>KDE</em></span> the debug file goes in your
1278     home directory, since that's considered the current directory. A file name
1279     can be specified using either <span class="emphasis"><em>gnashrc</em></span> or a
1280     call to the LogFile instance itself.
1281   </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>
1282         <span class="application">Gnash</span> provides 9 specialized logging calls, each using the <span class="emphasis"><em>printf()</em></span>-style
1283         call similar to this:
1284         </p><pre class="programlisting">log_error(const char* fmt, ...)</pre><p>
1285         The different
1286         calls and their purposes are described below. The output to stdout and to disk
1287         are always identical, although writing the log to disk can be separately disabled.
1288     </p><div class="variablelist"><dl><dt><span class="term">log_error</span></dt><dd><p>
1289             Display an error message if verbose output is enabled. This is
1290             always printed at a verbosity level of 1 or more.
1291           </p></dd><dt><span class="term">log_unimpl</span></dt><dd><p>
1292             Displays a warning to the user about missing Gnash features.
1293             We expect all calls to this function to disappear over time, as we
1294             implement those features of Flash. This is
1295             always printed at a verbosity level of 1 or more.
1296           </p></dd><dt><span class="term">log_trace</span></dt><dd><p>
1297             Used only for the output of the ActionScript <span class="emphasis"><em>trace()</em></span>
1298              function. This is
1299             always printed at a verbosity level of 1 or more.
1300           </p></dd><dt><span class="term">log_debug</span></dt><dd><p>
1301             Logs debug information. This is printed at a verbosity level of 2 or more.
1302           </p></dd><dt><span class="term">log_action</span></dt><dd><p>
1303             Log action execution information. Wrap all calls to this
1304             function (and other related statements) into an
1305             IF_VERBOSE_ACTION macro, so to allow completely removing
1306             all the overhead at compile time and reduce it at
1307             runtime. This is printed at a verbosity level of 1 or more
1308             only if action logging is enabled.
1309           </p></dd><dt><span class="term">log_parse</span></dt><dd><p>
1310             Log SWF parsing  Wrap all calls to this function (and
1311             other related statements) into an IF_VERBOSE_PARSE macro,
1312             so to allow completely removing all the overhead at
1313             compile time and reduce it at runtime. This is printed at a
1314             verbosity level of 1 or more
1315             only if parser logging is enabled.
1316           </p></dd><dt><span class="term">log_swferror</span></dt><dd><p>
1317             This indicates an error in how the binary SWF file was
1318             constructed, i.e.probably a bug in the tools used to build
1319             the SWF file. Wrap all calls to this function (and other
1320             related statements) into an IF_VERBOSE_MALFORMED_SWF
1321             macro, so to allow completely removing all the overhead at
1322             compile time and reduce it at runtime. This is printed at a
1323             verbosity level of 1 or more
1324             only if malformed SWF logging is enabled.
1325           </p></dd><dt><span class="term">log_aserror</span></dt><dd><p>
1326             This indicates an erroneous actionscript request such as
1327             an incorrect number of arguments or an invalid argument.
1328             Wrap all calls to this function (and other
1329             related statements) into an IF_VERBOSE_ASCODING_ERRORS
1330             macro, so to allow completely removing all the overhead at
1331             compile time and reduce it at runtime.
1332             This is printed at a
1333             verbosity level of 1 or more
1334             only if AS coding error logging is enabled.
1335           </p></dd><dt><span class="term">log_abc</span></dt><dd><p>
1336                 Extremely verbose logging related to AVM2/ABC execution.
1337                 This is printed at verbosity level 3.
1338           </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>
1339       This is the main API for initializing and manipulating the logging output.
1340       By default, the log will be written to <span class="emphasis"><em>gnash-dbg.log</em></span>
1341       file whenever a verbose option is
1342       supplied.
1343     </p><div class="variablelist"><dl><dt><span class="term">getDefaultInstance()</span></dt><dd><p>
1344             This allows the construction of a LogFile on the first call, so
1345             ensuring that it the logfile is always initialised before use.
1346             It is the only way to access a LogFile instance. The logfile
1347             itself is never opened until it is needed.
1348           </p></dd><dt><span class="term">setLogFilename(const std::string&amp; filename)</span></dt><dd><p>
1349             Use this to set a different name for the disk-based log file.
1350             This setting can be overridden by a directive in gnashrc. If the
1351             log file is already open, a call to setLogFilename() will close it;
1352             a file with the new name will be opened when it is next needed.
1353           </p></dd><dt><span class="term">closeLog()</span></dt><dd><p>
1354             Close a debug log. The disk file remains.
1355           </p></dd><dt><span class="term">removeLog()</span></dt><dd><p>
1356             Delete the debug log file from disk.
1357           </p></dd><dt><span class="term">setVerbosity()</span></dt><dd><p>
1358             Increment the verbosity level.
1359           </p></dd><dt><span class="term">setVerbosity(int level)</span></dt><dd><p>
1360             Set the verbosity level to a specified level.
1361           </p></dd><dt><span class="term">setStamp(bool flag)</span></dt><dd><p>
1362             If <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>true</em></span>, then print a
1363             timestamp prefixed to every output line. If
1364             <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>false</em></span>, then don't print
1365             a timestamp.
1366           </p></dd><dt><span class="term">setWriteDisk(bool flag)</span></dt><dd><p>
1367             If <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>true</em></span>, then create the
1368             disk file. If <span class="emphasis"><em>flag</em></span> is <span class="emphasis"><em>false</em></span>,
1369             then don't create the disk file.
1370           </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>
1371         Sound in <span class="application">Gnash</span> is handled by libgnashsound. This library takes
1372         care of interfacing with a sound handler.
1373     </p><p>
1374       There are two different settings related to sound support:
1375       <span class="emphasis"><em>pluginsound</em></span> and <span class="emphasis"><em>sound</em></span>.
1376       This was done in order to allow the plugin to be independently
1377       configured, for instance to block sound from advertisements.
1378     </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>
1379         Sounds can be divided into two groups: event-sounds and soundstreams.
1380         Event-sounds are contained in a single SWF frame, but the playtime can
1381         span multiple frames. Soundstreams can be (and normally are) divided
1382         between the SWF frames the soundstreams spans. This means that if a
1383         gotoframe-action jumps to a frame which contains data for a soundstream,
1384         playback of the stream can be picked up from there.
1385       </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>
1386         When <span class="application">Gnash</span> parses a SWF-file, it creates a sound handler if possible
1387         and hands over the sounds to it. Since the event-sounds are contained
1388         in one frame, the entire event-sound is retrieved at once, while a
1389         soundstream maybe not be completely retrieved before the entire
1390         SWF-file has been parsed. But since the entire soundstream doesn't need
1391         to be present when playback starts, it is not necessary to wait.
1392       </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>
1393         When a sound is about to be played <span class="application">Gnash</span> calls the sound handler, which
1394         then starts to play the sound and return. All the playing is done by
1395         threads (in both SDL and Gstreamer), so once
1396         started the audio and graphics are not sync'ed with each other, which
1397         means that we have to trust both the graphic backend and the audio
1398         backend to play at correct speed.
1399       </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>
1400         The current SDL sound backend has replaced the original sound
1401         handler, based on SDL_mixer, which by design had some limitations,
1402         making it difficult to implement needed features such as support
1403         for soundstreams.
1404         The SDL sound backend supports both event-sounds and soundstreams,
1405         using <span class="application">Gnash</span>'s internal ADPCM, and optionally MP3 support, using
1406         FFMPEG.
1407         When it receives sound data it is stored without being decoded, unless
1408         it is ADPCM, which is decoded in the parser. When playing, backend
1409         relies on a function callback for retrieving output sound, which is
1410         decoded and re-sampled if needed, and all sound output is mixed together.
1411         The current SDL sound backend was made since <span class="application">Gnash</span> needed a working
1412         sound backend as soon as possible, and since the gstreamer backend at
1413         the time suffered from bugs and/or lack of features in gstreamer. The
1414         result was the most complete and best sound handler so far.
1415         The advantages of the SDL sound handler is speed, and ease of use,
1416         while its only real disadvantage is that it has to be compiled with
1417         MP3 support, which some Linux distributions will probably not like...
1418       </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>
1419         The Gstreamer backend, though not complete, supports both soundstreams
1420         and event-sounds. When receiving sound data it stores it compressed,
1421         unless if it's ADPCM event-sounds, which it decodes by the parser.
1422         When the playback starts, the backend sets up a
1423         Gstreamer bin containing a decoder (and other things needed) and places
1424         it in a Gstreamer pipeline, which plays the audio. All the sound data is
1425         not passed at once, but in small chunks, and via callbacks the
1426         pipeline gets fed. The advantages of the Gstreamer backend is that it
1427         supports both kinds of sound, it avoids all the legal MP3-stuff, and it
1428         should be relatively easy to add VORBIS support. The drawbacks are that
1429         it has longer "reply delay" when starting the playback of a sound, and
1430         it suffers under some bugs in Gstreamer that are yet to be fixed.
1431       </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>
1432         Gstreamer uses pipelines, bins and elements. Pipelines are the
1433         main bin, where all other bins or elements are places. Visually the
1434         audio pipeline in <span class="application">Gnash</span> looks like this:
1435       </p><pre class="programlisting">
1436          ___
1437         |Bin|_
1438         |___| \
1439          ___   \ _____       ____________
1440         |Bin|___|Adder|_____|Audio output|
1441         |___|   |_____|     |____________|
1442          ___   /
1443         |Bin|_/
1444         |___|
1445
1446       </pre><p>
1447         There is one bin for each sound which is being played. If a sound is
1448         played more the once at the same time, multiple bins will be made. The
1449         bins contains:
1450       </p><pre class="programlisting">
1451
1452         |source|---|capsfilter|---|decoder|---|aconverter|---|aresampler|---|volume|
1453
1454       </pre><p>
1455         In the source element we place parts of the undecoded sound data, and
1456         when playing the pipeline will pull the data from the element. Via
1457         callbacks it is refilled if needed. In the capsfilter the data is
1458         labeled with the format of the data. The decoder (surprise!) decodes
1459         the data. The audioconverter converts the now raw sound data into a
1460         format accepted by the adder, all input to the adder must in the same
1461         format. The audio re-sampler re-samples the raw sound data into a sample
1462         accepted by the adder, all input to the adder must in the same
1463         sample rate. The volume element makes it possible to control the volume
1464         of each sound.
1465       </p><p>
1466         When a sound is done being played it emits a End-Of-Stream-signal
1467         (EOS), which is caught by an event-handler-callback, which then makes
1468         sure that the bin in question is removed from the pipeline. When a
1469         sound is told by <span class="application">Gnash</span> to stop playback before it has ended playback,
1470         we do something (not yet finally implemented), which makes the bin emit
1471         an EOS, and the event-handler-callback will remove the sound from the
1472         pipeline. Unfortunately Gstreamer currently has a bug which causes the
1473         entire pipeline to stop playing when unlinking an element from the
1474         pipeline; so far no fix is known.
1475       </p><p>
1476         Gstreamer also contains a bug concerning linking multiple elements to
1477         the adder in rapid succession, which causes to adder to "die" and stop
1478         the playback.
1479       </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>
1480        <a class="link" href="#runtests" title="Running the Tests">Instructions on running tests</a>
1481        can be found in the section on building <span class="application">Gnash</span>.
1482      </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>
1483         Currently <span class="application">Gnash</span> uses three other tools to help with
1484         testing. Two of these are free compilers for the SWF
1485         format. This lets us write simple test cases for <span class="application">Gnash</span> to test
1486         specific features, and to see how the features operate.
1487       </p><p>
1488         The primary compiler used at this time is <a class="ulink" href="http://ming.sf.net" target="_top">Ming</a>. Since release 0.3,
1489         <span class="emphasis"><em>Ming</em></span> includes a command-line compiler,
1490         <span class="emphasis"><em>makeswf</em></span>. This allows test case development
1491         to be done entirely with free tools.
1492       </p><p>
1493         The other tools are optional.
1494         <a class="ulink" href="http://www.gnu.org/software/dejagnu" target="_top">DejaGnu</a>
1495         is used to run multiple test cases in an automated
1496         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
1497         <a class="ulink" href="http://gcc.gnu.org" target="_top">GCC</a> and
1498         <a class="ulink" href="http://www.samba.org" target="_top">Samba</a>.
1499       </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>
1500         ActionScript test cases are located under testsuite/actionscript.all/;
1501         these are organized in one file for the ActionScript class.
1502         Other Ming-generated tests are under testsuite/ming-misc.all/;
1503         these are typically used to test specific tag types.
1504         Full movies are located in testsuite/movies.all/ and
1505         sample movies are found in testsuite/samples/.
1506         Other directories in testsuite/ are (or shall be) used for other
1507         kind of tests.
1508       </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>
1509         Writing ActionScript tests is very simple. The
1510         <span class="emphasis"><em>makeswf</em></span> compiler makes use of the C preprocessor,
1511         thus allowing the inclusion of definitions for macros and external
1512         files. We use these feature to provide common utilities
1513         for test units.
1514       </p><p>
1515         Each test unit sets an <span class="emphasis"><em>rcsid</em></span> variable, includes the
1516         <span class="emphasis"><em>check.as</em></span> file and performs some checks using
1517         the provided macros. Here is an example:
1518
1519         </p><pre class="programlisting">
1520
1521           // This variable will be used by check.as
1522           // to show testcase info as part of the test runs.
1523           rcsid="Name and version of this testcase, usually the RCS id";
1524
1525           #include "check.as"
1526
1527           // Test object creation
1528           check(new Object() instanceOf Object);
1529
1530           // Test parseInt
1531           check(isNaN(parseInt('none')));
1532
1533           // Test assignment
1534           var a = 1;
1535           check_equals(a, 1);
1536
1537           // .. your tests here ...
1538         </pre><p>
1539       </p><p>
1540         The check(expr) macro will <span class="emphasis"><em>trace</em></span> PASSED or FAILED
1541         together with the expression being evaluated and the line number
1542         of the check. This is the format expected by DejaGnu.
1543       </p><p>
1544         The <span class="emphasis"><em>check_equals(obtained, expected)</em></span> macro uses equality operator
1545         <span class="emphasis"><em>==</em></span> to check for equality. When possible, use of the
1546         <span class="emphasis"><em>check_equals()</em></span> macro is preferred over <span class="emphasis"><em>check()</em></span>
1547         because it shows what the actual result was in case of a failure.
1548       </p><p>
1549         Additionally, the check.as file provides a transparent way to send
1550         results to a TextField rather then using trace. This is very useful
1551         when you use a SWF player without tracing support.
1552       </p><p>
1553         Test units are built by running <span class="emphasis"><em>make TestName-v#.swf</em></span>.
1554         This will use TestName.as as source and the value of # as target version.
1555         Allowed target version are from 5 to 8 (inclusive).
1556       </p><p>
1557         Note that if you get a syntax error from the compiler, the line
1558         number will refer to the pre-processed file. This file is called
1559         <span class="emphasis"><em>TestName.as.pp</em></span> or <span class="emphasis"><em>TestName-v#.swf.frame#.pp</em></span>
1560         (depending on Ming version) and it's not thrown away by
1561         <span class="emphasis"><em>makeswf</em></span> to make debugging easier.
1562       </p><p>
1563         Sometimes an expression is only supported by a specific SWF
1564         version, or it's evaluated differently by different SWF versions.
1565         For this purpose the framework provides an OUTPUT_VERSION macro
1566         that you can use to switch code based on output version. For example:
1567
1568         </p><pre class="programlisting">
1569
1570           #if OUTPUT_VERSION &gt;= 7
1571           check(_root.getSWFVersion == OUTPUT_VERSION);
1572           #endif
1573
1574         </pre><p>
1575       </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>
1576         Ming-based test cases are located in testsuite/misc-ming.all
1577         and contain a test generator and a test runner.
1578         The test generator (usually a C program) is used to produce the SWF
1579         file, while the test runner (a C++ program) will run it using a
1580         MovieTester class.
1581         Note that only the test generator needs Ming, not the test
1582         runner, so if Ming isn't installed on the user's host,
1583         the test cases can still be run as long as SWF has been distributed.
1584       </p><p>
1585         Producing tests using Ming has the advantage that you can easily see
1586         and modify the full source code for the SWF movie, and you can use
1587         some <a class="link" href="#ming_testgenerator_facilities" title="Using Ming-based test generators facilities">facilities</a>
1588         provided by the <span class="application">Gnash</span> testing framework to easily run tests.
1589       </p><p>
1590         For generic Ming API documentation, see <a class="ulink" href="http://www.libming.org/" target="_top">http://www.libming.org</a>.
1591       </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>
1592         Ming-based test generator facilities, which might be moved into
1593         a loadable SWF in the future, can be currently used by your test
1594         generator by including the ming_utils.h file and calling the
1595         appropriate functions.
1596       </p><p>
1597         The most useful facility provided for Ming-based SWF test generators
1598         is a Dejagnu-like TestState ActionScript class.
1599         In order to use this facility you must call 'add_dejagnu_functions()'
1600         right after Movie creation.
1601         The function takes an SWFMovie object and some parameters specifying
1602         depth and location of the "visual" trace textfield; it instantiates
1603         a global 'TestState' ActionScript object to keep track of test's state.
1604       </p><p>
1605         You will <span class="emphasis"><em>not</em></span> need to directly invoke the
1606         TestState object created by the 'add_dejagnu_functions()' routine,
1607         rather you will be using C macros hiding its complexity:
1608
1609         </p><pre class="programlisting">
1610
1611         check(SWFMovie mo, const char* expr)
1612
1613                 Evaluate an ActionScript expression.
1614
1615         xcheck(SWFMovie mo, const char* expr)
1616
1617                 Evaluate an ActionScript expression.
1618                 A failure is expected
1619                 (for cases where the call exposes a known bug).
1620
1621         check_equals(SWFMovie mo, const char* obtained, const char* expected)
1622
1623                 Evaluate an ActionScript expression against an expected output.
1624
1625         xcheck_equals(SWFMovie mo, const char* obtained, const char* expected)
1626
1627                 Evaluate an ActionScript expression against an expected output.
1628                 A failure is expected (for cases where the call exposes a known bug).
1629
1630         print_tests_summary(SWFMovie mo)
1631
1632                 This will print a summary of tests run, and should be
1633                 called as the last step in your SWF generator.
1634         </pre><p>
1635
1636       </p><p>
1637         Test cases generated using Ming and the provided
1638         <a class="link" href="#ming_testgenerator_facilities" title="Using Ming-based test generators facilities">facilities</a>
1639         will be self-contained, which means they can be used as tests
1640         by simply running them with whatever Player you might have.
1641         Any 'check' or 'check_equals' result will be both traced and
1642         printed in a textfield. You can use 'gprocessor -v' to have
1643         <span class="application">Gnash</span> use them as tests.
1644       </p><p>
1645         See section <a class="link" href="#writing_test_runners" title="Writing Test Runners">Writing Test Runners</a>
1646         for information about writing SWF test runners.
1647       </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>
1648         If you want/need to use a different compiler for your test cases (there's
1649         plenty of open source tools for generating SWF out there), you can still
1650         make use of a loadable SWF utility provided as part of the <span class="application">Gnash</span> testsuite
1651         to let your test consistent with the rest of the suite.
1652       </p><p>
1653         The loadable module is called <span class="emphasis"><em>Dejagnu.swf</em></span> and is built during
1654         <span class="emphasis"><em>make check</em></span> under testsuite/misc-ming.all. In order to use it
1655         you will need to load it into your SWF. We currently load it with an IMPORT
1656         tag for our ActionScript based test cases, but you can probably also use
1657         loadMovie or whatever works in the target SWF you're generating. Just make
1658         sure that the module is initialized before using it. You can check this by
1659         inspecting the <span class="emphasis"><em>dejagnu_module_initialized</em></span> variable, which will
1660         be set to 'true' when all initialization actions contained in the
1661         <span class="emphasis"><em>Dejagnu.swf</em></span> file are executed.
1662       </p><p>
1663         Once the module is loaded you will be able to invoke the following functions,
1664         all registered against the <span class="emphasis"><em>_root</em></span> sprite (effects of <span class="emphasis"><em>_lockroot</em></span>
1665         untested):
1666         </p><pre class="programlisting">
1667
1668           check(expression, [message]);
1669
1670           Evaluate the expression.
1671           Trace result (PASSED: expression / FAILED: expression).
1672           If fails, *visually* trace the failure.
1673           If second argument is given, it will be used instead of
1674           'expression' for printing results.
1675
1676           check_equals(obtained, expected)
1677
1678           Evaluate an expression against an expected output.
1679           Trace result (PASSED: obtained == expected / FAILED: expected X, obtained Y)
1680           If fails, *visually* trace the failure.
1681
1682           xcheck(expression, [message]);
1683
1684           Evaluate the expression.
1685           Trace result (XPASSED: expression / XFAILED: expression).
1686           If fails, *visually* trace the failure.
1687           If second argument is given, it will be used instead of
1688           'expression' for printing results.
1689
1690           xcheck_equals(obtained, expected)
1691
1692           Evaluate an expression against an expected output.
1693           Trace result (XPASSED: obtained == expected / XFAILED: expected X, obtained Y)
1694           If fails, *visually* trace the failure.
1695
1696           note(string)
1697
1698           Print string, both as debugging and *visual* trace.
1699
1700           totals()
1701
1702           Print a summary of tests run, both as debugging and *visual* traces.
1703
1704         </pre><p>
1705       </p><p>
1706         Visual traces are lines of text pushed to a textarea defined
1707         by the <span class="emphasis"><em>Dejagnu.swf</em></span> module. The textarea is
1708         initially placed at <span class="emphasis"><em>0, 50</em></span> and is
1709         <span class="emphasis"><em>600x800</em></span> in size. You can resize/move the clip
1710         after loading it. Also, you can completely make the clip
1711         invisible if that bothers you. The important thing is the
1712         <span class="emphasis"><em>debugging</em></span> trace (call to the trace
1713         function). The latter will be used by the testing framework.
1714       </p><p>
1715         See section <a class="link" href="#writing_test_runners" title="Writing Test Runners">Writing Test Runners</a>
1716         for information about writing a test runners for your self-contained tests.
1717       </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>
1718         Test runners are executables that run one or more tests,
1719         writing results in Dejagnu form to standard output.
1720       </p><p>
1721         The Dejagnu form uses a standard set of labels when printing test
1722         results.  These are:
1723         </p><div class="informaltable"><table border="1" width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
1724                   <p>Label</p>
1725                 </th><th valign="top">
1726                   <p>Meaning</p>
1727                 </th></tr></thead><tbody><tr><td align="left" valign="top">
1728                   <p>PASSED</p>
1729                 </td><td align="left" valign="top">
1730                   <p>The test succeeded.</p>
1731                 </td></tr><tr><td align="left" valign="top">
1732                   <p>FAILED</p>
1733                 </td><td align="left" valign="top">
1734                   <p>The test failed.</p>
1735                 </td></tr><tr><td align="left" valign="top">
1736                   <p>XPASSED</p>
1737                 </td><td align="left" valign="top">
1738                   <p>The test succeeded, but was expected to fail.</p>
1739                 </td></tr><tr><td align="left" valign="top">
1740                   <p>XFAILED</p>
1741                 </td><td align="left" valign="top">
1742                   <p>The test failed, and was expected to fail.</p>
1743                 </td></tr><tr><td align="left" valign="top">
1744                   <p>UNRESOLVED</p>
1745                 </td><td align="left" valign="top">
1746                   <p>The results of the test could not be automatically
1747                   parsed.</p>
1748                 </td></tr><tr><td align="left" valign="top">
1749                   <p>UNTESTED</p>
1750                 </td><td align="left" valign="top">
1751                   <p>This test case is not complete.</p>
1752                 </td></tr><tr><td align="left" valign="top">
1753                   <p>UNSUPPORTED</p>
1754                 </td><td align="left" valign="top">
1755                   <p>The test case relies on a conditional feature which
1756                   is not present in your environment.</p>
1757                 </td></tr></tbody></table></div><p>
1758       </p><p>
1759         The following labels may also appear:
1760         </p><div class="informaltable"><table border="1" width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
1761                   <p>Label</p>
1762                 </th><th valign="top">
1763                   <p>Meaning</p>
1764                 </th></tr></thead><tbody><tr><td align="left" valign="top">
1765                   <p>ERROR</p>
1766                 </td><td align="left" valign="top">
1767                   <p>There was a serious error in running the test. </p>
1768                 </td></tr><tr><td align="left" valign="top">
1769                   <p>WARNING</p>
1770                 </td><td align="left" valign="top">
1771                   <p>There may have been a problem with running the
1772                   test.</p>
1773                 </td></tr><tr><td align="left" valign="top">
1774                   <p>NOTE</p>
1775                 </td><td align="left" valign="top">
1776                   <p>There was some additional information given about
1777                   the test.</p>
1778                 </td></tr></tbody></table></div><p>
1779       </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>
1780           The simplest test runner is one that simply invokes <span class="application">Gnash</span>
1781           in verbose mode against a self-contained SWF test movie.
1782           Self-contained SWF test movies are the ones that print
1783           the PASSED/FAILED etc. lines using ActionScript (traces).
1784           By invoking <span class="application">Gnash</span> in verbose mode this movie will behave
1785           as a compliant "Test Runner".
1786         </p><p>
1787           A generator for simple test runners can be found in
1788           <span class="emphasis"><em>testsuite/generic-testrunner.sh</em></span>.
1789           The script can be invoked by passing it <span class="emphasis"><em>$(top_builddir)</em></span>
1790           as the first argument and the name of the SWF file (without the path)
1791           as the second argument. This will create a specific runner for your
1792           test in the current build directory.
1793           A simple Makefile.am rule for doing this follows:
1794           </p><pre class="programlisting">
1795             MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
1796             sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf &gt; $@
1797             chmod +x $@
1798           </pre><p>
1799         </p><p>
1800           By default, the generated test runner will play the movie up to the
1801           last frame. If you want the movie to be played more then once (maybe
1802           because you're exactly testing loop features) you can use the -r switch
1803           to the generic-testrunner.sh call. The following will create a runner
1804           playing the movie twice:
1805           </p><pre class="programlisting">
1806             MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
1807             sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir) MyTest.swf &gt; $@
1808             chmod +x $@
1809           </pre><p>
1810         </p><p>
1811           In case your test movie stops before the last frame, or you want to control the
1812           exact number of times to call the frame advancement routine, you can use the
1813           -f switch to control that.
1814           </p><pre class="programlisting">
1815             MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
1816             sh $(srcdir)/../generic-testrunner.sh -f10 $(top_builddir) MyTest.swf &gt; $@
1817             chmod +x $@
1818           </pre><p>
1819           When both -f and -r are given, the first exit condition reached will take effect.
1820         </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>
1821           There are some parts of <span class="application">Gnash</span> that can NOT be tested
1822           by only using ActionScript tests. Examples include: frame
1823           advancements, actual actions execution, gui events and so on.
1824         </p><p>
1825           In this case you might want to use the MovieTester class to
1826           implement a C++ test runner. Be aware that you can <span class="emphasis"><em>mix</em></span> tests in
1827           the MovieTester-based class with <span class="emphasis"><em>self-contained</em></span>
1828           tests in the SWF file as long as you activate verbosity for
1829           the debug logfile. This is done, for example, for the
1830           DefineEditTextVariableNameTest.swf file. The corresponding
1831           test runner (DefineEditTextVariableNameTest-Runner) is a C++
1832           runner based on MovieTester class. If you run the runner you
1833           see two kinds of test results: the ones coming from the ActionScript
1834           engine, and the ones coming from the test runner. You can
1835           distinguish between the two because the former contains an additional
1836           timestamp and the latter does not. Also, you'll see two final
1837           summaries for the two test sets. The 'make check' rule, which uses
1838           the testsuite/simple.exp output parser as its work-horse, will
1839           count test results from both test sets.
1840         </p><p>
1841           Movie testers are executables which load an SWF, generate events
1842           (both user or system) on it, and check its state using
1843           a standard interface.
1844         </p><p>
1845           To help this process a MovieTester class is defined in the
1846           testsuite/MovieTester.{h,cpp} files; see Doxygen documentation
1847           for more information.
1848         </p><p>
1849           Note that you do NOT need access to the SWF source code in order
1850           to implement a Movie tester for it.  Some knowledge about the
1851           expected behavior suffices.
1852         </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>
1853       An ActionScript 2.0 class refers to two different kinds of objects:
1854       a genuine class that can be used to construct instances of that class,
1855       and a simple singleton object. Examples of the simple object classes
1856       are Mouse and Stage. This chapter is mainly concerned with genuine
1857       classes.
1858   </p><p>
1859       A genuine ActionScript 2.0 class comprises a constructor function
1860       and a prototype object. Classes may have native type information,
1861       but most do not.
1862   </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>
1863       In ActionScript, a prototype is an object that contains
1864       all the methods that an instantiated object will inherit.
1865     </p><p>
1866         In Gnash, the prototype of an ActionScript class, like all other
1867         objects, is implemented as an <span class="emphasis"><em>as_object</em></span>.
1868         When the class is initialized, the class interface - its
1869         inheritable properties - are attached to the prototype as_object.
1870         The following example demonstrates how methods can be attached:
1871       </p><pre class="programlisting">
1872         void
1873         attachBooleanInterface(as_object&amp; o)
1874         {
1875             Global_as&amp; gl = getGlobal(o);
1876             o.init_member("toString", gl.createFunction(boolean_tostring));
1877             o.init_member("valueOf", gl.createFunction(boolean_valueof));
1878         }
1879       </pre><p>
1880     </p><p>
1881       Classes may also have static properties. These are functions or
1882       data members attached directly to the class. They do not require
1883       an instance of the class to be used. These are attached in exactly
1884       the same way, but attached to the class (that is, the constructor
1885       function), not the prototype object.
1886     </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>
1887         A constructor function is an ActionScript callback function that
1888         is called when an instance of a class is created. The "this" object
1889         during the call is a new object.
1890     </p><p>
1891         Constructor functions may do tasks such as attaching properties or
1892         type information to the new object. They may also do absolutely
1893         nothing. Anything attached to the object during the constructor
1894         call is an "own property" of the new object, not an inherited property.
1895     </p><p>
1896         The following examples are valid constructors. A constructor should never return anything
1897         other than as_value() (an undefined value). Exceptions to this rule are the
1898         basic types String, Boolean, and Number. These have constructor functions that can
1899         also be called as conversion functions. They have a special implementation that
1900         behaves differently depending on the calling context.
1901     </p><pre class="programlisting">
1902         as_value
1903         movieclip_ctor(const fn_call&amp; fn)
1904         {
1905         }
1906
1907         as_value
1908         class_ctor(const fn_call&amp; fn)
1909         {
1910             as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);
1911
1912             if (fn.nargs) {
1913                 string_table&amp; st = getStringTable(fn);
1914                 this_ptr-&gt;set_member(st.find("property"), fn.arg(0));
1915             }
1916             return as_value();
1917         }
1918     </pre><p>
1919         Native typing is added using a Relay subclass. This only applies to a small number of
1920         classes. The native typing is added during the constructor function using the
1921         as_object::setRelay() function. All Relay types must inherit from the Relay base class.
1922     </p><p>
1923         Native typing can be accessed in ActionScript callback functions using the
1924         ensure&lt;&gt; function template:
1925     </p><pre class="programlisting">
1926           as_value
1927           boolean_toString(const fn_call&amp; fn)
1928           {
1929               // This ensures that the function can only be called as a
1930               // member function of a genuine Boolean_as object.
1931               Boolean_as* b = ensure&lt;IsNativeType&lt;Boolean_as&gt; &gt;(fn);
1932
1933               return as_value(b.value());
1934           }
1935       </pre></div><div class="sect1"><div class="titlepage"></div><p>
1936         There are three kinds of property: simple data members, functions, and getter-setters.
1937         All three kinds may be inherited. Getter-setters are attached using the
1938         init_property() function. Functions and data members using the init_member() function.
1939     </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>
1940     The Gnash project relies on the community of Gnash users to test
1941     the player.  Feedback is critical to any successful project.  Not
1942     only does it let us know that people use Gnash, but it helps us
1943     understand the community's needs. Gnash uses a bug tracker on
1944     <a class="ulink" href="http://savannah.gnu.org" target="_top">http://savannah.gnu.org</a> to manage these reports.
1945   </p><p>
1946     When filing a report, please follow the guidelines below. The better
1947     your bug report is, the easier it will be for the developers to
1948     address the issue. Bug reports without enough information will
1949     be asked to provide this information anyway. Adding
1950     critical details, like the Operating System you are on, its
1951     version, and any relevant error messages from Gnash that you get.
1952   </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>
1953       For starters, it's a good idea to obtain a copy of the latest
1954       snapshot. Although Gnash is primarily released as source, the
1955       Gnash build infrastructure allows the automated building of
1956       binary packages. Often the version of Gnash as packaged by a
1957       GNU/Linux or BSD distribution is based on the last official
1958       release, which could be months out of date. It helps us, if
1959       this is the case, for you to try a newer packaged build of Gnash.
1960     </p><p>
1961       You can get a fresh binary package of Gnash, as well as recent
1962       source packages from
1963       <a class="ulink" href="http://www.getgnash.org/packages/" target="_top">
1964         http://www.getgnash.org/packages
1965       </a>.
1966     </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>
1967       Search the <a class="ulink" href="https://savannah.gnu.org/bugs/?group=gnash" target="_top">Gnash
1968       bug tracker</a> to see if the bug has already been identified.
1969     </p><p>
1970       If the issue has already been reported, you should not file
1971       a bug report.  However, you may add some additional information
1972       to the ticket if you feel that it will be beneficial to the
1973       developers.  For instance, if someone reported a memory issue
1974       on Ubuntu GNU/Linux, and you noticed the same problem on OpenBSD,
1975       your stacktrace would be useful.  Conversely, adding a "me too"
1976       note to a feature request is not helpful.
1977     </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>
1978       A good bug report should be precise, explicit, and discrete.
1979       This means that there should be just one bug per ticket, and
1980       that a ticket should contain the following information:
1981     </p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p>
1982           An overview of the problem;
1983         </p></li><li class="listitem" style="list-style-type: circle"><p>
1984           Instructions on how to replicate the bug;
1985         </p></li><li class="listitem" style="list-style-type: circle"><p>
1986           A description of what happened when you performed the steps
1987           to replicate the bug, and what you expected to happen;
1988         </p></li><li class="listitem" style="list-style-type: circle"><p>
1989           Your system information: operating system name and version, as
1990           well as the versions of major development dependencies;
1991         </p></li><li class="listitem" style="list-style-type: circle"><p>
1992           The release number or checkout timestamp for the version of Gnash
1993           where you observe the problem;
1994         </p></li><li class="listitem" style="list-style-type: circle"><p>
1995           The file <code class="filename">config.log</code>, which should be
1996           attached as a file;
1997         </p></li><li class="listitem" style="list-style-type: circle"><p>
1998           A descriptive title.
1999         </p></li></ul></div><p>
2000       Include any additional information that you feel might be useful
2001       to the developers.
2002     </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>
2003       After following the steps described above, you can file a bug report at
2004       <a class="ulink" href="https://savannah.gnu.org/bugs/?group=gnash" target="_top">https://savannah.gnu.org/bugs/?group=gnash</a>.
2005     </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>
2006     <span class="application">Gnash</span> supports the creation of custom extensions to ActionScript. This
2007     allows you to integrate any conceivable system or library function into
2008     ActionScript execution.
2009   </p><p>
2010       Extensions do not represent a general alteration of the ActionScript
2011       language. They are designed to allow <span class="application">Gnash</span> to be more
2012       flexible and powerful where it is required. They allow you to
2013       customize <span class="application">Gnash</span> for your own purposes and to distribute those changes
2014       to other users who need them. They are not intended for use in
2015       normal SWF execution or internet browsing, but rather for
2016       executing SWFs designed to use those extensions under controlled
2017       conditions.
2018   </p><p>
2019       Some extensions are distributed with <span class="application">Gnash</span>, mainly to serve
2020       as an example. Extensions are not enabled by default, both for
2021       security and compatibility reasons.
2022   </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>
2023       Each new extension should live in its own directory. The
2024       extensions included in <span class="application">Gnash</span> are all in the
2025       <span class="emphasis"><em>gnash/extensions</em></span> directory. Creating an extension
2026       requires a Makefile.am,
2027     </p><p>
2028       If you are adding this extension to the <span class="application">Gnash</span> source tree
2029       itself, then you need to make two changes to add the new
2030       extension.  The first change is to add the directory to the list in
2031       extensions/Makefile.am. This can be done either by adding the
2032       new directory to the SUBDIRS setting, or by wrapping it in a
2033       conditional test.  The other change is to add it to the AC_OUTPUT list in
2034       <span class="emphasis"><em>configure.ac</em></span> so the new directory will be
2035       configured along with the rest of <span class="application">Gnash</span>.
2036     </p><p>
2037       Each extension should have an ActionScript source file included
2038       that tests the new class, and this file should be referenced in
2039       the new Makefile.am in the <span class="emphasis"><em>check_PROGRAMS</em></span>
2040       variable so that "make check" works.
2041     </p><p>
2042       When creating an extension that is a wrapper for an existing
2043       development library API, it's often better to make this a thin
2044       layer than to get carried away with creating beautiful
2045       abstractions. Higher-level classes that offer a lot of new
2046       functionality are fine, but this is different from wrapping a library
2047       so it can be used from within <span class="application">Gnash</span>.
2048     </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>
2049           An extension defines a built-in type of ActionScript object.
2050           An ActionScript object may have native type information known
2051           as a Relay. This adds an extra layer of complexity and runtime
2052           cost, so avoid using it unless necessary.
2053       </p><p>
2054           ActionScript classes consist of a constructor function and a
2055           prototype object. The constructor function is called when an
2056           instance of your extension class is created. The prototype object
2057           contains the properties inherited by instances of the extension
2058           class. To create an extension class, you must provide an entry
2059           function with the following signature:
2060       </p><pre class="programlisting">
2061               void extension_init(as_object&amp; where, const ObjectURI&amp; uri);
2062       </pre><p>
2063           This will be called during initialization. The first argument
2064           is the object to which your class will be attached. For extensions,
2065           this is the Global object, known as _global in ActionScript 2.0.
2066           The second argument is ignored for extension classes.
2067       </p><p>
2068           Our extension class will imaginatively be called
2069           "Extension". Our extension_init function takes care of
2070           attaching the prototype and constructor function to the passed object
2071           object. One way to do this is as follows:
2072       </p><pre class="programlisting">
2073           void
2074           extension_init(as_object&amp; where, const ObjectURI&amp; uri)
2075           {
2076               // Get a reference to the global object.
2077               Global_as&amp; gl = getGlobal(where);
2078
2079               // Create a prototype object
2080               as_object* proto = createObject(gl);
2081
2082               // Create the class
2083               as_object* cl = gl.createClass(&amp;extension_ctor, proto);
2084
2085               // Attach the class's functions to the prototype object.
2086               attachInterface(*proto);
2087
2088               // Attach static properties to the class itself
2089               attachStaticInterface(*cl);
2090
2091               // Attach the class to the passed object.
2092               where.init_member("Extension", cl);
2093           }
2094       </pre><p>
2095           You will notice three functions in the example above that need
2096           definition. The first two are attachInterface() and
2097           attachStaticInterface(). This is a convention
2098           in <span class="application">Gnash</span> to separate ActionScript interface creation from the
2099           registration of our Extension class. We will see why this is
2100           useful later. The attachInterface function may be defined
2101           as follows:
2102       </p><pre class="programlisting">
2103           void
2104           attachInterface(as_object&amp; obj)
2105           {
2106               Global_as&amp; gl = getGlobal(obj);
2107               obj.init_member("ext1", gl.createFunction(&amp;extension_ext1));
2108           }
2109       </pre><p>
2110           This attaches a function called ext1 to the Extension class
2111           prototype. When ext1 is called in ActionScript, <span class="application">Gnash</span> will
2112           execute the C++ function named extension_ext1. This is known as
2113           a ActionScript callback function and must have the correct signature.
2114           We will deal with this next. The member function function will be
2115           inherited by all instances of Extension.
2116       </p><p>
2117           The attachStaticInterface() function looks identical:
2118       </p><pre class="programlisting">
2119           void
2120           attachStaticInterface(as_object&amp; obj)
2121           {
2122               Global_as&amp; gl = getGlobal(obj);
2123               obj.init_member("static1", gl.createFunction(&amp;extension_static1));
2124           }
2125       </pre><p>
2126           This does exactly the same as the previous function, but it
2127           attaches "static" properties to the class. Such functions can
2128           be called directly, that is, without requiring an instance of
2129           Extension:
2130       </p><pre class="programlisting">
2131           Extension.static();
2132       </pre><p>
2133           The other undefined function is extension_ctor. Like extension_ext1,
2134           this is an ActionScript callback function. Such functions have the
2135           signature:
2136       </p><pre class="programlisting">
2137           as_value extension_ctor(const fn_call&amp; fn);
2138       </pre><p>
2139           The fn_call type contains information about the ActionScript function
2140           call, including the number of arguments, the "this" object
2141           (if
2142           present), the VM and the Global object. With one small exception,
2143           the constructor function extension_ctor, and the ext1 function
2144           implementation, extension_ext1, do the same thing.
2145       </p><p>
2146           The function extension_static is the simplest function. A possible
2147           implementation is as follows:
2148       </p><pre class="programlisting">
2149           as_value
2150           extension_static(const fn_call&amp; fn)
2151           {
2152               // Reject any calls with no arguments. We must ensure that
2153               // we do not access out-of-range arguments.
2154               if (!fn.nargs) return as_value();
2155
2156               // Convert the first argument to a double.
2157               const double d = fn.arg(0).to_number();
2158
2159               // This is the return value of the function.
2160               return as_value(d * 6);
2161           }
2162       </pre><p>
2163           The member function implementation extension_ext1 is barely more
2164           complex. It could look like this:
2165       </p><pre class="programlisting">
2166           as_value extension_ext1(const fn_call&amp; fn)
2167           {
2168               // This ensures that the function can only be called as a
2169               // member function of an object. If not, execution of the
2170               // function ends at this point.
2171               as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);
2172
2173               // Reject any calls with no arguments.
2174               if (!fn.nargs) return as_value();
2175
2176               const as_value&amp; arg0 = fn.arg(0);
2177
2178               // The string table manages all strings; we refer to strings
2179               // by their index in the table.
2180               string_table&amp; st = getStringTable(fn);
2181
2182               // Set a member named "property" on the object to the value of
2183               // the first argument.
2184               this_ptr-&gt;set_member(st.find("property"), arg0);
2185
2186               // This is the return value of the function.
2187               return as_value("return value");
2188           }
2189       </pre><p>
2190           It is not a very useful function. In ActionScript, this definition
2191           will have the following effect:
2192       </p><pre class="programlisting">
2193           var e = new Extension();
2194           var i = e.ext1(8);
2195           trace(e.property) // traces "8"
2196           trace(i) // traces "return value"
2197       </pre><p>
2198           The constructor function is very similar, but has a different
2199           purpose. When the actionscript "new Extension" is called,
2200           this extension_ctor function will be called with a newly-created
2201           object as the "this" object. Its job is to attach properties
2202           to the "this" object. Unlike the class prototype's propertes
2203           that we attached in the attachInterface function, any properties
2204           attached here belong directly to the new object.
2205       </p><pre class="programlisting">
2206           as_value
2207           extension_ctor(const fn_call&amp; fn)
2208           {
2209               // When called as a constructor, there is always a "this" object
2210               as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);
2211
2212               // The init_member function will never replace an existing
2213               // property.
2214               this_ptr-&gt;init_member("myProperty", true);
2215
2216               // A constructor function must not return anything.
2217               return as_value();
2218           }
2219       </pre><p>
2220           You may not want to do anything in your constructor. It is perfectly
2221           valid to use the following as a constructor function (and indeed
2222           this is recommended unless you need more complex behaviour):
2223       </p><pre class="programlisting">
2224           as_value extension_ctor(const fn_call&amp; fn)
2225           {
2226           }
2227       </pre><p>
2228           If you have defined all the callback functions in the way
2229           described above, you can simplify the class registration. <span class="application">Gnash</span>
2230           provides a convenience function to register a built-in class. In
2231           this case, your entry function would look like this:
2232       </p><pre class="programlisting">
2233           void
2234           extension_init(as_object&amp; where, const ObjectURI&amp; uri)
2235           {
2236               string_table&amp; st = getStringTable(where);
2237               registerBuiltinClass(where, extension_ctor, attachInterface,
2238                   0, st.find("Extension"));
2239           }
2240       </pre><p>
2241           For more advanced extensions, you may want to store extra information
2242           in an object. You can do this using a Relay. This imposes type
2243           restrictions when using the object in ActionScript. A Relay is
2244           a C++ class that could look like this:
2245       </p><pre class="programlisting">
2246           #include "Relay.h"
2247           #include &lt;complex&gt;
2248
2249           class Complex : public Relay
2250           {
2251           public:
2252               typedef std::complex&lt;double&gt; type;
2253               Complex(type c = type()) : _c(c) {}
2254               type _c;
2255           };
2256       </pre><p>
2257           Using this Relay involves two steps: attaching it, and accessing
2258           it. Relays must be attached in the constructor:
2259       </p><pre class="programlisting">
2260           as_value extension_ctor(const fn_call&amp; fn)
2261           {
2262               as_object* this_ptr = ensure&lt;ValidThis&gt;(fn);
2263               this_ptr-&gt;setRelay(new Complex())
2264           }
2265       </pre><p>
2266           To access this information in ActionScript callback functions, we
2267           must ensure that the object has the correct type of Relay attached.
2268           A toString function (which must also be attached to the prototype!)
2269           could look like this:
2270       </p><pre class="programlisting">
2271           as_value
2272           extension_toString(const fn_call&amp; fn)
2273           {
2274               // This ensures that the function can only be called as a
2275               // member function of a genuine Complex object.
2276               Complex* c = ensure&lt;IsNativeType&lt;Complex&gt; &gt;(fn);
2277
2278               std::ostringstream s;
2279               s &lt;&lt; "real:" &lt;&lt; c.real() &lt;&lt; ",imag: &lt;&lt; c.imag();
2280               // This is the return value of the function.
2281               return as_value(s.str());
2282           }
2283       </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>
2284       You can resort to the time honored technique of creating a
2285       loop before the point you want to set a breakpoint for. <span class="application">Gnash</span>
2286       will stop playing the movie at this point, and then you can
2287       externally attach GDB to the running process, or type
2288       <span class="emphasis"><em>^C</em></span> to drop into the GDB command console.
2289     </p><pre class="programlisting">
2290       bool stall = true;
2291       while (stall) {
2292           sleep 1;
2293       }
2294     </pre><p>
2295       Once you have set the breakpoints you want, reset the value of
2296       the <span class="emphasis"><em>stall</em></span> variable to break out of the
2297       loop, and the SWF movie will then continue playing.
2298     </p><pre class="programlisting">
2299       (gdb) set variable stall = false;
2300       continue
2301     </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>
2302       <span class="application">Gnash</span> has some extensions included in the distribution. This is
2303       mostly because they were written by the <span class="application">Gnash</span> team. Extensions
2304       can be external to gnash, <span class="application">Gnash</span> needs no compiled in knowledge
2305       to load an extension file.
2306     </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>
2307     The GTK ActionScript class follows the same API as Gtk2, even down
2308     to the same arguments to the same function names. This means
2309     you're actually programming GTK,you're just using ActionScript
2310     instead of python, perl, or C. This extension makes it possible to
2311     write Flash movies that use the Gtk2 widgets for user interface
2312     components.
2313   </p><div class="variablelist"><dl><dt><span class="term">window_new</span></dt><dd><p>
2314           Create a new window.
2315         </p></dd><dt><span class="term">signal_connect</span></dt><dd><p>
2316           Add an event handler to a widget.
2317         </p></dd><dt><span class="term">container_set_border_width</span></dt><dd><p>
2318           Set the width of the window border.
2319         </p></dd><dt><span class="term">button_new_with_label</span></dt><dd><p>
2320           Create a new button and give it the specified label.
2321         </p></dd><dt><span class="term">signal_connect_swapped</span></dt><dd><p>
2322           Swap signals. Commonly used for <span class="emphasis"><em>delete</em></span> event handling.
2323         </p></dd><dt><span class="term">container_add</span></dt><dd><p>
2324               Add one widget to another as a child.
2325             </p></dd><dt><span class="term">widget_show</span></dt><dd><p>
2326           Display the widget on the screen.
2327         </p></dd><dt><span class="term">main</span></dt><dd><p>
2328           Start the main GTK event loop. This function does not return.
2329         </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>
2330     Flash movies are traditionally forbidden from accessing the
2331     filesystem, but this may be necessary for some embedded
2332     applications. Especially in the case of a user console, currently
2333     there is no way to get input into a Flash movie but through a
2334     TextField.
2335   </p><div class="variablelist"><dl><dt><span class="term">fopen</span></dt><dd><p>
2336           Open the file.
2337         </p></dd><dt><span class="term">fread</span></dt><dd><p>
2338           Read a series of bytes from the opened file.
2339         </p></dd><dt><span class="term">fgetc</span></dt><dd><p>
2340           Read a single byte from the opened file.
2341         </p></dd><dt><span class="term">fgets</span></dt><dd><p>
2342           Read a single line until a Carriage Return from the opened file.
2343         </p></dd><dt><span class="term">gets</span></dt><dd><p>
2344           Read a single line from the standard in.
2345         </p></dd><dt><span class="term">getchar</span></dt><dd><p>
2346           Read a single character from the standard in.
2347         </p></dd><dt><span class="term">fwrite</span></dt><dd><p>
2348         </p></dd><dt><span class="term">fputc</span></dt><dd><p>
2349           Write a single character to the opened file.
2350         </p></dd><dt><span class="term">fputs</span></dt><dd><p>
2351           Write a single line to the opened file.
2352         </p></dd><dt><span class="term">puts</span></dt><dd><p>
2353           Write a single line to standard out..
2354         </p></dd><dt><span class="term">putchar</span></dt><dd><p>
2355           Write a single character to standard out..
2356         </p></dd><dt><span class="term">fflush</span></dt><dd><p>
2357           Flush the current opened file to disk.
2358         </p></dd><dt><span class="term">fseek</span></dt><dd><p>
2359           Seek to a location within the opened file.
2360         </p></dd><dt><span class="term">ftell</span></dt><dd><p>
2361           Report the current position within the opened file.
2362         </p></dd><dt><span class="term">fclose</span></dt><dd><p>
2363           Close the opened file.
2364         </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>
2365     The MySQL ActionScript class follows the same API as MySQL, even down
2366     to the same arguments to the same function names. This enables a
2367     Flash movie to have direct access to a MySQL
2368     database. Traditionally Flash movies have had no database
2369     support, they either had to use arrays, or use XML to communicate
2370     to an application specific external database daemon.
2371   </p><div class="variablelist"><dl><dt><span class="term">connect</span></dt><dd><p>
2372           Connect to a MySQL database.
2373         </p></dd><dt><span class="term">qetData</span></dt><dd><p>
2374           Get data from the database.
2375         </p></dd><dt><span class="term">disconnect</span></dt><dd><p>
2376           Disconnect from a MySQL database.
2377         </p></dd><dt><span class="term">query</span></dt><dd><p>
2378           Execute an SQL query to the database.
2379         </p></dd><dt><span class="term">fetch_row</span></dt><dd><p>
2380           Fetch a row from the query results.
2381         </p></dd><dt><span class="term">num_fields</span></dt><dd><p>
2382         </p></dd><dt><span class="term">free_result</span></dt><dd><p>
2383           Free the results of a query.
2384         </p></dd><dt><span class="term">store_results</span></dt><dd><p>
2385           Store the results of a query.
2386         </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>
2387     This document is based mostly on my own reverse engineering of the
2388     RTMP protocol and AMF format. <span class="emphasis"><em>tcpdump</em></span> and
2389     <span class="emphasis"><em>ethereal</em></span> are your friend. Some additional info that got
2390     me started was from the <a class="ulink" href="http://www.osflash.org/red5" target="_top">Red5</a>
2391     project. <span class="emphasis"><em>Red5</em></span> is the only other open source SWF
2392     server. So some details are still vague, but as the implementation
2393     appears to work, we'll figure out what they are later.
2394   </p><p>
2395     The Real Time Messaging Protocol was created by MacroMedia (now
2396     Adobe) for delivering SWF objects and video over a network
2397     connection. Currently the only servers which support this format
2398     are the MacroMedia Media sever, and the Open Source Red5 project.
2399   </p><p>
2400     This is a simple protocol, optimized for poor bandwidth
2401     connections. It can support up to 64 concurrent streams over the
2402     same network connection. Part of each AMF packet header contains
2403     the index number of the stream. A single RTMP message can contain
2404     multiple AMF packets.
2405   </p><p>
2406     An RTMP connection uses Tcp/ip port 1935. It is also possible to
2407     tunnel RTMP over an HTTP connection using port 80. Each AMF packet
2408     is 128 bytes long except for streaming audio, which has 64 byte
2409     packets.
2410   </p><p>
2411     The basics of the RTMP protocol are as follows. All communications
2412     are initiated by the client.
2413     </p><div class="mediaobject" align="center"><img src="images/rtmp.png" align="middle"></div><p>
2414   </p><p>
2415     The client starts the RTMP connection by sending a single byte
2416     with a value of 0x3. This byte is followed by a data block of 1536
2417     bytes. The format if this data block is unknown, but it appears to
2418     not be actually used by the protocol except as a handshake.
2419   </p><p>
2420     The server receives this packet, stores the 1536 byte data block,
2421     and then send a single byte with the value of 0x3, followed by two
2422     1536 data blocks. The second data block is the full contents of
2423     the original data block as sent by the client.
2424   </p><p>
2425     The client receives the 1536 byte data block, and if they match,
2426     the connection is established. After the handshake process is
2427     done, there are three other messages that the client sends to the
2428     sever to start the data flowing.
2429   </p><p>
2430     The first AMF packet sent to the server contains the
2431     <span class="emphasis"><em>connect</em></span> packet. This doesn't appear to do
2432     much but notify the server the client is happy with the
2433     handshake, and ready to start reading packets.
2434   </p><p>
2435     The second packet is the <span class="emphasis"><em>NetConnection</em></span> object from
2436     the client. This ActionScript class is used by the SWF movie to
2437     create the network connection to the server.
2438   </p><p>
2439     The third packet is the <span class="emphasis"><em>NetStream</em></span> object from the
2440     client. This is the ActionScript class used to specify the file to
2441     be streamed by the server.
2442   </p><p>
2443     The RTMP packet for our example looks like this:
2444
2445     </p><pre class="programlisting">
2446       030000190000c91400000000020007connect00?f0000000000000030003app0200#
2447       software/gnash/tests/1153948634.flv0008flashVer02000cLNX 6,0,82,0 0006
2448       swfUrl02001dfile:///file|%2Ftmp%2Fout.swfc30005tcUrl\002\0004
2449       rtmp://localhost/software/gnash/tests/1153948634.flv\000\000\t
2450       \002\000\005userx
2451     </pre><p>
2452
2453     We'll take this apart in a bit, but you can see how all three AMF
2454     packets are in the same message. The message is received in
2455     several 128 byte blocks, with the last one being less than
2456     that. The total size of the RTMP message is in the header, so the
2457     reader can tell if the entire message was read or not.
2458   </p><p>
2459     The RTMP header is first, followed by the connect message as an
2460     ASCII string as the message body. The following AMF packet is the
2461     <span class="emphasis"><em>NetConnection</em></span> one, which specifies that this is coming
2462     from a SWF application. This also contains the file path the server
2463     can use to find the file to stream. This is then followed by the
2464     version number, which I assume is the version of the SWF player,
2465     so the server knows what it is talking to.
2466   </p><p>
2467     The third packet is the one from <span class="emphasis"><em>NetStream</em></span>, which
2468     specifies the URL used for the movie, followed by the user name
2469     for a semblance of security.
2470   </p><p>
2471     For the next level of detail, we'll explain the format of AMF. AMF
2472     is used by the RTMP protocol to transfer data. Each SWF object
2473     is encapsulated in an AMF packet, including streaming audio or
2474     video.
2475   </p><p>
2476     The first byte of the RTMP header determines two things about the
2477     rest of the message. The first 2 bits of this byte signify the
2478     total size of the RTMP header. The RTMP header is of a variable
2479     size, so this is important.
2480
2481     </p><div class="variablelist"><dl><dt><span class="term">00</span></dt><dd><p>
2482             This specifies the header contains 12 bytes, including
2483             this one.
2484           </p></dd><dt><span class="term">01</span></dt><dd><p>
2485             This specifies the header contains 8 bytes, including this
2486             one.
2487           </p></dd><dt><span class="term">02</span></dt><dd><p>
2488             This specifies the header contains 4 bytes, including this
2489             one.
2490           </p></dd><dt><span class="term">03</span></dt><dd><p>
2491             This specifies the header contains 1 byte, so this is the
2492             complete header.
2493           </p></dd></dl></div><p>
2494   </p><p>
2495     The other 6 bits in this byte represent the AMF index. As a single
2496     RTMP connection can support multiple data streams, this signifies
2497     which stream this packet is for. Once an AMF object is fully
2498     received by the client, the AMF index may be reused.
2499   </p><p>
2500     For messages with headers of at least 4 bytes, the next 3 bytes are
2501     used by audio and video data packets, but at this time the meaning
2502     of this field is unknown.
2503   </p><p>
2504     For messages with a 8 byte or larger header, the next 3 bytes
2505     determine the size of the RTMP message being transmitted. Messages
2506     with a 1 byte or 4 byte header use a standard size, 128 bytes for
2507     video, and 64 bytes for audio.
2508   </p><p>
2509     For messages with an 8 byte or larger header, the next byte is the
2510     type of the AMF object.
2511
2512     </p><div class="variablelist"><dl><dt><span class="term">0x3</span></dt><dd><p>
2513             This specifies the content type of the RTMP packet is the
2514             number of bytes read. This is used to start the RTMP
2515             connection.
2516           </p></dd><dt><span class="term">0x4</span></dt><dd><p>
2517             This specifies the content type of the RTMP message is a
2518             <span class="emphasis"><em>ping</em></span> packet.
2519           </p></dd><dt><span class="term">0x5</span></dt><dd><p>
2520             This specifies the content type of the RTMP message is
2521             server response of some type.
2522           </p></dd><dt><span class="term">0x6</span></dt><dd><p>
2523             This specifies the content type of the RTMP packet is
2524             client request of some type.
2525           </p></dd><dt><span class="term">0x8</span></dt><dd><p>
2526             This specifies the content type of the RTMP packet is an
2527             audio message.
2528           </p></dd><dt><span class="term">0x9</span></dt><dd><p>
2529             This specifies the content type of the RTMP message is a
2530             video packet.
2531           </p></dd><dt><span class="term">0x12</span></dt><dd><p>
2532             This specifies the content type of the RTMP message is
2533             notify.
2534           </p></dd><dt><span class="term">0x13</span></dt><dd><p>
2535             This specifies the content type of the RTMP message is
2536             shared object.
2537           </p></dd><dt><span class="term">0x14</span></dt><dd><p>
2538             This specifies the content type of the RTMP message is
2539             remote procedure call. This invokes the method of a SWF
2540             class remotely.
2541           </p></dd></dl></div><p>
2542
2543   </p><p>
2544     There are two sets of data types to consider. One set is used by
2545     the to specify the content type of the AMF object, the other is an
2546     ActionScript data type tag used to denote which type of object is
2547     being transferred.
2548   </p><p>
2549     The values of the initial type byte are:
2550     </p><div class="variablelist"><dl><dt><span class="term">0x0</span></dt><dd><p>
2551             This specifies the data in the AMF packet is a numeric
2552             value. All numeric values in SWF are 64 bit,
2553             <span class="emphasis"><em>big-endian</em></span>.
2554           </p></dd><dt><span class="term">0x1</span></dt><dd><p>
2555             This specifies the data in the AMF packet is a boolean
2556             value.
2557           </p></dd><dt><span class="term">0x2</span></dt><dd><p>
2558             This specifies the data in the AMF packet is an
2559             <span class="emphasis"><em>ASCII</em></span> string.
2560           </p></dd><dt><span class="term">0x3</span></dt><dd><p>
2561             This specifies the data in the AMF packet is a SWF
2562             object. The SWF object data type field further along in
2563             the message specifies which type of ActionScript object it
2564             is.
2565           </p></dd><dt><span class="term">0x4</span></dt><dd><p>
2566             This specifies the data in the AMF packet is a SWF
2567             movie, ie. another SWF movie.
2568           </p></dd><dt><span class="term">0x5</span></dt><dd><p>
2569             This specifies the data in the AMF packet is a NULL
2570             value. NULL is often used as the return code from calling
2571             SWF functions.
2572           </p></dd><dt><span class="term">0x6</span></dt><dd><p>
2573             This specifies the data in the AMF packet is a
2574             undefined. This is also used as the return code from
2575             calling SWF functions.
2576           </p></dd><dt><span class="term">0x7</span></dt><dd><p>
2577             This specifies the data in the AMF packet is a reference.
2578           </p></dd><dt><span class="term">0x8</span></dt><dd><p>
2579             This specifies the data in the AMF packet is a ECMA
2580             array.
2581           </p></dd><dt><span class="term">0x9</span></dt><dd><p>
2582             This specifies the data in the AMF packet is the end of an
2583             object definition. As an object is transmitted with
2584             multiple AMF packets, this lets the server know when the
2585             end of the object is reached.
2586           </p></dd><dt><span class="term">0xa</span></dt><dd><p>
2587             This specifies the data in the AMF packet is a Strict
2588             array.
2589           </p></dd><dt><span class="term">0xb</span></dt><dd><p>
2590             This specifies the data in the AMF packet is a date.
2591           </p></dd><dt><span class="term">0xc</span></dt><dd><p>
2592             This specifies the data in the AMF packet is a multi-byte
2593             string. Multi-byte strings are used for international
2594             language support to represent non <span class="emphasis"><em>ASCII</em></span>
2595             fonts.
2596           </p></dd><dt><span class="term">0xd</span></dt><dd><p>
2597             This specifies the data in the AMF packet is a an
2598             unsupported feature.
2599           </p></dd><dt><span class="term">0xe</span></dt><dd><p>
2600             This specifies the data in the AMF packet is a record
2601             set.
2602           </p></dd><dt><span class="term">0xf</span></dt><dd><p>
2603             This specifies the data in the AMF packet is a AML
2604             object. XML objects are then parsed by the
2605             <span class="emphasis"><em>XML</em></span> ActionScript class.
2606           </p></dd><dt><span class="term">0x10</span></dt><dd><p>
2607             This specifies the data in the AMF packet is a typed object.
2608           </p></dd></dl></div><p>
2609
2610   </p><p>
2611     For messages with a 12 byte header, the last 4 bytes are the
2612     routing of the message. If the destination is the server, this
2613     value is the NetStream object source. If the destination is the
2614     client, this is the NetStream object for this RTMP message. A
2615     value of 0x00000000 appears to be reserved for the NetConnection
2616     object.
2617   </p><p>
2618     Multiple AMF streams can be contained in a single RTMP messages,
2619     so it's important to check the index of each AMF packet.
2620   </p><p>
2621     An example RTMP header might look like this. (spaces added between
2622     fields for clarity) All the numbers are in hex.
2623
2624     </p><pre class="screen">
2625       03 000019 0000c9 14 000000000
2626     </pre><p>
2627
2628     </p><div class="variablelist"><dl><dt><span class="term">03</span></dt><dd><p>
2629             The first two bits of this byte are the size of the
2630             header, which in this example is 00, for a 12 byte
2631             header. The next 6 bits is the AMF stream index number,
2632             which in this example is 0x3.
2633           </p></dd><dt><span class="term">000019</span></dt><dd><p>
2634             These 3 bytes currently have an unknown purpose.
2635           </p></dd><dt><span class="term">000c9</span></dt><dd><p>
2636             Since this example has a 12 byte header, this is the size
2637             of the RTMP message, in this case 201 bytes.
2638           </p></dd><dt><span class="term">14</span></dt><dd><p>
2639             This is the content type of the RTMP message, which in
2640             this case is to invoke a remote function call. (which we
2641             later see is the connect function).
2642           </p></dd><dt><span class="term">00000000</span></dt><dd><p>
2643             The source is the NetConnection object used to start this
2644             connection.
2645           </p></dd></dl></div><p>
2646
2647   </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>
2648     The AMF format is used in the LocalConnection, SharedObject,
2649     NetConnection, and NetStream ActionScript classes. This is a means
2650     of binary data interchange between SWF movies, or between a
2651     SWF player and a SWF server.
2652   </p><p>
2653     Like the RTMP messages, an AMF packet header can be of a variable
2654     size. The size is either the same as the initial header of the
2655     RTMP message, or a 1 byte header, which is commonly used for
2656     streaming audio or video data.
2657   </p><p>
2658     The body of an AMF packet may look something like this
2659     example. The spaces have been added for clarity.
2660
2661     </p><pre class="screen">
2662       02  0007 636f6e6e656374
2663     </pre><p>
2664
2665     </p><div class="variablelist"><dl><dt><span class="term">02</span></dt><dd><p>
2666             This is a single byte header. The value of the first 2
2667             bits is 0x3, and the AMF index is also 0x3.
2668           </p></dd><dt><span class="term">0007</span></dt><dd><p>
2669             This is the length in bytes of the string.
2670           </p></dd><dt><span class="term">63 6f 6e 6e 65 63 74</span></dt><dd><p>
2671             This is the string. Note that there is no null terminator
2672             since the length is specified.
2673           </p></dd></dl></div><p>
2674
2675   </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>
2676     The Mozilla SDK has two API layers for plugins. The older layer is
2677     documented in the <a class="ulink" href="http://www.gnu.org/software/gnash/manual/plugin.pdf" target="_top">
2678     Geeko Plugin API Reference</a>, and the newer layer doesn't
2679     appear to be documented. The new API is simpler, and is portable
2680     across multiple versions of Mozilla or Firefox. The new API is
2681     just a layer on top of the older one, so this manual still
2682     applies.
2683   </p><p>
2684     Most of the programming of a plugin is filling in real emphasis for
2685     the standard API functions and methods. Firefox uses these to
2686     create the plugin, and to send it data.
2687   </p><p>
2688     When initializing or destroying a plugin, no matter how many
2689     instances are being used, the C API is used. These functions are
2690     typically called once for each plugin that is loaded.
2691   </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>
2692       The lower layer is a C based API which is used by Firefox to
2693       initialize and destroy a plugin. This is so a plugin can be
2694       portable across multiple systems, since C++ emphasis is not portable
2695       between most C++ compilers. This is where most of the behind the
2696       scenes work is done in a plugin. For Gnash, the sources this
2697       lower layer are in <span class="emphasis"><em>plugin/mozilla-sdk</em></span>. They were
2698       added to the Gnash source tree so it wouldn't be necessary to
2699       have the Mozilla development packages installed to compile the
2700       Gnash plugin.
2701     </p><p>
2702       This is also the older API used for plugins, so is usually the
2703       one used if you dig around for plugin examples on the web. These
2704       are the main functions which have to be implemented in a plugin
2705       for it to be recognized by the browser, and to be initialized
2706       and destroyed.
2707     </p><div class="variablelist"><dl><dt><span class="term">NS_PluginInitialize</span></dt><dd><p>
2708             This C function gets called once when the plugin is
2709             loaded, regardless of how many instantiations there are
2710             actually playing movies. So this is where all the one
2711             time only initialization stuff goes that is shared by all
2712             the threads.
2713           </p></dd><dt><span class="term">NS_NewPluginInstance</span></dt><dd><p>
2714             This instantiates a new object for the browser. Returning
2715             a pointer to the C++ plugin object is what ties the C++
2716             and C emphasis parts of the API together.
2717           </p></dd><dt><span class="term">NS_DestroyPluginInstance</span></dt><dd><p>
2718             This destroys our instantiated object when the browser is
2719             done.
2720           </p></dd><dt><span class="term">NS_PluginShutdown</span></dt><dd><p>
2721             This is called when a plugin is shut down, so this is
2722             where all the one time only shutdown stuff goes.
2723           </p></dd><dt><span class="term">NPP_GetMIMEDescription</span></dt><dd><p>
2724             This is called to get the MIME types the plugin supports.
2725           </p></dd><dt><span class="term">NS_PluginGetValue</span></dt><dd><p>
2726             This is used by Firefox to query information from the
2727             plugin, like the supported MIME type, the version number,
2728             and a description.
2729           </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>
2730       The higher level layer is the one we are most concerned
2731       with. This is an instantiation of the
2732       <span class="emphasis"><em>nsPluginInstanceBase</em></span> class, as defined by the
2733       Mozilla SDK, for our plugin. With this API, a plugin is mostly
2734       defining the standard entry points for Firefox, and the emphasis
2735       that implements the glue between the Firefox and our plugin.
2736     </p><p>
2737       These are called for each instantiation of plugin. If there are
2738       three Flash movies on a web page, then three instances are
2739       created. Unfortunately for plugin programmers, these functions
2740       may randomly be called more than once, so it's good to use
2741       initialization flags for things that should only be done one per
2742       thread. For instance, <span class="emphasis"><em>nsPluginInstance::init()</em></span> and
2743       <span class="emphasis"><em>nsPluginInstance::SetWindow()</em></span> are called more than
2744       once, so the plugin must protect against actions that could be
2745       destructive.
2746     </p><div class="variablelist"><dl><dt><span class="term">nsPluginInstance::nsPluginInstance</span></dt><dd><p>
2747             Create a new plugin object.
2748           </p></dd><dt><span class="term">nsPluginInstance::init</span></dt><dd><p>
2749             This methods initializes the plugin object, and is
2750             called for every movie which gets played. This is where
2751             the thread-specific information goes.
2752           </p></dd><dt><span class="term">nsPluginInstance::SetWindow</span></dt><dd><p>
2753             This sets up the window the plugin is supposed to render
2754             into. This calls passes in various information used by
2755             the plugin to setup the window. This may get called
2756             multiple times by each instantiated object, so it can't
2757             do much but window specific setup here. This is where the
2758             main emphasis is that sets up the window for the plugin.
2759           </p></dd><dt><span class="term">nsPluginInstance::NewStream</span></dt><dd><p>
2760             Opens a new incoming data stream, which is the flash
2761             movie we want to play. A URL can be pretty ugly, like in
2762             this example:
2763             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"
2764             So this is where we parse the URL to get all the options
2765             passed in when invoking the plugin.
2766           </p></dd><dt><span class="term">nsPluginInstance::Write</span></dt><dd><p>
2767             Read the data stream from Mozilla/Firefox.  For now we
2768             read the bytes and write them to a disk file.
2769           </p></dd><dt><span class="term">nsPluginInstance::WriteReady</span></dt><dd><p>
2770             Return how many bytes we can read into the buffer.
2771           </p></dd><dt><span class="term">nsPluginInstance::DestroyStream</span></dt><dd><p>
2772             Destroy the data stream we've been reading. For Gnash,
2773             when the stream is destroyed means we've grabbed the
2774             entire movie. So we signal the thread to start reading and
2775             playing the movie.
2776           </p></dd><dt><span class="term">nsPluginInstance::shut</span></dt><dd><p>
2777             This is where the movie playing specific shutdown emphasis goes.
2778           </p></dd><dt><span class="term">nsPluginInstance::~nsPluginInstance</span></dt><dd><p>
2779             This destroys our plugin object.
2780           </p></dd><dt><span class="term">NS_PluginInitialize::initGL</span></dt><dd><p>
2781             This is a Gnash internal function that sets up OpenGL.
2782           </p></dd><dt><span class="term">NS_PluginInitialize::destroyContext</span></dt><dd><p>
2783             This is a Gnash internal function that destroys a GLX
2784             context.
2785           </p></dd><dt><span class="term">nsPluginInstance::getVersion</span></dt><dd><p>
2786             This returns the version of Mozilla this plugin supports.
2787           </p></dd><dt><span class="term">nsPluginInstance::GetValue</span></dt><dd><p>
2788             This returns information to the browser about the plugin's
2789             name and description.
2790           </p></dd><dt><span class="term">nsPluginInstance::URLNotify</span></dt><dd><p>
2791           </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>
2792       Neither OpenGL nor X11 has any built-in support for threads. Most
2793       actions aren't even atomic, so care has to be made to not corrupt
2794       any internal data. While it is difficult to render OpenGL from
2795       multiple threads, it can be done with the proper locking. The
2796       downside is the locking adds a performance hit, since all the
2797       threads will have to have the access synchronized by using
2798       mutexes.
2799     </p><p>
2800       The X11 context is maintained one per instantiation of the
2801       plugin. It is necessary to lock access to the X11 context when
2802       using threads by using <span class="emphasis"><em>XLockDisplay()</em></span> and
2803       <span class="emphasis"><em>XUnlockDisplay()</em></span>. A connection to the X11
2804       server is opened for every instantiation of the plugin using
2805       <span class="emphasis"><em>XOpenDisplay()</em></span>.
2806     </p><p>
2807       The <span class="emphasis"><em>GLX Context</em></span> is maintained one per
2808       instantiation of the plugin for a web page. If there are more
2809       than one Flash movie, there is more than one GLX Context. A GLX
2810       context can be created by using <span class="emphasis"><em>glXCreateContext()</em></span>,
2811       and then later destroyed by using <span class="emphasis"><em>glXDestroyContext()</em></span>.
2812       When swapping threads, the context is changed using
2813       <span class="emphasis"><em>glXMakeCurrent()</em></span>.
2814     </p><p>
2815       All the emphasis that directly accesses a GLX context or the X11
2816       display must be wrapped with a mutex.
2817     </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>
2818       Firefox on most UNIX systems is a GTK+ application, so it is
2819       possible to have the plugin hook into the X11 event handling via
2820       GLX or GTK. Since Firefox uses GTK, so does Gnash. This also
2821       allows the addition of a right-click mouse menu for controlling
2822       the player. The GTK build of Gnash offers the best browsing
2823       experience as it's more functional than the SDL version.
2824     </p><p>
2825       It is also possible to disable the <span class="emphasis"><em>GTK</em></span> support so
2826       only the older <span class="emphasis"><em>SDL</em></span> support is used. In this case
2827       Gnash can't support event handling within the browser. This
2828       means that when using the SDL of the plugin, mouse clicks and
2829       keys pressed get ignored. Windows also can't be resized, and
2830       sometimes they overrun their boundaries as well. To disable the
2831       GTK support and force SDL to be used anyway, configure with
2832       <span class="emphasis"><em>--disable-glext</em></span>
2833     </p><p>
2834
2835     </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>
2836       I know any discussion of coding styles leads to strong opinions,
2837       so I'll state simply I follow the <a class="ulink" href="http://www.gnu.org/prep/standards/standards.html" target="_top">GNU
2838       Coding Standards</a>. Where there is some flexibility as to
2839       the location of braces, I prefer mine on the end of a line when
2840       using an <span class="emphasis"><em>if</em></span>, <span class="emphasis"><em>while</em></span>, or <span class="emphasis"><em>do</em></span>
2841       statement. I find this more compact style easier to read and
2842       parse by eye. I'm also a big fan of always using
2843       braces around <span class="emphasis"><em>if</em></span> statements, even if they're one
2844       liners.
2845     </p><p>
2846       Here's my tweaked style settings for <span class="emphasis"><em>Emacs</em></span>, the one
2847       true editor to rule them all.
2848
2849       </p><pre class="programlisting">
2850       (defconst my-style
2851           '((c-tab-always-indent   . t)
2852            (c-auto-newline         . t)
2853            (c-hanging-braces-alist . (
2854                                    (brace-list-intro)
2855                                    (namespace-open)
2856                                    (inline-open)
2857                                    (block-open)
2858                                    (brace-list-open)
2859                                    (brace-list-close)
2860                                    (brace-entry-open)
2861                                    (brace-else-brace)
2862                                    (brace-elseif-brace)
2863                                    (class-open after)
2864                                    (class-close)
2865                                    (defun-open after)
2866                                    (defun-close)
2867                                    (extern-lang-open)
2868                                    (inexpr-class-open)
2869                                    (statement-open)
2870                                    (substatement-open)
2871                                    (inexpr-class-close)))
2872             (c-hanging-colons-alist . ((member-init-intro before)
2873                                    (inher-intro)
2874                                    (case-label after)
2875                                    (label after)
2876                                    (access-label after)))
2877             (c-offsets-alist    . (
2878                                    (innamespace . 0)
2879                                    (case-label  . 2)
2880                                    ))
2881             (c-cleanup-list     . (
2882                                    (scope-operator)
2883                                    (empty-defun-braces)
2884                                    (brace-else-brace)
2885                                    (brace-elseif-brace)
2886                                    (defun-close-semi)
2887                                    (list-close-comma)
2888                                    )
2889                                 )
2890     ;; no automatic newlines after ';' if following line non-blank or inside
2891     ;; one-line inline methods
2892     (add-to-list 'c-hanging-semi&amp;comma-criteria
2893                  'c-semi&amp;comma-no-newlines-before-nonblanks)
2894     (add-to-list 'c-hanging-semi&amp;comma-criteria
2895                  'c-semi&amp;comma-no-newlines-for-oneline-inliners)
2896 ;    (knr-argdecl-intro . -)
2897     (c-echo-syntactic-information-p . t)
2898     )
2899   "My GNU Programming Style")
2900     </pre><p>
2901
2902     </p><p>
2903       Another coding consideration: comments are good!  Over
2904       commenting isn't good.  Here is an over commented example:
2905
2906       </p><pre class="programlisting">
2907         counter++;              // increment counter
2908       </pre><p>
2909
2910       Gnash also uses <a class="ulink" href="http://www.doxygen.org" target="_top">Doxygen</a> style
2911       comments. These are processed by Doxygen when building a cross
2912       reference of all the classes, and is a good way to help push
2913       internals documentation from the depths of the code into
2914       documentation where it can be seen by others.
2915     </p><p>
2916       <span class="emphasis"><em>Doxygen</em></span> style comments for <span class="emphasis"><em>C++</em></span> code involves
2917       simply using three slashes <span class="emphasis"><em>///</em></span> instead of the
2918       standard two slashes <span class="emphasis"><em>//</em></span> used for C++
2919       comments. Here's a short comment block for the
2920       <span class="emphasis"><em>XML::cloneNode()</em></span> method:
2921
2922       </p><pre class="programlisting">
2923         /// \brief copy a node
2924         ///
2925         /// Method; constructs and returns a new XML node of the same type,
2926         /// name, value, and attributes as the specified XML object. If deep
2927         /// is set to true, all child nodes are recursively cloned, resulting
2928         /// in an exact copy of the original object's document tree.
2929         XMLNode &amp;
2930         XML::cloneNode(XMLNode &amp;newnode, bool deep) {
2931         ...
2932         }
2933       </pre><p>
2934     </p><p>
2935       The <span class="emphasis"><em>\brief</em></span> keyword means that the
2936       text becomes associated
2937       when listing all the classes on the generated web pages. The
2938       text after the blank link becomes the detailed description which
2939       appears on the generated web page for that class and method.
2940     </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>
2941         <span class="application">Gnash</span> is maintained by Rob Savoye. Other active developers
2942         are: Sandro Santilli, Bastiaan Jacques, Udo Giacomozzi, Chad
2943         Musick, Benjamin Wolsey, Zou Lunkai, and Russ Nelson. Please
2944         send all comments and suggestions to
2945         <code class="email">&lt;<a class="email" href="mailto:gnash-dev@gnu.org">gnash-dev@gnu.org</a>&gt;</code>. Past and sometimes current
2946         developers are Tomas Groth and Markus Gothe.
2947     </p><p>
2948         <span class="application">Gnash</span> was initially derived from <span class="application">GameSWF</span>.
2949         <span class="application">GameSWF</span> is maintained by
2950         Thatcher Ulrich <code class="email">&lt;<a class="email" href="mailto:tu@tulrich.com">tu@tulrich.com</a>&gt;</code>.  The following
2951         people contributed to <span class="application">GameSWF</span>:
2952         Mike Shaver, Thierry Berger-Perrin,
2953         Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit,
2954         and Rob Savoye.
2955     </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">
2956       Version 1.1, March 2000
2957     </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>
2958         </p><div class="address"><p>Free Software Foundation, Inc. <span class="street">59 Temple Place, <br>
2959         Suite 330</span>, <span class="city">Boston</span>, <span class="state">MA</span>  <br>
2960         <span class="postcode">02111-1307</span>  <span class="country">USA</span></p></div><p>
2961         Everyone is permitted to copy and distribute verbatim copies of this
2962         license document, but changing it is not allowed.
2963       </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>
2964       The purpose of this License is to make a manual, textbook, or
2965       other written document "free" in the sense of
2966       freedom: to assure everyone the effective freedom to copy and
2967       redistribute it, with or without modifying it, either
2968       commercially or non-commercially. Secondarily, this License
2969       preserves for the author and publisher a way to get credit for
2970       their work, while not being considered responsible for
2971       modifications made by others.
2972     </p><p>
2973       This License is a kind of "copyleft", which means
2974       that derivative works of the document must themselves be free in
2975       the same sense. It complements the GNU General Public License,
2976       which is a copyleft license designed for free software.
2977     </p><p>
2978       We have designed this License in order to use it for manuals for
2979       free software, because free software needs free documentation: a
2980       free program should come with manuals providing the same
2981       freedoms that the software does. But this License is not limited
2982       to software manuals; it can be used for any textual work,
2983       regardless of subject matter or whether it is published as a
2984       printed book. We recommend this License principally for works
2985       whose purpose is instruction or reference.
2986     </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>
2987       This License applies to any manual or other work that contains a
2988       notice placed by the copyright holder saying it can be
2989       distributed under the terms of this License. The
2990       "Document", below, refers to any such manual or
2991       work. Any member of the public is a licensee, and is addressed
2992       as "you".
2993     </p><p><a name="fdl-modified"></a>
2994       A "Modified Version" of the Document means any work
2995       containing the Document or a portion of it, either copied
2996       verbatim, or with modifications and/or translated into another
2997       language.
2998     </p><p><a name="fdl-secondary"></a>
2999       A "Secondary Section" is a named appendix or a
3000       front-matter section of the <a class="link" href="#fdl-document">Document</a> that deals exclusively
3001       with the relationship of the publishers or authors of the
3002       Document to the Document's overall subject (or to related
3003       matters) and contains nothing that could fall directly within
3004       that overall subject. (For example, if the Document is in part a
3005       textbook of mathematics, a Secondary Section may not explain any
3006       mathematics.)  The relationship could be a matter of historical
3007       connection with the subject or with related matters, or of
3008       legal, commercial, philosophical, ethical or political position
3009       regarding them.
3010     </p><p><a name="fdl-invariant"></a>
3011       The "Invariant Sections" are certain <a class="link" href="#fdl-secondary"> Secondary Sections</a> whose titles
3012       are designated, as being those of Invariant Sections, in the
3013       notice that says that the <a class="link" href="#fdl-document">Document</a> is released under this
3014       License.
3015     </p><p><a name="fdl-cover-texts"></a>
3016       The "Cover Texts" are certain short passages of
3017       text that are listed, as Front-Cover Texts or Back-Cover Texts,
3018       in the notice that says that the <a class="link" href="#fdl-document">Document</a> is released under this
3019       License.
3020     </p><p><a name="fdl-transparent"></a>
3021       A "Transparent" copy of the <a class="link" href="#fdl-document"> Document</a> means a machine-readable
3022       copy, represented in a format whose specification is available
3023       to the general public, whose contents can be viewed and edited
3024       directly and straightforwardly with generic text editors or (for
3025       images composed of pixels) generic paint programs or (for
3026       drawings) some widely available drawing editor, and that is
3027       suitable for input to text formatters or for automatic
3028       translation to a variety of formats suitable for input to text
3029       formatters. A copy made in an otherwise Transparent file format
3030       whose markup has been designed to thwart or discourage
3031       subsequent modification by readers is not Transparent.  A copy
3032       that is not "Transparent" is called "Opaque".
3033     </p><p>
3034       Examples of suitable formats for Transparent copies include
3035       plain ASCII without markup, Texinfo input format, LaTeX input
3036       format, SGML or XML using a publicly available DTD, and
3037       standard-conforming simple HTML designed for human
3038       modification. Opaque formats include PostScript, PDF,
3039       proprietary formats that can be read and edited only by
3040       proprietary word processors, SGML or XML for which the DTD
3041       and/or processing tools are not generally available, and the
3042       machine-generated HTML produced by some word processors for
3043       output purposes only.
3044     </p><p><a name="fdl-title-page"></a>
3045       The "Title Page" means, for a printed book, the
3046       title page itself, plus such following pages as are needed to
3047       hold, legibly, the material this License requires to appear in
3048       the title page. For works in formats which do not have any title
3049       page as such, "Title Page" means the text near the
3050       most prominent appearance of the work's title, preceding the
3051       beginning of the body of the text.
3052     </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>
3053       You may copy and distribute the <a class="link" href="#fdl-document">Document</a> in any medium, either
3054       commercially or noncommercially, provided that this License, the
3055       copyright notices, and the license notice saying this License
3056       applies to the Document are reproduced in all copies, and that
3057       you add no other conditions whatsoever to those of this
3058       License. You may not use technical measures to obstruct or
3059       control the reading or further copying of the copies you make or
3060       distribute. However, you may accept compensation in exchange for
3061       copies. If you distribute a large enough number of copies you
3062       must also follow the conditions in <a class="link" href="#fdl-section3" title="3. COPYING IN QUANTITY">section 3</a>.
3063     </p><p>
3064       You may also lend copies, under the same conditions stated
3065       above, and you may publicly display copies.
3066     </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>
3067       If you publish printed copies of the <a class="link" href="#fdl-document">Document</a> numbering more than 100,
3068       and the Document's license notice requires <a class="link" href="#fdl-cover-texts">Cover Texts</a>, you must enclose
3069       the copies in covers that carry, clearly and legibly, all these
3070       Cover Texts: Front-Cover Texts on the front cover, and
3071       Back-Cover Texts on the back cover. Both covers must also
3072       clearly and legibly identify you as the publisher of these
3073       copies. The front cover must present the full title with all
3074       words of the title equally prominent and visible. You may add
3075       other material on the covers in addition. Copying with changes
3076       limited to the covers, as long as they preserve the title of the
3077       <a class="link" href="#fdl-document">Document</a> and satisfy these
3078       conditions, can be treated as verbatim copying in other
3079       respects.
3080     </p><p>
3081       If the required texts for either cover are too voluminous to fit
3082       legibly, you should put the first ones listed (as many as fit
3083       reasonably) on the actual cover, and continue the rest onto
3084       adjacent pages.
3085     </p><p>
3086       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,
3087       you must either include a machine-readable <a class="link" href="#fdl-transparent">Transparent</a> copy along with
3088       each Opaque copy, or state in or with each Opaque copy a
3089       publicly-accessible computer-network location containing a
3090       complete Transparent copy of the Document, free of added
3091       material, which the general network-using public has access to
3092       download anonymously at no charge using public-standard network
3093       protocols. If you use the latter option, you must take
3094       reasonably prudent steps, when you begin distribution of Opaque
3095       copies in quantity, to ensure that this Transparent copy will
3096       remain thus accessible at the stated location until at least one
3097       year after the last time you distribute an Opaque copy (directly
3098       or through your agents or retailers) of that edition to the
3099       public.
3100     </p><p>
3101       It is requested, but not required, that you contact the authors
3102       of the <a class="link" href="#fdl-document">Document</a> well before
3103       redistributing any large number of copies, to give them a chance
3104       to provide you with an updated version of the Document.
3105     </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>
3106       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
3107       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
3108       the Modified Version under precisely this License, with the
3109       Modified Version filling the role of the Document, thus
3110       licensing distribution and modification of the Modified Version
3111       to whoever possesses a copy of it. In addition, you must do
3112       these things in the Modified Version:
3113     </p><div class="itemizedlist"><ul class="itemizedlist" type="opencircle"><li class="listitem" style="list-style-type: circle"><p title="A"><b>A. </b>
3114             Use in the <a class="link" href="#fdl-title-page">Title
3115             Page</a> (and on the covers, if any) a title distinct
3116             from that of the <a class="link" href="#fdl-document">Document</a>, and from those of
3117             previous versions (which should, if there were any, be
3118             listed in the History section of the Document). You may
3119             use the same title as a previous version if the original
3120             publisher of that version gives permission.
3121           </p></li><li class="listitem" style="list-style-type: circle"><p title="B"><b>B. </b>
3122             List on the <a class="link" href="#fdl-title-page">Title
3123             Page</a>, as authors, one or more persons or entities
3124             responsible for authorship of the modifications in the
3125             <a class="link" href="#fdl-modified">Modified Version</a>,
3126             together with at least five of the principal authors of
3127             the <a class="link" href="#fdl-document">Document</a> (all of
3128             its principal authors, if it has less than five).
3129           </p></li><li class="listitem" style="list-style-type: circle"><p title="C"><b>C. </b>
3130             State on the <a class="link" href="#fdl-title-page">Title
3131             Page</a> the name of the publisher of the <a class="link" href="#fdl-modified">Modified Version</a>, as the
3132             publisher.
3133           </p></li><li class="listitem" style="list-style-type: circle"><p title="D"><b>D. </b>
3134             Preserve all the copyright notices of the <a class="link" href="#fdl-document">Document</a>.
3135           </p></li><li class="listitem" style="list-style-type: circle"><p title="E"><b>E. </b>
3136             Add an appropriate copyright notice for your modifications
3137             adjacent to the other copyright notices.
3138           </p></li><li class="listitem" style="list-style-type: circle"><p title="F"><b>F. </b>
3139             Include, immediately after the copyright notices, a
3140             license notice giving the public permission to use the
3141             <a class="link" href="#fdl-modified">Modified Version</a> under
3142             the terms of this License, in the form shown in the
3143             Addendum below.
3144           </p></li><li class="listitem" style="list-style-type: circle"><p title="G"><b>G. </b>
3145             Preserve in that license notice the full lists of <a class="link" href="#fdl-invariant"> Invariant Sections</a> and
3146             required <a class="link" href="#fdl-cover-texts">Cover
3147             Texts</a> given in the <a class="link" href="#fdl-document">Document's</a> license notice.
3148           </p></li><li class="listitem" style="list-style-type: circle"><p title="H"><b>H. </b>
3149             Include an unaltered copy of this License.
3150           </p></li><li class="listitem" style="list-style-type: circle"><p title="I"><b>I. </b>
3151             Preserve the section entitled "History", and
3152             its title, and add to it an item stating at least the
3153             title, year, new authors, and publisher of the <a class="link" href="#fdl-modified">Modified Version </a>as given on
3154             the <a class="link" href="#fdl-title-page">Title Page</a>.  If
3155             there is no section entitled "History" in the
3156             <a class="link" href="#fdl-document">Document</a>, create one
3157             stating the title, year, authors, and publisher of the
3158             Document as given on its Title Page, then add an item
3159             describing the Modified Version as stated in the previous
3160             sentence.
3161           </p></li><li class="listitem" style="list-style-type: circle"><p title="J"><b>J. </b>
3162             Preserve the network location, if any, given in the <a class="link" href="#fdl-document">Document</a> for public access
3163             to a <a class="link" href="#fdl-transparent">Transparent</a>
3164             copy of the Document, and likewise the network locations
3165             given in the Document for previous versions it was based
3166             on. These may be placed in the "History"
3167             section.  You may omit a network location for a work that
3168             was published at least four years before the Document
3169             itself, or if the original publisher of the version it
3170             refers to gives permission.
3171           </p></li><li class="listitem" style="list-style-type: circle"><p title="K"><b>K. </b>
3172             In any section entitled "Acknowledgements" or
3173             "Dedications", preserve the section's title,
3174             and preserve in the section all the substance and tone of
3175             each of the contributor acknowledgements and/or
3176             dedications given therein.
3177           </p></li><li class="listitem" style="list-style-type: circle"><p title="L"><b>L. </b>
3178             Preserve all the <a class="link" href="#fdl-invariant">Invariant
3179             Sections</a> of the <a class="link" href="#fdl-document">Document</a>, unaltered in their
3180             text and in their titles.  Section numbers or the
3181             equivalent are not considered part of the section titles.
3182           </p></li><li class="listitem" style="list-style-type: circle"><p title="M"><b>M. </b>
3183             Delete any section entitled
3184             "Endorsements". Such a section may not be
3185             included in the <a class="link" href="#fdl-modified">Modified
3186             Version</a>.
3187           </p></li><li class="listitem" style="list-style-type: circle"><p title="N"><b>N. </b>
3188             Do not retitle any existing section as
3189             "Endorsements" or to conflict in title with
3190             any <a class="link" href="#fdl-invariant">Invariant
3191             Section</a>.
3192           </p></li></ul></div><p>
3193       If the <a class="link" href="#fdl-modified">Modified Version</a>
3194       includes new front-matter sections or appendices that qualify as
3195       <a class="link" href="#fdl-secondary">Secondary Sections</a> and
3196       contain no material copied from the Document, you may at your
3197       option designate some or all of these sections as invariant. To
3198       do this, add their titles to the list of <a class="link" href="#fdl-invariant">Invariant Sections</a> in the
3199       Modified Version's license notice.  These titles must be
3200       distinct from any other section titles.
3201     </p><p>
3202       You may add a section entitled "Endorsements",
3203       provided it contains nothing but endorsements of your <a class="link" href="#fdl-modified">Modified Version</a> by various
3204       parties--for example, statements of peer review or that the text
3205       has been approved by an organization as the authoritative
3206       definition of a standard.
3207     </p><p>
3208       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
3209       of up to 25 words as a <a class="link" href="#fdl-cover-texts">Back-Cover Text</a>, to the end of
3210       the list of <a class="link" href="#fdl-cover-texts">Cover Texts</a>
3211       in the <a class="link" href="#fdl-modified">Modified Version</a>.
3212       Only one passage of Front-Cover Text and one of Back-Cover Text
3213       may be added by (or through arrangements made by) any one
3214       entity. If the <a class="link" href="#fdl-document">Document</a>
3215       already includes a cover text for the same cover, previously
3216       added by you or by arrangement made by the same entity you are
3217       acting on behalf of, you may not add another; but you may
3218       replace the old one, on explicit permission from the previous
3219       publisher that added the old one.
3220     </p><p>
3221       The author(s) and publisher(s) of the <a class="link" href="#fdl-document">Document</a> do not by this License
3222       give permission to use their names for publicity for or to
3223       assert or imply endorsement of any <a class="link" href="#fdl-modified">Modified Version </a>.
3224     </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>
3225       You may combine the <a class="link" href="#fdl-document">Document</a>
3226       with other documents released under this License, under the
3227       terms defined in <a class="link" href="#fdl-section4" title="4. MODIFICATIONS">section 4</a>
3228       above for modified versions, provided that you include in the
3229       combination all of the <a class="link" href="#fdl-invariant">Invariant
3230       Sections</a> of all of the original documents, unmodified,
3231       and list them all as Invariant Sections of your combined work in
3232       its license notice.
3233     </p><p>
3234       The combined work need only contain one copy of this License,
3235       and multiple identical <a class="link" href="#fdl-invariant">Invariant
3236       Sections</a> may be replaced with a single copy. If there are
3237       multiple Invariant Sections with the same name but different
3238       contents, make the title of each such section unique by adding
3239       at the end of it, in parentheses, the name of the original
3240       author or publisher of that section if known, or else a unique
3241       number. Make the same adjustment to the section titles in the
3242       list of Invariant Sections in the license notice of the combined
3243       work.
3244     </p><p>
3245       In the combination, you must combine any sections entitled
3246       "History" in the various original documents,
3247       forming one section entitled "History"; likewise
3248       combine any sections entitled "Acknowledgements",
3249       and any sections entitled "Dedications".  You must
3250       delete all sections entitled "Endorsements."
3251     </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>
3252       You may make a collection consisting of the <a class="link" href="#fdl-document">Document</a> and other documents
3253       released under this License, and replace the individual copies
3254       of this License in the various documents with a single copy that
3255       is included in the collection, provided that you follow the
3256       rules of this License for verbatim copying of each of the
3257       documents in all other respects.
3258     </p><p>
3259       You may extract a single document from such a collection, and
3260       distribute it individually under this License, provided you
3261       insert a copy of this License into the extracted document, and
3262       follow this License in all other respects regarding verbatim
3263       copying of that document.
3264     </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>
3265       A compilation of the <a class="link" href="#fdl-document">Document</a> or its derivatives with
3266       other separate and independent documents or works, in or on a
3267       volume of a storage or distribution medium, does not as a whole
3268       count as a <a class="link" href="#fdl-modified">Modified Version</a>
3269       of the Document, provided no compilation copyright is claimed
3270       for the compilation.  Such a compilation is called an
3271       "aggregate", and this License does not apply to the
3272       other self-contained works thus compiled with the Document , on
3273       account of their being thus compiled, if they are not themselves
3274       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
3275       copies of the Document, then if the Document is less than one
3276       quarter of the entire aggregate, the Document's Cover Texts may
3277       be placed on covers that surround only the Document within the
3278       aggregate. Otherwise they must appear on covers around the whole
3279       aggregate.
3280     </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>
3281       Translation is considered a kind of modification, so you may
3282       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
3283       translations requires special permission from their copyright
3284       holders, but you may include translations of some or all
3285       Invariant Sections in addition to the original versions of these
3286       Invariant Sections. You may include a translation of this
3287       License provided that you also include the original English
3288       version of this License. In case of a disagreement between the
3289       translation and the original English version of this License,
3290       the original English version will prevail.
3291     </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>
3292       You may not copy, modify, sublicense, or distribute the <a class="link" href="#fdl-document">Document</a> except as expressly
3293       provided for under this License. Any other attempt to copy,
3294       modify, sublicense or distribute the Document is void, and will
3295       automatically terminate your rights under this License. However,
3296       parties who have received copies, or rights, from you under this
3297       License will not have their licenses terminated so long as such
3298       parties remain in full compliance.
3299     </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>
3300       The <a class="ulink" href="http://www.gnu.org/fsf/fsf.html" target="_top">Free Software
3301       Foundation</a> may publish new, revised versions of the GNU
3302       Free Documentation License from time to time. Such new versions
3303       will be similar in spirit to the present version, but may differ
3304       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>.
3305     </p><p>
3306       Each version of the License is given a distinguishing version
3307       number. If the <a class="link" href="#fdl-document">Document</a>
3308       specifies that a particular numbered version of this License
3309       "or any later version" applies to it, you have the
3310       option of following the terms and conditions either of that
3311       specified version or of any later version that has been
3312       published (not as a draft) by the Free Software Foundation. If
3313       the Document does not specify a version number of this License,
3314       you may choose any version ever published (not as a draft) by
3315       the Free Software Foundation.
3316     </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>
3317       To use this License in a document you have written, include a copy of
3318       the License in the document and put the following copyright and
3319       license notices just after the title page:
3320     </p><div class="blockquote"><blockquote class="blockquote"><p>
3321         Copyright 2008, Free Software Foundation.
3322       </p><p>
3323         Permission is granted to copy, distribute and/or modify this
3324         document under the terms of the GNU Free Documentation
3325         License, Version 1.1 or any later version published by the
3326         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>,
3327         and with no <a class="link" href="#fdl-cover-texts">Back-Cover
3328         Texts</a>. A copy of the license is included in
3329         the section entitled "GNU Free Documentation License".
3330       </p></blockquote></div><p>
3331       If your document contains nontrivial examples of program code,
3332       we recommend releasing these examples in parallel under your
3333       choice of free software license, such as the <a class="ulink" href="http://www.gnu.org/copyleft/gpl.html" target="_top"> GNU General Public
3334       License</a>, to permit their use in free software.
3335     </p></div></div></div></body></html>