[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnash-commit] gnash ChangeLog doc/C/Makefile.am doc/C/preform... [relea
|
From: |
Sandro Santilli |
|
Subject: |
[Gnash-commit] gnash ChangeLog doc/C/Makefile.am doc/C/preform... [release_0_8_2_rc1] |
|
Date: |
Tue, 04 Mar 2008 16:37:14 +0000 |
CVSROOT: /sources/gnash
Module name: gnash
Branch: release_0_8_2_rc1
Changes by: Sandro Santilli <strk> 08/03/04 16:37:13
Modified files:
. : ChangeLog
doc/C : Makefile.am
Removed files:
doc/C/preformatted: gnash_ref.html.in gnash_user.html.in
Log message:
Preformatted html files don't have the embedded underscore..
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&only_with_tag=release_0_8_2_rc1&r1=1.5711.2.51&r2=1.5711.2.52
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/Makefile.am?cvsroot=gnash&only_with_tag=release_0_8_2_rc1&r1=1.48.2.3&r2=1.48.2.4
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/preformatted/gnash_ref.html.in?cvsroot=gnash&only_with_tag=release_0_8_2_rc1&r1=1.1.2.1&r2=0
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/preformatted/gnash_user.html.in?cvsroot=gnash&only_with_tag=release_0_8_2_rc1&r1=1.1.2.1&r2=0
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnash/gnash/ChangeLog,v
retrieving revision 1.5711.2.51
retrieving revision 1.5711.2.52
diff -u -b -r1.5711.2.51 -r1.5711.2.52
--- ChangeLog 4 Mar 2008 16:00:26 -0000 1.5711.2.51
+++ ChangeLog 4 Mar 2008 16:37:12 -0000 1.5711.2.52
@@ -1,5 +1,10 @@
2008-03-04 Sandro Santilli <address@hidden>
+ * doc/C/Makefile.am: Preformatted html files don't have
+ the embedded underscore..
+
+2008-03-04 Sandro Santilli <address@hidden>
+
* Makefile.am: --with-plugindir was deprecated in favor
of --with-npapi-plugindir. Update distcheck flags.
* doc/C/Makefile.am: explicitly list file to distribute.
Index: doc/C/Makefile.am
===================================================================
RCS file: /sources/gnash/gnash/doc/C/Makefile.am,v
retrieving revision 1.48.2.3
retrieving revision 1.48.2.4
diff -u -b -r1.48.2.3 -r1.48.2.4
--- doc/C/Makefile.am 4 Mar 2008 15:50:49 -0000 1.48.2.3
+++ doc/C/Makefile.am 4 Mar 2008 16:37:13 -0000 1.48.2.4
@@ -225,12 +225,12 @@
gnashref.html: gnashref.xml
@if test -d $(srcdir)/preformatted; then \
echo "WARNING: Linking to preformatted version of $@, it could be out
of date."; \
- $(LN_S) -f $(srcdir)/preformatted/gnash_ref.html.in ./gnashref.html; \
+ $(LN_S) -f $(srcdir)/preformatted/gnashref.html.in ./gnashref.html; \
fi
gnashuser.html: gnashref.xml
@if test -d $(srcdir)/preformatted; then \
echo "WARNING: Linking to preformatted version of $@, it could be out
of date."; \
- $(LN_S) -f $(srcdir)/preformatted/gnash_user.html.in
./gnashuser.html; \
+ $(LN_S) -f $(srcdir)/preformatted/gnashuser.html.in ./gnashuser.html;
\
fi
endif
Index: doc/C/preformatted/gnash_ref.html.in
===================================================================
RCS file: doc/C/preformatted/gnash_ref.html.in
diff -N doc/C/preformatted/gnash_ref.html.in
--- doc/C/preformatted/gnash_ref.html.in 3 Mar 2008 23:46:42 -0000
1.1.2.1
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,3506 +0,0 @@
-<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.73.2"></head><body bgcolor="white"
text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"
lang="en"><div class="titlepage"><div><div><h1 class="title"><a
name="index"></a>Gnash Reference Manual</h1></div><div><p class="releaseinfo">
- This manual describes version 0.8.2 of Gnash.
- </p></div><div><p class="copyright">Copyright © 2005, 2006, 2007, 2008
Free Software Foundation</p></div><div><div class="legalnotice"><a
name="legalnotice"></a><p>
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the <a class="link" href="#fdl" title="Appendix A. GNU
Free Documentation License"><em class="citetitle">GNU
- Free Documentation License</em></a>, Version 1.1 or any later
- version published by the Free Software Foundation with no Invariant
- Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find
- a copy of the GFDL at this
- <a class="link" href="#fdl" title="Appendix A. GNU Free Documentation
License">link</a> or in the file COPYING-DOCS
- distributed with this manual.
- </p></div></div><div><div class="revhistory"><table border="1" width="100%"
summary="Revision history"><tr><th align="left" valign="top"
colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision
Gnash User Manual version 0.4</td><td align="left">Feb 2008</td></tr><tr><td
align="left" colspan="2">
- <p class="author">Rob Savoye
- <code class="email"><<a class="email"
href="mailto:address@hidden";>address@hidden</a>></code>
- The end user parts of the manual have been pulled out of
- the original version of the manual, and rewritten. This
- is now a reference manual only.
- </p>
-
- <p class="publisher">Open Media Now! Foundation</p>
- </td></tr></table></div></div></div><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">CVS
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 Gnash</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 Debug Logging
System</a></span></dt></dl></dd><dt><span class="sect1"><a
href="#soundhandlers">Sound handling in Gnash</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="#audio-future">Future audio backends</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. Gnash
Extensions</a></span></dt><dd><dl><dt><span class="sect1"><a
href="#newext">Creating A New Extension</a></span></dt><dd><dl><dt><span
class="sect2"><a href="#craftext">Crafting an
Extension</a></span></dt></dl></dd><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" lang="en"><div class="titlepage"><div><div><h2 class="title"><a
name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a
href="#audience">Audience</a></span></dt><dt><span class="sect1"><a
href="#runs-on">What Is Supported?</a></span></dt></dl></div><p>
- <span class="application">Gnash</span> is a free SWF movie player. It is
available as a
- stand-alone application or as a plugin for several popular
- web browsers. It supports playing media from a disk or streaming
- over a network connection. Some popular video sharing sites like
- YouTube are supported on a wide variety of devices from
- embedded ones to modern desktops.
- </p><p>
- <span class="application">Gnash</span> has a better focus on security,
allowing the user tight
- control of all network or disk based I/O. Gnash also supports
- extending ActionScript by creating your own classes. You can write
- wrappers for any development library, and import them into the
- player much like Perl or Python does.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a
name="audience"></a>Audience</h2></div></div></div><p>
- This manual is primarily focused on users interested in how to
- get Gnash installed from a package, and basic usage as a web
- browser plugin. For more technical details, please refer to the
- Gnash Reference manual.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="runs-on"></a>What Is Supported?</h2></div></div></div><p>
- Gnash is known to compile for most any POSIX and ANSI C++
- conforming system if you have all the dependent libraries
- installed. Systems we test on, and which Gnash is known to
- run on are Ubuntu, Fedora, Debian, Mandriva, OpenBSD, NetBSD, FreeBSD,
- Win32, and Darwin (OSX) primarily. Occasionally other platforms
- are built, primarily by those distribution maintainers. This
- includes BeOS, Haiku, Syllable, OS/2, Solaris, Slackware, and
- Gentoo.
- </p><p>
- Gnash is capable of reading up to SWF v9 files and opcodes,
- but primarily supports SWF v7, with better SWF v8 and v9
- support under heavy development. With the 0.8.2 release,
- Gnash includes initial parser support for SWF v8 and v9.
- Not all ActionScript 2 classes are implemented yet, but all of the
- most heavily used ones are. Many ActionScript 2 classes are
- partially implemented; there is support for all of the
- commonly used methods of each class.
- </p><p>
- Gnash has implemented about 80% of ActionScript v2.0, and has
- begun implementing ActionScript v3.0. Gnash supports the
- majority of Flash opcodes up to SWF v9, and a wide
- sampling of ActionScript classes for SWF v8.
- </p><p>
- As ActionScript 3 is a more developed version of
- ActionScript 2, many of the same classes work for
- both. Support has been added to Gnash's ActionScript library
- to support the new ActionScript 3 filters, which get applied
- to every class. Implementing ActionScript clases is often the
- easiest way for new Gnash developers to make a contribution
- without a deep internal knpowledge of Gnash.
- </p><p>
- Gnash has included video support since early 2007, but this is
- an ever changing field of reverse engineering. Many of the
- popular video sharing sites use SWF v8 or v9, which Gnash
- still has imperfect support for. This is improving all the
- time, so often builds from a development snapshot will work
- when using the older release packaged in your distribution
- doesn't. You can find daily snapshots of the latest CVS tree
- at: <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/";
target="_top">
- http://www.gnashdev.org/dev_snapshots</a>.
- </p><p>
- Gnash uses ffmpeg for codecs, so any file supported by Mplayer
- should work with Gnash. Gnash supports the loading of patent
- free codecs like Ogg Vorbis or Theora from disk based files,
- while work is being done to support these codecs when embedded
- in a SWF file. Ffmpeg contains the codecs used by the current
- SWF defintion, FLV, VP6 (ON2), H.263, H.264, and MP3.
- </p></div></div><div class="chapter" lang="en"><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">CVS
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"
lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear:
both"><a name="building_overview"></a>Overview</h2></div></div></div><p>
- The typical process of building from source will involve
- <a class="link" href="#gettingsource" title="Getting The Source">getting
the source</a>,
- <a class="link" href="#dependencies" title="Code Dependencies">build
dependencies</a>,
- <a class="link" href="#configure" title="Configuring
Gnash">configuration</a>,
- <a class="link" href="#compile" title="Compiling the
Code">compilation</a>,
- <a class="link" href="#runtests" title="Running the Tests">testing</a>,
and
- <a class="link" href="#install" title="Installation">installation</a>.
- A simplified overview of the process would be:
- </p><pre class="programlisting">
- ./autogen.sh
- ./configure
- make
- make check
- make install
- </pre><p>
- </p><p>
- If you are compiling with GCC you will probably need to use a machine
- with at least 128 megabytes of physical RAM; 64MB is not enough for a
- couple of the files, even with swap enabled and optimisation turned off.
- </p><p>
- At present the Gnash source is about 30 MB extracted and configured
- and requires a total of about 125 megabytes to compile it.
- </p><p>
- Continue reading for detailed step-by-step instructions
- of the entire procedure.
- </p></div><div class="sect1" lang="en"><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" lang="en"><div class="titlepage"><div><div><h3 class="title"><a
name="sourcereleases"></a>Releases</h3></div></div></div><p>
- Tarballs of official releases can be found in the download area
- of the project's GNU Savannah page at
- <a class="ulink" href="http://savannah.gnu.org/projects/gnash";
target="_top">
- http://savannah.gnu.org/projects/gnash
- </a>
- or under
- <a class="ulink" href="http://ftp.gnu.org/gnu/gnash"; target="_top">
- http://ftp.gnu.org/gnu/gnash
- </a>
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="sourcecvs"></a>CVS
Access</h3></div></div></div><p>
- The latest Gnash development sources are available via anonymous CVS.
- Use the following commands to check them out
- (just hit return when you are prompted for the password):
- </p><pre class="programlisting">
- export CVS_RSH=ssh
- cvs -z3 -d:pserver:address@hidden:/sources/gnash co gnash
- </pre><p>
- You will then be able to update your copy from the repository using
- </p><pre class="programlisting">
- cd gnash
- cvs update -d
- </pre><p>
- </p><p>
- If you only have access to the internet via a web proxy,
- you will find daily source snapshots of the latest CVS tree in
- <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/";
target="_top">
- http://www.gnashdev.org/dev_snapshots
- </a>
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="dependencies"></a>Code Dependencies</h2></div></div></div><p>
- <span class="application">Gnash</span> has a number of dependencies on
other packages.
- If you install the dependencies using a package
- manager, be certain to install the development versions
- of the packages. The normal versions are often missing
- the headers <span class="application">Gnash</span> needs to compile.
- </p><p>
- Some dependencies have other dependencies, like GTk also needs
- glib2, atk, and pango to produce a fully linked
- executable. Different distributions also use differing
- dependencies, sometimes a package will depend on libxml2 on one
- system, but libexpat on another.
- </p><div class="table"><a name="codedeps"></a><p class="title"><b>Table 2.1.
Code Dependency Table</b></p><div class="table-contents"><table summary="Code
Dependency Table"
border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th
align="left">Name</th><th align="left">Level</th><th
align="left">Version</th><th align="left">Description</th><th
align="left">Explanation</th><th align="left">apt-get package</th><th
align="left">RPM/Yum package</th><th align="left">BSD
package</th></tr></thead><tbody><tr><td align="left">Boost</td><td
align="left">Required</td><td align="left">1.32 or higher</td><td align="left">
- Boost is a library of portable C++ classes and
- templates.
- </td><td align="left">
- In <span class="application">Gnash</span>, Boost libraries are used
extensively, primarily
- boost-gthread and boost-date-time. Boost is used for thread and
mutext
- handling.
- </td><td align="left">
- <code class="filename">libboost-thread-dev, libboost-date-time-dev
libboost-dev
- </code>
- </td><td align="left">
- <code class="filename">
- libboost-thread-devel, libboost-date-time-devel
- </code>
- </td><td align="left">
- <code class="filename">
- boost-headers, boost-libs, or just boost
- </code></td></tr><tr><td align="left">libxml2</td><td
align="left">Required</td><td align="left"> </td><td align="left">
- Libxml2 is the GNOME XML parser library and
- is available at <a class="ulink" href="http://xmlsoft.org";
target="_top">http://xmlsoft.org</a>.
- </td><td align="left">
- This library is used to parse messages for the
- XML XMLNode, or XMLSocket ActionScript classes.
- </td><td align="left"><code
class="filename">libxml2-dev</code></td><td align="left"><code
class="filename">libxml2-devel</code></td><td align="left"><code
class="filename">libxml2</code></td></tr><tr><td align="left">AGG</td><td
align="left">Possibly Required</td><td align="left">2.4 or higher</td><td
align="left">
- AGG is the AntiGrain low-level 2D graphics
- library.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- renderer. AGG is considered the <span class="emphasis"><em>best
- supported</em></span> renderer for <span
class="application">Gnash</span>.
- </td><td align="left"><code
class="filename">libagg-dev</code></td><td align="left"><code
class="filename">agg-devel</code></td><td align="left"><code
class="filename">agg</code></td></tr><tr><td align="left">OpenGL</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- OpenGL is a standard specification defining a
- cross-language cross-platform API for writing
- applications which produce 3D and 2D graphics.
- It supports hardware acceleration.
- You can download a free implementation from
- <a class="ulink" href="http://www.mesa3d.org";
target="_top">http://www.mesa3d.org</a>,
- although it doesn't support hardware acceleration.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- renderer. If you don't have a hardware accelerated driver,
- you're better off using AGG for the renderer.
- </td><td align="left"><code
class="filename">libgl1-mesa-dev</code></td><td align="left"><code
class="filename">libmesa-devel</code></td><td align="left"><code
class="filename">mesa</code></td></tr><tr><td align="left">Cairo</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- Cairo is a 2D graphics library with support for
- multiple output devices. It will automatically use
- graphic card acceleration when available, and has
- an experimental OpenGL backend.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- renderer. Cairo is considered
- the <span class="emphasis"><em>least supported</em></span> renderer
- for <span class="application">Gnash</span>.
- </td><td align="left"><code
class="filename">libcairo2-dev</code></td><td align="left"><code
class="filename">cairo-devel</code></td><td align="left"><code
class="filename">cairo</code></td></tr><tr><td align="left">GTK</td><td
align="left">Possibly Required</td><td align="left">2.2 or higher</td><td
align="left">
- GTK is the GIMP Toolkit GUI library used by the GNOME
- desktop. It uses Cairo internally. Gtk enables better
- integration with Firefox, as well as better event handling
- and higher level GUI constructs like menus and dialog
- boxes.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- GUI library. GTK is considered to be the
- <span class="emphasis"><em>best supported</em></span> GUI library
- option for <span class="application">Gnash</span>.
- </td><td align="left"><code
class="filename">libgtk2.0-dev</code></td><td align="left"><code
class="filename">gtk-devel</code></td><td align="left"><code
class="filename">gtk+2</code></td></tr><tr><td align="left">GtkGlExt</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- GtkGlExt integrates OpenGL into GTK.
- </td><td align="left">
- This library is required in order to use
- the GTK GUI library in conjunction with the
- OpenGL renderer.
- </td><td align="left"><code
class="filename">libgtkglext1-dev</code></td><td align="left"><code
class="filename">gtkglext-devel</code></td><td align="left"><code
class="filename">gtkglext</code></td></tr><tr><td align="left">SDL</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- The Simple DirectMedia Layer is a cross-platform
- multimedia library which provides abstraction for
- audio, graphics, sound and input APIs.
- SDL is available from
- <a class="ulink" href="http://www.libsdl.org"; target="_top">
- http://www.libsdl.org</a>.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- GUI library. SDL may also be used as a sound
- handler regardless of whether it is employed as
- a GUI library. The GUI
- library is <span class="emphasis"><em>poorly supported</em></span>
- in <span class="application">Gnash</span>, but the sound handler is
the
- <span class="emphasis"><em>best supported</em></span> in <span
class="application">Gnash</span>.
- </td><td align="left"><code
class="filename">libsdl1.2-dev</code></td><td align="left"><code
class="filename">SDL-devel</code></td><td align="left"><code
class="filename">SDL-1.2</code></td></tr><tr><td align="left">FLTK</td><td
align="left">Possibly Required</td><td align="left">2.0 or higher</td><td
align="left">
- The Fast Light ToolKit is a portable GUI library
- which is intended as a replacement for the SDL GUI.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- GUI library. FLTK may be used in conjunction with
- the Cairo and AGG renderers.
- </td><td align="left">No distribution packages are available.</td><td
align="left">No distribution packages are available.</td><td align="left">No
distribution packages are available.</td></tr><tr><td align="left">KDE</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- Kdelibs is a collection of libraries needed to
- compile KDE applications.
- </td><td align="left">
- <span class="application">Gnash</span> requires the installation of
at least one
- GUI library. Kdelibs is also required for the
- Kpart plugin for Konqueror.
- </td><td align="left"><code class="filename">kdelibs3-dev,
kdebase-dev</code></td><td align="left"><code class="filename">kdelibs-devel,
kdebase-devel</code></td><td align="left"><code class="filename">kdelibs,
kdebase</code></td></tr><tr><td align="left">Gstreamer</td><td
align="left">Optional</td><td align="left"> </td><td align="left">
- Gstreamer is a video handler.
- </td><td align="left">
- If you would like video playback, you must
- install one of the video handlers.
- </td><td align="left"><code
class="filename">libgstreamer0.8-dev</code></td><td align="left"><code
class="filename">gstreamer-devel</code></td><td align="left"><code
class="filename">gstreamer-0.10</code></td></tr><tr><td
align="left">gst-ffmpeg</td><td align="left">Possibly Required</td><td
align="left"> </td><td align="left">
- gst-ffmpeg allows you to use the FFMPEG decoder
- with Gstreamer.
- </td><td align="left">
- This package is required if you would like to
- use Gstreamer as a video handler.
- </td><td align="left"><code
class="filename">gstreamer0.8-ffmpeg-dev</code></td><td align="left"><code
class="filename">gstreamer-ffmpeg-devel</code></td><td align="left"><code
class="filename">gstreamer-ffmpeg</code></td></tr><tr><td
align="left">FFMPEG</td><td align="left">Possibly Required</td><td
align="left"> </td><td align="left">
- FFMPEG is a video handler.
- </td><td align="left">
- If you would like video playback, you must
- install one of the video handlers. When using the
- gstreamer-ffmpeg plugin, ffmpeg doesn't need to be
- installed, as it's part of the plugin. For systems
- without Gstreamer support, ffmpeg can be used directly.
- </td><td align="left"><code
class="filename">ffmpeg-dev</code></td><td align="left"><code
class="filename">ffmpeg-devel</code></td><td align="left"><code
class="filename">ffmpeg</code></td></tr><tr><td align="left">JPEG</td><td
align="left">Optional</td><td align="left"> </td><td align="left">
- <a class="ulink" href="http://www.ijg.org/"; target="_top">JPEG</a>
- is a lossy image format which is heavily used for images.
- </td><td align="left">
- This library is used for rendering JPEGs.
- </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">Optional</td><td align="left"> </td><td align="left">
- <a class="ulink" href="http://www.libpng.org/pub/png/";
target="_top">PNG</a> is
- a patent-free image format which is comparable to
- <span class="emphasis"><em>GIF</em></span>.
- </td><td align="left">
- This library is used for rendering PNGs.
- </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">libcurl</td><td
align="left">Optional</td><td align="left"> </td><td align="left">
- libcurl is the multiprotocal file transfer library.
- </td><td align="left">
- This library is used for URL downloading.
- </td><td align="left"><code
class="filename">libcurl4-gnutls</code></td><td align="left"><code
class="filename">libcurl</code></td><td align="left"><code
class="filename">curl</code></td></tr><tr><td align="left">Glib2</td><td
align="left">Optional</td><td align="left"> </td><td align="left">
- Glib2 is a dependency of Gtk, and is a collection of
- commonly used functions.
- </td><td align="left">
- This library is used for convenience.
- </td><td align="left"><code class="filename">glib2-dev</code></td><td
align="left"><code class="filename">glib2-devel</code></td><td
align="left"><code class="filename">glib2</code></td></tr><tr><td
align="left">Atk</td><td align="left">Optional</td><td align="left"> </td><td
align="left">
- Atk is a dependency of Gtk, and is used for accessibility
- support.
- </td><td align="left">
- This library is used for accessiblity..
- </td><td align="left"><code class="filename">atk-dev</code></td><td
align="left"><code class="filename">atk-devel</code></td><td align="left"><code
class="filename">atk</code></td></tr><tr><td align="left">Pango</td><td
align="left">Optional</td><td align="left"> </td><td align="left">
- Pango is a dependency of Gtk, and is used for font handling.
- </td><td align="left">
- This library is used for font handling.
- </td><td align="left"><code class="filename">pango-dev</code></td><td
align="left"><code class="filename">pango-devel</code></td><td
align="left"><code class="filename">pango</code></td></tr><tr><td
align="left">automake</td><td align="left">Possibly Required</td><td
align="left">1.6.0</td><td align="left">
- Automake is a tool for generating
- <span class="emphasis"><em>Makefile.in</em></span> files.
- </td><td align="left">
- This package is required to run
- <span class="emphasis"><em>autogen.sh</em></span>, which is a
requirement
- if you are using the development source from CVS.
- </td><td align="left"><code class="filename">automake</code></td><td
align="left"><code class="filename">automake</code></td><td align="left"><code
class="filename">automake</code></td></tr><tr><td align="left">autoconf</td><td
align="left">Possibly Required</td><td align="left">2.59</td><td align="left">
- Autoconf is a package for generating configure
- scripts.
- </td><td align="left">
- This package is required to run
- <span class="emphasis"><em>autogen.sh</em></span>, which is a
requirement
- if you are using the development source from CVS.
- </td><td align="left"><code class="filename">autoconf</code></td><td
align="left"><code class="filename">autoconf</code></td><td align="left"><code
class="filename">autoconf</code></td></tr><tr><td align="left">gettext</td><td
align="left">Possibly Required</td><td align="left">0.14.6</td><td align="left">
- Gettext is part of the GNU Translation Project.
- </td><td align="left">
- This package is required to run
- <span class="emphasis"><em>autogen.sh</em></span>, which is a
requirement
- if you are using the development source from CVS.
- </td><td align="left"><code class="filename">gettext</code></td><td
align="left"><code class="filename">gettext</code></td><td align="left"><code
class="filename">gettext</code></td></tr><tr><td align="left">libtool</td><td
align="left">Possibly Required</td><td align="left">1.5.22</td><td align="left">
- This is a generic library support script.
- </td><td align="left">
- This package is required to run
- <span class="emphasis"><em>autogen.sh</em></span>, which is a
requirement
- if you are using the development source from CVS.
- </td><td align="left"><code
class="filename">libltdl3-dev</code></td><td align="left"><code
class="filename">libtool</code></td><td align="left"><code
class="filename">libtool</code></td></tr></tbody></table></div></div><br
class="table-break"></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="testdep"></a>Testing Dependencies</h2></div></div></div><p>
- <span class="application">Gnash</span> tries to run as many tests as
possible, but will
- simply skip tests if the tools to run them are unavailable.
- </p><div class="table"><a name="testdeps"></a><p class="title"><b>Table 2.2.
Testing Dependency Table</b></p><div class="table-contents"><table
summary="Testing Dependency Table"
border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th
align="left">Name</th><th align="left">Level</th><th
align="left">Version</th><th align="left">Description</th><th
align="left">Explanation</th><th align="left">apt-get package</th><th
align="left">RPM/Yum package</th><th align="left">BSD
package</th></tr></thead><tbody><tr><td align="left">Ming</td><td
align="left">Optional</td><td align="left">0.4.0_beta4 or higher</td><td
align="left">
- Ming is an ActionScript compiler.
- </td><td align="left">
- Ming is the primary compiler for ActionScript testcases.
- </td><td align="left">No distribution packages are available.</td><td
align="left">No distribution packages are available.</td><td align="left">No
distribution packages are available.</td></tr><tr><td
align="left">Mtasc</td><td align="left">Optional</td><td align="left">1.12 or
higher</td><td align="left">
- Mtasc is an ActionScript compiler.
- </td><td align="left">
- Mtasc is used in some tests.
- </td><td align="left"><code class="filename">mtasc</code></td><td
align="left">No distribution packages are available.</td><td align="left">No
distribution packages are available.</td></tr><tr><td align="left">swfc</td><td
align="left">Optional</td><td align="left">part of swftools 0.8.1</td><td
align="left">
- Swfc a swf decompiler.
- </td><td align="left">
- Swfc is used in some testcases.
- </td><td align="left">No distribution packages are available.</td><td
align="left">No distribution packages are available.</td><td align="left">No
distribution packages are available.</td></tr><tr><td
align="left">swfmill</td><td align="left">Optional</td><td align="left">
0.2.12</td><td align="left">
- Swfmill is an XML-based SWF (Shockwave Flash) processing tool.
- </td><td align="left">
- Swfmill is used in some testcases.
- </td><td align="left">No distribution packages are available.</td><td
align="left">No distribution packages are available.</td><td align="left">No
distribution packages are available.</td></tr><tr><td
align="left">Python</td><td align="left">Optional</td><td align="left">2.4 or
higher</td><td align="left">
- Python is a scripting language.
- </td><td align="left">
- Python is used by part of the testing framework.
- </td><td align="left"><code class="filename">python</code></td><td
align="left"><code class="filename">python</code></td><td align="left"><code
class="filename">python</code></td></tr><tr><td align="left">DejaGnu</td><td
align="left">Optional</td><td align="left">1.4 or higher</td><td align="left">
- DejaGnu is a testing framework.
- </td><td align="left">
- DejaGnu is used to run multiple tests in an
- automated fashion.
- </td><td align="left"><code class="filename">dejagnu</code></td><td
align="left"><code class="filename">dejagnu</code></td><td align="left"><code
class="filename">dejagnu</code></td></tr></tbody></table></div></div><br
class="table-break"></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="docdepend"></a>Documentation Dependencies</h2></div></div></div><p>
- The following packages are used to build <span
class="application">Gnash</span>'s documentation.
- </p><div class="table"><a name="docdeps"></a><p class="title"><b>Table 2.3.
Documentation Dependency Table</b></p><div class="table-contents"><table
summary="Documentation Dependency Table"
border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th
align="left">Name</th><th align="left">Level</th><th
align="left">Version</th><th align="left">Description</th><th
align="left">Explanation</th><th align="left">apt-get package</th><th
align="left">RPM/Yum package</th><th align="left">BSD
package</th></tr></thead><tbody><tr><td align="left">Docbook</td><td
align="left">Required</td><td align="left"> </td><td align="left">
- <a class="ulink" href="http://http://docbook.sourceforge.net/";
target="_top">Docbook</a> is
- is an industry-standard XML format for technical
- documentation. You can download it from
- <a class="ulink"
href="http://sourceforge.net/project/showfiles.php?group_id=21935#files";
target="_top">http://sourceforge.net/project/showfiles.php?group_id=21935#files</a>.
- </td><td align="left">
- <span class="application">Gnash</span> documentation is written in
Docbook.
- </td><td align="left">
- <code class="filename">docbook-utils</code> and <code
class="filename">docbook-dsssl</code>
- </td><td align="left">
- <code class="filename">docbook-dtd41-sgml</code> and <code
class="filename">docbook-style-dsssl</code>
- </td><td align="left">docbook</td></tr><tr><td
align="left">DocBook2X</td><td align="left">Optional</td><td align="left">
</td><td align="left">
- This software package converts Docbook documents to
- the traditional man page format, GNU Texinfo
- format, and HTML (via Texinfo) format.
- It is available at <a class="ulink"
href="http://docbook2x.sourceforge.net/";
target="_top">http://docbook2x.sourceforge.net/</a>.
- </td><td align="left">
- DocBook2X is required to produce HTML and Texinfo
- formats.
- </td><td align="left"><code class="filename">docbook2x</code></td><td
align="left"><code class="filename">docbook2x</code></td><td align="left"><code
class="filename">docbook2x</code></td></tr><tr><td
align="left">DocBook-utils</td><td align="left">Optional</td><td align="left">
</td><td align="left">
- This software package converts Docbook documents to
- the traditional man page format, GNU Texinfo
- format, and HTML (via Texinfo) format.
- </td><td align="left">
- DocBook-utils is required to produce HTML and Texinfo
- formats.
- </td><td align="left"><code
class="filename">docbook-utils</code></td><td align="left"><code
class="filename">docbook-utils</code></td><td align="left"><code
class="filename">docbook-utils</code></td></tr><tr><td
align="left">Texinfo</td><td align="left">Possibly Required</td><td
align="left"> </td><td align="left">
- Texinfo can be used to convert DocBook2X output
- into GNU info pages. You can download it from
- <a class="ulink" href="http://ftp.gnu.org/gnu/texinfo/";
target="_top">http://ftp.gnu.org/gnu/texinfo/</a>.
- </td><td align="left">
- Texinfo is required if you wish to product GNU info
- pages.
- </td><td align="left"><code class="filename">texinfo</code></td><td
align="left"><code class="filename">texinfo</code></td><td align="left"><code
class="filename">texinfo</code></td></tr><tr><td align="left">FOP</td><td
align="left">Optional</td><td align="left">0.20.5</td><td align="left">
- Formatting Objects Processor is a print formatter
- driven by XSL formatting objects. It is a Java
- application which can output PDF, PCL, PS, SVG, XML,
- Print, AWT, MIF, and Text. It is available at
- <a class="ulink" href="http://xmlgraphics.apache.org/fop/";
target="_top">http://xmlgraphics.apache.org/fop/</a>.
- </td><td align="left">
- FOP is required for PDF output.
- </td><td align="left"><code class="filename">fop</code></td><td
align="left"><code class="filename">fop</code></td><td align="left"><code
class="filename">fop</code></td></tr><tr><td align="left">Java (j2re)</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- FOP requires Sun's Java runtime (GCJ does not work with
- FOP). You can download it from
- <a class="ulink" href="http://java.sun.com";
target="_top">http://java.sun.com</a>.
- </td><td align="left">
- Sun's Java runtime (j2re) is required to use FOP.
- </td><td align="left">
- Download the package from <a class="ulink"
href="http://java.sun.com"; target="_top">Sun</a>.
- </td><td align="left">
- Download the package from <a class="ulink"
href="http://java.sun.com"; target="_top">Sun</a>.
- </td><td align="left"> </td></tr><tr><td align="left">JAI</td><td
align="left">Possibly Required</td><td align="left"> </td><td align="left">
- Sun's Java Advanced Imaging API can be downloaded from
- <a class="ulink"
href="http://java.sun.com/products/java-media/jai/iio.html";
target="_top">http://java.sun.com/products/java-media/jai/iio.html</a>.
- </td><td align="left">
- JAI is required
- if you wish to include graphics in a PDF file being
- generated with FOP.
- </td><td align="left">
- Download the package from <a class="ulink"
href="http://java.sun.com/products/java-media/jai/iio.html";
target="_top">Sun</a>.
- </td><td align="left">
- Download the package from <a class="ulink"
href="http://java.sun.com/products/java-media/jai/iio.html";
target="_top">Sun</a>.
- </td><td align="left"> </td></tr></tbody></table></div></div><br
class="table-break"><p>
- If you install j2re, set the <span
class="emphasis"><em>JAVA_HOME</em></span>
- environment variable to the top directory of the j2re
- installation. If you encounter problems with the Java
- installation, you may also need to add this path to the
- <span class="emphasis"><em>CLASSPATH</em></span> environment variable.
- </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="configure"></a>Configuring
Gnash</h2></div></div></div><p>
- <span class="application">Gnash</span>, like most GNU projects, allows a
user to select various
- options before compiling its source code. These options include
- selecting from the available features, specifying custom paths for
- installation, and cross compiling support uses <a class="ulink"
href="http://www.gnu.org/software/autoconf/"; target="_top">GNU Autoconf</a>
- for configuration.
- </p><p>
- If you opted to download the development snapshot
- of <span class="application">Gnash</span>, the <span
class="emphasis"><em>configure</em></span> script will
- not be included. It can be created by running
- <span class="emphasis"><em>autogen.sh</em></span> from the source root
directory:
- </p><pre class="programlisting">
- ./autogen.sh
- </pre><p>
- Note that there are some
- <a class="link" href="#dependencies" title="Code
Dependencies">dependencies</a> for
- autogen.
- </p><p>
- All the standard <span class="command"><strong>configure</strong></span>
options
- are available. In addition, <span class="application">Gnash</span> has
two types of
- options: those that <a class="link" href="#configfeatures"
title="Features">enable or disable
- features</a>, and
- those that <a class="link" href="#custompath" title="Specifying Custom
Paths">specify custom paths for
- development packages</a>
- which are not found during the default search. A complete
- list of <span class="emphasis"><em>all</em></span> configuration options,
including
- standard ones, can be seen by typing:
- </p><pre class="programlisting">
- ./configure --help | less
- </pre><p>
- Read further for a more detailed explanation of <span
class="application">Gnash</span>-specific
- options.
- </p><p>
- The syntax for running <span class="emphasis"><em>configure</em></span> is
as follows:
- </p><pre class="programlisting">
- configure <em class="replaceable"><code><options></code></em>
- </pre><p>
- The example below shows the <span
class="command"><strong>configure</strong></span> options
- which create the smallest working standalone version of <span
class="application">Gnash</span>. In
- this example, <span class="command"><strong>configure</strong></span> is
being run from the
- source root directory:
- </p><pre class="programlisting">
- ./configure --disable-debugger --disable-cygnal \
- --disable-plugin --enable-media=ffmpeg --enable-gui=sdl
- </pre><p>
- By default, you shouldn't need to supply any options to
- configure. The configure script will attempt to determine what to
- build based on the development libraries you have installed. The
- default configuration for Gnash is both GTK and KDE GUIs, the AGG
- renderer, and Gstreamer for multimedia support, with no extensions
- built.
- </p><p>
- Being highly portable, <span class="application">Gnash</span> has many
configuration options
- available, and not all are supposed to work together. A common
- mistake when configuring <span class="application">Gnash</span> is to
supply too many options,
- overdriving <span class="application">Gnash</span>'s ability to do the
right thing.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a
name="configfeatures"></a>Features</h2></div></div></div><p>
- Some switches can be used during configuration to enable or disable
- features of <span class="application">Gnash</span>. Some of the most
important configuration options
- are:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p>
- <code class="option">--enable-gui</code> lets you specify your GUI of
choice.
- The default option is GTK.
- </p></li><li style="list-style-type: circle"><p>
- <code class="option">--enable-renderer</code> allows a renderer to be
- chosen. The default renderer is AGG.
- </p></li><li style="list-style-type: circle"><p>
- <code class="option">--enable-media</code> permits a media handler to be
- selected. The default is Gstreamer.
- </p></li></ul></div><p>
- A complete list of available features follows.
- </p><div class="table"><a name="tb-config-features"></a><p
class="title"><b>Table 2.4. Configuration Options - Features</b></p><div
class="table-contents"><table summary="Configuration Options - Features"
border="1"><colgroup><col><col></colgroup><thead><tr><th
align="left">Option</th><th
align="left">Function</th></tr></thead><tbody><tr><td align="left"><code
class="option">--enable-debugger</code></td><td align="left">Enable support for
the Flash debugger. The debugger is
- mainly of interest to Flash developers, and is still under
development.</td></tr><tr><td align="left"><code
class="option">--enable-lirc</code></td><td align="left">
- Enable support for the LIRC remote control protocol.
- </td></tr><tr><td align="left"><code
class="option">--enable-cygnal</code></td><td align="left">
- Build the Cygnal streaming media server.
- </td></tr><tr><td align="left"><code
class="option">--disable-menus</code></td><td align="left">
- Disable building all the menus for the GUI. THis is used
- by mobile devices without as much screen space.
- </td></tr><tr><td align="left"> <code
class="option">--enable-docbook</code></td><td align="left"> Enable the
generation of HTML, INFO, and MAN
- versions of the documentation from the Docbook XML. You will
- then be able to use <span class="command"><strong>make
html</strong></span>,
- <span class="command"><strong>make info</strong></span>, and <span
class="command"><strong>make
- man</strong></span> commands. By default, man,info and html pages
- are generated.</td></tr><tr><td align="left"><code
class="option">--enable-gui=gtk|sdl|kde|fltk|fb|hildon|alp</code></td><td
align="left"><p>Select the Graphic User Interface to use (choose one).</p>
- <div class="variablelist"><dl><dt><span
class="term">GTK</span></dt><dd><p>
- The GTK+ toolkit, which is the default GUI.
- Said to interwork particularly well with firefox.
- </p></dd><dt><span class="term">Hildon</span></dt><dd><p>
- The Hildon toolkist is based on GTK+, and is use by
- some mobile devices.
- </p></dd><dt><span class="term">ALP</span></dt><dd><p>
- The ALP "Hiker" GUI is used for the Access Linux platform.
- </p></dd><dt><span class="term">SDL</span></dt><dd><p>
- Simple DirectMedia Layer, a simple and portable GUI.
- Its sound facilities are used when --enable-media=ffmpeg
- regardless of whether it is also in charge of the GUI.
- </p></dd><dt><span class="term">KDE</span></dt><dd><p>
- An interface adapted to the KDE Desktop Environment.
- This must be selected when building the Konqueror plugin
- "klash". Furthermore, the only renderer that currently
- works with KDE is opengl.
- </p></dd><dt><span class="term">FLTK</span></dt><dd><p>
- Fast Light ToolKit, low on resource usage.
- Since all build using fltk are now broken, we declare it
- "for developers".
- </p></dd><dt><span class="term">FB</span></dt><dd><p>
- The Linux Frame Buffer, also known as /dev/fb0.
- AGG is the only renderer that can currently be used
- with the framebuffer GUI.
- </p></dd></dl></div>
- </td></tr><tr><td align="left"><code
class="option">--enable-i810-lod-bias</code>
- </td><td align="left">Enable fix for Intel 810 LOD bias problem.
Older versions
- of libMesa on the Intel i810 or i815 graphics processor
- need this flag or Gnash will core dump. This has been
- fixed in newer versions (summer 2005) of libMesa.</td></tr><tr><td
align="left"><code class="option">--enable-media=ffmpeg|gst|none</code>
- </td><td align="left"> <p>
- Select the specified media decoder and sound engine.
- FFMPEG uses the SDL sound engine; GST uses its own.
- <code class="option">GST</code> is the default decoder.
- </p>
- <p>
- You should only select one media decoder.
- </p></td></tr><tr><td align="left">
- <code class="option">--disable-nsapi</code>
- <code class="option">--enable-nsapi</code>
- </td><td align="left">Force disable/enable building the NPAPI plugin.
- By default the Mozilla plugin is built if the GTK gui
- is selected. Specify the
- <code class="option">--with-npapi-plugindir=</code> option to specify
where the
- plugin should be installed.
- </td></tr><tr><td align="left">
- <code class="option">--disable-kparts</code>
- <code class="option">--enable-kparts</code>
- </td><td align="left">Force disable/enable building the KPARTS
plugin. By default the
- KDE plugin is built if the kde gui is selected.
- Specify the <code class="option">--with-kde-plugindir=</code> and
- <code class="option">--with-kde-servicesdir=</code> options (or more
generally
- the <code class="option">--with-kde-pluginprefix=</code> one) to
specify where the
- plugin should be installed. The default installation dir is extracted
- from kde-config.
- </td></tr><tr><td align="left">
- <code class="option">--disable-plugins</code>
- </td><td align="left">Disable build of both kparts and npapi
plugins</td></tr><tr><td align="left"><code
class="option">--enable-renderer=opengl|cairo|agg</code>
- </td><td align="left">Enable support for the a graphics backend.
Currently
- only <code class="option">opengl</code> and
- <code class="option">agg</code> work sufficiently. OpenGL is
- used when you have hardware accelerated graphics. AGG i
- used when you do not have hardware accelerated
- graphics. Typically most desktop machines have OpenGL
- support, and most embedded systems do not. OpenGl is the
- default when building Gnash, although the quality of AGG's
- rendering is currently superior to OpenGL.</td></tr><tr><td
align="left"><code class="option">--enable-sdk-install</code>
- </td><td align="left">Enable installing the libraries and headers as
an SDK.
- </td></tr><tr><td align="left"><code
class="option">--disable-shared</code>
- </td><td align="left">Enable installing the shared libraries and
headers.
- Note that the extensions mechanism may not work if shared
- libraries are disabled.</td></tr><tr><td align="left"><code
class="option">--enable-strict</code>
- </td><td align="left">Turn verbose GCC compiler warnings. By default
only
- <code class="option">-Wall</code> is used with GCC.</td></tr><tr><td
align="left"><code class="option">--enable-fps-debug</code>
- </td><td align="left">Enable FPS debugging code. When this feature is
compiled in you can use the -f switch of <span class="application">Gnash</span>
- to have FPS printed at regular intervals.</td></tr><tr><td
align="left"><code class="option">--enable-write</code></td><td
align="left">Makes the Mozilla plugin write the currently playing SWF movie to
<code class="filename">/tmp</code>.
- </td></tr><tr><td align="left"><code
class="option">--disable-mit-shm</code>
- </td><td align="left">Disable support for the MIT-SHM X extensions.
- Currently support is only available using GTK gui and AGG renderer.
- Keeping it enabled is not a problem as it will not be used if not
- available in the current X session.
- </td></tr></tbody></table></div></div><br
class="table-break"></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="custompath"></a>Specifying Custom Paths</h2></div></div></div><p>
- By default, none of these options should be required
- unless you want <span class="application">Gnash</span> to use a specific
version of a
- development package, or if the configure test fails to
- find a component. Please <a class="link" href="#bugreport" title="Chapter
5. Reporting Bugs">report the problem</a> if a
- configure test fails.
- </p><p>
- The following custom path options are available:
- </p><div class="table"><a name="tb-configure-paths"></a><p
class="title"><b>Table 2.5. Custom Path Options</b></p><div
class="table-contents"><table summary="Custom Path Options"
border="1"><colgroup><col><col></colgroup><thead><tr><th
align="left">Option</th><th
align="left">Function</th></tr></thead><tbody><tr><td align="left">
- <code class="option">--x-includes=DIR</code>
- </td><td align="left">
- X include files are in DIR.
- </td></tr><tr><td align="left">
- <code class="option">--x-libraries=DIR</code>
- </td><td align="left">
- X library files are in DIR.
- </td></tr><tr><td align="left">
- <code class="option">--with-libxml=PFX</code>
- </td><td align="left">
- Prefix to where libxml is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-libxml-libraries=DIR</code>
- </td><td align="left">
- Directory where libxml library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-libxml-includes=DIR</code>
- </td><td align="left">
- Directory where libxml header files are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-docbook=DIR</code>
- </td><td align="left">
- Directory where the DocBook style-sheets are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-sdl-prefix=PFX</code>
- </td><td align="left">
- Prefix where SDL is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-zlib-incl</code>
- </td><td align="left">
- Directory where zlib header is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-zlib-lib</code>
- </td><td align="left">
- Directory where zlib library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-jpeg-incl</code>
- </td><td align="left">
- Directory where jpeg header is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-jpeg-lib</code>
- </td><td align="left">
- Directory where jpeg library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-png-incl</code>
- </td><td align="left">
- Directory where png header is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-png-lib</code>
- </td><td align="left">
- Directory where png library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-qt-dir</code>
- </td><td align="left">
- Directory where QT is installed. This is only used by
- the Klash plugin.
- </td></tr><tr><td align="left">
- <code class="option">--with-qt-includes</code>
- </td><td align="left">
- Directory where the QT header files are installed. This
- is only used by the Klash plugin.
- </td></tr><tr><td align="left">
- <code class="option">--with-qt-libraries</code>
- </td><td align="left">
- Directory where the QT libraries are installed. This is
- only used by the Klash plugin.
- </td></tr><tr><td align="left">
- <code class="option">--with-npapi-plugindir</code>
- </td><td align="left">
- This is the directory to install the NPAPI (Mozilla) plugin in.
- By default it goes to ~/.mozilla/plugins.
- </td></tr><tr><td align="left">
- <code class="option">--with-kde-pluginprefix</code>
- </td><td align="left">
- This option sets the default install dir for all KPARTS (kde) files.
- The plugin will be installed in PREFIX/lib/kde3, use
- <code class="option">-with-kde-plugindir</code> to override. The
service file in
- PREFIX/share/services, use <code
class="option">--with-kde-servicesdir</code> to
- override. The config file in PREFIX/share/config, use
- <code class="option">--with-kde-configdir</code> to override. The
- appdata file in PREFIX/share/apps/klash, use
- <code class="option">--with-kde-appsdatadir</code> to override.
- </td></tr><tr><td align="left">
- <code class="option">--with-kde-plugindir</code>
- </td><td align="left">
- This is the directory to install the KPARTS (kde) plugin in.
- By default it is what's set by --with-kde-pluginprefix or what's
returned by kde-config --install module --expandvars,
- or $(prefix)/share/services if kde-config is not found.
- </td></tr><tr><td align="left">
- <code class="option">--with-kde-servicesdir</code>
- </td><td align="left">
- This is the directory to install the KPARTS (kde) service in.
- By default it is what's set by --with-kde-pluginprefix or what's
returned by kde-config --install services --expandvars,
- or $(libdir)/kde3 if kde-config is not found.
- </td></tr><tr><td align="left">
- <code class="option">--with-kde-configdir</code>
- </td><td align="left">
- This is the directory to install the KPARTS (kde) config files in.
- By default it is what's set by --with-kde-pluginprefix or what's
returned by kde-config --install config --expandvars,
- or $(prefix)/share/config if kde-config is not found.
- </td></tr><tr><td align="left">
- <code class="option">--with-kde-appsdatadir</code>
- </td><td align="left">
- This is the directory to install the KPARTS (kde) application data
files in.
- By default it is what's set by --with-kde-pluginprefix or what's
returned by kde-config --install data --expandvars,
- or $(prefix)/share/apps if kde-config is not found.
- </td></tr><tr><td align="left">
- <code class="option">--with-ming</code>
- </td><td align="left">
- Ming is used to build test cases, but not by the Gnash
- player itself.
- </td></tr><tr><td align="left">
- <code class="option">--with-ogg_incl</code>
- </td><td align="left">
- Directory where the libogg headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-ogg_lib</code>
- </td><td align="left">
- Directory where the libogg library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-gstreamer-incl</code>
- </td><td align="left">
- Directory where the Gstreamer headers are
- installed. Gstreamer version 0.10 or greater must be used.
- </td></tr><tr><td align="left">
- <code class="option">--with-gstreamer-lib</code>
- </td><td align="left">
- Directory where the Gstreamer library is
- installed. Gstreamer version 0.10 or greater must be used.
- </td></tr><tr><td align="left">
- <code class="option">--with-opengl-includes</code>
- </td><td align="left">
- Directory where OpenGL (libMesa) headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-opengl-lib</code>
- </td><td align="left">
- Directory where the OpenGL (libMesa) library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-glext-incl</code>
- </td><td align="left">
- Directory where GtkGlExt headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-glext-lib</code>
- </td><td align="left">
- Directory where the GtkGlExt library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-gtk2-incl</code>
- </td><td align="left">
- Directory where the Gtk2 headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-gtk2-lib</code>
- </td><td align="left">
- Directory where the Gtk2 library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-cairo_incl</code>
- </td><td align="left">
- Directory where the Cairo headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-cairo-lib</code>
- </td><td align="left">
- Directory where the Cairo library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-glib-incl</code>
- </td><td align="left">
- Directory where the Glib headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-glib-lib</code>
- </td><td align="left">
- Directory where the Glib library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-pango-incl</code>
- </td><td align="left">
- Directory where the Pango headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-pango-lib</code>
- </td><td align="left">
- Directory where the Pango library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-atk-incl</code>
- </td><td align="left">
- Directory where the ATK headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-atk-lib</code>
- </td><td align="left">
- Directory where the ATK library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-pthread-incl</code>
- </td><td align="left">
- Directory where the Pthread headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-pthread-lib</code>
- </td><td align="left">
- Directory where the Pthread library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-agg-incl</code>
- </td><td align="left">
- Directory where the AGG (Antigrain) headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-agg-lib</code>
- </td><td align="left">
- Directory where the AGG (Antigrain) library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-ffmpeg-incl</code>
- </td><td align="left">
- Directory where the FFMPEG headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-ffmpeg-lib</code>
- </td><td align="left">
- Directory where the FFMPEG library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-boost-incl</code>
- </td><td align="left">
- Directory where the Boost headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-boost-lib</code>
- </td><td align="left">
- Directory where the Boost library is installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-curl-incl</code>
- </td><td align="left">
- Directory where the libCurl headers are installed.
- </td></tr><tr><td align="left">
- <code class="option">--with-curl-lib</code>
- </td><td align="left">
- Directory where the libCurl library is installed.
- </td></tr></tbody></table></div></div><br
class="table-break"></div></div><p>
- Once you have <span class="application">Gnash</span> configured, you are
ready to build the code. <span class="application">Gnash</span> is built using
- <span class="emphasis"><em>GNU make</em></span>.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="compile"></a>Compiling the
Code</h2></div></div></div><p>
- The most basic way to compile code is simply:
- </p><pre class="programlisting">
- make
- </pre><p>
- If the compilation ends with an error, check the output of
- <span class="emphasis"><em>configure</em></span> and ensure that you are
not missing
- any required prerequisites. The output of <span
class="command"><strong>make</strong></span> can be verbose; you may wish to
pipe the output to a file.
- </p><p>
- The variables used by <span class="command"><strong>make</strong></span>
can be redefined when
- the program is invoked, if you desire it. The most interesting flags
- are <span class="emphasis"><em>CFLAGS</em></span> and <span
class="emphasis"><em>CXXFLAGS</em></span>,
- which are often used to enable debugging or turn of optimization.
- The default value for both of these variables is
- <span class="emphasis"><em>-O2 -g</em></span>. A list of influential
- environment variables can be seen in the configuration help:
- </p><pre class="programlisting">./configure --help</pre><p>
- In the following example, debugging is enabled and optimization is
- disabled:
- </p><pre class="programlisting">make CFLAGS=-g CXXFLAGS=-g</pre></div><div
class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title"
style="clear: both"><a name="processdoc"></a>Creating the
Documentation</h2></div></div></div><p>
- By default, documentation is not built when you
- <a class="link" href="#install" title="Installation">install</a> <span
class="application">Gnash</span>. This is because
- there are a number of <a class="link" href="#docdepend"
title="Documentation Dependencies">dependencies
- for the documentation</a>. Documentation is built when it
- is specified with a specific target in the generated
- <span class="command"><strong>Makefile</strong></span> in the <code
class="filename">doc/C</code>
- sub-directory. If you type <span class="command"><strong>make
install</strong></span> in
- this directory, all documents will be built.
- </p><p>
- You must specify a target output format when you wish to create
- documentation. The available output formats are: <span
class="command"><strong>html</strong></span>,
- <span class="command"><strong>pdf</strong></span>, <span
class="command"><strong>info</strong></span>,
- <span class="command"><strong>man</strong></span>, and <span
class="command"><strong>alldocs</strong></span>.
- It is also possible to output <span class="command"><strong>GNOME
help</strong></span> if
- the <a class="link" href="#configfeatures" title="Features">configure
option</a>
- <code class="option">--enable-ghelp</code> was used.
- The <span class="command"><strong>alldocs</strong></span> target will
build all output formats
- except <span class="emphasis"><em>GNOME help</em></span>.
- For example, to create HTML output, type:
- </p><pre class="programlisting">
- make html
- </pre><p>
- </p><p>
- <span class="application">Gnash</span> also uses <a class="ulink"
href="http://www.stack.nl/~dimitri/doxygen/index.html";
target="_top">Doxygen</a> to produce <span class="emphasis"><em>HTML</em></span>
- documentation of <span class="application">Gnash</span> internals. You
must have Doxygen installed
- to produce this documentation, which is built from the
- <code class="filename">doc</code> directory with the command (documents
- will be placed in the subdirectory <code
class="filename">apidoc/html</code>):
- </p><pre class="programlisting">
- make apidoc
- </pre><p>
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="runtests"></a>Running the Tests</h2></div></div></div><p>
- Before beginning the potentially lengthy install, it is wise to
- test the installation. If a test fails, please report it by
- following the <a class="link" href="#bugreport" title="Chapter 5.
Reporting Bugs">instructions for
- reporting a bug</a>.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="dejagnu"></a>Using DejaGnu</h3></div></div></div><p>
-
- The easiest way to run <span class="application">Gnash</span>'s test
suite is to install
- <span class="emphasis"><em><a class="ulink"
href="http://www.gnu.org/software/dejagnu";
target="_top">DejaGnu</a></em></span>.
- After installing DejaGnu, run:
- </p><pre class="programlisting">
- make check
- </pre><p>
- </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5
class="title"><a name="testing_verbosity"></a>Increasing
Verbosity</h5></div></div></div><p>
- If you encounter a problem with a test, increasing the
- verbosity may make the issue easier to spot.
- Additional details are visible when
- <span class="emphasis"><em>RUNTESTFLAGS</em></span> are used to add
the
- <span class="emphasis"><em>verbose</em></span> and <span
class="emphasis"><em>all</em></span> options.
- The <code class="option">verbose</code> option prints more
information about the testing process, while
- the <code class="option">all</code> option includes details on
passing tests.
- </p><pre class="programlisting">
- make check RUNTESTFLAGS="-v -a"
- </pre><p>
- </p></div><div class="sect4" lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
name="running_some_tests"></a>Running Some Tests</h5></div></div></div><p>
- It is possible to run just a single test, or
- a subdirectory of tests, by specifying the directory or
- compiled test file.
- </p><p>
- Some tests rely on <span
class="emphasis"><em>testsuite/Dejagnu.swf</em></span>,
- which in turn relies on <span class="emphasis"><em>Ming</em></span>.
- This file is created when you run <span class="command"><strong>make
check</strong></span> for the entire
- testsuite, and can also be created on demand:
- </p><pre class="programlisting">
- make -C testsuite Dejagnu.swf
- </pre><p>
- </p><p>
- In this example, the <span
class="command"><strong>clip_as_button2</strong></span> test is compiled and
- run:
- </p><pre class="programlisting">
- make -C testsuite/samples clip_as_button2-TestRunner
- cd testsuite/samples && ./clip_as_button2-TestRunner
- </pre><p>
- This creates and runs all the tests in the directory
- <code class="filename">movies.all</code>:
- </p><pre class="programlisting">
- make -C testsuite/movies.all check
- </pre><p>
- </p></div></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="manually"></a>Running
The Tests Manually</h3></div></div></div><p>
- You may also run test cases by hand, which can be useful if you
- want to see all the debugging output from the test case. Often
- the messages which come from deep within <span
class="application">Gnash</span> are most useful for
- development.
- </p><p>
- The first step is to compile the test case, which can be done
- with <code class="filename">make XML-v#.swf</code> where the '#' is
replaced
- with the <span class="emphasis"><em>target</em></span> SWF version or
versions.
- For example:
- </p><pre class="programlisting">
- make XML-v{5,6,7,8}.swf
- </pre><p>
- </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5
class="title"><a name="manual_compiled_tests"></a>Movie
tests</h5></div></div></div><p>
- This creates a Flash movie version of the test case, which
- can be run with a standalone Flash player. For instance,
- the target for SWF version 6 could be run with <span
class="application">Gnash</span>:
- </p><pre class="programlisting">
- gnash -v XML-v6.swf
- </pre><p>
- </p></div><div class="sect4" lang="en"><div
class="titlepage"><div><div><h5 class="title"><a
name="manual_actionscript_tests"></a>ActionScript Unit
Tests</h5></div></div></div><p>
- Unit tests for ActionScript classes in <span
class="command"><strong>testsuite/actionscript.all</strong></span>
- are run without a graphical display:
- </p><pre class="programlisting">
- gprocessor -v XML-v6.swf
- </pre><p>
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="install"></a>Installation</h2></div></div></div><p>
- Now that <span class="application">Gnash</span> has been compiled and
tested, use the following command to install it:
- </p><pre class="programlisting">
- make install
- </pre><p>
- The above command installs the standalone player. If the correct
- files were found by <span
class="command"><strong>configure</strong></span> and if the
- <code class="option">--disable-plugin</code> option was not specified, the
- <span class="application">Gnash</span> browser plugin is also installed.
- </p><p>
- <span class="application">Gnash</span> installs a number of <a
class="link" href="#libinstall" title="Libraries">libraries</a>,
- namely: <span class="emphasis"><em>libgnashbase</em></span>,
- <span class="emphasis"><em>libgnashamf</em></span>, <span
class="emphasis"><em>libgnashmedia</em></span>,
- <span class="emphasis"><em>libserver</em></span>, and <span
class="emphasis"><em>libgnashplugin</em></span>.
- <a class="link" href="#appinstall" title="Executables">Executables</a>
- consist of the (optional) plugin, <code class="filename">gprocessor</code>,
- <code class="filename">cygnal</code>, <code
class="filename">dumpshm</code>,
- <code class="filename">soldumper</code>, and <code
class="filename">gnash</code>.
- <a class="link" href="#docinstall" title="Documentation">Documentation</a>
may also be installed.
- The installation location is controlled with the
- <span class="emphasis"><em>--prefix</em></span> <a class="link"
href="#custompath" title="Specifying Custom Paths">configure
- option</a>, except for plugins, which are explicitly set with
- <span class="emphasis"><em>--plugin-dir</em></span>.
- </p><p>
- Note that if you are using a single file-system <span
class="emphasis"><em>NFS</em></span>
- mounted to multiple platforms, the
- <a class="link" href="#custompath" title="Specifying Custom
Paths">configuration option</a>
- <span class="emphasis"><em>--exec-prefix</em></span> may be used to
specify where
- platform-dependent executables and libraries are installed.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="libinstall"></a>Libraries</h3></div></div></div><p>
- Installed libraries are located in
- <code class="filename">/usr/local/lib</code> by default.
- If the <span class="emphasis"><em>--prefix</em></span> option was used
during the
- configuration step, the libraries will
- be installed in the directory <code class="filename">lib</code> inside
the
- path you specified. If the libraries are stored in a non-standard
- location, you must identify the path in one of two ways.
- </p><p>
- The traditional way to do this on UNIX
- platforms is to set the <span
class="emphasis"><em>LD_LIBRARY_PATH</em></span> variable
- to the path plus <code class="filename">/lib</code>. For example, if you
- installed in <code class="filename">/home/gnash</code>, the
- <span class="emphasis"><em>LD_LIBRARY_PATH</em></span> path would be
- <code class="filename">/home/gnash/lib</code>. Multiple paths are
delimited
- with a colon (':').
- </p><p>
- GNU/Linux allows the custom path to be added to
- <code class="filename">/etc/ld.so.conf</code>. After adding the path,
- run <span class="emphasis"><em>ldconfig</em></span> as root to update
the runtime
- cache.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="appinstall"></a>Executables</h3></div></div></div><p>
- The Mozilla plugin is built from headers (the Mozilla SDK) provided with
Gnash and
- does not need extra development packages to be installed. By default, the
- plugin is installed to <code
class="filename">~/.mozilla/plugins/</code>. To enable
- the plugin for other users, copy the file <code
class="filename">libgnashplugin.so</code>
- to <code class="filename">.mozilla/plugins/</code> in their home
directory.
- You may also specify the plugin installation directory by using the
- <code class="option">--with-plugindir</code> <a class="link"
href="#custompath" title="Specifying Custom Paths">option
- at configuration time</a>.
- </p><p>
- These defaults are likely to change in future versions of Gnash.
- </p><p>
- The remaining executables are installed in the <code
class="filename">bin</code>
- subdirectory of the directory specified by during configuration.
- If no path was specified, the default is
- <code class="filename">/usr/local/bin</code>.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="docinstall"></a>Documentation</h3></div></div></div><p>
- Documentation is not built by default; please refer to the
- <a class="link" href="#processdoc" title="Creating the
Documentation">section on documentation</a> for
- more information on building documentation.
- </p><p>
- <span class="command"><strong>man</strong></span> and <span
class="command"><strong>info</strong></span>
- are installed in <code class="filename">/usr/local/share/man</code>
- and <code class="filename">/usr/local/share/info</code> respectively,
unless
- the <code class="option">--mandir</code> or <code
class="option">--infodir</code>
- <a class="link" href="#custompath" title="Specifying Custom
Paths">configuration options</a> are used.
- </p><p>
- <span class="emphasis"><em>GNOME help</em></span> documentation uses the
directory
- <code class="filename">/usr/local/share/gnash/doc/gnash/C/</code> by
default.
- A configuration file in the <span class="application">Gnash</span>
source tree,
- <code class="filename">doc/C/gnash.omf</code> is used to specify under
- which menu item <span class="application">Gnash</span> appears in the
<span class="emphasis"><em>GNOME help</em></span>
- system.
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="cross"></a>Cross Configuring</h2></div></div></div><p>
- To cross configure and compile <span class="application">Gnash</span>,
begin by building a target system
- on your workstation. This includes cross compilers for the target
- architecture, and some system headers.
- You will also need to cross compile all the <a class="link"
href="#docdepend" title="Documentation Dependencies">dependencies
- </a> normally needed to build Gnash. This can on occasion be a
- daunting process, as not all libraries will cross configure and cross
- compile. There is more information about cross compiling all the
- dependant packages on the <a class="ulink" href="http://www.gnashdev.org";
target="_top">http://www.gnashdev.org</a> web
- site.
- </p><p>
- If you need to build your own tool chain, that is beyond the scope
- of this manual. There are various resources on the web for howto's
- on building GCC based cross toolchains. Two popular sites are
- <a class="ulink" href="http://frank.harvard.edu/~coldwell/toolchain/";
target="_top">http://frank.harvard.edu/~coldwell/toolchain/</a>
- and <a class="ulink" href="http://www.kegel.com/crosstool/";
target="_top">http://www.kegel.com/crosstool/</a>. This
- can also be a very time consuming and frustrating process, even
- for experienced developers.
- </p><p>
- Because the process of building your own cross tool chain can be
- harder than one may wish, there are several other cross
- development environments that simulate a native environment to
- make it easier to develop. These also let you develop for both
- native and cross builds. Several popular ones are
- <a class="ulink"
href="http://www.access-company.com/products/linux/alp.html"; target="_top">
- Access Linux Platform</a>,
- <a class="ulink" href="http://www.scratchbox.org/"; target="_top">
- Scratchbox</a>,
- <a class="ulink" href="http://www.openembedded.org/"; target="_top">
- Open Embedded</a>,
- <a class="ulink" href="http://maemo.org/"; target="_top">
- Maemo</a>.
- </p><p>
- To build for an ARM based system on an x86 based systems,
- configure like this using the traditional style cross toolchain,
- configure like this:
- </p><pre class="programlisting">
- ../../gnash/configure --build=i686-pc-linux-gnu
- --host=arm-linux --prefix=/usr/local/arm/oe --disable-nsapi
- --disable-kparts --enable-gui=fb --enable-renderer=agg
- --disable-shared --disable-menus
-
- </pre><p>
- The important configuration options are the ones which specify the
- architecture for the build:
- </p><div class="variablelist"><dl><dt><span
class="term">--target</span></dt><dd><p>
- The target architecture, where the final executables are expected
- to run.
- </p></dd><dt><span class="term">--host</span></dt><dd><p>
- The host architecture, where the executables are expected
- to run. Usually this is the same as the <span
class="emphasis"><em>--target</em></span>,
- except when building a compiler as a Canadian Cross. In this
- case, you might build a cross compiler on a UNIX system which
- runs on a win32 machine, producing code for a third architecture,
- such as ARM. In this example, <span
class="emphasis"><em>--target</em></span> would
- be 'arm-unknown-linux-gnu', while <span
class="emphasis"><em>--host</em></span> would
- be 'win32'.
- </p></dd><dt><span class="term">--build</span></dt><dd><p>
- This is the system the build is running on.
- </p></dd></dl></div><p>
- The following example of <span class="emphasis"><em>configure</em></span>
builds for an
- ARM system on an x86 system. It was run after an ARM system was built
- in <code class="filename">/usr/arm</code> and other required libraries
were
- cross compiled.
- </p><pre class="programlisting">
- ./configure -target=arm-unknown-linux-gnu --prefix=/usr/arm \
- --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu --disable-plugin
- </pre><p>
- </p></div></div></div><div class="chapter" lang="en"><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
Gnash</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 Debug Logging System</a></span></dt></dl></dd><dt><span
class="sect1"><a href="#soundhandlers">Sound handling in
Gnash</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="#audio-future">Future
audio backends</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" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="tour"></a>A Tour of Gnash</h2></div></div></div><p>
- The top level of Gnash has several libraries, <span
class="emphasis"><em>libgnashbase</em></span>,
- <span class="emphasis"><em>libgnashserver</em></span>,
- <span class="emphasis"><em>libgnashasobjs</em></span> and
- <span class="emphasis"><em>libgnashbackend</em></span>. There are
several utility programs
- included for debug parsing and processing of Flash movie files,
- and other useful utilities for examining local Shared Objects and
- sniffing LocalConnections.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="The%20Libraries"></a>The
Libraries</h3></div></div></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libbase"></a>libgnashbase</h4></div></div></div><p>
- Libgnashbase contains support classes used by the rest of the
- code.This library has no dependencies on any of the other
- <span class="application">Gnash</span> libraries.
- </p><p>
- <span class="application">Gnash</span> makes heavy use of smart
pointers, so memory allocations
- are freed up automatically by the interpreter. Both STL and
- Boost smart pointers are used.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libgnashgui"></a>libgnashgui</h4></div></div></div><p>
- Libgnashgui contains code for a portable GUI class that
- supports using GTK2, a framebuffer, SDL, or KDE, FLTK, or Aqua.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libgnashserver"></a>libgnashserver</h4></div></div></div><p>
- Libgnashserver is the guts of the interpreter itself. This is where
- the main code for the interpreter lives. Includes in
- libserver are the two support libraries for the parser and
- the core of the virtual machine.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libgnashasobjs"></a>libgnashasobjs</h4></div></div></div><p>
- Libgnashasobjs contains all the ActionScript classes used by
- the interpreter.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libgnashamf"></a>libgnashamf</h4></div></div></div><p>
- AMF is the data format used internally by SWF files. This is
- Gnash's support library to handle AMF data. This is used by
- the ActionScript classes SharedObject and
- LocalConnection. This is also used by the NetStream class
- when using thre RTMP streaming network protocol.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libgnashbackend"></a>libgnashbackend</h4></div></div></div><p>
- Libgnashbackend is a library containing the rendering
- code that glues this display to the Gnash. Supported
- rendering backends are OpenGL, Cairo, and AGG.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libgnashpluin"></a>libgnashplugin</h4></div></div></div><p>
- Libgnashplugin is the Mozilla/Firefox plugin.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="libklashpart"></a>libklashpart</h4></div></div></div><p>
- Libklashpart is the Konqueror plugin.
- </p></div></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="apps"></a>The
Applications</h3></div></div></div><p>
- There are currently a few standalone programs in Gnash,
- which serve either to assist with Gnash development or to play flash
- movies.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="Gnash"></a>The Standalone
Player</h4></div></div></div><p>
- This is the standalone OpenGL backend used to play
- movies. There are several command line options and keyboard
- control keys used by Gnash.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="processor"></a>Gprocessor</h4></div></div></div><p>
- Gprocessor is used to print out the actions (using the -va
- option) or the parsing (using the -vp option) of a flash
- movie. It is also used to produce the <span
class="emphasis"><em>.gsc</em></span>
- files that Gnash uses to cache data, thereby speeding up the
- loading of files.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="soldumper"></a>SOLdumper</h4></div></div></div><p>
- SOLDumper is a utility program used to find and dump the
- content of <span class="emphasis"><em>Local Shared
Objects</em></span>, also
- called "Flash Cookies" by some.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="dumpshm"></a>Dumpshm</h4></div></div></div><p>
- Dumpshm is a program used to find and dump the contents of
- the <span class="emphasis"><em>LocalConnection</em></span> shared
memory segment.
- </p></div></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="plugin"></a>The
Plugin</h3></div></div></div><p>
- The plugin is designed to work within Mozilla or Firefox,
- although there is Konqueror support as well. The plugin uses
- the Mozilla NPAPI plugin API to be cross platform, and is
- portable, as well as being well integrated into Mozilla based
- browsers.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="pluginstatus"></a>Current
Status</h4></div></div></div><p>
- As of March 30, 2006, the plugin works! This works in a
- fashion similar to MozPlugger in that the standalone player
- is used instead of using a thread. This gets around the
- issue of having to maintain a separate player to support the
- plugin. It also gets around the other issues that Gnash
- itself is not thread safe at this time.
- </p><p>
- As of Jan, 2007, streaming video, ala "YouTube"
- works, along with other video sharing sites.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a name="gui"></a>GUI
Support</h4></div></div></div><p>
- Any plugin that wants to display in a browser window needs
- to be tied into the windowing system of the platform being
- used. On GNU/Linux systems, Firefox is a GTK2+ application.
- There is also KDE support through the use of the Klash
- plugin.
- </p><p>
- Gnash can use either several different GUI toolkits to create the
window,
- and to handle events for the standalone player.
- </p><p>
- The SDL version is more limited, but runs on all
- platforms, including win32. It has no support for event
- handling, which means mouse clicks, keyboard presses, and
- window resizing doesn't work. I personally find the default
- event handler slow and unresponsive. Gnash has support to
- use fast events, (currently not enabled) which is an SDL
- hack using a background thread to pump events into the SDL
- event queue at a much higher rate.
- </p><p>
- There are a variety of development libraries that build a GUI
- widget system on top of SDL and OpenGL. The use of these to
- add menus and dialog boxes to the SDL version is being
- considered.
- </p><p>
- The GTK support is currently the most functional, and the
- best integrated into Firefox. The performance of this
- version is better than the SDL version because of the more
- efficient event handling within GTK. For the best end user
- experience, use the GTK enabled version.
- </p><p>
- GTK also allows Gnash to have menus and dialog
- boxes. Currently this is only being utilized in a limited
- fashion for now. There is a right mouse button menu that
- allows the user to control the movie being player the same
- way the existing keyboard commands do.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="mozplugger"></a>Mozplugger</h4></div></div></div><p>
- <a class="ulink" href="http://mozplugger.mozdev.org/";
target="_top">Mozplugger</a> is a
- <span class="emphasis"><em>Mozilla/Firefox</em></span> plugin that
uses external
- programs to play video, audio, and other multimedia content
- in the browser. With some support added to the external
- application, it's possible to force the external program to
- use the internal window in the browser where this plugin is
- supposed to display. This enables one to then run the
- standalone player and display its output in the browser.
- </p><p>
- While this is not an optimal solution, it does enable one to
- use Gnash as the flash player when browsing. The main issue
- appears to be that the Flash movie being played doesn't get
- any mouse or keyboard input. That may be a mozplugger
- configuration issue, however.
- </p><p>
- Use of MozPlugger is obsolete now that the Gnash plugin
- works. Still, this may be useful still on some platforms.
- </p><p>
- Add this to your <span
class="emphasis"><em>$(HOME)/.mozilla/mozpluggerrc</em></span>
- file to enable this:
-
- </p><pre class="programlisting">
- application/x-shockwave-flash:swf:Shockwave Gnash
- nokill embed noisy ignore_errors hidden fill swallow(Gnash) loop:
gnash -v "$file" -x $window
- : gnash -v "$file" -x $window
- </pre><p>
- </p><p>
- Once this is added, you must delete the
- <span
class="emphasis"><em>$(HOME)/.mozilla/firefox/pluginreg.dat</em></span> file to
- force Firefox to register the plugins again. This is an
- ASCII text file, so if the patch has been added correctly,
- you'll see an entry for <span class="emphasis"><em>swf</em></span>
files after it is
- recreated. You will need to restart Firefox to recreate this
- file.
- </p><p>
- This file is not recreated immediately when restarting
- Firefox, but waits till the first time a plugin is used. You
- can force creation of this file by typing
- <span class="emphasis"><em>about:plugins</em></span> into the URL
entry of the browser
- window. The output will also contain information about the
- mozplugger. You should see an entry for Gnash now.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="Klash"></a>Klash</h4></div></div></div><p>
- Klash is MozPlugger type support for KDE's Konqueror web
- browser. Klash makes Gnash a <span
class="emphasis"><em>kpart</em></span>, so it's
- integrated into KDE better than when using MozPlugger. Klash
- uses the standalone player, utilizing Gnash's "-x" window
- plugin command line option.
- </p><p>
- By default, Klash is not built. To enable building Klash,
- use the <span class="emphasis"><em>--enable-klash</em></span> option
when
- configuring. Other than installing, there is nothing else
- that needs to be done to install Klash.
- </p></div></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="logging"></a>The Debug
Logging System</h3></div></div></div><p>
- Gnash supports a debug logging system which supports both C and C++
- natively. This means you can use both <span
class="emphasis"><em>printf()</em></span> style
- debug messages and C++ <span class="emphasis"><em>iostreams</em></span>
style, where you can
- print C++ objects directly as you would when using
- <span class="emphasis"><em>cout</em></span>.
- </p><p>
- In the beginning, Gnash only supported the C API for debug
- logging, so it is the most heavily used in Gnash. This API was used in
- the <span class="emphasis"><em>log_msg()</em></span> and <span
class="emphasis"><em>log_error()</em></span> functions,
- and used a callback to set them up.
- </p><p>
- If a filename is not specified at object construction time, a
- default name of <span class="emphasis"><em>gnash-dbg.log</em></span> is
used. If Gnash is
- started from the command line, the debug log will be created in
- the current directory. When executing Gnash from a launcher under
- <span class="emphasis"><em>GNOME</em></span> or <span
class="emphasis"><em>KDE</em></span> the debug file goes in your
- home directory, since that's considered the current directory.
- </p><p>
- There is common functionality between using the C or C++
- API. Optional output is based on flags that can be set or
- unset. Multiple levels of verbosity are supported, so you can get
- more output by supplying multiple <span
class="emphasis"><em>-v</em></span> options on the
- command line. You can also disable the creation of the debug log.
- </p><p>
- Currently the use of the C++ API for logging is discouraged, do to
- performance issues.and the generic log_msg() has been replaced by
- more spcific function calls to allow more control of what gets
- displayed and logged.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="capi"></a>Logging System C API</h4></div></div></div><p>
- These functions are clones of the originals as they were used
- for Gnash. These function the same as always except output can
- be logged to disk now as well. These currently print no
- timestamp with the output, which is the older functionality. As
- these functions are implemented on top of the C++ API now, they
- can be used without corrupting the output buffers.
- </p><div class="variablelist"><dl><dt><span class="term">log_error(const
char* fmt, ...)</span></dt><dd><p>
- Display an error message if verbose output is enabled. By
- default the error messages are always written to the disk
- file, but optionally displayed in the terminal.
- </p></dd><dt><span class="term">void log_unimpl</span></dt><dd><p>
- Displays a warning to the user about missing Gnash features.
- We expect all calls to this function to disappear over time, as we
- implement those features of Flash.
- </p></dd><dt><span class="term">void log_trace</span></dt><dd><p>
- Used only for explicit user traces
- </p></dd><dt><span class="term">void log_debug</span></dt><dd><p>
- Logs debug information.
- </p></dd><dt><span class="term">void log_action</span></dt><dd><p>
- Log action execution information. Wrap all calls to this
- function (and other related statements) into an
- IF_VERBOSE_ACTION macro, so to allow completely removing
- all the overhead at compile time and reduce it at
- runtime.
- </p></dd><dt><span class="term">void log_parse</span></dt><dd><p>
- Log SWF parsing Wrap all calls to this function (and
- other related statements) into an IF_VERBOSE_PARSE macro,
- so to allow completely removing all the overhead at
- compile time and reduce it at runtime.
- </p></dd><dt><span class="term">void log_security</span></dt><dd><p>
- Display a message with security related information.
- </p></dd><dt><span class="term">void log_swferror</span></dt><dd><p>
- This indicates an error in how the binary SWF file was
- constructed, i.e.probably a bug in the tools used to build
- the SWF file. Wrap all calls to this function (and other
- related statements) into an IF_VERBOSE_MALFORMED_SWF
- macro, so to allow completely removing all the overhead at
- compile time and reduce it at runtime.
- </p></dd><dt><span class="term">log_warning(const char* fmt,
...)</span></dt><dd><p>
- Display a warning message if verbose output is enabled. By
- default the error messages are always written to the disk
- file, but optionally displayed in the terminal.
- </p></dd></dl></div></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a name="cppapi"></a>Logging
System C++ API</h4></div></div></div><p>
- This is the new C++ streams based API that can be used to print
- C++ objects natively. All output lines are timestamped.
- </p><p>
- There are two macros used for program tracing. these can be used
- in both C or C++ code with one little difference. Since C
- doesn't have destructors, you must call
- <span class="emphasis"><em>GNASH_REPORT_RETURN</em></span> at the end of
a function to
- display the function returning message.
- </p><div class="variablelist"><dl><dt><span
class="term">GNASH_REPORT_FUNCTION;</span></dt><dd><p>
- When this is included in a C++ method, a message is
- printed when entering and exiting this method by hooking
- into the constructor and destructor. These are always
- written to the disk file, but optionally written to the
- screen only at the highest levels of verbosity.
- </p></dd><dt><span
class="term">GNASH_REPORT_RETURN;</span></dt><dd><p>
- This is used by C functions to print the returning from
- function debug message. For C++, this macro is executed
- automatically by the destructor.
- </p></dd></dl></div><p>
- This is the main API for the logging system. By default
- everything is setup to write to the default
- <span class="emphasis"><em>gnash-dbg.log</em></span> file whenever a
verbose option is
- supplied. Optionally it is possible to open a log file with a
- specified name, allowing multiple output files.
- </p><div class="variablelist"><dl><dt><span
class="term">closeLog(void)</span></dt><dd><p>
- Close a debug log. The disk file remains.
- </p></dd><dt><span class="term">removeLog(void)</span></dt><dd><p>
- Delete the debug log file from disk.
- </p></dd><dt><span class="term">setVerbosity(void)</span></dt><dd><p>
- Increment the verbosity level.
- </p></dd><dt><span class="term">setVerbosity(int)</span></dt><dd><p>
- Set the verbosity level.
- </p></dd><dt><span class="term">setStamp(bool flag)</span></dt><dd><p>
- If <span class="emphasis"><em>flag</em></span> is <span
class="emphasis"><em>true</em></span>, then print a
- timestamp prefixed to every output line. If
- <span class="emphasis"><em>flag</em></span> is <span
class="emphasis"><em>false</em></span>, then don't print
- a timestamp.
- </p></dd><dt><span class="term">setWriteDisk(bool
flag)</span></dt><dd><p>
- If <span class="emphasis"><em>flag</em></span> is <span
class="emphasis"><em>true</em></span>, then create the
- disk file. If <span class="emphasis"><em>flag</em></span> is <span
class="emphasis"><em>false</em></span>,
- then don't create the disk file.
- </p></dd></dl></div></div></div></div><div class="sect1"
lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear:
both"><a name="soundhandlers"></a>Sound handling in
Gnash</h2></div></div></div><p>
- When a SWF-file contains audio Gnash uses its sound handlers to play it.
- At the moment there are two sound handlers, but it is likely that more
- will be made.
- </p><p>
- There are two different settings related to sound support:
- <span class="emphasis"><em>pluginsound</em></span> and <span
class="emphasis"><em>sound</em></span>.
- This was done in order to allow the plugin to be independently
- configured, for instance to block sound from advertisements.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="soundtypes"></a>Sound types</h3></div></div></div><p>
- Sounds can be divided into two groups: event-sounds and soundstreams.
- Event-sounds are contained in a single SWF frame, but the playtime can
- span multiple frames. Soundstreams can be (and normally are) divided
- between the SWF frames the soundstreams spans. This means that if a
- gotoframe-action jumps to a frame which contains data for a soundstream,
- playback of the stream can be picked up from there.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="soundparsing"></a>Sound
parsing</h3></div></div></div><p>
- When Gnash parses a SWF-file, it creates a sound handler if possible
- and hands over the sounds to it. Since the event-sounds are contained
- in one frame, the entire event-sound is retrieved at once, while a
- soundstream maybe not be completely retrieved before the entire
- SWF-file has been parsed. But since the entire soundstream doesn't need
- to be present when playback starts, it is not necessary to wait.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="soundplayback"></a>Sound
playback</h3></div></div></div><p>
- When a sound is about to be played Gnash calls the sound handler, which
- then starts to play the sound and return. All the playing is done by
- threads (in both SDL and Gstreamer), so once
- started the audio and graphics are not sync'ed with each other, which
- means that we have to trust both the graphic backend and the audio
- backend to play at correct speed.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="sdlsound"></a>The SDL
sound backend</h3></div></div></div><p>
- The current SDL sound backend has replaced the original sound
- handler, based on SDL_mixer, which by design had some limitations,
- making it difficult to implement needed features such as support
- for soundstreams.
- The SDL sound backend supports both event-sounds and soundstreams,
- using Gnash's internal ADPCM, and optionally MP3 support, using
- either FFMPEG or LIBMAD.
- When it receives sound data it is stored without being decoded, unless
- it is ADPCM, which is decoded in the parser. When playing, backend
- relies on a function callback for retrieving output sound, which is
- decoded and re-sampled if needed, and all sound output is mixed
together.
- The current SDL sound backend was made since Gnash needed a working
- sound backend as soon as possible, and since the gstreamer backend at
- the time suffered from bugs and/or lack of features in gstreamer. The
- result was the most complete and best sound handler so far.
- The advantages of the SDL sound handler is speed, and ease of use,
- while its only real disadvantage is that it has to be compiled with
- MP3 support, which some Linux distributions will probably not like...
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="gstreamer"></a>The
Gstreamer backend</h3></div></div></div><p>
- The Gstreamer backend, though not complete, supports both soundstreams
- and event-sounds. When receiving sound data it stores it compressed,
- unless if it's ADPCM event-sounds, which it decodes by the parser.
- When the playback starts, the backend sets up a
- Gstreamer bin containing a decoder (and other things needed) and places
- it in a Gstreamer pipeline, which plays the audio. All the sound data is
- not passed at once, but in small chunks, and via callbacks the
- pipeline gets fed. The advantages of the Gstreamer backend is that it
- supports both kinds of sound, it avoids all the legal MP3-stuff, and it
- should be relatively easy to add VORBIS support. The drawbacks are that
- it has longer "reply delay" when starting the playback of a sound, and
- it suffers under some bugs in Gstreamer that are yet to be fixed.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="audio-future"></a>Future
audio backends</h3></div></div></div><p>
- It would probably be desirable to make more backends in the future,
- either because other and better backend systems are brought to our
- attention, or perhaps because an internal sound handling is better
- suited for embedded platform with limited software installed.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="gstreamer-details"></a>Detailed description of the Gstreamer
backend</h3></div></div></div><p>
- Gstreamer uses pipelines, bins and elements. Pipelines are the
- main bin, where all other bins or elements are places. Visually the
- audio pipeline in Gnash looks like this:
- </p><pre class="programlisting">
- ___
- |Bin|_
- |___| \
- ___ \ _____ ____________
- |Bin|___|Adder|_____|Audio output|
- |___| |_____| |____________|
- ___ /
- |Bin|_/
- |___|
-
- </pre><p>
- There is one bin for each sound which is being played. If a sound is
- played more the once at the same time, multiple bins will be made. The
- bins contains:
- </p><pre class="programlisting">
-
-
|source|---|capsfilter|---|decoder|---|aconverter|---|aresampler|---|volume|
-
- </pre><p>
- In the source element we place parts of the undecoded sound data, and
- when playing the pipeline will pull the data from the element. Via
- callbacks it is refilled if needed. In the capsfilter the data is
- labeled with the format of the data. The decoder (surprise!) decodes
- the data. The audioconverter converts the now raw sound data into a
- format accepted by the adder, all input to the adder must in the same
- format. The audio re-sampler re-samples the raw sound data into a sample
- accepted by the adder, all input to the adder must in the same
- sample rate. The volume element makes it possible to control the volume
- of each sound.
- </p><p>
- When a sound is done being played it emits a End-Of-Stream-signal
- (EOS), which is caught by an event-handler-callback, which then makes
- sure that the bin in question is removed from the pipeline. When a
- sound is told by Gnash to stop playback before it has ended playback,
- we do something (not yet finally implemented), which makes the bin emit
- an EOS, and the event-handler-callback will remove the sound from the
- pipeline. Unfortunately Gstreamer currently has a bug which causes the
- entire pipeline to stop playing when unlinking an element from the
- pipeline; so far no fix is known.
- </p><p>
- Gstreamer also contains a bug concerning linking multiple elements to
- the adder in rapid succession, which causes to adder to "die" and stop
- the playback.
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="testing"></a>Testing </h2></div></div></div><p>
- <a class="link" href="#runtests" title="Running the Tests">Instructions
on running tests</a>
- can be found in the section on building Gnash.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="testtools"></a>Testing Tools</h3></div></div></div><p>
- Currently Gnash uses three other tools to help with
- testing. Two of these are free compilers for the Flash
- format. This lets us write simple test cases for Gnash to test
- specific features, and to see how the features operate.
- </p><p>
- The primary compiler used at this time is <a class="ulink"
href="http://ming.sf.net"; target="_top">Ming</a>. Since release 0.3,
- <span class="emphasis"><em>Ming</em></span> includes a command-line
compiler,
- <span class="emphasis"><em>makeswf</em></span>. This allows test case
development
- to be done entirely with free tools.
- </p><p>
- The other tools are optional.
- <a class="ulink" href="http://www.gnu.org/software/dejagnu";
target="_top">DejaGnu</a>
- is used to run multiple test cases in an automated
- manner. <span class="emphasis"><em>DejaGnu</em></span> is used by many
other <a class="ulink" href="http://www.gnu.org"; target="_top">GNU</a> projects
like
- <a class="ulink" href="http://gcc.gnu.org"; target="_top">GCC</a> and
- <a class="ulink" href="http://www.samba.org"; target="_top">Samba</a>.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="testcases"></a>Test
Cases</h3></div></div></div><p>
- ActionScript test cases are located under testsuite/actionscript.all/;
- these are organized in one file for the ActionScript class.
- Other Ming-generated tests are under testsuite/ming-misc.all/;
- these are typically used to test specific tag types.
- Full movies are located in testsuite/movies.all/ and
- sample movies are found in testsuite/samples/.
- Other directories in testsuite/ are (or shall be) used for other
- kind of tests.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="writeastests"></a>Writing ActionScript Tests</h3></div></div></div><p>
- Writing ActionScript tests is very simple. The
- <span class="emphasis"><em>makeswf</em></span> compiler makes use of
the C preprocessor,
- thus allowing the inclusion of definitions for macros and external
- files. We use these feature to provide common utilities
- for test units.
- </p><p>
- Each test unit sets an <span class="emphasis"><em>rcsid</em></span>
variable, includes the
- <span class="emphasis"><em>check.as</em></span> file and performs some
checks using
- the provided macros. Here is an example:
-
- </p><pre class="programlisting">
-
- // This variable will be used by check.as
- // to show testcase info as part of the test runs.
- rcsid="Name and version of this testcase, usually the RCS id";
-
- #include "check.as"
-
- // Test object creation
- check(new Object() instanceOf Object);
-
- // Test parseInt
- check(isNaN(parseInt('none')));
-
- // Test assignment
- var a = 1;
- check_equals(a, 1);
-
- // .. your tests here ...
- </pre><p>
- </p><p>
- The check(expr) macro will <span class="emphasis"><em>trace</em></span>
PASSED or FAILED
- together with the expression being evaluated and the line number
- of the check. This is the format expected by DejaGnu.
- </p><p>
- The <span class="emphasis"><em>check_equals(obtained,
expected)</em></span> macro uses equality operator
- <span class="emphasis"><em>==</em></span> to check for equality. When
possible, use of the
- <span class="emphasis"><em>check_equals()</em></span> macro is
preferred over <span class="emphasis"><em>check()</em></span>
- because it shows what the actual result was in case of a failure.
- </p><p>
- Additionally, the check.as file provides a transparent way to send
- results to a TextField rather then using trace. This is very useful
- when you use a flash player without tracing support.
- </p><p>
- Test units are built by running <span class="emphasis"><em>make
TestName-v#.swf</em></span>.
- This will use TestName.as as source and the value of # as target
version.
- Allowed target version are from 5 to 8 (inclusive).
- </p><p>
- Note that if you get a syntax error from the compiler, the line
- number will refer to the pre-processed file. This file is called
- <span class="emphasis"><em>TestName.as.pp</em></span> or <span
class="emphasis"><em>TestName-v#.swf.frame#.pp</em></span>
- (depending on Ming version) and it's not thrown away by
- <span class="emphasis"><em>makeswf</em></span> to make debugging easier.
- </p><p>
- Sometimes an expression is only supported by a specific SWF
- version, or it's evaluated differently by different SWF versions.
- For this purpose the framework provides an OUTPUT_VERSION macro
- that you can use to switch code based on output version. For example:
-
- </p><pre class="programlisting">
-
- #if OUTPUT_VERSION >= 7
- check(_root.getSWFVersion == OUTPUT_VERSION);
- #endif
-
- </pre><p>
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="writemingtests"></a>Writing Ming-based self-contained SWF
tests</h3></div></div></div><p>
- Ming-based test cases are located in testsuite/misc-ming.all
- and contain a test generator and a test runner.
- The test generator (usually a C program) is used to produce the SWF
- file, while the test runner (a C++ program) will run it using a
- MovieTester class.
- Note that only the test generator needs Ming, not the test
- runner, so if Ming isn't installed on the user's host,
- the test cases can still be run as long as SWF has been distributed.
- </p><p>
- Producing tests using Ming has the advantage that you can easily see
- and modify the full source code for the SWF movie, and you can use
- some <a class="link" href="#ming_testgenerator_facilities" title="Using
Ming-based test generators facilities">facilities</a>
- provided by the Gnash testing framework to easily run tests.
- </p><p>
- For generic Ming API documentation, see <a class="ulink"
href="http://www.libming.org/"; target="_top">http://www.libming.org</a>.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="ming_testgenerator_facilities"></a>Using Ming-based test
generators facilities</h4></div></div></div><p>
- Ming-based test generator facilities, which might be moved into
- a loadable SWF in the future, can be currently used by your test
- generator by including the ming_utils.h file and calling the
- appropriate functions.
- </p><p>
- The most useful facility provided for Ming-based SWF test generators
- is a Dejagnu-like TestState ActionScript class.
- In order to use this facility you must call 'add_dejagnu_functions()'
- right after Movie creation.
- The function takes an SWFMovie object and some parameters specifying
- depth and location of the "visual" trace textfield; it instantiates
- a global 'TestState' ActionScript object to keep track of test's state.
- </p><p>
- You will <span class="emphasis"><em>not</em></span> need to directly
invoke the
- TestState object created by the 'add_dejagnu_functions()' routine,
- rather you will be using C macros hiding its complexity:
-
- </p><pre class="programlisting">
-
- check(SWFMovie mo, const char* expr)
-
- Evaluate an ActionScript expression.
-
- xcheck(SWFMovie mo, const char* expr)
-
- Evaluate an ActionScript expression.
- A failure is expected
- (for cases where the call exposes a known bug).
-
- check_equals(SWFMovie mo, const char* obtained, const char* expected)
-
- Evaluate an ActionScript expression against an expected output.
-
- xcheck_equals(SWFMovie mo, const char* obtained, const char* expected)
-
- Evaluate an ActionScript expression against an expected output.
- A failure is expected (for cases where the call exposes a known
bug).
-
- print_tests_summary(SWFMovie mo)
-
- This will print a summary of tests run, and should be
- called as the last step in your SWF generator.
- </pre><p>
-
- </p><p>
- Test cases generated using Ming and the provided
- <a class="link" href="#ming_testgenerator_facilities" title="Using
Ming-based test generators facilities">facilities</a>
- will be self-contained, which means they can be used as tests
- by simply running them with whatever Player you might have.
- Any 'check' or 'check_equals' result will be both traced and
- printed in a textfield. You can use 'gprocessor -v' to have
- Gnash use them as tests.
- </p><p>
- See section <a class="link" href="#writing_test_runners" title="Writing
Test Runners">Writing Test Runners</a>
- for information about writing SWF test runners.
- </p></div></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="writing_dejagnu_so_tests"></a>Writing self-contained SWF tests with other
compilers</h3></div></div></div><p>
- If you want/need to use a different compiler for your test cases
(there's
- plenty of open source tools for generating SWF out there), you can still
- make use of a loadable SWF utility provided as part of the Gnash
testsuite
- to let your test consistent with the rest of the suite.
- </p><p>
- The loadable module is called <span
class="emphasis"><em>Dejagnu.swf</em></span> and is built during
- <span class="emphasis"><em>make check</em></span> under
testsuite/misc-ming.all. In order to use it
- you will need to load it into your SWF. We currently load it with an
IMPORT
- tag for our ActionScript based test cases, but you can probably also use
- loadMovie or whatever works in the target SWF you're generating. Just
make
- sure that the module is initialized before using it. You can check this
by
- inspecting the <span
class="emphasis"><em>dejagnu_module_initialized</em></span> variable, which will
- be set to 'true' when all initialization actions contained in the
- <span class="emphasis"><em>Dejagnu.swf</em></span> file are executed.
- </p><p>
- Once the module is loaded you will be able to invoke the following
functions,
- all registered against the <span class="emphasis"><em>_root</em></span>
sprite (effects of <span class="emphasis"><em>_lockroot</em></span>
- untested):
- </p><pre class="programlisting">
-
- check(expression, [message]);
-
- Evaluate the expression.
- Trace result (PASSED: expression / FAILED: expression).
- If fails, *visually* trace the failure.
- If second argument is given, it will be used instead of
- 'expression' for printing results.
-
- check_equals(obtained, expected)
-
- Evaluate an expression against an expected output.
- Trace result (PASSED: obtained == expected / FAILED: expected X,
obtained Y)
- If fails, *visually* trace the failure.
-
- xcheck(expression, [message]);
-
- Evaluate the expression.
- Trace result (XPASSED: expression / XFAILED: expression).
- If fails, *visually* trace the failure.
- If second argument is given, it will be used instead of
- 'expression' for printing results.
-
- xcheck_equals(obtained, expected)
-
- Evaluate an expression against an expected output.
- Trace result (XPASSED: obtained == expected / XFAILED: expected X,
obtained Y)
- If fails, *visually* trace the failure.
-
- note(string)
-
- Print string, both as debugging and *visual* trace.
-
- totals()
-
- Print a summary of tests run, both as debugging and *visual* traces.
-
- </pre><p>
- </p><p>
- Visual traces are lines of text pushed to a textarea defined
- by the <span class="emphasis"><em>Dejagnu.swf</em></span> module. The
textarea is
- initially placed at <span class="emphasis"><em>0, 50</em></span> and is
- <span class="emphasis"><em>600x800</em></span> in size. You can
resize/move the clip
- after loading it. Also, you can completely make the clip
- invisible if that bothers you. The important thing is the
- <span class="emphasis"><em>debugging</em></span> trace (call to the
trace
- function). The latter will be used by the testing framework.
- </p><p>
- See section <a class="link" href="#writing_test_runners" title="Writing
Test Runners">Writing Test Runners</a>
- for information about writing a test runners for your self-contained
tests.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="writing_test_runners"></a>Writing Test Runners</h3></div></div></div><p>
- Test runners are executables that run one or more tests,
- writing results in Dejagnu form to standard output.
- </p><p>
- The Dejagnu form uses a standard set of labels when printing test
- results. These are:
- </p><div class="informaltable"><table border="1"
width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
- <p>Label</p>
- </th><th valign="top">
- <p>Meaning</p>
- </th></tr></thead><tbody><tr><td align="left" valign="top">
- <p>PASSED</p>
- </td><td align="left" valign="top">
- <p>The test succeeded.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>FAILED</p>
- </td><td align="left" valign="top">
- <p>The test failed.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>XPASSED</p>
- </td><td align="left" valign="top">
- <p>The test succeeded, but was expected to fail.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>XFAILED</p>
- </td><td align="left" valign="top">
- <p>The test failed, and was expected to fail.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>UNRESOLVED</p>
- </td><td align="left" valign="top">
- <p>The results of the test could not be automatically
- parsed.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>UNTESTED</p>
- </td><td align="left" valign="top">
- <p>This test case is not complete.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>UNSUPPORTED</p>
- </td><td align="left" valign="top">
- <p>The test case relies on a conditional feature which
- is not present in your environment.</p>
- </td></tr></tbody></table></div><p>
- </p><p>
- The following labels may also appear:
- </p><div class="informaltable"><table border="1"
width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
- <p>Label</p>
- </th><th valign="top">
- <p>Meaning</p>
- </th></tr></thead><tbody><tr><td align="left" valign="top">
- <p>ERROR</p>
- </td><td align="left" valign="top">
- <p>There was a serious error in running the test. </p>
- </td></tr><tr><td align="left" valign="top">
- <p>WARNING</p>
- </td><td align="left" valign="top">
- <p>There may have been a problem with running the
- test.</p>
- </td></tr><tr><td align="left" valign="top">
- <p>NOTE</p>
- </td><td align="left" valign="top">
- <p>There was some additional information given about
- the test.</p>
- </td></tr></tbody></table></div><p>
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="generic_test_runner"></a>Using the generic test runner
for self-contained SWF tests</h4></div></div></div><p>
- The simplest test runner is one that simply invokes Gnash
- in verbose mode against a self-contained SWF test movie.
- Self-contained SWF test movies are the ones that print
- the PASSED/FAILED etc. lines using ActionScript (traces).
- By invoking Gnash in verbose mode this movie will behave
- as a compliant "Test Runner".
- </p><p>
- A generator for simple test runners can be found in
- <span
class="emphasis"><em>testsuite/generic-testrunner.sh</em></span>.
- The script can be invoked by passing it <span
class="emphasis"><em>$(top_builddir)</em></span>
- as the first argument and the name of the SWF file (without the path)
- as the second argument. This will create a specific runner for your
- test in the current build directory.
- A simple Makefile.am rule for doing this follows:
- </p><pre class="programlisting">
- MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
- sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf
> $@
- chmod +x $@
- </pre><p>
- </p><p>
- By default, the generated test runner will play the movie up to the
- last frame. If you want the movie to be played more then once (maybe
- because you're exactly testing loop features) you can use the -r
switch
- to the generic-testrunner.sh call. The following will create a runner
- playing the movie twice:
- </p><pre class="programlisting">
- MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
- sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir)
MyTest.swf > $@
- chmod +x $@
- </pre><p>
- </p><p>
- In case your test movie stops before the last frame, or you want to
control the
- exact number of times to call the frame advancement routine, you can
use the
- -f switch to control that.
- </p><pre class="programlisting">
- MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
- sh $(srcdir)/../generic-testrunner.sh -f10 $(top_builddir)
MyTest.swf > $@
- chmod +x $@
- </pre><p>
- When both -f and -r are given, the first exit condition reached will
take effect.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="writing_movie_testers"></a>Writing Movie testers</h4></div></div></div><p>
- There are some parts of Gnash that can NOT be tested
- by only using ActionScript tests. Examples include: frame
- advancements, actual actions execution, gui events and so on.
- </p><p>
- In this case you might want to use the MovieTester class to
- implement a C++ test runner. Be aware that you can <span
class="emphasis"><em>mix</em></span> tests in
- the MovieTester-based class with <span
class="emphasis"><em>self-contained</em></span>
- tests in the SWF file as long as you activate verbosity for
- the debug logfile. This is done, for example, for the
- DefineEditTextVariableNameTest.swf file. The corresponding
- test runner (DefineEditTextVariableNameTest-Runner) is a C++
- runner based on MovieTester class. If you run the runner you
- see two kinds of test results: the ones coming from the ActionScript
- engine, and the ones coming from the test runner. You can
- distinguish between the two because the former contains an additional
- timestamp and the latter does not. Also, you'll see two final
- summaries for the two test sets. The 'make check' rule, which uses
- the testsuite/simple.exp output parser as its work-horse, will
- count test results from both test sets.
- </p><p>
- Movie testers are executables which load an SWF, generate events
- (both user or system) on it, and check its state using
- a standard interface.
- </p><p>
- To help this process a MovieTester class is defined in the
- testsuite/MovieTester.{h,cpp} files; see Doxygen documentation
- for more information.
- </p><p>
- Note that you do NOT need access to the SWF source code in order
- to implement a Movie tester for it. Some knowledge about the
- expected behavior suffices.
- </p></div></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="newclass"></a>Chapter 4.
Adding New ActionScript Class</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="#declaration">Declaration</a></span></dt><dt><span class="sect1"><a
href="#instantiation">Instantiation</a></span></dt><dt><span class="sect1"><a
href="#methods">Methods</a></span></dt><dt><span class="sect1"><a
href="#properties">Dynamic Properties</a></span></dt><dt><span class="sect1"><a
href="#as_value">The <span class="emphasis"><em>as_value</em></span> Object
Type</a></span></dt><dd><dl><dt><span class="sect2"><a href="#data_types">Data
Types</a></span></dt><dt><span class="sect2"><a href="#is_methods">Determining
the Type</a></span></dt><dt><span class="sect2"><a href="#to_methods">Fetching
the Value</a></span></dt><dt><span class="sect2"><a href="#set_methods">Setting
the Value and Type</a></span></dt><dt><span class="sect2"><a
href="#further_as_value_reading">Further
Reading</a></span></dt></dl></dd><dt><span class="sect1"><a
href="#asobject">Object ActionScript Class</a></span></dt><dd><dl><dt><span
class="sect2"><a href="#objectmethods">The Methods of the
Class</a></span></dt><dt><span class="sect2"><a href="#objectprops">The
Properties of the Object Class</a></span></dt><dt><span class="sect2"><a
href="#objectconf">Object Class
Conformance</a></span></dt></dl></dd></dl></div><p>
- In this document, the term 'ActionScript class' refers to the
- C++ class which is instantiated by Gnash when some ActionScript
- code instantiates a corresponding class. The C++ class
- stores instance data and implements the methods which are
- called on the object in the ActionScript code.
- </p><p>
- Adding a new ActionScript class is relatively simple, but the
- process is complicated by the fact that the interface has evolved
- over time and the current code base represents several different
- formats. This document describes the current interface. The
- Boolean class should be considered the authoritative example of
- a modern ActionScript class.
- </p><p>
- ActionScript classes contain a header file and a C++
- implementation. The name is usually the name of the
- class as it is called in the ActionScript specifications;
- for instance <span class="emphasis"><em>Boolean.cpp</em></span> for the
Boolean class.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a
name="prototype"></a>Prototype</h2></div></div></div><p>
- In ActionScript, a prototype is a base object which contains
- all the methods that an instantiated object will contain.
- In short, it contains every part of the class except for
- the portions dealing with the storage of instance data.
- </p><p>
- In Gnash, the prototype of an ActionScript object is
- implemented as an <span class="emphasis"><em>as_object</em></span>.
- At startup, the methods and properties of the ActionScript class
- are attached to the <span class="emphasis"><em>as_object</em></span>.
The
- following example demonstrates how methods can be attached:
- </p><pre class="programlisting">
- static void
- attachBooleanInterface(as_object& o) {
- o.init_member("toString", new builtin_function(boolean_tostring));
- o.init_member("valueOf", new builtin_function(boolean_valueof));
- }
- </pre><p>
- </p><p>
- Static properties can also be added to the ActionScript prototype
- (<a class="link" href="#properties" title="Dynamic Properties">dynamic
properties</a>
- are addressed later). They are attached in a similar way:
- </p><pre class="programlisting">
- o.init_member("myProperty", as_value("HelloWorld"));
- </pre><p>
- </p><p>
- Properties which have been added in this manner can be
- directly accessed in ActionScript code without a function
- call, as this piece of ActionScript code compiled by Ming's
- <span class="emphasis"><em>makeswf</em></span> compiler demonstrates:
- </p><pre class="programlisting">
- // Get the value of the myProperty property
- if (node.myProperty == "HelloWorld") {
- trace("MATCHED");
- }
- </pre><p>
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="declaration"></a>Declaration</h2></div></div></div><p>
- A new class should derive from <span
class="emphasis"><em>as_object</em></span>,
- which is the base class of every ActionScript object in Gnash.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="instantiation"></a>Instantiation</h2></div></div></div><p>
- When a new object is needed, instance data is added to
- the methods and properties inherited from the prototype.
- </p><p>
- The init method should be called in the constructor in
- <span class="emphasis"><em>Global.cpp</em></span>, where all other
ActionScript
- classes are similarly referenced. This method constructs a
- prototype, which is implemented as an
- <span class="emphasis"><em>as_object</em></span>. In addition, the
method
- registers the constructor to be used for future object creation,
- and attaches methods and properties to the prototype.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="methods"></a>Methods</h2></div></div></div><p>
- Every method you implement and
- <a class="link" href="#prototype" title="Prototype">attach</a> will
receive an
- <span class="emphasis"><em>fn_call</em></span> data structure as an
argument when it is called.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="arguments"></a>Accessing
Arguments</h4></div></div></div><p>
- The arguments stored in <span class="emphasis"><em>fn_call</em></span>
- should be accessed using <span class="emphasis"><em>arg()</em></span>.
For
- instance, the first element can be popped with
- <span class="emphasis"><em>fn.arg(0)</em></span>.
- </p><p>
- The element popped off the stack is an
- <a class="link" href="#as_value" title="The as_value Object Type"><span
class="emphasis"><em>as_value</em></span>
- object</a>.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a name="return"></a>Returning a
Value to ActionScript</h4></div></div></div><p>
- The return value should be an
- <a class="link" href="#as_value" title="The as_value Object Type"><span
class="emphasis"><em>as_value</em></span>
- object</a>. For example:
- </p><pre class="programlisting">
- return as_value('Goodbye, cruel world.');
- </pre><p>
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="additional_fn_call"></a>Additional <span
class="emphasis"><em>fn_call</em></span> Members</h4></div></div></div><p>
- There are two other useful members of the <span
class="emphasis"><em>fn_call</em></span>
- structure, namely <span class="emphasis"><em>this_ptr</em></span> and
- <span class="emphasis"><em>nargs</em></span>. The former points to the
- class which is invoking this method, while the latter
- is a count of the number of
- <a class="link" href="#arguments" title="Accessing Arguments">arguments
in the stack</a>.
- </p><p>
- You may also see instances of the <span
class="emphasis"><em>env</em></span>
- pointer being used. This is being deprecated. Instances
- which could be replaced with
- <a class="link" href="#arguments" title="Accessing Arguments"><span
class="emphasis"><em>arg()</em></span></a>
- are already deprecated; other uses will be deprecated
- in the near future.
- </p><p>
- Beyond the <span class="emphasis"><em><a class="link" href="#arguments"
title="Accessing Arguments">arg()</a></em></span> method, there
- is one method of note. <span
class="emphasis"><em>dump_args()</em></span>
- can be used in debugging to output the entire argument
- stack.
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="properties"></a>Dynamic Properties</h2></div></div></div><p>
- This section describes accessors to dynamic properties.
- Read-only properties are described
- in the <a class="link" href="#prototype" title="Prototype">prototype</a>
section.
- </p><p>
- Accessors should be written as a single get/set method.
- Previously this was done by overriding
- <span class="emphasis"><em>get_member()</em></span> and
- <span class="emphasis"><em>set_member()</em></span>, but this practice
- is deprecated.
- </p><p>
- The accessor is written so that it sets the property
- if it is called with an argument, and puts the property in
- the <a class="link" href="#methods" title="Methods"><span
class="emphasis"><em>fn_call</em></span></a>
- <a class="link" href="#return" title="Returning a Value to
ActionScript">result pointer</a>. For instance:
- </p><pre class="programlisting">
- void
- MyClass::myProperty_getset(const fn_call& fn) {
- boost::intrusive_ptr<MyClass> ptr =
ensureType<MyClass>(fn.this_ptr);
-
- // setter
- if ( fn.nargs > 0 ) {
- bool h = fn.arg(0).to_bool();
- ptr->MyMethod(h);
- return;
- }
-
- // getter
- bool h = ptr->MyMethod();
- fn.result->set_bool(h);
- }
- </pre><p>
- </p><p>
- It has not yet been decided whether properties should be set
- in the <a class="link" href="#prototype" title="Prototype">exported
interface</a>
- or attached to instances of the class. A property is attached
- in the following manner:
- </p><pre class="programlisting">
- boost::intrusive_ptr<builtin_function> gettersetter;
- gettersetter = new builtin_function(&MyClass::myProperty_getset,
NULL);
- o.init_property("myProperty", *gettersetter, *gettersetter);
- </pre><p>
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="as_value"></a>The <span class="emphasis"><em>as_value</em></span> Object
Type</h2></div></div></div><p>
- The <span class="emphasis"><em>as_value</em></span> class is used
throughout
- the interpreter to create generic objects to hold data.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="data_types"></a>Data Types</h3></div></div></div><p>
- The following data types are supported:
- <span class="emphasis"><em>NULLTYPE</em></span>,
- <span class="emphasis"><em>BOOLEAN</em></span>, <span
class="emphasis"><em>STRING</em></span>,
- <span class="emphasis"><em>NUMBER</em></span>, <span
class="emphasis"><em>OBJECT</em></span>,
- <span class="emphasis"><em>AS_FUNCTION</em></span>, and
- <span class="emphasis"><em>MOVIECLIP</em></span> (sprite).
- The type <span class="emphasis"><em>C_FUNCTION</em></span> is being
deprecated.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="is_methods"></a>Determining the Type</h3></div></div></div><p>
- Several methods allow you to determine if a value stored in
- <span class="emphasis"><em>as_value</em></span> is of a specific type.
These
- follow the form of <span class="emphasis"><em>is_TYPE</em></span>, for
example
- <span class="emphasis"><em>is_as_function()</em></span> and
- <span class="emphasis"><em>is_number()</em></span>. In general, the
type names
- match the <a class="link" href="#data_types" title="Data Types">data
types</a> listed
- above, with the exception of the type <span
class="emphasis"><em>MOVIECLIP</em></span>
- which has a method <span class="emphasis"><em>is_sprite()</em></span>.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="to_methods"></a>Fetching
the Value</h3></div></div></div><p>
- Another set of methods will return a representation of
- the value as a particular type. They follow the
- <span class="emphasis"><em>to_TYPE</em></span> naming convention.
Examples
- are <span class="emphasis"><em>to_number()</em></span> and
- <span class="emphasis"><em>to_bool()</em></span>. The type names are as
- <a class="link" href="#data_types" title="Data Types">listed</a>
earlier, except for
- <span class="emphasis"><em>MOVIECLIP</em></span>, which uses
- <span class="emphasis"><em>to_sprite()</em></span>.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="set_methods"></a>Setting
the Value and Type</h3></div></div></div><p>
- Finally, there is the <span class="emphasis"><em>set_TYPE</em></span>
series
- of methods. They change the type to the type specified in
- the method name, and set the value to the one given as an
- argument. It is also possible to accomplish the same thing
- with the <span class="emphasis"><em>=</em></span> operator. Again, type
names
- match those <a class="link" href="#data_types" title="Data Types">named
earlier</a>,
- except in the case of <span class="emphasis"><em>MOVIECLASS</em></span>.
Its
- method is called <span class="emphasis"><em>set_sprite()</em></span>.
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a
name="further_as_value_reading"></a>Further Reading</h3></div></div></div><p>
- Please refer to <span class="emphasis"><em>as_value.h</em></span> or the
- Doxygen documentation (see 'Processing The Documentation'
- in the Gnash manual for instructions on generating
- documents with Doxygen) for more information
- about which methods are available for the
- <span class="emphasis"><em>as_value</em></span> object.
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="asobject"></a>Object ActionScript Class</h2></div></div></div><p>
- This class implements an Object object.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="objectmethods"></a>The Methods of the
Class</h3></div></div></div><p>
- </p><div class="variablelist"><dl><dt><span
class="term">addProperty()</span></dt><dd><p>
- </p></dd><dt><span class="term">registerClass()</span></dt><dd><p>
- </p></dd><dt><span class="term">toString()</span></dt><dd><p>
- </p></dd><dt><span class="term">unwatch()</span></dt><dd><p>
- </p></dd><dt><span class="term">valueOf()</span></dt><dd><p>
- </p></dd><dt><span class="term">watch()</span></dt><dd><p>
- </p></dd><dt><span class="term">Sharedclear()</span></dt><dd><p>
- </p></dd><dt><span class="term">Sharedflush()</span></dt><dd><p>
- </p></dd><dt><span class="term">SharedgetLocal()</span></dt><dd><p>
- </p></dd><dt><span class="term">SharedgetSize()</span></dt><dd><p>
- </p></dd></dl></div><p>
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="objectprops"></a>The
Properties of the Object Class</h3></div></div></div><p>
- </p><div class="variablelist"><dl><dt><span
class="term">constructor</span></dt><dd><p>
- </p></dd><dt><span class="term">__proto__</span></dt><dd><p>
- </p></dd><dt><span class="term">__resolve</span></dt><dd><p>
- </p></dd><dt><span class="term">Shareddata</span></dt><dd><p>
- </p></dd><dt><span class="term">SharedonStatus</span></dt><dd><p>
- </p></dd></dl></div><p>
- </p></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="objectconf"></a>Object
Class Conformance</h3></div></div></div><p>
- </p><div class="informaltable"><table border="1"
width="75%"><colgroup><col><col></colgroup><thead><tr><th valign="top">
- <p>Class Name</p>
- </th><th valign="top">
- <p>Conformance</p>
- </th></tr></thead><tbody><tr><td align="left" valign="top">
- <p>addProperty()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>registerClass()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>toString()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>unwatch()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>valueOf()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>watch()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>Sharedclear()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>Sharedflush()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>SharedgetLocal()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>SharedgetSize()</p>
- </td><td align="center" valign="top">
- <p>
- This method has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>constructor</p>
- </td><td align="center" valign="top">
- <p>
- This property has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>__proto__</p>
- </td><td align="center" valign="top">
- <p>
- This property has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>__resolve</p>
- </td><td align="center" valign="top">
- <p>
- This property has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>Shareddata</p>
- </td><td align="center" valign="top">
- <p>
- This property has an unknown status.
- </p>
- </td></tr><tr><td align="left" valign="top">
- <p>SharedonStatus</p>
- </td><td align="center" valign="top">
- <p>
- This property has an unknown status.
- </p>
- </td></tr></tbody></table></div><p>
- </p></div></div></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="bugreport"></a>Chapter
5. Reporting Bugs</h2></div></div></div><div class="toc"><p><b>Table of
Contents</b></p><dl><dt><span class="sect1"><a href="#bugstep_package">Get a
Fresh Binary Package</a></span></dt><dt><span class="sect1"><a
href="#bugstep_search">Determine if the bug was previously
reported</a></span></dt><dt><span class="sect1"><a
href="#bugstep_guidelines">Review the bug writing
guidelines</a></span></dt><dt><span class="sect1"><a
href="#bugstep_file">Filing a bug report</a></span></dt></dl></div><p>
- The Gnash project relies on the community of Gnash users to test
- the player, feedback is critical to any successful project. Not
- only does it let us know that people use Gnash, but it helps us
- understand the community's needs. Gnash uses a bug tracker on
- <a class="ulink" href="http://savannah.gnu.org";
target="_top">http://savannah.gnu.org</a> to manage these reports.
- </p><p>
- When filing a report, please follow the guidelines below. The better
- your bug report is, the easier it will be for the developers to
- address the issue. Bug reports without enough information will
- initially be asked to provide this information anyway. Adding
- critical details, like the Operating System you are on, its
- version, and any relevant error messages from Gnash that you get.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="bugstep_package"></a>Get a Fresh
Binary Package</h2></div></div></div><p>
- For starters, it's a good idea to obtain a copy of the latest
- snapshot. Although Gnash is primarily released as source, the
- Gnash build infrastructure allows the automated building of
- binary packages. Often the version of Gnash as packaged by a
- GNU/Linux or BSD distribution is based on the last official
- release, which could be months out of date. It is helpful if
- this is the case to try a newer packaged build of Gnash.
- </p><p>
- You can get a fresh binary package of Gnash, as well as recent
- source packages from
- <a class="ulink" href="http://www.getgnash.org/packages/"; target="_top">
- http://www.getgnash.org/packages
- </a>.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="bugstep_search"></a>Determine if the bug was previously
reported</h2></div></div></div><p>
- Search the <a class="ulink"
href="https://savannah.gnu.org/bugs/?group=gnash"; target="_top">Gnash
- bug tracker</a> to see if the bug has already been identified.
- </p><p>
- If the issue has already been reported, you should not file
- a bug report. However, you may add some additional information
- to the ticket if you feel that it will be beneficial to the
- developers. For instance, if someone reported a memory issue
- on Ubuntu GNU/Linux, and you noticed the same problem on OpenBSD,
- your stacktrace would be useful. Conversely, adding a "me too"
- note to a feature request is not helpful.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="bugstep_guidelines"></a>Review the bug writing
guidelines</h2></div></div></div><p>
- A good bug report should be precise, explicit, and discrete.
- This means that there should be just one bug per ticket, and
- that a ticket should contain the following information:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p>
- An overview of the problem;
- </p></li><li style="list-style-type: circle"><p>
- Instructions on how to replicate the bug;
- </p></li><li style="list-style-type: circle"><p>
- A description of what happened when you performed the steps
- to replicate the bug, and what you expected to happen;
- </p></li><li style="list-style-type: circle"><p>
- Your system information: operating system name and version, as
- well as the versions of major development dependencies;
- </p></li><li style="list-style-type: circle"><p>
- The release number or checkout timestamp for the version of Gnash
- where you observe the problem;
- </p></li><li style="list-style-type: circle"><p>
- The file <code class="filename">config.log</code>, which should be
- attached as a file;
- </p></li><li style="list-style-type: circle"><p>
- A descriptive title.
- </p></li></ul></div><p>
- Include any additional information that you feel might be useful
- to the developers.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="bugstep_file"></a>Filing a bug report</h2></div></div></div><p>
- After following the steps described above, you can file a bug report at
- <a class="ulink" href="https://savannah.gnu.org/bugs/?group=gnash";
target="_top">https://savannah.gnu.org/bugs/?group=gnash</a>.
- </p></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="extensions"></a>Chapter
6. Gnash 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><dd><dl><dt><span class="sect2"><a
href="#craftext">Crafting an Extension</a></span></dt></dl></dd><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>
- Gnash supports extending the Flash specification by creating
- custom ActionScript classes that are compiled code, as opposed to
- the existing method of defining custom classes as
- ActionScript. Executing compiled code has many performance
- benefits over having to interpret the byte stream of the
- ActionScript opcodes.
- </p><p>
- I can already hear people complaining now about the concept of
- extending Flash, so this in no way affects Gnash's ability to play
- Flash movies when functioning as a browser plugin.
- Gnash's goal is still to function in a way that is compatible
- with the current proprietary Flash player.
- </p><p>
- But at the same time, we see Flash as the ideal scripting language
- for a digital multi-media streaming environment. There are many
- resources for Flash movie creators for widgets, higher level APIs,
- all sorts of desirable things. But for those of use committed to
- using free software tools for Flash, our options are very
- limited.
- </p><p>
- Rather than launching a multi-year project to duplicate all
- classes in the commercial Flash IDE, it's much more efficient to
- use existing development libraries much like Python or Perl
- do. The extension mechanism in Gnash allows wrappers to be created
- for any C or C++ development library. Unlike the proprietary Flash
- IDE, which compiles all the extension libraries into byte codes
- from ActionScript, the support is moved to the player side. Movies
- with all of the goodies of the proprietary IDE in them play in
- Gnash just fine, as it's all just byte codes by then.
- </p><p>
- This trick works because until Flash player version 9, all the
- ActionScript class names and methods are passed as ASCII strings
- into the Flash movie. So the Gnash Virtual Machine just loads the
- extension file if that class name is invoked in the movie. All
- extension files specify the class name and methods it implements
- in an identical style as adding any new ActionScript class. The
- advantage is the class itself is compiled code, and runs much
- faster than the equivalent byte codes which all have to be
- interpreted..
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="newext"></a>Creating A New
Extension</h2></div></div></div><p>
- Each new extension should live in it's own directory. The
- extensions included in Gnash are all in the
- <span class="emphasis"><em>gnash/extensions</em></span> directory.
Creating an extension
- requires a Makefile.am,
- </p><p>
- If you are adding this extension to the Gnash source tree
- itself, then you need to make two changes to add the new
- extension.
- </p><p>
- The first change is to add the directory to the list in
- extensions/Makefile.am. This can be done either by adding the
- new directory to the SUBDIRS setting, or by wrapping it in a
- conditional test.
- </p><p>
- The other change is to add it to the AC_OUTPUT list in
- <span class="emphasis"><em>configure.ac</em></span> so the new directory
will be
- configured along with the rest of Gnash.
- </p><p>
- Each extension should have an ActionScript source file included
- that tests the new class, and this file should be referenced in
- the new Makefile.am in the <span
class="emphasis"><em>check_PROGRAMS</em></span>
- variable so that "make check" works.
- </p><p>
- When creating an extension that is a wrapper for an existing
- development library API, it's often better to make this a thin
- layer, than to get carried away with creating beautiful
- abstractions. Higher-level classes that offer a lot of new
- functionality are fine, but is different than wrapping a library
- so it can be used from within Gnash.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="craftext"></a>Crafting an
Extension</h3></div></div></div><p>
- All extensions have the same requirements, namely setting up a
- few defined function callbacks, which the Gnash VM then uses
- to do the right thing. The initial two function callbacks are
- for handling the interface of the newly created object so that
- Gnash can find and use it.
- </p><p>
- The first function is commonly called
- <span class="emphasis"><em>attachInterface</em></span>, and this sets
the other
- function callbacks for all the methods this class
- supports. The method callbacks are attached to the parent
- class by using <span class="emphasis"><em>init_member()</em></span> to
set a C
- function pointer to the string value used in the Flash movie.
- </p><pre class="programlisting">
- // Attach DummyClass 'func1' and 'func2' methods to the given object
- static void
- attachInterface(as_object& obj) {
- obj.init_member("func1", &ext_func1);
- obj.init_member("func2", &ext_func2);
- }
- </pre><p>
- The second function is commonly called
- <span class="emphasis"><em>getInterface()</em></span>, and this returns
a
- pointer to a static prototype of the class.
- Gnash uses garbage collection for ActionScript objects
- so you need to register the static with the VM to give it
- a chance to be marked as reachable.
- </p><pre class="programlisting">
- static as_object*
- getInterface()
- {
- static boost::intrusive_ptr<as_object> o;
- if (o == NULL) {
- o = new as_object();
- VM::get().addStatic(o);
- attachInterface(*o);
- }
- return o.get();
- }
- </pre><p>
- This is the callback that gets executed when constructing a
- new object for the VM. In this example we'll assume the new
- ActionScript class is called <span
class="emphasis"><em>DummyExt</em></span>,
- and has two methods, <span class="emphasis"><em>func1</em></span> and
- <span class="emphasis"><em>func2</em></span>.
- </p><pre class="programlisting">
- static as_value
- dummyext_ctor(const fn_call& fn)
- {
- DummyExt *obj = new DummyExt(); // will setup prototypes
-
- return as_value(obj);
- }
- </pre><p>
- The trick for the above simple constructor to work is that
- class appartenence is setup in the C++ DummyExt constructor
- itself, which should derive from as_object and construct the
- base passing it the interface (prototype) of it's class.
- </p><pre class="programlisting">
- class DummyExt : public as_object
- {
- public:
- DummyExt()
- :
- as_object(getInterface()) // returns the static prototype
- {}
-
- };
- </pre><p>
- Initialize the extension. This is looked for by the extension
- handling code in each extension, and is executed when the
- extension is loaded. This is the main entry point into the
- extension. This function can be found because the prefix of
- <span class="emphasis"><em>dummyext</em></span>, which also matches the
file
- name of the extension. Gnash uses the name of the extension
- file itself when looking for the init function.
- </p><pre class="programlisting">
- extern "C" {
- void
- dummyext_class_init(as_object &obj)
- {
- static builtin_function* cl=NULL;
- if (!cl)
- {
- // Create a builtin function using the given constructor
- // to instanciate objects and exporting the given interface
- cl = new builtin_function(&dummyext_ctor,
getInterface());
- VM::get().addStatic(cl); // will forbid to collect the class
- }
-
- obj.init_member("DummyExt", cl);
- }
- } // end of extern C
- </pre><p>
- The callbacks are all C functions. Like all the other code
- that implements ActionScript, parameters to the function are
- passed in using the <span class="emphasis"><em>fn_call</em></span> data
- structure. The return code, if any, is also returned using
- this data structure. <span class="emphasis"><em>this_ptr</em></span> is
the
- object that the method is a member of.
- </p><pre class="programlisting">
- // Creates a new button with the label as the text.
- as_value func1(const fn_call& fn) {
- // Following line will ensure 'func1' is called for a DummyExt
instance,
- // or would throw an exception which should behave as if we
returned the
- // undefined value.
- boost::intrusive_ptr<DummyExt> ptr =
ensureType<DummyExt>(fn.this_ptr);
-
- if (fn.nargs > 0) {
- std::string label = fn.arg(0).to_string();
- bool ret = ptr->dummy_text_label(label);
- return as_value(ret);
- }
- }
- </pre></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="debuext"></a>Debugging An Extension</h2></div></div></div><p>
- As extensions are loaded dynamically at runtime, debugging one
- can be difficult. You can use GDB, but you have the problem of
- not being able to set a breakpoint in Gnash until
- <span class="emphasis"><em>after</em></span> the extension has been
loaded into
- Gnash's VM. The easy solution is to use the Gnash debugger.
- </p><p>
- You can insert these few lines in any file that you wish to
- manually start the debugger. Once at the console, you can attach
- GDB to the process. Then you can set breakpoints, etc... and you
- are at the point of execution where the console was started. To
- then continue playing the movie, type the <span
class="emphasis"><em>c</em></span>
- (for continue) command to the Gnash console.
- </p><pre class="programlisting">
- // Get the debugger instance
- static Debugger& debugger = Debugger::getDefaultInstance();
-
- // Enable the debugger
- debugger.enabled(true);
- // Stop and drop into a console
- debugger.console();
- </pre><p>
- You can also resort to the time honored technique of creating a
- loop before the point you want to set a breakpoint for. Gnash
- will stop playing the movie at this point, and then you can
- externally attach GDB to the running process, or type
- <span class="emphasis"><em>^C</em></span> to drop into the GDB command
console.
- </p><pre class="programlisting">
- bool stall = true;
- while (stall) {
- sleep 1;
- }
- </pre><p>
- Once you have set the breakpoints you want, reset the value of
- the <span class="emphasis"><em>stall</em></span> variable to break out
of the
- loop, and the Flash movie will then continue playing.
- </p><pre class="programlisting">
- (gdb) set variable stall = false;
- continue
- </pre></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="inclext"></a>Included Extensions</h2></div></div></div><p>
- Gnash has some extensions included in the distribution. This is
- mostly because they were written by the Gnash team. Extensions
- can be external to gnash, Gnash needs no compiled in knowledge
- to load an extension file.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="gtkext"></a>Gtk Extension</h4></div></div></div><p>
- The GTK ActionScript class follows the same API as Gtk2, even down
- to the same arguments to the same function names. This means
- you're actually programming GTK,you're just using ActionScript
- instead of python, perl, or C. This extension makes it possible to
- write Flash movies that use the Gtk2 widgets for user interface
- components.
- </p><div class="variablelist"><dl><dt><span
class="term">window_new</span></dt><dd><p>
- Create a new window.
- </p></dd><dt><span class="term">signal_connect</span></dt><dd><p>
- Add an event handler to a widget.
- </p></dd><dt><span
class="term">container_set_border_width</span></dt><dd><p>
- Set the width of the window border.
- </p></dd><dt><span class="term">button_new_with_label</span></dt><dd><p>
- Create a new button and give it the specified label.
- </p></dd><dt><span
class="term">signal_connect_swapped</span></dt><dd><p>
- Swap signals. Commonly used for <span
class="emphasis"><em>delete</em></span> event handling.
- </p></dd><dt><span class="term">container_add</span></dt><dd><p>
- Add one widget to another as a child.
- </p></dd><dt><span class="term">widget_show</span></dt><dd><p>
- Display the widget on the screen.
- </p></dd><dt><span class="term">main</span></dt><dd><p>
- Start the main GTK event loop. This function does not return.
- </p></dd></dl></div></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a name="fileioext"></a>File I/O
Extension</h4></div></div></div><p>
- Flash movies are traditionally forbidden from accessing the
- filesystem, but this may be necessary for some embedded
- applications. Especially in the case of a user console, currently
- there is no way to get input into a Flash movie but through a
- TextField.
- </p><div class="variablelist"><dl><dt><span
class="term">fopen</span></dt><dd><p>
- Open the file.
- </p></dd><dt><span class="term">fread</span></dt><dd><p>
- Read a series of bytes from the opened file.
- </p></dd><dt><span class="term">fgetc</span></dt><dd><p>
- Read a single byte from the opened file.
- </p></dd><dt><span class="term">fgets</span></dt><dd><p>
- Read a single line until a Carriage Return from the opened file.
- </p></dd><dt><span class="term">gets</span></dt><dd><p>
- Read a single line from the standard in.
- </p></dd><dt><span class="term">getchar</span></dt><dd><p>
- Read a single character from the standard in.
- </p></dd><dt><span class="term">fwrite</span></dt><dd><p>
- </p></dd><dt><span class="term">fputc</span></dt><dd><p>
- Write a single character to the opened file.
- </p></dd><dt><span class="term">fputs</span></dt><dd><p>
- Write a single line to the opened file.
- </p></dd><dt><span class="term">puts</span></dt><dd><p>
- Write a single line to standard out..
- </p></dd><dt><span class="term">putchar</span></dt><dd><p>
- Write a single character to standard out..
- </p></dd><dt><span class="term">fflush</span></dt><dd><p>
- Flush the current opened file to disk.
- </p></dd><dt><span class="term">fseek</span></dt><dd><p>
- Seek to a location within the opened file.
- </p></dd><dt><span class="term">ftell</span></dt><dd><p>
- Report the current position within the opened file.
- </p></dd><dt><span class="term">fclose</span></dt><dd><p>
- Close the opened file.
- </p></dd></dl></div></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a name="mysqlext"></a>MySQL
Extension</h4></div></div></div><p>
- The MySQL ActionScript class follows the same API as MySQL, even down
- to the same arguments to the same function names. This enables a
- Flash movie to have direct access to a MySQL
- database. Traditionally Flash movies have had no database
- support, they either had to use arrays, or use XML to communicate
- to an application specific external database daemon.
- </p><div class="variablelist"><dl><dt><span
class="term">connect</span></dt><dd><p>
- Connect to a MySQL database.
- </p></dd><dt><span class="term">qetData</span></dt><dd><p>
- Get data from the database.
- </p></dd><dt><span class="term">disconnect</span></dt><dd><p>
- Disconnect from a MySQL database.
- </p></dd><dt><span class="term">query</span></dt><dd><p>
- Execute an SQL query to the database.
- </p></dd><dt><span class="term">fetch_row</span></dt><dd><p>
- Fetch a row from the query results.
- </p></dd><dt><span class="term">num_fields</span></dt><dd><p>
- </p></dd><dt><span class="term">free_result</span></dt><dd><p>
- Free the results of a query.
- </p></dd><dt><span class="term">store_results</span></dt><dd><p>
- Store the results of a query.
- </p></dd></dl></div></div></div></div><div class="chapter"
lang="en"><div class="titlepage"><div><div><h2 class="title"><a
name="rtmp"></a>Chapter 7. RTMP Protocol</h2></div></div></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a
href="#amf">AMF Format</a></span></dt></dl></div><p>
- This document is based mostly on my own reverse engineering of the
- RTMP protocol and AMF format. <span
class="emphasis"><em>tcpdump</em></span> and
- <span class="emphasis"><em>ethereal</em></span> are your friend. Some
additional info that got
- me started was from the <a class="ulink"
href="http://www.osflash.org/red5"; target="_top">Red5</a>
- project. <span class="emphasis"><em>Red5</em></span> is the only other
open source Flash
- server. So some details are still vague, but as the implementation
- appears to work, we'll figure out what they are later.
- </p><p>
- The Real Time Messaging Protocol was created by MacroMedia (now
- Adobe) for delivering Flash objects and video over a network
- connection. Currently the only servers which support this format
- are the MacroMedia Media sever, and the Open Source Red5 project.
- </p><p>
- This is a simple protocol, optimized for poor bandwidth
- connections. It can support up to 64 concurrent streams over the
- same network connection. Part of each AMF packet header contains
- the index number of the stream. A single RTMP message can contain
- multiple AMF packets.
- </p><p>
- An RTMP connection uses Tcp/ip port 1935. It is also possible to
- tunnel RTMP over an HTTP connection using port 80. Each AMF packet
- is 128 bytes long except for streaming audio, which has 64 byte
- packets.
- </p><p>
- The basics of the RTMP protocol are as follows. All communications
- are initiated by the client.
- </p><div class="mediaobject" align="center"><img src="images/rtmp.png"
align="middle"></div><p>
- </p><p>
- The client starts the RTMP connection by sending a single byte
- with a value of 0x3. This byte is followed by a data block of 1536
- bytes. The format if this data block is unknown, but it appears to
- not be actually used by the protocol except as a handshake.
- </p><p>
- The server receives this packet, stores the 1536 byte data block,
- and then send a single byte with the value of 0x3, followed by two
- 1536 data blocks. The second data block is the full contents of
- the original data block as sent by the client.
- </p><p>
- The client receives the 1536 byte data block, and if they match,
- the connection is established. After the handshake process is
- done, there are three other messages that the client sends to the
- sever to start the data flowing.
- </p><p>
- The first AMF packet sent to the server contains the
- <span class="emphasis"><em>connect</em></span> packet. This doesn't appear
to do
- much but notify the server the client is happy with the
- handshake, and ready to start reading packets.
- </p><p>
- The second packet is the <span
class="emphasis"><em>NetConnection</em></span> object from
- the client. This ActionScript class is used by the Flash movie to
- create the network connection to the server.
- </p><p>
- The third packet is the <span class="emphasis"><em>NetStream</em></span>
object from the
- client. This is the ActionScript class used to specify the file to
- be streamed by the server.
- </p><p>
- The RTMP packet for our example looks like this:
-
- </p><pre class="programlisting">
- 030000190000c91400000000020007connect00?f0000000000000030003app0200#
- software/gnash/tests/1153948634.flv0008flashVer02000cLNX 6,0,82,0 0006
- swfUrl02001dfile:///file|%2Ftmp%2Fout.swfc30005tcUrl\002\0004
- rtmp://localhost/software/gnash/tests/1153948634.flv\000\000\t
- \002\000\005userx
- </pre><p>
-
- We'll take this apart in a bit, but you can see how all three AMF
- packets are in the same message. The message is received in
- several 128 byte blocks, with the last one being less than
- that. The total size of the RTMP message is in the header, so the
- reader can tell if the entire message was read or not.
- </p><p>
- The RTMP header is first, followed by the connect message as an
- ASCII string as the message body. The following AMF packet is the
- <span class="emphasis"><em>NetConnection</em></span> one, which specifies
that this is coming
- from a Flash application. This also contains the file path the server
- can use to find the file to stream. This is then followed by the
- version number, which I assume is the version of the Flash player,
- so the server knows what it is talking to.
- </p><p>
- The third packet is the one from <span
class="emphasis"><em>NetStream</em></span>, which
- specifies the URL used for the movie, followed by the user name
- for a semblance of security.
- </p><p>
- For the next level of detail, we'll explain the format of AMF. AMF
- is used by the RTMP protocol to transfer data. Each Flash object
- is encapsulated in an AMF packet, including streaming audio or
- video.
- </p><p>
- The first byte of the RTMP header determines two things about the
- rest of the message. The first 2 bits of this byte signify the
- total size of the RTMP header. The RTMP header is of a variable
- size, so this is important.
-
- </p><div class="variablelist"><dl><dt><span
class="term">00</span></dt><dd><p>
- This specifies the header contains 12 bytes, including
- this one.
- </p></dd><dt><span class="term">01</span></dt><dd><p>
- This specifies the header contains 8 bytes, including this
- one.
- </p></dd><dt><span class="term">02</span></dt><dd><p>
- This specifies the header contains 4 bytes, including this
- one.
- </p></dd><dt><span class="term">03</span></dt><dd><p>
- This specifies the header contains 1 byte, so this is the
- complete header.
- </p></dd></dl></div><p>
- </p><p>
- The other 6 bits in this byte represent the AMF index. As a single
- RTMP connection can support multiple data streams, this signifies
- which stream this packet is for. Once an AMF object is fully
- received by the client, the AMF index may be reused.
- </p><p>
- For messages with headers of at least 4 bytes, the next 3 bytes are
- used by audio and video data packets, but at this time the meaning
- of this field is unknown.
- </p><p>
- For messages with a 8 byte or larger header, the next 3 bytes
- determine the size of the RTMP message being transmitted. Messages
- with a 1 byte or 4 byte header use a standard size, 128 bytes for
- video, and 64 bytes for audio.
- </p><p>
- For messages with an 8 byte or larger header, the next byte is the
- type of the AMF object.
-
- </p><div class="variablelist"><dl><dt><span
class="term">0x3</span></dt><dd><p>
- This specifies the content type of the RTMP packet is the
- number of bytes read. This is used to start the RTMP
- connection.
- </p></dd><dt><span class="term">0x4</span></dt><dd><p>
- This specifies the content type of the RTMP message is a
- <span class="emphasis"><em>ping</em></span> packet.
- </p></dd><dt><span class="term">0x5</span></dt><dd><p>
- This specifies the content type of the RTMP message is
- server response of some type.
- </p></dd><dt><span class="term">0x6</span></dt><dd><p>
- This specifies the content type of the RTMP packet is
- client request of some type.
- </p></dd><dt><span class="term">0x8</span></dt><dd><p>
- This specifies the content type of the RTMP packet is an
- audio message.
- </p></dd><dt><span class="term">0x9</span></dt><dd><p>
- This specifies the content type of the RTMP message is a
- video packet.
- </p></dd><dt><span class="term">0x12</span></dt><dd><p>
- This specifies the content type of the RTMP message is
- notify.
- </p></dd><dt><span class="term">0x13</span></dt><dd><p>
- This specifies the content type of the RTMP message is
- shared object.
- </p></dd><dt><span class="term">0x14</span></dt><dd><p>
- This specifies the content type of the RTMP message is
- remote procedure call. This invokes the method of a Flash
- class remotely.
- </p></dd></dl></div><p>
-
- </p><p>
- There are two sets of data types to consider. One set is used by
- the to specify the content type of the AMF object, the other is an
- ActionScript data type tag used to denote which type of object is
- being transferred.
- </p><p>
- The values of the initial type byte are:
- </p><div class="variablelist"><dl><dt><span
class="term">0x0</span></dt><dd><p>
- This specifies the data in the AMF packet is a numeric
- value. All numeric values in Flash are 64 bit,
- <span class="emphasis"><em>big-endian</em></span>.
- </p></dd><dt><span class="term">0x1</span></dt><dd><p>
- This specifies the data in the AMF packet is a boolean
- value.
- </p></dd><dt><span class="term">0x2</span></dt><dd><p>
- This specifies the data in the AMF packet is an
- <span class="emphasis"><em>ASCII</em></span> string.
- </p></dd><dt><span class="term">0x3</span></dt><dd><p>
- This specifies the data in the AMF packet is a Flash
- object. The Flash object data type field further along in
- the message specifies which type of ActionScript object it
- is.
- </p></dd><dt><span class="term">0x4</span></dt><dd><p>
- This specifies the data in the AMF packet is a Flash
- movie, ie. another Flash movie.
- </p></dd><dt><span class="term">0x5</span></dt><dd><p>
- This specifies the data in the AMF packet is a NULL
- value. NULL is often used as the return code from calling
- Flash functions.
- </p></dd><dt><span class="term">0x6</span></dt><dd><p>
- This specifies the data in the AMF packet is a
- undefined. This is also used as the return code from
- calling Flash functions.
- </p></dd><dt><span class="term">0x7</span></dt><dd><p>
- This specifies the data in the AMF packet is a reference.
- </p></dd><dt><span class="term">0x8</span></dt><dd><p>
- This specifies the data in the AMF packet is a ECMA
- array.
- </p></dd><dt><span class="term">0x9</span></dt><dd><p>
- This specifies the data in the AMF packet is the end of an
- object definition. As an object is transmitted with
- multiple AMF packets, this lets the server know when the
- end of the object is reached.
- </p></dd><dt><span class="term">0xa</span></dt><dd><p>
- This specifies the data in the AMF packet is a Strict
- array.
- </p></dd><dt><span class="term">0xb</span></dt><dd><p>
- This specifies the data in the AMF packet is a date.
- </p></dd><dt><span class="term">0xc</span></dt><dd><p>
- This specifies the data in the AMF packet is a multi-byte
- string. Multi-byte strings are used for international
- language support to represent non <span
class="emphasis"><em>ASCII</em></span>
- fonts.
- </p></dd><dt><span class="term">0xd</span></dt><dd><p>
- This specifies the data in the AMF packet is a an
- unsupported feature.
- </p></dd><dt><span class="term">0xe</span></dt><dd><p>
- This specifies the data in the AMF packet is a record
- set.
- </p></dd><dt><span class="term">0xf</span></dt><dd><p>
- This specifies the data in the AMF packet is a AML
- object. XML objects are then parsed by the
- <span class="emphasis"><em>XML</em></span> ActionScript class.
- </p></dd><dt><span class="term">0x10</span></dt><dd><p>
- This specifies the data in the AMF packet is a typed object.
- </p></dd></dl></div><p>
-
- </p><p>
- For messages with a 12 byte header, the last 4 bytes are the
- routing of the message. If the destination is the server, this
- value is the NetStream object source. If the destination is the
- client, this is the NetStream object for this RTMP message. A
- value of 0x00000000 appears to be reserved for the NetConnection
- object.
- </p><p>
- Multiple AMF streams can be contained in a single RTMP messages,
- so it's important to check the index of each AMF packet.
- </p><p>
- An example RTMP header might look like this. (spaces added between
- fields for clarity) All the numbers are in hex.
-
- </p><pre class="screen">
- 03 000019 0000c9 14 000000000
- </pre><p>
-
- </p><div class="variablelist"><dl><dt><span
class="term">03</span></dt><dd><p>
- The first two bits of this byte are the size of the
- header, which in this example is 00, for a 12 byte
- header. The next 6 bits is the AMF stream index number,
- which in this example is 0x3.
- </p></dd><dt><span class="term">000019</span></dt><dd><p>
- These 3 bytes currently have an unknown purpose.
- </p></dd><dt><span class="term">000c9</span></dt><dd><p>
- Since this example has a 12 byte header, this is the size
- of the RTMP message, in this case 201 bytes.
- </p></dd><dt><span class="term">14</span></dt><dd><p>
- This is the content type of the RTMP message, which in
- this case is to invoke a remote function call. (which we
- later see is the connect function).
- </p></dd><dt><span class="term">00000000</span></dt><dd><p>
- The source is the NetConnection object used to start this
- connection.
- </p></dd></dl></div><p>
-
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="amf"></a>AMF
Format</h2></div></div></div><p>
- The AMF format is used in the LocalConnection, SharedObject,
- NetConnection, and NetStream ActionScript classes. This is a means
- of binary data interchange between Flash movies, or between a
- Flash player and a Flash server.
- </p><p>
- Like the RTMP messages, an AMF packet header can be of a variable
- size. The size is either the same as the initial header of the
- RTMP message, or a 1 byte header, which is commonly used for
- streaming audio or video data.
- </p><p>
- The body of an AMF packet may look something like this
- example. The spaces have been added for clarity.
-
- </p><pre class="screen">
- 02 0007 636f6e6e656374
- </pre><p>
-
- </p><div class="variablelist"><dl><dt><span
class="term">02</span></dt><dd><p>
- This is a single byte header. The value of the first 2
- bits is 0x3, and the AMF index is also 0x3.
- </p></dd><dt><span class="term">0007</span></dt><dd><p>
- This is the length in bytes of the string.
- </p></dd><dt><span class="term">63 6f 6e 6e 65 63
74</span></dt><dd><p>
- This is the string. Note that there is no null terminator
- since the length is specified.
- </p></dd></dl></div><p>
-
- </p></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="nsapi"></a>Chapter 8.
Mozilla/Firefox NPAPI Plugin</h2></div></div></div><div class="toc"><p><b>Table
of Contents</b></p><dl><dt><span class="sect1"><a href="#plugincapi">Plugin C
API</a></span></dt><dt><span class="sect1"><a href="#plugincppapi">Plugin C++
API</a></span></dt><dt><span class="sect1"><a href="#glthread">OpenGL and
Threads</a></span></dt><dt><span class="sect1"><a href="#eventhandle">Plugin
Event Handling</a></span></dt></dl></div><p>
- The Mozilla SDK has two API layers for plugins. The older layer is
- documented in the <a class="ulink"
href="http://www.gnu.org/software/gnash/manual/plugin.pdf"; target="_top">
- Geeko Plugin API Reference</a>, and the newer layer doesn't
- appear to be documented. The new API is simpler, and is portable
- across multiple versions of Mozilla or Firefox. The new API is
- just a layer on top of the older one, so this manual still
- applies.
- </p><p>
- Most of the programming of a plugin is filling in real emphasis for
- the standard API functions and methods. Firefox uses these to
- create the plugin, and to send it data.
- </p><p>
- When initializing or destroying a plugin, no matter how many
- instances are being used, the C API is used. These functions are
- typically called once for each plugin that is loaded.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="plugincapi"></a>Plugin C
API</h2></div></div></div><p>
- The lower layer is a C based API which is used by Firefox to
- initialize and destroy a plugin. This is so a plugin can be
- portable across multiple systems, since C++ emphasis is not portable
- between most C++ compilers. This is where most of the behind the
- scenes work is done in a plugin. For Gnash, the sources this
- lower layer are in <span
class="emphasis"><em>plugin/mozilla-sdk</em></span>. They were
- added to the Gnash source tree so it wouldn't be necessary to
- have the Mozilla development packages installed to compile the
- Gnash plugin.
- </p><p>
- This is also the older API used for plugins, so is usually the
- one used if you dig around for plugin examples on the web. These
- are the main functions which have to be implemented in a plugin
- for it to be recognized by the browser, and to be initialized
- and destroyed.
- </p><div class="variablelist"><dl><dt><span
class="term">NS_PluginInitialize</span></dt><dd><p>
- This C function gets called once when the plugin is
- loaded, regardless of how many instantiations there are
- actually playing movies. So this is where all the one
- time only initialization stuff goes that is shared by all
- the threads.
- </p></dd><dt><span
class="term">NS_NewPluginInstance</span></dt><dd><p>
- This instantiates a new object for the browser. Returning
- a pointer to the C++ plugin object is what ties the C++
- and C emphasis parts of the API together.
- </p></dd><dt><span
class="term">NS_DestroyPluginInstance</span></dt><dd><p>
- This destroys our instantiated object when the browser is
- done.
- </p></dd><dt><span class="term">NS_PluginShutdown</span></dt><dd><p>
- This is called when a plugin is shut down, so this is
- where all the one time only shutdown stuff goes.
- </p></dd><dt><span
class="term">NPP_GetMIMEDescription</span></dt><dd><p>
- This is called to get the MIME types the plugin supports.
- </p></dd><dt><span class="term">NS_PluginGetValue</span></dt><dd><p>
- This is used by Firefox to query information from the
- plugin, like the supported MIME type, the version number,
- and a description.
- </p></dd></dl></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="plugincppapi"></a>Plugin C++ API</h2></div></div></div><p>
- The higher level layer is the one we are most concerned
- with. This is an instantiation of the
- <span class="emphasis"><em>nsPluginInstanceBase</em></span> class, as
defined by the
- Mozilla SDK, for our plugin. With this API, a plugin is mostly
- defining the standard entry points for Firefox, and the emphasis
- that implements the glue between the Firefox and our plugin.
- </p><p>
- These are called for each instantiation of plugin. If there are
- three Flash movies on a web page, then three instances are
- created. Unfortunately for plugin programmers, these functions
- may randomly be called more than once, so it's good to use
- initialization flags for things that should only be done one per
- thread. For instance, <span
class="emphasis"><em>nsPluginInstance::init()</em></span> and
- <span class="emphasis"><em>nsPluginInstance::SetWindow()</em></span> are
called more than
- once, so the plugin must protect against actions that could be
- destructive.
- </p><div class="variablelist"><dl><dt><span
class="term">nsPluginInstance::nsPluginInstance</span></dt><dd><p>
- Create a new plugin object.
- </p></dd><dt><span
class="term">nsPluginInstance::init</span></dt><dd><p>
- This methods initializes the plugin object, and is
- called for every movie which gets played. This is where
- the thread-specific information goes.
- </p></dd><dt><span
class="term">nsPluginInstance::SetWindow</span></dt><dd><p>
- This sets up the window the plugin is supposed to render
- into. This calls passes in various information used by
- the plugin to setup the window. This may get called
- multiple times by each instantiated object, so it can't
- do much but window specific setup here. This is where the
- main emphasis is that sets up the window for the plugin.
- </p></dd><dt><span
class="term">nsPluginInstance::NewStream</span></dt><dd><p>
- Opens a new incoming data stream, which is the flash
- movie we want to play. A URL can be pretty ugly, like in
- this example:
-
http://www.sickwave.com/swf/navbar/navbar_sw.swf?atfilms=http%3a//www.atm.com/af/home/&shickwave=http%3a//www.sickwave.com&gblst=http%3a//gbst.sickwave.com/gb/gbHome.jsp&known=0
../flash/gui.swf?ip_addr=foobar.com&ip_port=3660&show_cursor=true&path_prefix=../flash/&trapallkeys=true"
- So this is where we parse the URL to get all the options
- passed in when invoking the plugin.
- </p></dd><dt><span
class="term">nsPluginInstance::Write</span></dt><dd><p>
- Read the data stream from Mozilla/Firefox. For now we
- read the bytes and write them to a disk file.
- </p></dd><dt><span
class="term">nsPluginInstance::WriteReady</span></dt><dd><p>
- Return how many bytes we can read into the buffer.
- </p></dd><dt><span
class="term">nsPluginInstance::DestroyStream</span></dt><dd><p>
- Destroy the data stream we've been reading. For Gnash,
- when the stream is destroyed means we've grabbed the
- entire movie. So we signal the thread to start reading and
- playing the movie.
- </p></dd><dt><span
class="term">nsPluginInstance::shut</span></dt><dd><p>
- This is where the movie playing specific shutdown emphasis goes.
- </p></dd><dt><span
class="term">nsPluginInstance::~nsPluginInstance</span></dt><dd><p>
- This destroys our plugin object.
- </p></dd><dt><span
class="term">NS_PluginInitialize::initGL</span></dt><dd><p>
- This is a Gnash internal function that sets up OpenGL.
- </p></dd><dt><span
class="term">NS_PluginInitialize::destroyContext</span></dt><dd><p>
- This is a Gnash internal function that destroys a GLX
- context.
- </p></dd><dt><span
class="term">nsPluginInstance::getVersion</span></dt><dd><p>
- This returns the version of Mozilla this plugin supports.
- </p></dd><dt><span
class="term">nsPluginInstance::GetValue</span></dt><dd><p>
- This returns information to the browser about the plugin's
- name and description.
- </p></dd><dt><span
class="term">nsPluginInstance::URLNotify</span></dt><dd><p>
- </p></dd></dl></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="glthread"></a>OpenGL and Threads</h2></div></div></div><p>
- Neither OpenGL nor X11 has any built-in support for threads. Most
- actions aren't even atomic, so care has to be made to not corrupt
- any internal data. While it is difficult to render OpenGL from
- multiple threads, it can be done with the proper locking. The
- downside is the locking adds a performance hit, since all the
- threads will have to have the access synchronized by using
- mutexes.
- </p><p>
- The X11 context is maintained one per instantiation of the
- plugin. It is necessary to lock access to the X11 context when
- using threads by using <span
class="emphasis"><em>XLockDisplay()</em></span> and
- <span class="emphasis"><em>XUnlockDisplay()</em></span>. A connection to
the X11
- server is opened for every instantiation of the plugin using
- <span class="emphasis"><em>XOpenDisplay()</em></span>.
- </p><p>
- The <span class="emphasis"><em>GLX Context</em></span> is maintained one
per
- instantiation of the plugin for a web page. If there are more
- than one Flash movie, there is more than one GLX Context. A GLX
- context can be created by using <span
class="emphasis"><em>glXCreateContext()</em></span>,
- and then later destroyed by using <span
class="emphasis"><em>glXDestroyContext()</em></span>.
- When swapping threads, the context is changed using
- <span class="emphasis"><em>glXMakeCurrent()</em></span>.
- </p><p>
- All the emphasis that directly accesses a GLX context or the X11
- display must be wrapped with a mutex.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="eventhandle"></a>Plugin Event Handling</h2></div></div></div><p>
- Firefox on most UNIX systems is a GTK+ application, so it is
- possible to have the plugin hook into the X11 event handling via
- GLX or GTK. Since Firefox uses GTK, so does Gnash. This also
- allows the addition of a right-click mouse menu for controlling
- the player. The GTK build of Gnash offers the best browsing
- experience as it's more functional than the SDL version.
- </p><p>
- It is also possible to disable the <span
class="emphasis"><em>GTK</em></span> support so
- only the older <span class="emphasis"><em>SDL</em></span> support is
used. In this case
- Gnash can't support event handling within the browser. This
- means that when using the SDL of the plugin, mouse clicks and
- keys pressed get ignored. Windows also can't be resized, and
- sometimes they overrun their boundaries as well. To disable the
- GTK support and force SDL to be used anyway, configure with
- <span class="emphasis"><em>--disable-glext</em></span>
- </p><p>
-
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="appendix"></a>Appendix</h2></div></div></div><div class="sect2"
lang="en"><div class="titlepage"><div><div><h3 class="title"><a
name="codestyle"></a>Code Style</h3></div></div></div><p>
- I know any discussion of coding styles leads to strong opinions,
- so I'll state simply I follow the <a class="ulink"
href="http://www.gnu.org/prep/standards/standards.html"; target="_top">GNU
- Coding Standards</a>. Where there is some flexibility as to
- the location of braces, I prefer mine on the end of a line when
- using an <span class="emphasis"><em>if</em></span>, <span
class="emphasis"><em>while</em></span>, or <span
class="emphasis"><em>do</em></span>
- statement. I find this more compact style easier to read and
- parse by eye. I'm also a big fan of always using
- braces around <span class="emphasis"><em>if</em></span> statements, even
if they're one
- liners.
- </p><p>
- Here's my tweaked style settings for <span
class="emphasis"><em>Emacs</em></span>, the one
- true editor to rule them all.
-
- </p><pre class="programlisting">
- (defconst my-style
- '((c-tab-always-indent . t)
- (c-auto-newline . t)
- (c-hanging-braces-alist . (
- (brace-list-intro)
- (namespace-open)
- (inline-open)
- (block-open)
- (brace-list-open)
- (brace-list-close)
- (brace-entry-open)
- (brace-else-brace)
- (brace-elseif-brace)
- (class-open after)
- (class-close)
- (defun-open after)
- (defun-close)
- (extern-lang-open)
- (inexpr-class-open)
- (statement-open)
- (substatement-open)
- (inexpr-class-close)))
- (c-hanging-colons-alist . ((member-init-intro before)
- (inher-intro)
- (case-label after)
- (label after)
- (access-label after)))
- (c-offsets-alist . (
- (innamespace . 0)
- (case-label . 2)
- ))
- (c-cleanup-list . (
- (scope-operator)
- (empty-defun-braces)
- (brace-else-brace)
- (brace-elseif-brace)
- (defun-close-semi)
- (list-close-comma)
- )
- )
- ;; no automatic newlines after ';' if following line non-blank or inside
- ;; one-line inline methods
- (add-to-list 'c-hanging-semi&comma-criteria
- 'c-semi&comma-no-newlines-before-nonblanks)
- (add-to-list 'c-hanging-semi&comma-criteria
- 'c-semi&comma-no-newlines-for-oneline-inliners)
-; (knr-argdecl-intro . -)
- (c-echo-syntactic-information-p . t)
- )
- "My GNU Programming Style")
- </pre><p>
-
- </p><p>
- Another coding consideration: comments are good! Over
- commenting isn't good. Here is an over commented example:
-
- </p><pre class="programlisting">
- counter++; // increment counter
- </pre><p>
-
- Gnash also uses <a class="ulink" href="http://www.doxygen.org";
target="_top">Doxygen</a> style
- comments. These are processed by Doxygen when building a cross
- reference of all the classes, and is a good way to help push
- internals documentation from the depths of the code into
- documentation where it can be seen by others.
- </p><p>
- <span class="emphasis"><em>Doxygen</em></span> style comments for <span
class="emphasis"><em>C++</em></span> code involves
- simply using three slashes <span class="emphasis"><em>///</em></span>
instead of the
- standard two slashes <span class="emphasis"><em>//</em></span> used for
C++
- comments. Here's a short comment block for the
- <span class="emphasis"><em>XML::cloneNode()</em></span> method:
-
- </p><pre class="programlisting">
- /// \brief copy a node
- ///
- /// Method; constructs and returns a new XML node of the same type,
- /// name, value, and attributes as the specified XML object. If deep
- /// is set to true, all child nodes are recursively cloned, resulting
- /// in an exact copy of the original object's document tree.
- XMLNode &
- XML::cloneNode(XMLNode &newnode, bool deep) {
- ...
- }
- </pre><p>
- </p><p>
- The <span class="emphasis"><em>\brief</em></span> keyword means that the
- text becomes associated
- when listing all the classes on the generated web pages. The
- text after the blank link becomes the detailed description which
- appears on the generated web page for that class and method.
- </p></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="authors"></a>Chapter 9.
Authors</h2></div></div></div><p>
- <span class="application">Gnash</span> is maintained by Rob Savoye.
Other active developers
- are: Sandro Santilli, Bastiaan Jacques, Udo Giacomozzi, Chad
- Musick, Benjamin Wolsey, and Zou Lunkai. Please send all
- comments and suggestions to <code class="email"><<a class="email"
href="mailto:address@hidden";>address@hidden
- </a>></code>. Past and sometimes current developers are Tomas
- Groth and Markus Gothe.
- </p><p>
- <span class="application">Gnash</span> was initially derived from
<span class="application">GameSWF</span>.
- <span class="application">GameSWF</span> is maintained by
- Thatcher Ulrich <code class="email"><<a class="email"
href="mailto:address@hidden";>address@hidden</a>></code>. The following
- people contributed to <span class="application">GameSWF</span>:
- Mike Shaver, Thierry Berger-Perrin,
- Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit,
- and Rob Savoye.
- </p></div><div class="appendix" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="fdl"></a>Appendix A. GNU
Free Documentation License</h2></div><div><p class="releaseinfo">
- Version 1.1, March 2000
- </p></div><div><p class="copyright">Copyright © 2000 Free Software
Foundation, Inc.</p></div><div><div class="legalnotice"><a
name="fdl-legalnotice"></a><p>
- </p><div class="address"><p>Free Software Foundation, Inc. <span
class="street">59 Temple Place, <br>
- Suite 330</span>, <span class="city">Boston</span>, <span
class="state">MA</span> <br>
- <span class="postcode">02111-1307</span> <span
class="country">USA</span></p></div><p>
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- </p></div></div></div></div><div class="toc"><p><b>Table of
Contents</b></p><dl><dt><span class="sect1"><a href="#fdl-preamble">0.
PREAMBLE</a></span></dt><dt><span class="sect1"><a href="#fdl-section1">1.
APPLICABILITY AND DEFINITIONS</a></span></dt><dt><span class="sect1"><a
href="#fdl-section2">2. VERBATIM COPYING</a></span></dt><dt><span
class="sect1"><a href="#fdl-section3">3. COPYING IN
QUANTITY</a></span></dt><dt><span class="sect1"><a href="#fdl-section4">4.
MODIFICATIONS</a></span></dt><dt><span class="sect1"><a href="#fdl-section5">5.
COMBINING DOCUMENTS</a></span></dt><dt><span class="sect1"><a
href="#fdl-section6">6. COLLECTIONS OF DOCUMENTS</a></span></dt><dt><span
class="sect1"><a href="#fdl-section7">7. AGGREGATION WITH INDEPENDENT
WORKS</a></span></dt><dt><span class="sect1"><a href="#fdl-section8">8.
TRANSLATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section9">9.
TERMINATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section10">10.
FUTURE REVISIONS OF THIS LICENSE</a></span></dt><dt><span class="sect1"><a
href="#fdl-using">Addendum</a></span></dt></dl></div><div class="sect1"
lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear:
both"><a name="fdl-preamble"></a>0. PREAMBLE</h2></div></div></div><p>
- The purpose of this License is to make a manual, textbook, or
- other written document "free" in the sense of
- freedom: to assure everyone the effective freedom to copy and
- redistribute it, with or without modifying it, either
- commercially or non-commercially. Secondarily, this License
- preserves for the author and publisher a way to get credit for
- their work, while not being considered responsible for
- modifications made by others.
- </p><p>
- This License is a kind of "copyleft", which means
- that derivative works of the document must themselves be free in
- the same sense. It complements the GNU General Public License,
- which is a copyleft license designed for free software.
- </p><p>
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same
- freedoms that the software does. But this License is not limited
- to software manuals; it can be used for any textual work,
- regardless of subject matter or whether it is published as a
- printed book. We recommend this License principally for works
- whose purpose is instruction or reference.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section1"></a>1. APPLICABILITY AND
DEFINITIONS</h2></div></div></div><p><a name="fdl-document"></a>
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be
- distributed under the terms of this License. The
- "Document", below, refers to any such manual or
- work. Any member of the public is a licensee, and is addressed
- as "you".
- </p><p><a name="fdl-modified"></a>
- A "Modified Version" of the Document means any work
- containing the Document or a portion of it, either copied
- verbatim, or with modifications and/or translated into another
- language.
- </p><p><a name="fdl-secondary"></a>
- A "Secondary Section" is a named appendix or a
- front-matter section of the <a class="link"
href="#fdl-document">Document</a> that deals exclusively
- with the relationship of the publishers or authors of the
- Document to the Document's overall subject (or to related
- matters) and contains nothing that could fall directly within
- that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of
- legal, commercial, philosophical, ethical or political position
- regarding them.
- </p><p><a name="fdl-invariant"></a>
- The "Invariant Sections" are certain <a class="link"
href="#fdl-secondary"> Secondary Sections</a> whose titles
- are designated, as being those of Invariant Sections, in the
- notice that says that the <a class="link"
href="#fdl-document">Document</a> is released under this
- License.
- </p><p><a name="fdl-cover-texts"></a>
- The "Cover Texts" are certain short passages of
- text that are listed, as Front-Cover Texts or Back-Cover Texts,
- in the notice that says that the <a class="link"
href="#fdl-document">Document</a> is released under this
- License.
- </p><p><a name="fdl-transparent"></a>
- A "Transparent" copy of the <a class="link" href="#fdl-document">
Document</a> means a machine-readable
- copy, represented in a format whose specification is available
- to the general public, whose contents can be viewed and edited
- directly and straightforwardly with generic text editors or (for
- images composed of pixels) generic paint programs or (for
- drawings) some widely available drawing editor, and that is
- suitable for input to text formatters or for automatic
- translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format
- whose markup has been designed to thwart or discourage
- subsequent modification by readers is not Transparent. A copy
- that is not "Transparent" is called "Opaque".
- </p><p>
- Examples of suitable formats for Transparent copies include
- plain ASCII without markup, Texinfo input format, LaTeX input
- format, SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human
- modification. Opaque formats include PostScript, PDF,
- proprietary formats that can be read and edited only by
- proprietary word processors, SGML or XML for which the DTD
- and/or processing tools are not generally available, and the
- machine-generated HTML produced by some word processors for
- output purposes only.
- </p><p><a name="fdl-title-page"></a>
- The "Title Page" means, for a printed book, the
- title page itself, plus such following pages as are needed to
- hold, legibly, the material this License requires to appear in
- the title page. For works in formats which do not have any title
- page as such, "Title Page" means the text near the
- most prominent appearance of the work's title, preceding the
- beginning of the body of the text.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section2"></a>2. VERBATIM COPYING</h2></div></div></div><p>
- You may copy and distribute the <a class="link"
href="#fdl-document">Document</a> in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that
- you add no other conditions whatsoever to those of this
- License. You may not use technical measures to obstruct or
- control the reading or further copying of the copies you make or
- distribute. However, you may accept compensation in exchange for
- copies. If you distribute a large enough number of copies you
- must also follow the conditions in <a class="link" href="#fdl-section3"
title="3. COPYING IN QUANTITY">section 3</a>.
- </p><p>
- You may also lend copies, under the same conditions stated
- above, and you may publicly display copies.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section3"></a>3. COPYING IN QUANTITY</h2></div></div></div><p>
- If you publish printed copies of the <a class="link"
href="#fdl-document">Document</a> numbering more than 100,
- and the Document's license notice requires <a class="link"
href="#fdl-cover-texts">Cover Texts</a>, you must enclose
- the copies in covers that carry, clearly and legibly, all these
- Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also
- clearly and legibly identify you as the publisher of these
- copies. The front cover must present the full title with all
- words of the title equally prominent and visible. You may add
- other material on the covers in addition. Copying with changes
- limited to the covers, as long as they preserve the title of the
- <a class="link" href="#fdl-document">Document</a> and satisfy these
- conditions, can be treated as verbatim copying in other
- respects.
- </p><p>
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
- </p><p>
- If you publish or distribute <a class="link"
href="#fdl-transparent">Opaque</a> copies of the <a class="link"
href="#fdl-document">Document</a> numbering more than 100,
- you must either include a machine-readable <a class="link"
href="#fdl-transparent">Transparent</a> copy along with
- each Opaque copy, or state in or with each Opaque copy a
- publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added
- material, which the general network-using public has access to
- download anonymously at no charge using public-standard network
- protocols. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will
- remain thus accessible at the stated location until at least one
- year after the last time you distribute an Opaque copy (directly
- or through your agents or retailers) of that edition to the
- public.
- </p><p>
- It is requested, but not required, that you contact the authors
- of the <a class="link" href="#fdl-document">Document</a> well before
- redistributing any large number of copies, to give them a chance
- to provide you with an updated version of the Document.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section4"></a>4. MODIFICATIONS</h2></div></div></div><p>
- You may copy and distribute a <a class="link"
href="#fdl-modified">Modified Version</a> of the <a class="link"
href="#fdl-document">Document</a> under the conditions of
- sections <a class="link" href="#fdl-section2" title="2. VERBATIM
COPYING">2</a> and <a class="link" href="#fdl-section3" title="3. COPYING IN
QUANTITY">3</a> above, provided that you release
- the Modified Version under precisely this License, with the
- Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version
- to whoever possesses a copy of it. In addition, you must do
- these things in the Modified Version:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><b>A. </b>
- Use in the <a class="link" href="#fdl-title-page">Title
- Page</a> (and on the covers, if any) a title distinct
- from that of the <a class="link" href="#fdl-document">Document</a>,
and from those of
- previous versions (which should, if there were any, be
- listed in the History section of the Document). You may
- use the same title as a previous version if the original
- publisher of that version gives permission.
- </p></li><li style="list-style-type: circle"><p><b>B. </b>
- List on the <a class="link" href="#fdl-title-page">Title
- Page</a>, as authors, one or more persons or entities
- responsible for authorship of the modifications in the
- <a class="link" href="#fdl-modified">Modified Version</a>,
- together with at least five of the principal authors of
- the <a class="link" href="#fdl-document">Document</a> (all of
- its principal authors, if it has less than five).
- </p></li><li style="list-style-type: circle"><p><b>C. </b>
- State on the <a class="link" href="#fdl-title-page">Title
- Page</a> the name of the publisher of the <a class="link"
href="#fdl-modified">Modified Version</a>, as the
- publisher.
- </p></li><li style="list-style-type: circle"><p><b>D. </b>
- Preserve all the copyright notices of the <a class="link"
href="#fdl-document">Document</a>.
- </p></li><li style="list-style-type: circle"><p><b>E. </b>
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- </p></li><li style="list-style-type: circle"><p><b>F. </b>
- Include, immediately after the copyright notices, a
- license notice giving the public permission to use the
- <a class="link" href="#fdl-modified">Modified Version</a> under
- the terms of this License, in the form shown in the
- Addendum below.
- </p></li><li style="list-style-type: circle"><p><b>G. </b>
- Preserve in that license notice the full lists of <a class="link"
href="#fdl-invariant"> Invariant Sections</a> and
- required <a class="link" href="#fdl-cover-texts">Cover
- Texts</a> given in the <a class="link"
href="#fdl-document">Document's</a> license notice.
- </p></li><li style="list-style-type: circle"><p><b>H. </b>
- Include an unaltered copy of this License.
- </p></li><li style="list-style-type: circle"><p><b>I. </b>
- Preserve the section entitled "History", and
- its title, and add to it an item stating at least the
- title, year, new authors, and publisher of the <a class="link"
href="#fdl-modified">Modified Version </a>as given on
- the <a class="link" href="#fdl-title-page">Title Page</a>. If
- there is no section entitled "History" in the
- <a class="link" href="#fdl-document">Document</a>, create one
- stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- </p></li><li style="list-style-type: circle"><p><b>J. </b>
- Preserve the network location, if any, given in the <a class="link"
href="#fdl-document">Document</a> for public access
- to a <a class="link" href="#fdl-transparent">Transparent</a>
- copy of the Document, and likewise the network locations
- given in the Document for previous versions it was based
- on. These may be placed in the "History"
- section. You may omit a network location for a work that
- was published at least four years before the Document
- itself, or if the original publisher of the version it
- refers to gives permission.
- </p></li><li style="list-style-type: circle"><p><b>K. </b>
- In any section entitled "Acknowledgements" or
- "Dedications", preserve the section's title,
- and preserve in the section all the substance and tone of
- each of the contributor acknowledgements and/or
- dedications given therein.
- </p></li><li style="list-style-type: circle"><p><b>L. </b>
- Preserve all the <a class="link" href="#fdl-invariant">Invariant
- Sections</a> of the <a class="link"
href="#fdl-document">Document</a>, unaltered in their
- text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
- </p></li><li style="list-style-type: circle"><p><b>M. </b>
- Delete any section entitled
- "Endorsements". Such a section may not be
- included in the <a class="link" href="#fdl-modified">Modified
- Version</a>.
- </p></li><li style="list-style-type: circle"><p><b>N. </b>
- Do not retitle any existing section as
- "Endorsements" or to conflict in title with
- any <a class="link" href="#fdl-invariant">Invariant
- Section</a>.
- </p></li></ul></div><p>
- If the <a class="link" href="#fdl-modified">Modified Version</a>
- includes new front-matter sections or appendices that qualify as
- <a class="link" href="#fdl-secondary">Secondary Sections</a> and
- contain no material copied from the Document, you may at your
- option designate some or all of these sections as invariant. To
- do this, add their titles to the list of <a class="link"
href="#fdl-invariant">Invariant Sections</a> in the
- Modified Version's license notice. These titles must be
- distinct from any other section titles.
- </p><p>
- You may add a section entitled "Endorsements",
- provided it contains nothing but endorsements of your <a class="link"
href="#fdl-modified">Modified Version</a> by various
- parties--for example, statements of peer review or that the text
- has been approved by an organization as the authoritative
- definition of a standard.
- </p><p>
- You may add a passage of up to five words as a <a class="link"
href="#fdl-cover-texts">Front-Cover Text</a>, and a passage
- of up to 25 words as a <a class="link"
href="#fdl-cover-texts">Back-Cover Text</a>, to the end of
- the list of <a class="link" href="#fdl-cover-texts">Cover Texts</a>
- in the <a class="link" href="#fdl-modified">Modified Version</a>.
- Only one passage of Front-Cover Text and one of Back-Cover Text
- may be added by (or through arrangements made by) any one
- entity. If the <a class="link" href="#fdl-document">Document</a>
- already includes a cover text for the same cover, previously
- added by you or by arrangement made by the same entity you are
- acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
- </p><p>
- The author(s) and publisher(s) of the <a class="link"
href="#fdl-document">Document</a> do not by this License
- give permission to use their names for publicity for or to
- assert or imply endorsement of any <a class="link"
href="#fdl-modified">Modified Version </a>.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section5"></a>5. COMBINING DOCUMENTS</h2></div></div></div><p>
- You may combine the <a class="link" href="#fdl-document">Document</a>
- with other documents released under this License, under the
- terms defined in <a class="link" href="#fdl-section4" title="4.
MODIFICATIONS">section 4</a>
- above for modified versions, provided that you include in the
- combination all of the <a class="link" href="#fdl-invariant">Invariant
- Sections</a> of all of the original documents, unmodified,
- and list them all as Invariant Sections of your combined work in
- its license notice.
- </p><p>
- The combined work need only contain one copy of this License,
- and multiple identical <a class="link" href="#fdl-invariant">Invariant
- Sections</a> may be replaced with a single copy. If there are
- multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding
- at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique
- number. Make the same adjustment to the section titles in the
- list of Invariant Sections in the license notice of the combined
- work.
- </p><p>
- In the combination, you must combine any sections entitled
- "History" in the various original documents,
- forming one section entitled "History"; likewise
- combine any sections entitled "Acknowledgements",
- and any sections entitled "Dedications". You must
- delete all sections entitled "Endorsements."
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section6"></a>6. COLLECTIONS OF DOCUMENTS</h2></div></div></div><p>
- You may make a collection consisting of the <a class="link"
href="#fdl-document">Document</a> and other documents
- released under this License, and replace the individual copies
- of this License in the various documents with a single copy that
- is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
- </p><p>
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you
- insert a copy of this License into the extracted document, and
- follow this License in all other respects regarding verbatim
- copying of that document.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section7"></a>7. AGGREGATION WITH INDEPENDENT
WORKS</h2></div></div></div><p>
- A compilation of the <a class="link" href="#fdl-document">Document</a>
or its derivatives with
- other separate and independent documents or works, in or on a
- volume of a storage or distribution medium, does not as a whole
- count as a <a class="link" href="#fdl-modified">Modified Version</a>
- of the Document, provided no compilation copyright is claimed
- for the compilation. Such a compilation is called an
- "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document , on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document. If the <a class="link"
href="#fdl-cover-texts">Cover Text</a> requirement of <a class="link"
href="#fdl-section3" title="3. COPYING IN QUANTITY">section 3</a> is applicable
to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may
- be placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section8"></a>8. TRANSLATION</h2></div></div></div><p>
- Translation is considered a kind of modification, so you may
- distribute translations of the <a class="link"
href="#fdl-document">Document</a> under the terms of <a class="link"
href="#fdl-section4" title="4. MODIFICATIONS">section 4</a>. Replacing <a
class="link" href="#fdl-invariant"> Invariant Sections</a> with
- translations requires special permission from their copyright
- holders, but you may include translations of some or all
- Invariant Sections in addition to the original versions of these
- Invariant Sections. You may include a translation of this
- License provided that you also include the original English
- version of this License. In case of a disagreement between the
- translation and the original English version of this License,
- the original English version will prevail.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section9"></a>9. TERMINATION</h2></div></div></div><p>
- You may not copy, modify, sublicense, or distribute the <a class="link"
href="#fdl-document">Document</a> except as expressly
- provided for under this License. Any other attempt to copy,
- modify, sublicense or distribute the Document is void, and will
- automatically terminate your rights under this License. However,
- parties who have received copies, or rights, from you under this
- License will not have their licenses terminated so long as such
- parties remain in full compliance.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section10"></a>10. FUTURE REVISIONS OF THIS
LICENSE</h2></div></div></div><p>
- The <a class="ulink" href="http://www.gnu.org/fsf/fsf.html";
target="_top">Free Software
- Foundation</a> may publish new, revised versions of the GNU
- Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ
- in detail to address new problems or concerns. See <a class="ulink"
href="http://www.gnu.org/copyleft";
target="_top">http://www.gnu.org/copyleft/</a>.
- </p><p>
- Each version of the License is given a distinguishing version
- number. If the <a class="link" href="#fdl-document">Document</a>
- specifies that a particular numbered version of this License
- "or any later version" applies to it, you have the
- option of following the terms and conditions either of that
- specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by
- the Free Software Foundation.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-using"></a>Addendum</h2></div></div></div><p>
- To use this License in a document you have written, include a copy of
- the License in the document and put the following copyright and
- license notices just after the title page:
- </p><div class="blockquote"><blockquote class="blockquote"><p>
- Copyright 2008, Free Software Foundation.
- </p><p>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License, Version 1.1 or any later version published by the
- Free Software Foundation; with no<a class="link"
href="#fdl-invariant">Invariant Sections</a>, with no <a class="link"
href="#fdl-cover-texts">Front-Cover Texts</a>,
- and with no <a class="link" href="#fdl-cover-texts">Back-Cover
- Texts</a>. A copy of the license is included in
- the section entitled "GNU Free Documentation License".
- </p></blockquote></div><p>
- If your document contains nontrivial examples of program code,
- we recommend releasing these examples in parallel under your
- choice of free software license, such as the <a class="ulink"
href="http://www.gnu.org/copyleft/gpl.html"; target="_top"> GNU General Public
- License</a>, to permit their use in free software.
- </p></div></div></div></body></html>
Index: doc/C/preformatted/gnash_user.html.in
===================================================================
RCS file: doc/C/preformatted/gnash_user.html.in
diff -N doc/C/preformatted/gnash_user.html.in
--- doc/C/preformatted/gnash_user.html.in 3 Mar 2008 23:46:43 -0000
1.1.2.1
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,1316 +0,0 @@
-<html><head><meta http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"><title>Gnash User Manual</title><meta name="generator"
content="DocBook XSL Stylesheets V1.73.2"></head><body bgcolor="white"
text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"
lang="en"><div class="titlepage"><div><div><h1 class="title"><a
name="index"></a>Gnash User Manual</h1></div><div><p class="releaseinfo">
- This manual describes version 0.8.2 of Gnash.
- </p></div><div><p class="copyright">Copyright © 2005, 2006, 2007, 2008
Free Software Foundation</p></div><div><div class="legalnotice"><a
name="legalnotice"></a><p>
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the <a class="link" href="#fdl" title="Appendix A. GNU
Free Documentation License"><em class="citetitle">GNU
- Free Documentation License</em></a>, Version 1.1 or any later
- version published by the Free Software Foundation with no Invariant
- Sections, no Front-Cover Texts, and no Back-Cover Texts. You can find
- a copy of the GFDL at this
- <a class="link" href="#fdl" title="Appendix A. GNU Free Documentation
License">link</a> or in the file COPYING-DOCS
- distributed with this manual.
- </p></div></div><div><div class="revhistory"><table border="1" width="100%"
summary="Revision history"><tr><th align="left" valign="top"
colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision
Gnash User Manual version 0.1</td><td align="left">Feb 2008</td></tr><tr><td
align="left" colspan="2">
- <p class="author">Rob Savoye
- <code class="email"><<a class="email"
href="mailto:address@hidden";>address@hidden</a>></code>
- The end user parts of the manual have been pulled out of
- the original version of the manual and rewritten.
- </p>
-
- <p class="publisher">Open Media Now! Foundation</p>
- </td></tr></table></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="#usage">2. Using <span
class="application">Gnash</span></a></span></dt><dd><dl><dt><span
class="sect1"><a href="#options"><span class="application">Gnash</span> Command
Line Options</a></span></dt><dt><span class="sect1"><a href="#keys"><span
class="application">Gnash</span> Interactive Control
Keys</a></span></dt><dt><span class="sect1"><a href="#gnashrc">User
Configuration File</a></span></dt></dl></dd><dt><span class="chapter"><a
href="#build">3. Installing and Configuring
Gnash</a></span></dt><dd><dl><dt><span class="sect1"><a
href="#requirements">Requirements</a></span></dt><dd><dl><dt><span
class="sect2"><a href="#hardware">Hardware
Requirements</a></span></dt><dt><span class="sect2"><a
href="#software">Software Requirements</a></span></dt></dl></dd><dt><span
class="sect1"><a href="#downloading">Downloading
Gnash</a></span></dt><dd><dl><dt><span class="sect2"><a
href="#gettingsource">Getting the Source</a></span></dt><dt><span
class="sect2"><a href="#getcodecs">Getting Codec
Support</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a
href="#bugreport">4. 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="glossary"><a href="#glossary">Glossary</a></span></dt><dt><span
class="chapter"><a href="#authors">5. 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="#tb-command-line-options">Gnash Command Line Options</a></dt><dt>2.2. <a
href="#tb-control-keys">Gnash Interactive Control Keys</a></dt><dt>2.3. <a
href="#tb-config-variables">User Configuration Variables</a></dt><dt>3.1. <a
href="#tb-os-cpu">Build Matrix</a></dt></dl></div><div class="chapter"
lang="en"><div class="titlepage"><div><div><h2 class="title"><a
name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a
href="#audience">Audience</a></span></dt><dt><span class="sect1"><a
href="#runs-on">What Is Supported?</a></span></dt></dl></div><p>
- <span class="application">Gnash</span> is a free SWF movie player. It is
available as a
- stand-alone application or as a plugin for several popular
- web browsers. It supports playing media from a disk or streaming
- over a network connection. Some popular video sharing sites like
- YouTube are supported on a wide variety of devices from
- embedded ones to modern desktops.
- </p><p>
- <span class="application">Gnash</span> has a better focus on security,
allowing the user tight
- control of all network or disk based I/O. Gnash also supports
- extending ActionScript by creating your own classes. You can write
- wrappers for any development library, and import them into the
- player much like Perl or Python does.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a
name="audience"></a>Audience</h2></div></div></div><p>
- This manual is primarily focused on users interested in how to
- get Gnash installed from a package, and basic usage as a web
- browser plugin. For more technical details, please refer to the
- Gnash Reference manual.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="runs-on"></a>What Is Supported?</h2></div></div></div><p>
- Gnash is known to compile for most any POSIX and ANSI C++
- conforming system if you have all the dependent libraries
- installed. Systems we test on, and which Gnash is known to
- run on are Ubuntu, Fedora, Debian, Mandriva, OpenBSD, NetBSD, FreeBSD,
- Win32, and Darwin (OSX) primarily. Occasionally other platforms
- are built, primarily by those distribution maintainers. This
- includes BeOS, Haiku, Syllable, OS/2, Solaris, Slackware, and
- Gentoo.
- </p><p>
- Gnash is capable of reading up to SWF v9 files and opcodes,
- but primarily supports SWF v7, with better SWF v8 and v9
- support under heavy development. With the 0.8.2 release,
- Gnash includes initial parser support for SWF v8 and v9.
- Not all ActionScript 2 classes are implemented yet, but all of the
- most heavily used ones are. Many ActionScript 2 classes are
- partially implemented; there is support for all of the
- commonly used methods of each class.
- </p><p>
- Gnash has implemented about 80% of ActionScript v2.0, and has
- begun implementing ActionScript v3.0. Gnash supports the
- majority of Flash opcodes up to SWF v9, and a wide
- sampling of ActionScript classes for SWF v8.
- </p><p>
- As ActionScript 3 is a more developed version of
- ActionScript 2, many of the same classes work for
- both. Support has been added to Gnash's ActionScript library
- to support the new ActionScript 3 filters, which get applied
- to every class. Implementing ActionScript clases is often the
- easiest way for new Gnash developers to make a contribution
- without a deep internal knpowledge of Gnash.
- </p><p>
- Gnash has included video support since early 2007, but this is
- an ever changing field of reverse engineering. Many of the
- popular video sharing sites use SWF v8 or v9, which Gnash
- still has imperfect support for. This is improving all the
- time, so often builds from a development snapshot will work
- when using the older release packaged in your distribution
- doesn't. You can find daily snapshots of the latest CVS tree
- at: <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/";
target="_top">
- http://www.gnashdev.org/dev_snapshots</a>.
- </p><p>
- Gnash uses ffmpeg for codecs, so any file supported by Mplayer
- should work with Gnash. Gnash supports the loading of patent
- free codecs like Ogg Vorbis or Theora from disk based files,
- while work is being done to support these codecs when embedded
- in a SWF file. Ffmpeg contains the codecs used by the current
- SWF defintion, FLV, VP6 (ON2), H.263, H.264, and MP3.
- </p></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="usage"></a>Chapter 2.
Using <span class="application">Gnash</span></h2></div></div></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a
href="#options"><span class="application">Gnash</span> Command Line
Options</a></span></dt><dt><span class="sect1"><a href="#keys"><span
class="application">Gnash</span> Interactive Control
Keys</a></span></dt><dt><span class="sect1"><a href="#gnashrc">User
Configuration File</a></span></dt></dl></div><p>
- When used as a standalone player, you can play any Flash file from
- the command line by entering a command of the format:
- </p><pre class="programlisting">
- gnash <em class="replaceable"><code><option>
<flashfile.swf></code></em>
- </pre><p>
- The only required argument is the name (and location)of the file
- to be played.
- </p><p>
- The available options are listed in the following section, or you
- may view them in the terminal window by executing the following at
- the command line:
- </p><pre class="programlisting">
- gnash --help | less
- </pre><p>
- </p><p>
- The source code download of <span class="application">Gnash</span>
includes several example .SWF
- files. They are located in the
- <code class="filename">testsuite/samples/</code> directory of the <span
class="application">Gnash</span>
- source directory. If you have installed <span
class="application">Gnash</span> correctly, issuing
- the a command similar to the following plays a short animation of
- a car swerving and crashing:
- </p><pre class="programlisting">
- gnash
- /home/<em
class="replaceable"><code><username></code></em>/gnash/testsuite/car_smash.swf
- </pre><p>
- </p><div class="mediaobject" align="center"><img
src="images/car_crash.png" align="middle"></div><p>
- </p><p>
- The above is useful for playing Flash files downloaded to your
- local system. It is also possible to play Flash files directly
- from the web. To do so, use the <code class="option">-u</code> option
along
- with the URL of the desired file.
- </p><pre class="programlisting">
- gnash -u http://example.domain.com/flashfile.swf
- </pre><p>
- Note that this will not work with every website; some embedded
- Flash files are difficult to play.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="options"></a><span
class="application">Gnash</span> Command Line Options</h2></div></div></div><p>
- No options are required for <span class="application">Gnash</span>'s
default behavior. However,
- there are many options that can be used to that behavior.
- </p><p>
- </p><pre class="programlisting">
- gnash <em class="replaceable"><code><options></code></em>
- <code class="filename">filename.swf</code>
- </pre><p>
- </p><div class="table"><a name="tb-command-line-options"></a><p
class="title"><b>Table 2.1. Gnash Command Line Options</b></p><div
class="table-contents"><table summary="Gnash Command Line Options"
border="1"><colgroup><col><col></colgroup><thead><tr><th
align="left">Option</th><th
align="left">Function</th></tr></thead><tbody><tr><td align="left"><code
class="option">-h</code></td><td align="left">
- Print usage information.
- </td></tr><tr><td align="left">
- <code class="option">-s factor</code>
- </td><td align="left">
- Scale the movie up/down by the specified factor.
- </td></tr><tr><td align="left">
- <code class="option">-c</code>
- </td><td align="left">
- Produce a core file instead of letting SDL trap it. By
- default, SDL traps all signals, but sometimes a core file
- is desired to assist with debugging.
- </td></tr><tr><td align="left">
- <code class="option">-d num</code>
- </td><td align="left">
- Number of milliseconds to delay in main loop. The main
- loop polls continuously with a delay to adjust how long
- <span class="emphasis"><em><span
class="application">Gnash</span></em></span> sleeps between iterations of the
- loop. The smaller the number, the higher the CPU load
- gets, and of course, the more iterations of the main
- command loop.
- </td></tr><tr><td align="left">
- <code class="option">-v</code>
- </td><td align="left">
- Be verbose; i.e. print important messages to stdout.
- </td></tr><tr><td align="left">
- <code class="option">-vv</code>
- </td><td align="left">
- Be very verbose; i.e. also print debug messages to stdout.
- </td></tr><tr><td align="left">
- <code class="option">-va</code>
- </td><td align="left">
- Be verbose about movie actions (for ActionScript debugging). This
- generates very large amounts of text and will affect <span
class="application">Gnash</span>'s performance.
- </td></tr><tr><td align="left">
- <code class="option">-vp</code>
- </td><td align="left">
- Be verbose about parsing the movie. Warning: this can
- generate a lot of text, and can affect the performance of
- the movie you are playing.
- </td></tr><tr><td align="left">
- <code class="option">-ml bias</code>
- </td><td align="left">
- Specify the texture LOD bias (float, default is -1) This
- affects the fuzziness of small objects, especially small
- text.
- </td></tr><tr><td align="left">
- <code class="option">-w</code>
- </td><td align="left">
- Write a debug log called gnash-dbg.log. This will
- record of all the debug messages whether they are printed
- to the screen or not.
- </td></tr><tr><td align="left">
- <code class="option">-j</code>
- </td><td align="left">
- Specify the width of the window. This is mostly used
- only by the plugin.
- </td></tr><tr><td align="left">
- <code class="option">-k</code>
- </td><td align="left">
- Specify the height of the window. This is mostly used
- only by the plugin.
- </td></tr><tr><td align="left">
- <code class="option">-1</code>
- </td><td align="left">
- Play once; exit when/if movie reaches the last
- frame.
- </td></tr><tr><td align="left">
- <code class="option">-r [0|1|2|3]</code>
- </td><td align="left">
- <div class="itemizedlist"><ul type="disc"><li><p>
- 0 disables rendering and sound (good for batch tests).
- </p></li><li><p>
- 1 enables rendering and disables sound (default setting).
- </p></li><li><p>
- 2 enables sound and disables rendering.
- </p></li><li><p>
- 3 enables rendering and sound.
- </p></li></ul></div>
- </td></tr><tr><td align="left">
- <code class="option">-t sec</code>
- </td><td align="left">
- Timeout and exit after the specified number of
- seconds. This is useful for movies which repeat
- themselves.
- </td></tr><tr><td align="left">
- <code class="option">-g</code>
- </td><td align="left">
- Start <span class="application">Gnash</span> with a Flash
debugger console so one can set
- break points or watchpoints.
- </td></tr><tr><td align="left">
- <code class="option">-x id</code>
- </td><td align="left">
- This specifies the X11 window ID to display
- in; this is mainly used by plugins.
- </td></tr><tr><td align="left">
- <code class="option">-u url</code>
- </td><td align="left">
- Set the _url member of the root movie. This is useful
- when you download a movie and play it from a different
- location. See also the -U switch.
- </td></tr><tr><td align="left">
- <code class="option">-U baseurl</code>
- </td><td align="left">
- Set base URL for this run. URLs are resolved relative to
- this base. If omitted defaults to the _url member of the
- top-level movie (see the -u switch).
- </td></tr><tr><td align="left">
- <code class="option">-P parameter</code>
- </td><td align="left">
- Parameters are given in the syntax "ParamName=Value" and are
mostly
- useful for the plugin to honour EMBED tags attributes
- or explicit OBJECT PARAM tags. A common use for -P
- is to provide FlashVars
- (ie: -P "FlashVars=home=http://www.gnu.org";).
- </td></tr><tr><td align="left">
- <code class="option">-F filedescriptor</code>
- </td><td align="left">
- Use the given filedescriptor to send requests to the host
- application. This is currently only used for GETURL requests.
- The protocol is not documented yet, and also needs improvement.
- Primary use for this switch is for the NPAPI plugin to properly
- support javascript and target windows in geturl requests.
- </td></tr></tbody></table></div></div><br
class="table-break"></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="keys"></a><span class="application">Gnash</span> Interactive Control
Keys</h2></div></div></div><p>
- While a movie is playing, there are several control
- keys. These can be used to step through frames, pause the
- playing, and control other actions.
- </p><div class="table"><a name="tb-control-keys"></a><p
class="title"><b>Table 2.2. Gnash Interactive Control Keys</b></p><div
class="table-contents"><table summary="Gnash Interactive Control Keys"
border="1"><colgroup><col><col></colgroup><thead><tr><th align="left">Key
Combination</th><th align="left">Function</th></tr></thead><tbody><tr><td
align="left">
- <code class="option">CTRL-Q</code>
- </td><td align="left">
- Quit/Exit.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-W</code>
- </td><td align="left">
- Quit/Exit.
- </td></tr><tr><td align="left">
- <code class="option">ESC</code>
- </td><td align="left">
- Quit/Exit.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-P</code>
- </td><td align="left">
- Toggle Pause.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-R </code>
- </td><td align="left">
- Restart the movie.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-L</code>
- </td><td align="left">
- Force immediate redraw.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-T</code>
- </td><td align="left">
- Debug. Test the set_variable() function.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-G</code>
- </td><td align="left">
- Debug. Test the get_variable() function.
- </td></tr><tr><td align="left">
- <code class="option">CTRL-M</code>
- </td><td align="left">
- Debug. Test the call_method() function.
- </td></tr></tbody></table></div></div><br
class="table-break"></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="gnashrc"></a>User Configuration File</h2></div></div></div><p>
- Individual user preferences may be set by editing variables with
- the <code class="filename">.gnashrc</code> file:
- </p><pre class="programlisting">
- ~/.gnashrc
- </pre><p>
- </p><p>
- Each line must begin with an action: either
- <span class="emphasis"><em>set</em></span> or, in the case of lists, also
- <span class="emphasis"><em>append</em></span>.
- </p><p>
- The values in this configuration file apply only to an individual
- user, and become the default settings of the standalone player and
- the plugin. Note that any command line options take precedence
- over <code class="filename">.gnashrc</code> settings.
- </p><p>
- The variables in the <code class="filename">.gnashrc</code> file support
- three types of arguments: on/off, numeric values, or in the case
- of the whitelist and blacklist, a list of hostnames as ASCII text.
- </p><div class="table"><a name="tb-config-variables"></a><p
class="title"><b>Table 2.3. User Configuration Variables</b></p><div
class="table-contents"><table summary="User Configuration Variables"
border="1"><colgroup><col><col><col></colgroup><thead><tr><th
align="left">Variable</th><th align="left">Value</th><th
align="left">Function</th></tr></thead><tbody><tr><td
align="left">localdomain</td><td align="left">on/off</td><td align="left">This
value can be set to either <span class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls the loading
of
- external Flash movies over a network. This option
- tells Gnash to only load Flash movies from the existing
domain.</td></tr><tr><td align="left">localhost</td><td
align="left">on/off</td><td align="left">This value can be set to either <span
class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls the loading
of
- external Flash movies over a network. This is a stricter
- version of the <span class="emphasis"><em>localdomain</em></span>
setting as
- this allows the loading of Flash movies to the same host
- that is running <span
class="application">Gnash</span>.</td></tr><tr><td
align="left">whitelist</td><td align="left">hostnames</td><td align="left">This
is a list of hostnames separated by spaces, or <span
class="emphasis"><em>off</em></span>
- to disable the whitelist. The hostname must be given
- without a protocol (http://, https://). If this list is populated,
- <span class="application">Gnash</span> will only load external Flash
movies from the specified hosts. The
- whitelist takes precedence over the blacklist. Because several files
can
- be parsed in succession, each file can override or add to
- lists in other files. Use <span class="emphasis"><em>set</em></span>
to override
- all other lists or <span class="emphasis"><em>append</em></span> to
add your blacklisted
- hosts to lists in previously parsed files.</td></tr><tr><td
align="left">blacklist</td><td align="left">hostnames</td><td align="left">This
is a list of hostnames separated by spaces, or <span
class="emphasis"><em>off</em></span>
- to disable the blacklist. The hostname must be given
- without a protocol (http://, https://).
- External flash movies from these
- domains are never allowed to load. If whitelist is present
- and not empty, blacklist is not used. Because several files can
- be parsed in succession, each file can override or add to
- lists in other files. Use <span class="emphasis"><em>set</em></span>
to override
- all other lists or <span class="emphasis"><em>append</em></span> to
add your blacklisted
- hosts to lists in previously parsed files.</td></tr><tr><td
align="left">localSandboxPath</td><td align="left">dirs</td><td
align="left">This is a list of directories separated by spaces.
- Only resources from these directories and from the directory
- portion of movie filename (if loaded from filesystem) are allowed to
load.
- Because several files can be parsed in succession, each file can
override
- or add to lists in other files. Use <span
class="emphasis"><em>set</em></span> to override
- all other lists or <span class="emphasis"><em>append</em></span> to
add new sandboxes.
- Note that there's currently no way to *drop* the directory of base dir
- from the list of allowed local sandboxes.
- </td></tr><tr><td align="left">delay</td><td
align="left">Number</td><td align="left"><span class="application">Gnash</span>
uses a timer-based event mechanism to advance frames
- at a steady rate. This option overrides the default
- setting in Gnash to play a movie slower or faster.</td></tr><tr><td
align="left">verbosity</td><td align="left">Number</td><td align="left">This is
a numeric value which defines the default level of
- verbosity from the player.</td></tr><tr><td
align="left">MalformedSWFVerbosity</td><td align="left">on/off</td><td
align="left">This value can be set to either <span
class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls whether
malformed SWF errors should
- be printed. If set to true, verbosity level is automatically
incremented.
- Set <code class="option">verbosity</code> to 0 afterwards to
hush.</td></tr><tr><td align="left">ASCodingErrorsVerbosity</td><td
align="left">on/off</td><td align="left">This value can be set to either <span
class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls whether
ActionScript coding
- errors should be printed. If set to true, verbosity level is
- automatically incremented. Set <code class="option">verbosity</code>
to 0 afterwards to hush.</td></tr><tr><td align="left">debuglog</td><td
align="left">Absolute path</td><td align="left">This is the full path and name
of debug logfile as
- produced by <span class="application">Gnash</span>. On systems with a
UNIX-type shell,
- a tilde prefix (~) will be expanded as by Posix shell requirements
- (see
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_06_01).</td></tr><tr><td
align="left">writelog</td><td align="left">on/off</td><td align="left">This
value can be set to either <span class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls whether a
debug log
- is always written by <span class="application">Gnash</span>, or not
at all.</td></tr><tr><td align="left">sound</td><td align="left">on/off</td><td
align="left">This value can be set to either <span
class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls the sound of
the
- standalone player. By default <span class="application">Gnash</span>
enables playing the
- sound in any Flash movie.</td></tr><tr><td
align="left">pluginsound</td><td align="left">on/off</td><td align="left">This
value can be set to either <span class="emphasis"><em>on</em></span> or
- <span class="emphasis"><em>off</em></span>, and controls the sound of
the
- player when running as a browser plugin. By default, sound
- is enabled when using <span class="application">Gnash</span> as a
browser plugin.</td></tr><tr><td align="left">EnableExtensions</td><td
align="left">on/off</td><td align="left">Set to <span
class="emphasis"><em>on</em></span> to enable extensions. This option is <span
class="emphasis"><em>off</em></span> by default</td></tr><tr><td
align="left">StartStopped</td><td align="left">on/off</td><td align="left">Set
to <span class="emphasis"><em>on</em></span> to have the GUI start in "stop"
mode. This is useful in particular
- for the plugin, so you have to explicitly start any movie on a
webpage. This option is <span class="emphasis"><em>off</em></span> by default.
- </td></tr><tr><td align="left">flashVersionString</td><td
align="left">string</td><td align="left">Set the string returned by $version
and System.capabilities.version.
- Useful to get around some flash version detection movies.
- Note that the version advertised by the plugin is NOT affected by
this setting,
- instead you need to set the GNASH_FLASH_VERSION environment variable
for
- the latter (which doesn't affect $version and
System.capabilities.version).</td></tr><tr><td
align="left">flashSystemOS</td><td align="left">string</td><td align="left">The
string that Gnash should return for System.capabilities.OS</td></tr><tr><td
align="left">flashSystemManufacturer</td><td align="left">string</td><td
align="left">The string that Gnash should return for
System.capabilities.manufacturer</td></tr><tr><td
align="left">StreamsTimeout</td><td align="left">double</td><td align="left">
- Set the number of seconds after which streams download time out.
Note that timeouts only occurs after the given number of seconds
- passed w/out anything was received.
- </td></tr><tr><td align="left">insecureSSL</td><td
align="left">on/off</td><td align="left">If set to <span
class="emphasis"><em>on</em></span>, no verification of SSL connections
- is performed. This means that, although the connection is encrypted,
the server
- certificate could be invalid, may not belong to the host, or both.
Equivalent
- to curl --insecure. By default, this option is <span
class="emphasis"><em>off</em></span> and
- connections will fail when a host cannot be
verified.</td></tr><tr><td align="left">SOLsafedir</td><td
align="left">Absolute path</td><td align="left">The full path to a directory
where <span class="application">Gnash</span> should store Shared Object files
("flash cookies") if
- they are enabled.</td></tr><tr><td align="left">SOLreadonly</td><td
align="left">on/off</td><td align="left">If set to <span
class="emphasis"><em>on</em></span>, <span class="application">Gnash</span>
will not write Shared Object files.</td></tr><tr><td
align="left">URLOpenerFormat</td><td align="left">string</td><td align="left">
- Set the format of an url opener command. The %u label would be
substituted by the actual url to be opened.
- Examples:
- <pre class="programlisting">
- set urlOpenerFormat firefox -remote 'openurl(%u)'
- set urlOpenerFormat xdg-open %u
- set urlOpenerFormat open %u
- set urlOpenerFormat kfmclient exec %u
- </pre>
- </td></tr></tbody></table></div></div><br class="table-break"><p>
- The following example <code class="filename">.gnashrc</code> file allows a
user to only play Flash files saved locally to the machine on which <span
class="application">Gnash</span> is running. It also specifically forbids
content from doubleclick.com and mochibot.com. <span
class="application">Gnash</span>'s error output is set to be fairly verbose,
with the debug log placed in a location convenient for the user. Finally,
sound is turned on for both the standalone player and the plugin.
- </p><pre class="programlisting">
-
- #
- # Gnash client options
- #
-
- # Only access remote content from our local domain
- set localdomain on
-
- # Only access content from our local host
- set localhost on
-
- # These sites are OK
- # uncommenting the following line will allow load of external
- # movies *only* from the specified hosts.
- #set whitelist www.doonesbury.com www.cnn.com www.9news.com
-
- # Disable whitelists set in any other gnashrc files, because
- # these could override our blacklist.
- set whitelist off
-
- # Don't access content from these sites
- set blacklist www.doubleclick.com mochibot.com
-
- # The delay between timer interrupts
- set delay 50
-
- # The default verbosity level
- set verbosity 1
-
- # Be verbose about malformed SWF
- set MalformedSWFVerbosity true
-
- # Be verbose about AS coding errors
- set ASCodingErrorsVerbosity true
-
- # The full path to the debug log
- set debuglog ~/gnash-dbg.log
-
- # Write a debug log to disk
- set writelog on
-
- # Enable or Disable sound for the standalone player
- set sound on
-
- # Enable or Disable sound for the standalone player
- set pluginsound on
-
- # Make sure SSL connections are always verified
- set insecureSSL off
-
- # Use firefox to open urls
- set urlOpenerFormat firefox -remote 'openurl(%u)'
-
- </pre></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="build"></a>Chapter 3.
Installing and Configuring Gnash</h2></div></div></div><div
class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a
href="#requirements">Requirements</a></span></dt><dd><dl><dt><span
class="sect2"><a href="#hardware">Hardware
Requirements</a></span></dt><dt><span class="sect2"><a
href="#software">Software Requirements</a></span></dt></dl></dd><dt><span
class="sect1"><a href="#downloading">Downloading
Gnash</a></span></dt><dd><dl><dt><span class="sect2"><a
href="#gettingsource">Getting the Source</a></span></dt><dt><span
class="sect2"><a href="#getcodecs">Getting Codec
Support</a></span></dt></dl></dd></dl></div><p>
- There are two ways of installing Gnash:
-
- using a package manager, or <a class="link" href="#gettingsource"
title="Getting the Source">installing from source</a>.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a
name="requirements"></a>Requirements</h2></div></div></div><p>
- Before downloading and installing Gnash, check that your
- hardware and software meet the following requirements.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="hardware"></a>Hardware
Requirements</h3></div></div></div><p>
- One of the goals of Gnash is to make it portable enough to
- install on small devices. As a result, the hardware
- requirements are minimal. Gnash has even run on an ARM9 at 200
- MHz with 32 MB of RAM! (It ran without video support in this
- case.) While firm minimums have not been established, Gnash
- has been shown to run successfully with the following:
- </p><div class="itemizedlist"><ul type="disc"><li><p>
- 336 MHz processor
- </p></li><li><p>
- 128 MB RAM
- </p></li><li><p>
- Gnash will run on anything from a raw frame
- buffer up to an OpenGL-supporting graphics card.
- </p></li></ul></div><p>
- The following table provides a list of the Operating System/CPU
- combinations on which Gnash has been shown to run.
- </p><div class="table"><a name="tb-os-cpu"></a><p class="title"><b>Table
3.1. Build Matrix</b></p><div class="table-contents"><table summary="Build
Matrix" border="1"><colgroup><col><col></colgroup><thead><tr><th
align="left">Operating System</th><th
align="left">Processor</th></tr></thead><tbody><tr><td align="left">OpenBSD,
FreeBSD, NetBSD</td><td align="left">Alpha AXP, AMD64, i386, Itanium, PC-98,
PowerPC, SPARC64
- </td></tr><tr><td align="left">Debian</td><td align="left">Alpha
AXP, AMD64, ARM, hppa, i386, Itanium, MIPS,
- PowerPC, IBM zSeries (s390), SPARC
- </td></tr><tr><td align="left">Fedora</td><td
align="left">x86-32, x86-64, Geode GX, Geode LX
- </td></tr><tr><td align="left">Gentoo</td><td align="left">AMD64,
PowerPC, SPARC, x86
- </td></tr><tr><td align="left">Maemo 2.1</td><td
align="left">i385, ARMv5t</td></tr><tr><td align="left">Scratchbox</td><td
align="left">i386, ARMv5t</td></tr><tr><td align="left">Access Linux Platform
- </td><td align="left">i386, ARMv5t</td></tr><tr><td
align="left">Mandriva
- </td><td align="left">i386, x86-64, MIPS</td></tr><tr><td
align="left">Open Embedded, OpenMoko, Poky
- </td><td align="left">ARM
- </td></tr><tr><td align="left">YellowDog Linux 6
- </td><td align="left">PowerPC, PS3
- </td></tr><tr><td align="left">OpenSuSE 10
- </td><td align="left">i586, x86-64
- </td></tr><tr><td align="left">Red Hat Enterprise, CentOS
- </td><td align="left">x86-32, x86-64
- </td></tr><tr><td align="left">Ubuntu
- </td><td align="left">x86-64, x86-32, PowerPC, UltraSPARC
- </td></tr><tr><td align="left">Haiku</td><td
align="left">i386</td></tr><tr><td align="left">Syllable</td><td
align="left">i386</td></tr><tr><td align="left">Irix 6.5
- </td><td align="left">MIPS R10K
- </td></tr><tr><td align="left">Darwin (MacOS X)
- </td><td align="left">PowerPC and x86-32
- </td></tr><tr><td align="left">Windows XP, Windows Vista</td><td
align="left">x86-32</td></tr></tbody></table></div></div><br
class="table-break"></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="software"></a>Software
Requirements</h3></div></div></div><p>
- The 0.8.2 release of Gnash has been designed to run on
- UNIX/Linux variants, and has been run on most of the free ones.
- However, Gnash has successfully run on Windows, Darwin (Mac OS X),
- Irix, Solaris, BeOs, OS/2, and Haiku. Gnash has also run on the
- following 64-bit systems: PowerPC, Itanium, UltraSparc, and AMD64.
- For now, it is important to be sure that the following code, testing,
- and documentation dependencies are met before installing Gnash. If
- you will be downloading Gnash with a package manager, these
- dependencies may be solved by the package manager. Otherwise, you
- must first verify that each of these dependencies are installed on the
- target system.
- </p></div></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="downloading"></a>Downloading Gnash</h2></div></div></div><p>
- There are two ways to download Gnash: using a package manager or by
- downloading the source code and building it on your system. If
- possible, it is advisable to use a package manager to download Gnash,
- as it will resolve dependencies for you. However, if you want the
- very latest features, or a Gnash package is not available for your
- operating system, it is better to download the source code and build
- Gnash locally.
- </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3
class="title"><a name="gettingsource"></a>Getting the
Source</h3></div></div></div><p>
- Gnash is available as a <a class="link" href="#sourcereleases"
title="Releases">release
- tarball</a>, a <a class="link" href="#sourcerepo"
title="Repository">development
- checkout</a>, or a <a class="link" href="#sourcesnapshot"
title="Snapshot">development
- snapshot</a>.
- </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4
class="title"><a name="sourcereleases"></a>Releases</h4></div></div></div><p>
- The source can be acquired from a
- <a class="ulink" href="http://www.gnu.org/prep/ftp.html";
target="_top">GNU FTP
- Mirror</a>. The release version is intended to be
- stable, and is probably your best choice if the release took
- place recently. If you need features or fixes which were
- introduced after the release, consider a
- <a class="link" href="#sourcerepo" title="Repository">CVS
checkout</a> or the
- <a class="link" href="#sourcesnapshot" title="Snapshot">daily
snapshot</a>.
- </p><p>
- To download, select a mirror near you, then choose the
- <code class="filename">gnash</code> directory.
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="sourcesnapshot"></a>Snapshot</h4></div></div></div><p>
- The daily development snapshot can be downloaded from
- <a class="ulink" href="http://www.gnashdev.org/dev_snapshots/";
target="_top">http://www.gnashdev.org/dev_snapshots/</a>.
- This is the best option if you need changes which were introduced
- after the <a class="link" href="#sourcereleases"
title="Releases">last release</a> of
- Gnash, but are unable to <a class="link" href="#sourcerepo"
title="Repository">download
- directly from the repository.</a>
- </p></div><div class="sect3" lang="en"><div
class="titlepage"><div><div><h4 class="title"><a
name="sourcerepo"></a>Repository</h4></div></div></div><p>
- The latest development sources are available via
- anonymous CVS. This is recommended
- if you need features or bug fixes which were introduced after
- the <a class="link" href="#sourcereleases" title="Releases">last
release</a>. Look at
- the <a class="link" href="#sourcesnapshot" title="Snapshot">daily
snapshot</a> if you
- experience difficulty accessing the repository.
- </p><p>
- To download via anonymous CVS, first set the
- environment variable <span
class="command"><strong>CVS_RSH</strong></span> to
- <span class="command"><strong>ssh</strong></span>, then check out
the source code.
- The example below uses the GNU Bourne-Again shell (bash):
- </p><pre class="screen">
- export CVS_RSH="ssh"
- cvs -z3 -d:pserver:address@hidden:/sources/gnash co gnash
- </pre><p>
- It is also possible to browse the repository
- <a class="ulink"
href="http://cvs.savannah.gnu.org/viewcvs/gnash/?root=gnash";
target="_top">http://cvs.savannah.gnu.org/viewcvs/gnash/?root=gnash</a> on the
web.
- </p></div></div><div class="sect2" lang="en"><div
class="titlepage"><div><div><h3 class="title"><a name="getcodecs"></a>Getting
Codec Support</h3></div></div></div><p>
- Gnash requires codec support to handle audio and video
- correctly. Some platforms like Ubuntu or Fedora under the
- GNOME desktop will automatically notify the user that the
- proper codecs aren't installed, and pop up a dialog box to
- let the user download the codecs Gnash needs to make site
- like YouTube work correctly. If you have installed Gnash on
- any other platform, and video doesn't work, it's highly
- likely you need to install the proper codecs. For most
- platforms, this is the Gstreamer-ffmpeg plugin, available
- from your distributions repository.
- </p></div></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="bugreport"></a>Chapter
4. Reporting Bugs</h2></div></div></div><div class="toc"><p><b>Table of
Contents</b></p><dl><dt><span class="sect1"><a href="#bugstep_package">Get a
Fresh Binary Package</a></span></dt><dt><span class="sect1"><a
href="#bugstep_search">Determine if the bug was previously
reported</a></span></dt><dt><span class="sect1"><a
href="#bugstep_guidelines">Review the bug writing
guidelines</a></span></dt><dt><span class="sect1"><a
href="#bugstep_file">Filing a bug report</a></span></dt></dl></div><p>
- The Gnash project relies on the community of Gnash users to test
- the player, feedback is critical to any successful project. Not
- only does it let us know that people use Gnash, but it helps us
- understand the community's needs. Gnash uses a bug tracker on
- <a class="ulink" href="http://savannah.gnu.org";
target="_top">http://savannah.gnu.org</a> to manage these reports.
- </p><p>
- When filing a report, please follow the guidelines below. The better
- your bug report is, the easier it will be for the developers to
- address the issue. Bug reports without enough information will
- initially be asked to provide this information anyway. Adding
- critical details, like the Operating System you are on, its
- version, and any relevant error messages from Gnash that you get.
- </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2
class="title" style="clear: both"><a name="bugstep_package"></a>Get a Fresh
Binary Package</h2></div></div></div><p>
- For starters, it's a good idea to obtain a copy of the latest
- snapshot. Although Gnash is primarily released as source, the
- Gnash build infrastructure allows the automated building of
- binary packages. Often the version of Gnash as packaged by a
- GNU/Linux or BSD distribution is based on the last official
- release, which could be months out of date. It is helpful if
- this is the case to try a newer packaged build of Gnash.
- </p><p>
- You can get a fresh binary package of Gnash, as well as recent
- source packages from
- <a class="ulink" href="http://www.getgnash.org/packages/"; target="_top">
- http://www.getgnash.org/packages
- </a>.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="bugstep_search"></a>Determine if the bug was previously
reported</h2></div></div></div><p>
- Search the <a class="ulink"
href="https://savannah.gnu.org/bugs/?group=gnash"; target="_top">Gnash
- bug tracker</a> to see if the bug has already been identified.
- </p><p>
- If the issue has already been reported, you should not file
- a bug report. However, you may add some additional information
- to the ticket if you feel that it will be beneficial to the
- developers. For instance, if someone reported a memory issue
- on Ubuntu GNU/Linux, and you noticed the same problem on OpenBSD,
- your stacktrace would be useful. Conversely, adding a "me too"
- note to a feature request is not helpful.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="bugstep_guidelines"></a>Review the bug writing
guidelines</h2></div></div></div><p>
- A good bug report should be precise, explicit, and discrete.
- This means that there should be just one bug per ticket, and
- that a ticket should contain the following information:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p>
- An overview of the problem;
- </p></li><li style="list-style-type: circle"><p>
- Instructions on how to replicate the bug;
- </p></li><li style="list-style-type: circle"><p>
- A description of what happened when you performed the steps
- to replicate the bug, and what you expected to happen;
- </p></li><li style="list-style-type: circle"><p>
- Your system information: operating system name and version, as
- well as the versions of major development dependencies;
- </p></li><li style="list-style-type: circle"><p>
- The release number or checkout timestamp for the version of Gnash
- where you observe the problem;
- </p></li><li style="list-style-type: circle"><p>
- The file <code class="filename">config.log</code>, which should be
- attached as a file;
- </p></li><li style="list-style-type: circle"><p>
- A descriptive title.
- </p></li></ul></div><p>
- Include any additional information that you feel might be useful
- to the developers.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="bugstep_file"></a>Filing a bug report</h2></div></div></div><p>
- After following the steps described above, you can file a bug report at
- <a class="ulink" href="https://savannah.gnu.org/bugs/?group=gnash";
target="_top">https://savannah.gnu.org/bugs/?group=gnash</a>.
- </p></div></div><div class="glossary"><div class="titlepage"><div><div><h2
class="title"><a name="glossary"></a>Glossary</h2></div></div></div><div
class="glossdiv"><h3 class="title">A</h3><dl><dt>
- ActionScript
- </dt><dd><p>
- <span class="emphasis"><em>ActionScript</em></span>, or "AS", is the
scripting
- language for <span class="emphasis"><em>Flash</em></span>
- applications. It is compiled to bytecode, which is a subset of
- the <span class="emphasis"><em>SWF</em></span> format.
- </p></dd><dt>
- AGG
- </dt><dd><p>
- AGG is the AntiGrain 2D graphics library, which can be used
- as a renderer in Gnash. It is faster than OpenGL on systems
- without hardware graphics acceleration. As of Gnash version
- 0.8.1 it is the more feature complete renderer.
- </p></dd><dt>
- AMF
- </dt><dd><p>
- <span class="emphasis"><em>AMF</em></span>
- is the object format used by <span
class="emphasis"><em>Flash</em></span>
- for shared objects and streaming video.
- </p></dd><dt>
- as_environment
- </dt><dd><p>
- In Gnash terms, the as_environment, or ActionScript
- execution environment, contains a stack of objects,
- characters and values which are in the immediate environment
- of the current fn_call. Please refer to the Gnash
- ActionScript manual for more information.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">C</h3><dl><dt>
- Cairo
- </dt><dd><p>
- Cairo is a 2D graphics library with support for multiple
- output devices. Can be used as a renderer in Gnash. A useful
- feature of Cairo is that it will automatically use graphic
- card acceleration when available. Cairo has an experimental
- OpenGL backend.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">D</h3><dl><dt>
- DejaGNU
- </dt><dd><p>
- DejaGNU is a framework for testing software.
- </p></dd><dt>
- DocBook
- </dt><dd><p>
- <span class="emphasis"><em>DocBook</em></span>
- is a markup language for presentation-neutral
- documentation, such as manuals.
- </p></dd><dt>
- Doxygen
- </dt><dd><p>
- <span class="emphasis"><em>Doxygen</em></span>
- is a documentation generator for for multiple languages
- which uses comments in the source code to create stand-alone
- documentation.
- </p></dd><dt>
- Drupal
- </dt><dd><p>
- Drupal is a CMS/blog system used for the main Gnash website.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">E</h3><dl><dt>
- extensions
- </dt><dd><p>
- A <span class="application">Gnash</span> <span
class="emphasis"><em>extension</em></span> is a plugin (not a
- browser plugin) which implements additional functionality
- beyond what is covered by <span class="emphasis"><em>Flash</em></span>
- specification. These are shared libraries which are loaded
- at runtime.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">F</h3><dl><dt>
- ffmpeg
- </dt><dd><p>
- ffmpeg is an audio and video decoding library which can be
- used by Gnash to decode mp3, FLV and other media types.
- </p></dd><dt>
- Flash
- </dt><dd><p>
- The term <span class="emphasis"><em>Flash</em></span> is used to
describe both the
- Adobe IDE for creating <span class="emphasis"><em>SWF</em></span>
- files, and the technology itself. Flash is a trademarked
- term of Adobe's, we prfer to use SWF to refer to the files
- themselves, as well as the format, instead of flash(tm).
- </p></dd><dt>
- FLV
- </dt><dd><p>
- FLV is a proprietary file format used to deliver Flash
- video. It is used by YouTube, among others.
- </p></dd><dt>
- FLTK
- </dt><dd><p>
- FLTK, or the 'Fast Light ToolKit', is a portable GUI library
- which is intended to replace the SDL GUI. Currently in Gnash,
- FLTK may be used with the Cairo and AGG renderers. FLTK has an
- experimental Cairo backend.
- </p></dd><dt>
- FrameBuffer
- </dt><dd><p>
- In Gnash, this is a GUI library that outputs directly to the
- Linux Frame Buffer and so does not need a window system to
- run. This makes it particularly suitable for use on small
- devices.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">G</h3><dl><dt>
- Gnash
- </dt><dd><p>
- Gnash is the GNU Flash movie player.
- </p></dd><dt>
- Gstreamer
- </dt><dd><p>
- Gstreamer is a multimedia framework which Gnash can use for
- decoding audio and video. Gstreamer itself cannot decode
- anything, so it needs some appropriate decoding-plugins to do
- the work for it. Remember to install them if you use Gnash
- with Gstreamer enabled. To get the best out of Gnashs
- gstreamer-parts, it is recommended to install the
- gst-plugins-good, gst-plugins-good and gst-ffmpeg plugins
- packages.
- </p></dd><dt>
- GTK
- </dt><dd><p>
- GTK is the GIMP Toolkit GUI library. It is one of the GUI
- options for Gnash. As of Gnash 0.7.2, this is the more
- performant and feature-rich choice. GTK uses Cairo
- internally.
- </p></dd><dt>
- GUI
- </dt><dd><p>
- A <span class="emphasis"><em>GUI</em></span> is a
- "graphical user interface". In <span class="application">Gnash</span>,
the GUI
- library provides a wrapper for mouse and keyboard events,
- menus, windowing (where available) and a drawing area.
- You must choose a GUI library during the
- configuration stage of building Gnash.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">K</h3><dl><dt>
- Klash
- </dt><dd><p>
- <span class="emphasis"><em>Klash</em></span> was the name given to
the stand-alone
- instance of <span class="application">Gnash</span> which used the KDE
GUI. It has been replaced with
- an implementation using Qt. Some documentation may incorrectly
- refer to the Konqueror plugin as <span
class="emphasis"><em>Klash</em></span>.
- The plugin was renamed <span class="emphasis"><em>Kpart</em></span>.
- </p></dd><dt>
- Kpart
- </dt><dd><p>
- <span class="emphasis"><em>Kpart</em></span> is a plugin for
Konqueror which is
- enabled with the configuration option --enable-kparts.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">L</h3><dl><dt>
- libmad
- </dt><dd><p>
- libmad is a mp3-decoding library, which used to be an option for Gnash
- handling of sound (dropped since 0.8.2).
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">M</h3><dl><dt>
- Mesa
- </dt><dd><p>
- <span class="emphasis"><em>Mesa</em></span> is the free software
OpenGL
- implementation. <span class="application">Gnash</span> documentation
will sometimes use the
- glossterms 'OpenGL' and 'Mesa' interchangeably.
- </p></dd><dt>
- Ming
- </dt><dd><p>
- Ming is a C library for generating SWF ("Flash") format
- movies, plus a set of wrappers for using the library. It is
- used by the Gnash project for generating testcases.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">N</h3><dl><dt>
- Nellymoser
- </dt><dd><p>
- Nellymoser is a proprietary audio codec introduced in the
- Flash Player in version 6. For more information, please see
- Wikipedia.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">O</h3><dl><dt>
- OpenGL
- </dt><dd><p>
- OpenGL (Open Graphics Library) is a standard specification
- defining a cross-language cross-platform API for writing
- applications that produce 3D and 2D computer
- graphics. Accelerated graphic cards usually provide OpenGL at
- the hardware level. Please refer to Wikipedia for availability
- of free software OpenGL hardware drivers. A free software
- implementation of the API is available (Mesa). OpenGL can be
- used as a renderer in Gnash.
- </p></dd><dt>
- ORM
- </dt><dd><p>
- ORM is a system for ensuring the rights of the creator over a piece
of digital content. It is more passive than DRM.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">P</h3><dl><dt>
- plugin
- </dt><dd><p>
- The glossterm <span class="emphasis"><em>plugin</em></span> is used
in <span class="application">Gnash</span> to
- refer to both any <span class="application">Gnash</span> browser
plugin, as well as the Firefox
- plugin specifically. The Konqueror plugin is called
- <span class="emphasis"><em>Kpart</em></span>. Sometimes, the term is
used in
- an even more generic sense to refer to
- <span class="emphasis"><em>extensions</em></span>.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">Q</h3><dl><dt>
- Qt
- </dt><dd><p>
- Qt is a GUI library which is used by KDE. The plugin version
- of Gnash using this GUI library is Kpart. The standalone
- version is enabled with --enable-gui=kde.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">R</h3><dl><dt>
- renderer
- </dt><dd><p>
- The <span class="emphasis"><em>renderer</em></span> is the subsystem
of <span class="application">Gnash</span>
- which renders content. Only one renderer may be used; it is
- selected at configuration time if building from source.
- </p><p>
- Available renderers are: AGG, OpenGL, and Cairo. In terms of
- feature completeness, AGG comes first; followed by OpenGL and
- then Cairo. In most cases, AGG is preferred for performance,
- except cases where it is beneficial to have hardware accelerated
- rendering (for example, when you have a very slow CPU but a very
- fast graphics card). In this case OpenGL should be used.
- </p></dd><dt>
- RTMP
- </dt><dd><p>
- RTMP is the Real Time Messaging Protocol primarily used with
- to stream audio and video over the internet to the Flash
- Player client.
- </p></dd><dt>
- RTMPT
- </dt><dd><p>
- RTMPT is basically a HTTP wrapper around the RTMP protocol
- that is sent using POST requests from the client to the
- server. Because of the non-persistent nature of HTTP
- connections, RTMPT requires the clients to poll for updates
- periodically in order to get notified about events that are
- generated by the server or other clients.
- </p></dd><dt>
- RTMPTS
- </dt><dd><p>
- RTMPTS is the same as RTMPT, but instead of being a HTTP
- wrapper, it is a HTTP SSL wrapper (HTTP secure connection).
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">S</h3><dl><dt>
- SDL
- </dt><dd><p>
- Simple DirectMedia Layer is a cross-platform multimedia free
- software library that creates an abstraction over various
- platforms' graphics, sound, and input APIs. Gnash can use it
- as a GUI and/or as a sound handler. Note that the two usages
- are independent of each other: you can use it for a task and
- not for the other if you wish. At time or writing (2007-01-11)
- the SDL GUI lacks menus and a performant input event
- architecture; the SDL sound handler is the most feature rich,
- supporting Video through ffmpeg.
- </p></dd><dt>
- sound handler
- </dt><dd><p>
- The <span class="emphasis"><em>sound handler</em></span> is the part
of <span class="application">Gnash</span>
- which handles both event sounds and streaming sound. Audio
- from external sources are also handled through the sound handler
- when SDL is used. The sound handler must be selected during
- configuration of Gnash when compiling.
- </p><p>
- There are currently two sound handlers available in <span
class="application">Gnash</span>:
- ffmpeg and Gstreamer. The ffmpeg sound handler uses SDL for
- mixing.
- The Gstreamer-sound handler uses the available
- plugins to decode the audio, so it might not work if some
- important plugins are missing. The GST sound handler is
- recommended (the default).
- </p></dd><dt>
- sprite
- </dt><dd><p>
- A sprite is an element of an Flash Movie. It's basically a
- Movie inside another, having its own timeline.
- </p></dd><dt>
- Stage
- </dt><dd><p>
- The visible area of a Flash movie. The name derives from a
theater analogy. Graphical elements are referred to as
- characters.
- </p></dd><dt>
- SWF
- </dt><dd><p>
- <span class="emphasis"><em>SWF</em></span> is the file format for
- <span class="emphasis"><em>Flash</em></span> movies.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">T</h3><dl><dt>
- Tamarin
- </dt><dd><p>
- The Tamarin project seeks to create an open source
- implementation of the ECMAScript 4th edition language
- specification. The code is used by Adobe as part of the
- ActionScript Virtual Machine within the Adobe Flash
- Player. Gnash does not use Tamarin; it already has a working
- virtual server and most ActionScript classes are implemented.
- </p></dd><dt>
- timeline
- </dt><dd><p>
- In Flash technology, a timeline is a sequence of "frames". A
- single Flash movie can contain multiple timelines, each
- independently controlled (STOP or PLAY). At regular intervals
- (FPS) the player advances all timelines in PLAY mode to the
- next frame, looping back when last frame is reached.
- </p></dd></dl></div><div class="glossdiv"><h3
class="title">X</h3><dl><dt>
- X.org
- </dt><dd><p>
- X.org is the most commonly used X server; it was forked from
- XFree86.
- </p></dd></dl></div></div><div class="chapter" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="authors"></a>Chapter 5.
Authors</h2></div></div></div><p>
- <span class="application">Gnash</span> is maintained by Rob Savoye.
Other active developers
- are: Sandro Santilli, Bastiaan Jacques, Udo Giacomozzi, Chad
- Musick, Benjamin Wolsey, and Zou Lunkai. Please send all
- comments and suggestions to <code class="email"><<a class="email"
href="mailto:address@hidden";>address@hidden
- </a>></code>. Past and sometimes current developers are Tomas
- Groth and Markus Gothe.
- </p><p>
- <span class="application">Gnash</span> was initially derived from
<span class="application">GameSWF</span>.
- <span class="application">GameSWF</span> is maintained by
- Thatcher Ulrich <code class="email"><<a class="email"
href="mailto:address@hidden";>address@hidden</a>></code>. The following
- people contributed to <span class="application">GameSWF</span>:
- Mike Shaver, Thierry Berger-Perrin,
- Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit,
- and Rob Savoye.
- </p></div><div class="appendix" lang="en"><div
class="titlepage"><div><div><h2 class="title"><a name="fdl"></a>Appendix A. GNU
Free Documentation License</h2></div><div><p class="releaseinfo">
- Version 1.1, March 2000
- </p></div><div><p class="copyright">Copyright © 2000 Free Software
Foundation, Inc.</p></div><div><div class="legalnotice"><a
name="fdl-legalnotice"></a><p>
- </p><div class="address"><p>Free Software Foundation, Inc. <span
class="street">59 Temple Place, <br>
- Suite 330</span>, <span class="city">Boston</span>, <span
class="state">MA</span> <br>
- <span class="postcode">02111-1307</span> <span
class="country">USA</span></p></div><p>
- Everyone is permitted to copy and distribute verbatim copies of this
- license document, but changing it is not allowed.
- </p></div></div></div></div><div class="toc"><p><b>Table of
Contents</b></p><dl><dt><span class="sect1"><a href="#fdl-preamble">0.
PREAMBLE</a></span></dt><dt><span class="sect1"><a href="#fdl-section1">1.
APPLICABILITY AND DEFINITIONS</a></span></dt><dt><span class="sect1"><a
href="#fdl-section2">2. VERBATIM COPYING</a></span></dt><dt><span
class="sect1"><a href="#fdl-section3">3. COPYING IN
QUANTITY</a></span></dt><dt><span class="sect1"><a href="#fdl-section4">4.
MODIFICATIONS</a></span></dt><dt><span class="sect1"><a href="#fdl-section5">5.
COMBINING DOCUMENTS</a></span></dt><dt><span class="sect1"><a
href="#fdl-section6">6. COLLECTIONS OF DOCUMENTS</a></span></dt><dt><span
class="sect1"><a href="#fdl-section7">7. AGGREGATION WITH INDEPENDENT
WORKS</a></span></dt><dt><span class="sect1"><a href="#fdl-section8">8.
TRANSLATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section9">9.
TERMINATION</a></span></dt><dt><span class="sect1"><a href="#fdl-section10">10.
FUTURE REVISIONS OF THIS LICENSE</a></span></dt><dt><span class="sect1"><a
href="#fdl-using">Addendum</a></span></dt></dl></div><div class="sect1"
lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear:
both"><a name="fdl-preamble"></a>0. PREAMBLE</h2></div></div></div><p>
- The purpose of this License is to make a manual, textbook, or
- other written document "free" in the sense of
- freedom: to assure everyone the effective freedom to copy and
- redistribute it, with or without modifying it, either
- commercially or non-commercially. Secondarily, this License
- preserves for the author and publisher a way to get credit for
- their work, while not being considered responsible for
- modifications made by others.
- </p><p>
- This License is a kind of "copyleft", which means
- that derivative works of the document must themselves be free in
- the same sense. It complements the GNU General Public License,
- which is a copyleft license designed for free software.
- </p><p>
- We have designed this License in order to use it for manuals for
- free software, because free software needs free documentation: a
- free program should come with manuals providing the same
- freedoms that the software does. But this License is not limited
- to software manuals; it can be used for any textual work,
- regardless of subject matter or whether it is published as a
- printed book. We recommend this License principally for works
- whose purpose is instruction or reference.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section1"></a>1. APPLICABILITY AND
DEFINITIONS</h2></div></div></div><p><a name="fdl-document"></a>
- This License applies to any manual or other work that contains a
- notice placed by the copyright holder saying it can be
- distributed under the terms of this License. The
- "Document", below, refers to any such manual or
- work. Any member of the public is a licensee, and is addressed
- as "you".
- </p><p><a name="fdl-modified"></a>
- A "Modified Version" of the Document means any work
- containing the Document or a portion of it, either copied
- verbatim, or with modifications and/or translated into another
- language.
- </p><p><a name="fdl-secondary"></a>
- A "Secondary Section" is a named appendix or a
- front-matter section of the <a class="link"
href="#fdl-document">Document</a> that deals exclusively
- with the relationship of the publishers or authors of the
- Document to the Document's overall subject (or to related
- matters) and contains nothing that could fall directly within
- that overall subject. (For example, if the Document is in part a
- textbook of mathematics, a Secondary Section may not explain any
- mathematics.) The relationship could be a matter of historical
- connection with the subject or with related matters, or of
- legal, commercial, philosophical, ethical or political position
- regarding them.
- </p><p><a name="fdl-invariant"></a>
- The "Invariant Sections" are certain <a class="link"
href="#fdl-secondary"> Secondary Sections</a> whose titles
- are designated, as being those of Invariant Sections, in the
- notice that says that the <a class="link"
href="#fdl-document">Document</a> is released under this
- License.
- </p><p><a name="fdl-cover-texts"></a>
- The "Cover Texts" are certain short passages of
- text that are listed, as Front-Cover Texts or Back-Cover Texts,
- in the notice that says that the <a class="link"
href="#fdl-document">Document</a> is released under this
- License.
- </p><p><a name="fdl-transparent"></a>
- A "Transparent" copy of the <a class="link" href="#fdl-document">
Document</a> means a machine-readable
- copy, represented in a format whose specification is available
- to the general public, whose contents can be viewed and edited
- directly and straightforwardly with generic text editors or (for
- images composed of pixels) generic paint programs or (for
- drawings) some widely available drawing editor, and that is
- suitable for input to text formatters or for automatic
- translation to a variety of formats suitable for input to text
- formatters. A copy made in an otherwise Transparent file format
- whose markup has been designed to thwart or discourage
- subsequent modification by readers is not Transparent. A copy
- that is not "Transparent" is called "Opaque".
- </p><p>
- Examples of suitable formats for Transparent copies include
- plain ASCII without markup, Texinfo input format, LaTeX input
- format, SGML or XML using a publicly available DTD, and
- standard-conforming simple HTML designed for human
- modification. Opaque formats include PostScript, PDF,
- proprietary formats that can be read and edited only by
- proprietary word processors, SGML or XML for which the DTD
- and/or processing tools are not generally available, and the
- machine-generated HTML produced by some word processors for
- output purposes only.
- </p><p><a name="fdl-title-page"></a>
- The "Title Page" means, for a printed book, the
- title page itself, plus such following pages as are needed to
- hold, legibly, the material this License requires to appear in
- the title page. For works in formats which do not have any title
- page as such, "Title Page" means the text near the
- most prominent appearance of the work's title, preceding the
- beginning of the body of the text.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section2"></a>2. VERBATIM COPYING</h2></div></div></div><p>
- You may copy and distribute the <a class="link"
href="#fdl-document">Document</a> in any medium, either
- commercially or noncommercially, provided that this License, the
- copyright notices, and the license notice saying this License
- applies to the Document are reproduced in all copies, and that
- you add no other conditions whatsoever to those of this
- License. You may not use technical measures to obstruct or
- control the reading or further copying of the copies you make or
- distribute. However, you may accept compensation in exchange for
- copies. If you distribute a large enough number of copies you
- must also follow the conditions in <a class="link" href="#fdl-section3"
title="3. COPYING IN QUANTITY">section 3</a>.
- </p><p>
- You may also lend copies, under the same conditions stated
- above, and you may publicly display copies.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section3"></a>3. COPYING IN QUANTITY</h2></div></div></div><p>
- If you publish printed copies of the <a class="link"
href="#fdl-document">Document</a> numbering more than 100,
- and the Document's license notice requires <a class="link"
href="#fdl-cover-texts">Cover Texts</a>, you must enclose
- the copies in covers that carry, clearly and legibly, all these
- Cover Texts: Front-Cover Texts on the front cover, and
- Back-Cover Texts on the back cover. Both covers must also
- clearly and legibly identify you as the publisher of these
- copies. The front cover must present the full title with all
- words of the title equally prominent and visible. You may add
- other material on the covers in addition. Copying with changes
- limited to the covers, as long as they preserve the title of the
- <a class="link" href="#fdl-document">Document</a> and satisfy these
- conditions, can be treated as verbatim copying in other
- respects.
- </p><p>
- If the required texts for either cover are too voluminous to fit
- legibly, you should put the first ones listed (as many as fit
- reasonably) on the actual cover, and continue the rest onto
- adjacent pages.
- </p><p>
- If you publish or distribute <a class="link"
href="#fdl-transparent">Opaque</a> copies of the <a class="link"
href="#fdl-document">Document</a> numbering more than 100,
- you must either include a machine-readable <a class="link"
href="#fdl-transparent">Transparent</a> copy along with
- each Opaque copy, or state in or with each Opaque copy a
- publicly-accessible computer-network location containing a
- complete Transparent copy of the Document, free of added
- material, which the general network-using public has access to
- download anonymously at no charge using public-standard network
- protocols. If you use the latter option, you must take
- reasonably prudent steps, when you begin distribution of Opaque
- copies in quantity, to ensure that this Transparent copy will
- remain thus accessible at the stated location until at least one
- year after the last time you distribute an Opaque copy (directly
- or through your agents or retailers) of that edition to the
- public.
- </p><p>
- It is requested, but not required, that you contact the authors
- of the <a class="link" href="#fdl-document">Document</a> well before
- redistributing any large number of copies, to give them a chance
- to provide you with an updated version of the Document.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section4"></a>4. MODIFICATIONS</h2></div></div></div><p>
- You may copy and distribute a <a class="link"
href="#fdl-modified">Modified Version</a> of the <a class="link"
href="#fdl-document">Document</a> under the conditions of
- sections <a class="link" href="#fdl-section2" title="2. VERBATIM
COPYING">2</a> and <a class="link" href="#fdl-section3" title="3. COPYING IN
QUANTITY">3</a> above, provided that you release
- the Modified Version under precisely this License, with the
- Modified Version filling the role of the Document, thus
- licensing distribution and modification of the Modified Version
- to whoever possesses a copy of it. In addition, you must do
- these things in the Modified Version:
- </p><div class="itemizedlist"><ul type="opencircle"><li
style="list-style-type: circle"><p><b>A. </b>
- Use in the <a class="link" href="#fdl-title-page">Title
- Page</a> (and on the covers, if any) a title distinct
- from that of the <a class="link" href="#fdl-document">Document</a>,
and from those of
- previous versions (which should, if there were any, be
- listed in the History section of the Document). You may
- use the same title as a previous version if the original
- publisher of that version gives permission.
- </p></li><li style="list-style-type: circle"><p><b>B. </b>
- List on the <a class="link" href="#fdl-title-page">Title
- Page</a>, as authors, one or more persons or entities
- responsible for authorship of the modifications in the
- <a class="link" href="#fdl-modified">Modified Version</a>,
- together with at least five of the principal authors of
- the <a class="link" href="#fdl-document">Document</a> (all of
- its principal authors, if it has less than five).
- </p></li><li style="list-style-type: circle"><p><b>C. </b>
- State on the <a class="link" href="#fdl-title-page">Title
- Page</a> the name of the publisher of the <a class="link"
href="#fdl-modified">Modified Version</a>, as the
- publisher.
- </p></li><li style="list-style-type: circle"><p><b>D. </b>
- Preserve all the copyright notices of the <a class="link"
href="#fdl-document">Document</a>.
- </p></li><li style="list-style-type: circle"><p><b>E. </b>
- Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- </p></li><li style="list-style-type: circle"><p><b>F. </b>
- Include, immediately after the copyright notices, a
- license notice giving the public permission to use the
- <a class="link" href="#fdl-modified">Modified Version</a> under
- the terms of this License, in the form shown in the
- Addendum below.
- </p></li><li style="list-style-type: circle"><p><b>G. </b>
- Preserve in that license notice the full lists of <a class="link"
href="#fdl-invariant"> Invariant Sections</a> and
- required <a class="link" href="#fdl-cover-texts">Cover
- Texts</a> given in the <a class="link"
href="#fdl-document">Document's</a> license notice.
- </p></li><li style="list-style-type: circle"><p><b>H. </b>
- Include an unaltered copy of this License.
- </p></li><li style="list-style-type: circle"><p><b>I. </b>
- Preserve the section entitled "History", and
- its title, and add to it an item stating at least the
- title, year, new authors, and publisher of the <a class="link"
href="#fdl-modified">Modified Version </a>as given on
- the <a class="link" href="#fdl-title-page">Title Page</a>. If
- there is no section entitled "History" in the
- <a class="link" href="#fdl-document">Document</a>, create one
- stating the title, year, authors, and publisher of the
- Document as given on its Title Page, then add an item
- describing the Modified Version as stated in the previous
- sentence.
- </p></li><li style="list-style-type: circle"><p><b>J. </b>
- Preserve the network location, if any, given in the <a class="link"
href="#fdl-document">Document</a> for public access
- to a <a class="link" href="#fdl-transparent">Transparent</a>
- copy of the Document, and likewise the network locations
- given in the Document for previous versions it was based
- on. These may be placed in the "History"
- section. You may omit a network location for a work that
- was published at least four years before the Document
- itself, or if the original publisher of the version it
- refers to gives permission.
- </p></li><li style="list-style-type: circle"><p><b>K. </b>
- In any section entitled "Acknowledgements" or
- "Dedications", preserve the section's title,
- and preserve in the section all the substance and tone of
- each of the contributor acknowledgements and/or
- dedications given therein.
- </p></li><li style="list-style-type: circle"><p><b>L. </b>
- Preserve all the <a class="link" href="#fdl-invariant">Invariant
- Sections</a> of the <a class="link"
href="#fdl-document">Document</a>, unaltered in their
- text and in their titles. Section numbers or the
- equivalent are not considered part of the section titles.
- </p></li><li style="list-style-type: circle"><p><b>M. </b>
- Delete any section entitled
- "Endorsements". Such a section may not be
- included in the <a class="link" href="#fdl-modified">Modified
- Version</a>.
- </p></li><li style="list-style-type: circle"><p><b>N. </b>
- Do not retitle any existing section as
- "Endorsements" or to conflict in title with
- any <a class="link" href="#fdl-invariant">Invariant
- Section</a>.
- </p></li></ul></div><p>
- If the <a class="link" href="#fdl-modified">Modified Version</a>
- includes new front-matter sections or appendices that qualify as
- <a class="link" href="#fdl-secondary">Secondary Sections</a> and
- contain no material copied from the Document, you may at your
- option designate some or all of these sections as invariant. To
- do this, add their titles to the list of <a class="link"
href="#fdl-invariant">Invariant Sections</a> in the
- Modified Version's license notice. These titles must be
- distinct from any other section titles.
- </p><p>
- You may add a section entitled "Endorsements",
- provided it contains nothing but endorsements of your <a class="link"
href="#fdl-modified">Modified Version</a> by various
- parties--for example, statements of peer review or that the text
- has been approved by an organization as the authoritative
- definition of a standard.
- </p><p>
- You may add a passage of up to five words as a <a class="link"
href="#fdl-cover-texts">Front-Cover Text</a>, and a passage
- of up to 25 words as a <a class="link"
href="#fdl-cover-texts">Back-Cover Text</a>, to the end of
- the list of <a class="link" href="#fdl-cover-texts">Cover Texts</a>
- in the <a class="link" href="#fdl-modified">Modified Version</a>.
- Only one passage of Front-Cover Text and one of Back-Cover Text
- may be added by (or through arrangements made by) any one
- entity. If the <a class="link" href="#fdl-document">Document</a>
- already includes a cover text for the same cover, previously
- added by you or by arrangement made by the same entity you are
- acting on behalf of, you may not add another; but you may
- replace the old one, on explicit permission from the previous
- publisher that added the old one.
- </p><p>
- The author(s) and publisher(s) of the <a class="link"
href="#fdl-document">Document</a> do not by this License
- give permission to use their names for publicity for or to
- assert or imply endorsement of any <a class="link"
href="#fdl-modified">Modified Version </a>.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section5"></a>5. COMBINING DOCUMENTS</h2></div></div></div><p>
- You may combine the <a class="link" href="#fdl-document">Document</a>
- with other documents released under this License, under the
- terms defined in <a class="link" href="#fdl-section4" title="4.
MODIFICATIONS">section 4</a>
- above for modified versions, provided that you include in the
- combination all of the <a class="link" href="#fdl-invariant">Invariant
- Sections</a> of all of the original documents, unmodified,
- and list them all as Invariant Sections of your combined work in
- its license notice.
- </p><p>
- The combined work need only contain one copy of this License,
- and multiple identical <a class="link" href="#fdl-invariant">Invariant
- Sections</a> may be replaced with a single copy. If there are
- multiple Invariant Sections with the same name but different
- contents, make the title of each such section unique by adding
- at the end of it, in parentheses, the name of the original
- author or publisher of that section if known, or else a unique
- number. Make the same adjustment to the section titles in the
- list of Invariant Sections in the license notice of the combined
- work.
- </p><p>
- In the combination, you must combine any sections entitled
- "History" in the various original documents,
- forming one section entitled "History"; likewise
- combine any sections entitled "Acknowledgements",
- and any sections entitled "Dedications". You must
- delete all sections entitled "Endorsements."
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section6"></a>6. COLLECTIONS OF DOCUMENTS</h2></div></div></div><p>
- You may make a collection consisting of the <a class="link"
href="#fdl-document">Document</a> and other documents
- released under this License, and replace the individual copies
- of this License in the various documents with a single copy that
- is included in the collection, provided that you follow the
- rules of this License for verbatim copying of each of the
- documents in all other respects.
- </p><p>
- You may extract a single document from such a collection, and
- distribute it individually under this License, provided you
- insert a copy of this License into the extracted document, and
- follow this License in all other respects regarding verbatim
- copying of that document.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section7"></a>7. AGGREGATION WITH INDEPENDENT
WORKS</h2></div></div></div><p>
- A compilation of the <a class="link" href="#fdl-document">Document</a>
or its derivatives with
- other separate and independent documents or works, in or on a
- volume of a storage or distribution medium, does not as a whole
- count as a <a class="link" href="#fdl-modified">Modified Version</a>
- of the Document, provided no compilation copyright is claimed
- for the compilation. Such a compilation is called an
- "aggregate", and this License does not apply to the
- other self-contained works thus compiled with the Document , on
- account of their being thus compiled, if they are not themselves
- derivative works of the Document. If the <a class="link"
href="#fdl-cover-texts">Cover Text</a> requirement of <a class="link"
href="#fdl-section3" title="3. COPYING IN QUANTITY">section 3</a> is applicable
to these
- copies of the Document, then if the Document is less than one
- quarter of the entire aggregate, the Document's Cover Texts may
- be placed on covers that surround only the Document within the
- aggregate. Otherwise they must appear on covers around the whole
- aggregate.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section8"></a>8. TRANSLATION</h2></div></div></div><p>
- Translation is considered a kind of modification, so you may
- distribute translations of the <a class="link"
href="#fdl-document">Document</a> under the terms of <a class="link"
href="#fdl-section4" title="4. MODIFICATIONS">section 4</a>. Replacing <a
class="link" href="#fdl-invariant"> Invariant Sections</a> with
- translations requires special permission from their copyright
- holders, but you may include translations of some or all
- Invariant Sections in addition to the original versions of these
- Invariant Sections. You may include a translation of this
- License provided that you also include the original English
- version of this License. In case of a disagreement between the
- translation and the original English version of this License,
- the original English version will prevail.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section9"></a>9. TERMINATION</h2></div></div></div><p>
- You may not copy, modify, sublicense, or distribute the <a class="link"
href="#fdl-document">Document</a> except as expressly
- provided for under this License. Any other attempt to copy,
- modify, sublicense or distribute the Document is void, and will
- automatically terminate your rights under this License. However,
- parties who have received copies, or rights, from you under this
- License will not have their licenses terminated so long as such
- parties remain in full compliance.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-section10"></a>10. FUTURE REVISIONS OF THIS
LICENSE</h2></div></div></div><p>
- The <a class="ulink" href="http://www.gnu.org/fsf/fsf.html";
target="_top">Free Software
- Foundation</a> may publish new, revised versions of the GNU
- Free Documentation License from time to time. Such new versions
- will be similar in spirit to the present version, but may differ
- in detail to address new problems or concerns. See <a class="ulink"
href="http://www.gnu.org/copyleft";
target="_top">http://www.gnu.org/copyleft/</a>.
- </p><p>
- Each version of the License is given a distinguishing version
- number. If the <a class="link" href="#fdl-document">Document</a>
- specifies that a particular numbered version of this License
- "or any later version" applies to it, you have the
- option of following the terms and conditions either of that
- specified version or of any later version that has been
- published (not as a draft) by the Free Software Foundation. If
- the Document does not specify a version number of this License,
- you may choose any version ever published (not as a draft) by
- the Free Software Foundation.
- </p></div><div class="sect1" lang="en"><div
class="titlepage"><div><div><h2 class="title" style="clear: both"><a
name="fdl-using"></a>Addendum</h2></div></div></div><p>
- To use this License in a document you have written, include a copy of
- the License in the document and put the following copyright and
- license notices just after the title page:
- </p><div class="blockquote"><blockquote class="blockquote"><p>
- Copyright 2008, Free Software Foundation.
- </p><p>
- Permission is granted to copy, distribute and/or modify this
- document under the terms of the GNU Free Documentation
- License, Version 1.1 or any later version published by the
- Free Software Foundation; with no<a class="link"
href="#fdl-invariant">Invariant Sections</a>, with no <a class="link"
href="#fdl-cover-texts">Front-Cover Texts</a>,
- and with no <a class="link" href="#fdl-cover-texts">Back-Cover
- Texts</a>. A copy of the license is included in
- the section entitled "GNU Free Documentation License".
- </p></blockquote></div><p>
- If your document contains nontrivial examples of program code,
- we recommend releasing these examples in parallel under your
- choice of free software license, such as the <a class="ulink"
href="http://www.gnu.org/copyleft/gpl.html"; target="_top"> GNU General Public
- License</a>, to permit their use in free software.
- </p></div></div></div></body></html>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gnash-commit] gnash ChangeLog doc/C/Makefile.am doc/C/preform... [release_0_8_2_rc1],
Sandro Santilli <=