[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnash-commit] gnash/doc/C/preformatted gnash_ref.info.in gnas...
From: |
Rob Savoye |
Subject: |
[Gnash-commit] gnash/doc/C/preformatted gnash_ref.info.in gnas... |
Date: |
Sun, 02 Mar 2008 17:54:16 +0000 |
CVSROOT: /sources/gnash
Module name: gnash
Changes by: Rob Savoye <rsavoye> 08/03/02 17:54:16
Modified files:
doc/C/preformatted: gnash_ref.info.in gnash_user.info.in
gnashref.html.in gnashuser.html.in
Log message:
Updated.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/preformatted/gnash_ref.info.in?cvsroot=gnash&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/preformatted/gnash_user.info.in?cvsroot=gnash&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/preformatted/gnashref.html.in?cvsroot=gnash&r1=1.1&r2=1.2
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/preformatted/gnashuser.html.in?cvsroot=gnash&r1=1.1&r2=1.2
Patches:
Index: gnash_ref.info.in
===================================================================
RCS file: /sources/gnash/gnash/doc/C/preformatted/gnash_ref.info.in,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- gnash_ref.info.in 2 Mar 2008 16:32:21 -0000 1.1
+++ gnash_ref.info.in 2 Mar 2008 17:54:16 -0000 1.2
@@ -1,137 +1,3473 @@
-This is gnash_ref.info, produced by makeinfo version 4.8 from
-gnashref.texi.
+START-INFO-DIR-ENTRY
+This is gnash_ref.info, produced by makeinfo version 4.11 from gnash_ref.texi.
+
+* Gnash Reference Manual: (gnash_ref). Gnash
+END-INFO-DIR-ENTRY
+
+
+File: gnash_ref.info, Node: Top, Next: Introduction, Up: (dir)
+
+Gnash Reference Manual
+**********************
+
+* Menu:
+
+* Introduction::
+* Building from Source::
+* Software Internals::
+* Reporting Bugs::
+* Gnash Extensions::
+* RTMP Protocol::
+* Mozilla/Firefox NPAPI Plugin::
+* Appendix::
+* Authors::
+* GNU Free Documentation License::
+
+--- The Detailed Node Listing ---
+
+Introduction
+
+* Audience::
+* What Is Supported ?::
+
+Building from Source
+
+* Overview::
+* Getting The Source::
+* Code Dependencies::
+* Testing Dependencies::
+* Documentation Dependencies::
+* Configuring Gnash::
+* Compiling the Code::
+* Creating the Documentation::
+* Running the Tests::
+
+Software Internals
+
+* A Tour of Gnash::
+* Sound handling in Gnash::
+* Testing : Testing.
+* Adding New ActionScript Class::
+
+Reporting Bugs
+
+* Get a Fresh Binary Package::
+* Determine if the bug was previously reported::
+* Review the bug writing guidelines::
+* Filing a bug report::
+
+Gnash Extensions
+
+* Creating A New Extension::
+* Debugging An Extension::
+* Included Extensions::
+
+RTMP Protocol
+
+* AMF Format::
+
+Mozilla/Firefox NPAPI Plugin
+
+* Plugin C API::
+* Plugin C++ API::
+* OpenGL and Threads::
+* Plugin Event Handling::
+
+Appendix
+
+* Code Style::
+
+GNU Free Documentation License
+
+* 0. PREAMBLE: 0_ PREAMBLE.
+* 1. APPLICABILITY AND DEFINITIONS: 1_ APPLICABILITY AND DEFINITIONS.
+* 2. VERBATIM COPYING: 2_ VERBATIM COPYING.
+* 3. COPYING IN QUANTITY: 3_ COPYING IN QUANTITY.
+* 4. MODIFICATIONS: 4_ MODIFICATIONS.
+* 5. COMBINING DOCUMENTS: 5_ COMBINING DOCUMENTS.
+* 6. COLLECTIONS OF DOCUMENTS: 6_ COLLECTIONS OF DOCUMENTS.
+* 7. AGGREGATION WITH INDEPENDENT WORKS: 7_ AGGREGATION WITH INDEPENDENT WORKS.
+* 8. TRANSLATION: 8_ TRANSLATION.
+* 9. TERMINATION: 9_ TERMINATION.
+* 10. FUTURE REVISIONS OF THIS LICENSE: 10_ FUTURE REVISIONS OF THIS LICENSE.
+* Addendum::
+
+
+File: gnash_ref.info, Node: Introduction, Next: Building from Source, Prev:
Top, Up: Top
+
+1 Introduction
+**************
+
+Gnash is a free SWF movie player. It is available as a stand-alone
+application or as a plugin for several popular web browsers. It
+supports playing media from a disk or streaming over a network
+connection. Some popular video sharing sites like YouTube are supported
+from a wide vaariety of devices from embedded ones to modern desktops.
+
+ Gnash has a better focus on security, allowing the user tight
+control of all network or disk based I/O. Gnash also supports extending
+ActionScript by creating your own. You can write wrappers for any
+development library, and import them into the player much like perl or
+python does.
+
+* Menu:
+
+* Audience::
+* What Is Supported ?::
+
+
+File: gnash_ref.info, Node: Audience, Next: What Is Supported ?, Up:
Introduction
+
+1.1 Audience
+============
+
+This manual is primarily focused on users interested in how to get
+Gnash installed from a package, and basic usage as a web browser
+plugin. For more technical details, please refer to the Gnash Reference
+manual.
+
+
+File: gnash_ref.info, Node: What Is Supported ?, Prev: Audience, Up:
Introduction
+
+1.2 What Is Supported ?
+=======================
+
+Gnash is known to compile for most any POSIX and ANSI C++ conforming
+system if you have all the dependent libraries installed. Systems we
+test on, and which Gnash is know to run on are Ubuntu, Fedora, Debian,
+OpenBSD, NetBSD, FreeBSD, Win32, and Darwin (OSX) primarily.
+Occasionally other platforms are built, primarily by those distribution
+maintainers. This includes BeOS, Haiku, Syllable, OS/2, Solaris,
+Slackware, and Gentoo.
+
+ Gnash is a capable of reading up to SWF v9 files and opcodes, but
+primarily supports SWF v7, with better SWF v8 and v9 support under
+heavy developement. 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.
+
+ Gnash has implemented about 80% of ActionScript v. 2.0, and has
+begun implementing ActionScript v. 3.0. Gnash supports the majority of
+Flash opcodes up to SWF version 9, and a wide sampling of ActionScript
+classes for SWF version 8.
+
+ As ActionsScript 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.
+
+ Gnash has included video support since early 2007, but this is an
+every 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: http://www.gnashdev.org/dev_snapshots
+(http://www.gnashdev.org/dev_snapshots/).
+
+ Gnash uses ffmpeg for codecs, so any file supported by Mplayer
+should work with Gnash. Gnash supports the loading of patent free
+codecs like Ogg Vorbis or Theora from disk based files, while work is
+being done to support these codecs when embedded in a SWF file. Ffmpeg
+contains the codecs used by the current SWF defintion, FLV, VP6 (ON2),
+H.263, H.264, and MP3.
+
+
+File: gnash_ref.info, Node: Building from Source, Next: Software Internals,
Prev: Introduction, Up: Top
+
+2 Building from Source
+**********************
+
+* Menu:
+
+* Overview::
+* Getting The Source::
+* Code Dependencies::
+* Testing Dependencies::
+* Documentation Dependencies::
+* Configuring Gnash::
+* Compiling the Code::
+* Creating the Documentation::
+* Running the Tests::
+
+
+File: gnash_ref.info, Node: Overview, Next: Getting The Source, Up:
Building from Source
+
+2.1 Overview
+============
+
+The typical process of building from source will involve getting the
+source (*note Getting The Source::), build dependencies (*note Code
+Dependencies::), configuration (*note Configuring Gnash::), compilation
+(*note Compiling the Code::), testing (*note Running the Tests::), and
+installation (*note Installation::). A simplified overview of the
+process would be:
+
+
+ ./autogen.sh
+ ./configure
+ make
+ make check
+ make install
+
+ If you are compiling with GCC you will 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.
+
+ At present the Gnash source is about 30 MB extracted and configured
+and requires a total of about 125 megabytes to compile it.
+
+ Continue reading for detailed step-by-step instructions of the
+entire procedure.
+
+
+File: gnash_ref.info, Node: Getting The Source, Next: Code Dependencies,
Prev: Overview, Up: Building from Source
+
+2.2 Getting The Source
+======================
+
+* Menu:
+
+* Releases::
+* CVS Access::
+
+
+File: gnash_ref.info, Node: Releases, Next: CVS Access, Up: Getting The
Source
+
+2.2.1 Releases
+--------------
+
+Tarballs of official releases can be found in the download area of the
+project's GNU Savannah page at http://savannah.gnu.org/projects/gnash
+(http://savannah.gnu.org/projects/gnash) or under
+http://ftp.gnu.org/gnu/gnash (http://ftp.gnu.org/gnu/gnash)
+
+
+File: gnash_ref.info, Node: CVS Access, Prev: Releases, Up: Getting The
Source
+
+2.2.2 CVS Access
+----------------
+
+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):
+
+
+ export CVS_RSH=ssh
+ cvs -z3 -d:pserver:address@hidden:/sources/gnash co gnash
+
+You will then be able to update your copy from the repository using
+
+
+ cd gnash
+ cvs update -d
+
+ If you only have access to the internet via a web proxy, you will
+find daily source snapshots of the latest CVS tree in
+http://www.gnashdev.org/dev_snapshots
+(http://www.gnashdev.org/dev_snapshots/)
+
+
+File: gnash_ref.info, Node: Code Dependencies, Next: Testing Dependencies,
Prev: Getting The Source, Up: Building from Source
+
+2.3 Code Dependencies
+=====================
+
+Gnash has a number of dependencies on other packages. If you install
+the dependencies using a package manager, be certain to install the
+development versions of the packages. The normal versions are often
+missing the headers Gnash needs to compile.
+
+ 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.
+
+*Code Dependency Table*
+
+Name Level Version DescriptionExplanationapt-get RPM/Yum
+ package packageBSD
+ package
+Boost Required 1.32 or Boost is In Gnash, `libboost-thread-dev,`
+ higher a library Boost
libboost-date-time-devlibboost-thread-devel,
+ of libraries
libboost-devlibboost-date-time-devel
+ portable are used ' '`
+ C++ extensively,
boost-headers,
+ classes primarily boost-libs,
+ and boost-gthread or just
+ templates. and boost '
+ boost-date-time.
+ Boost is
+ used for
+ thread
+ and mutext
+ handling.
+libxml2 Required Libxml2 This
`libxml2-dev'`libxml2-devel'`libxml2'
+ is the library
+ GNOME XML is used
+ parser to parse
+ library messages
+ and is for the
+ available XML
+ at XMLNode,
+ http://xmlsoft.orgor
+ (http://xmlsoft.org).XMLSocket
+ ActionScript
+ classes.
+AGG Possibly 2.4 or AGG is Gnash
`libagg-dev'`agg-devel'`agg'
+ Required higher the requires
+ AntiGrain the
+ low-level installation
+ 2D of at
+ graphics least one
+ library. renderer.
+ AGG is
+ considered
+ the _best
+ supported_
+ renderer
+ for Gnash.
+OpenGL Possibly OpenGL Gnash
`libgl1-mesa-dev'`libmesa-devel'`mesa'
+ Required is a requires
+ standard the
+ specificationinstallation
+ defining a of at
+ cross-languageleast one
+ cross-platformrenderer.
+ API for If you
+ writing don't
+ applicationshave a
+ which hardware
+ produce accelerated
+ 3D and 2D driver,
+ graphics. you're
+ It better
+ supports off using
+ hardware AGG for
+ acceleration.the
+ You can renderer.
+ download
+ a free
+ implementation
+ from
+ http://www.mesa3d.org
+ (http://www.mesa3d.org),
+ although
+ it
+ doesn't
+ support
+ hardware
+ acceleration.
+Cairo Possibly Cairo is Gnash
`libcairo2-dev'`cairo-devel'`cairo'
+ Required a 2D requires
+ graphics the
+ library installation
+ with of at
+ support least one
+ for renderer.
+ multiple Cairo is
+ output considered
+ devices. the
+ It will _least
+ automaticallysupported_
+ use renderer
+ graphic for Gnash.
+ card
+ acceleration
+ when
+ available,
+ and has
+ an
+ experimental
+ OpenGL
+ backend.
+GTK Possibly 2.2 or GTK is Gnash
`libgtk2.0-dev'`gtk-devel'`gtk+2'
+ Required higher the GIMP requires
+ Toolkit the
+ GUI installation
+ library of at
+ used by least one
+ the GNOME GUI
+ desktop. library.
+ It uses GTK is
+ Cairo considered
+ internally.to be the
+ Gtk _best
+ enables supported_
+ better GUI
+ integrationlibrary
+ with option
+ Firefox, for Gnash.
+ as well
+ as better
+ event
+ handling
+ and
+ higher
+ level GUI
+ constructs
+ like
+ menus and
+ dialog
+ boxes.
+GtkGlExt Possibly GtkGlExt This
`libgtkglext1-dev'`gtkglext-devel'`gtkglext'
+ Required integrates library
+ OpenGL is
+ into GTK. required
+ in order
+ to use
+ the GTK
+ GUI
+ library
+ in
+ conjunction
+ with the
+ OpenGL
+ renderer.
+SDL Possibly The Gnash
`libsdl1.2-dev'`SDL-devel'`SDL-1.2'
+ Required Simple requires
+ DirectMediathe
+ Layer is installation
+ a of at
+ cross-platformleast one
+ multimedia GUI
+ library library.
+ which SDL may
+ provides also be
+ abstractionused as a
+ for sound
+ audio, handler
+ graphics, regardless
+ sound and of
+ input whether
+ APIs. it is
+ SDL is employed
+ available as a GUI
+ from library.
+ http://www.libsdl.orgThe GUI
+ (http://www.libsdl.org).library
+ is
+ _poorly
+ supported_
+ in Gnash,
+ but the
+ sound
+ handler
+ is the
+ _best
+ supported_
+ in Gnash.
+FLTK Possibly 2.0 or The Fast Gnash No No
+ Required higher Light requires distributiondistribution
+ ToolKit the packages packages
+ is a installationare are
+ portable of at available. available.No
+ GUI least one distribution
+ library GUI packages
+ which is library. are
+ intended FLTK may available.
+ as a be used
+ replacementin
+ for the conjunction
+ SDL GUI. with the
+ Cairo and
+ AGG
+ renderers.
+KDE Possibly Kdelibs Gnash
`kdelibs3-dev,`kdelibs-devel,
+ Required is a requires
kdebase-dev'kdebase-devel'`kdelibs,
+ collection the kdebase'
+ of installation
+ libraries of at
+ needed to least one
+ compile GUI
+ KDE library.
+ applications.Kdelibs
+ is also
+ required
+ for the
+ Kpart
+ plugin
+ for
+ Konqueror.
+Gstreamer Optional Gstreamer If you
`libgstreamer0.8-dev'`gstreamer-devel'`gstreamer-0.10'
+ is a would
+ video like
+ handler. video
+ playback,
+ you must
+ install
+ one of
+ the video
+ handlers.
+gst-ffmpeg Possibly gst-ffmpegThis
`gstreamer0.8-ffmpeg-dev'`gstreamer-ffmpeg-devel'`gstreamer-ffmpeg'
+ Required allows package
+ you to is
+ use the required
+ FFMPEG if you
+ decoder would
+ with like to
+ Gstreamer. use
+ Gstreamer
+ as a
+ video
+ handler.
+FFMPEG Possibly FFMPEG If you
`ffmpeg-dev'`ffmpeg-devel'`ffmpeg'
+ Required is a would
+ video like
+ handler. video
+ playback,
+ you must
+ install
+ one of
+ the video
+ handlers.
+ When
+ using the
+ gstreamer-ffmpeg
+ plugin,
+ ffmpeg
+ doesn't
+ need to be
+ installed,
+ as it's
+ part of
+ the
+ plugin.
+ For
+ systems
+ without
+ Gstreamer
+ support,
+ ffmpeg
+ can be
+ used
+ directly.
+JPEG Optional JPEG This
`libjpeg62-dev'`libjpeg'`jpeg'
+ (http://www.ijg.org/)library
+ is a is used
+ lossy for
+ image rendering
+ format JPEGs.
+ which is
+ heavily
+ used for
+ images.
+PNG Optional PNG This
`libpng12-dev'`libpng'`png'
+ (http://www.libpng.org/pub/png/)library
+ is a is used
+ patent-freefor
+ image rendering
+ format PNGs.
+ which is
+ comparable
+ to _GIF_.
+libcurl Optional libcurl This
`libcurl4-gnutls'`libcurl'`curl'
+ is the library
+ multiprotocalis used
+ file for URL
+ transfer downloading.
+ library.
+Glib2 Optional Glib2 is This
`glib2-dev'`glib2-devel'`glib2'
+ a library
+ dependency is used
+ of Gtk, for
+ and is a convenience.
+ collection
+ of
+ commonly
+ used
+ functions.
+Atk Optional Atk is a This `atk-dev'
`atk-devel'`atk'
+ dependency library
+ of Gtk, is used
+ and is for
+ used for accessiblity..
+ accessibility
+ support.
+Pango Optional Pango is This
`pango-dev'`pango-devel'`pango'
+ a library
+ dependency is used
+ of Gtk, for font
+ and is handling.
+ used for
+ font
+ handling.
+automake Possibly 1.6.0 Automake This `automake'
`automake'`automake'
+ Required is a tool package
+ for is
+ generating required
+ _Makefile.in_to run
+ files. _autogen.sh_,
+ which is
+ a
+ requirement
+ if you
+ are using
+ the
+ development
+ source
+ from CVS.
+autoconf Possibly 2.59 Autoconf This `autoconf'
`autoconf'`autoconf'
+ Required is a package
+ package is
+ for required
+ generating to run
+ configure _autogen.sh_,
+ scripts. which is
+ a
+ requirement
+ if you
+ are using
+ the
+ development
+ source
+ from CVS.
+gettext Possibly 0.14.6 Gettext This `gettext'
`gettext'`gettext'
+ Required is part package
+ of the is
+ GNU required
+ Translationto run
+ Project. _autogen.sh_,
+ which is
+ a
+ requirement
+ if you
+ are using
+ the
+ development
+ source
+ from CVS.
+libtool Possibly 1.5.22 This is This
`libltdl3-dev'`libtool'`libtool'
+ Required a generic package
+ library is
+ support required
+ script. to run
+ _autogen.sh_,
+ which is
+ a
+ requirement
+ if you
+ are using
+ the
+ development
+ source
+ from CVS.
+
+
+File: gnash_ref.info, Node: Testing Dependencies, Next: Documentation
Dependencies, Prev: Code Dependencies, Up: Building from Source
+
+2.4 Testing Dependencies
+========================
+
+Gnash tries to run as many tests as possible, but will simply skip
+tests if the tools to run them are unavailable.
+
+*Testing Dependency Table*
+
+Name Level Version DescriptionExplanationapt-get RPM/Yum
+ package packageBSD
+ package
+Ming Optional 0.4.0_beta4 Ming is Ming is No No
+ or higher an the distributiondistribution
+ ActionScriptprimary packages packages
+ compiler. compiler are are
+ for available. available.No
+ ActionScript distribution
+ testcases. packages
+ are
+ available.
+Mtasc Optional 1.12 or Mtasc is Mtasc is `mtasc' No
+ higher an used in distribution
+ ActionScriptsome packages
+ compiler. tests. are
+ available.No
+ distribution
+ packages
+ are
+ available.
+swfc Optional part of Swfc a Swfc is No No
+ swftools swf used in distributiondistribution
+ 0.8.1 decompiler.some packages packages
+ testcases. are are
+ available. available.No
+ distribution
+ packages
+ are
+ available.
+swfmill Optional 0.2.12 Swfmill Swfmill No No
+ is an is used distributiondistribution
+ XML-based in some packages packages
+ SWF testcases. are are
+ (Shockwave available. available.No
+ Flash) distribution
+ processing packages
+ tool. are
+ available.
+Python Optional 2.4 or Python Python is `python'
`python'`python'
+ higher is a used by
+ scripting part of
+ language. the
+ testing
+ framework.
+DejaGnu Optional 1.4 or DejaGnu DejaGnu `dejagnu'
`dejagnu'`dejagnu'
+ higher is a is used
+ testing to run
+ framework. multiple
+ tests in
+ an
+ automated
+ fashion.
+
+
+File: gnash_ref.info, Node: Documentation Dependencies, Next: Configuring
Gnash, Prev: Testing Dependencies, Up: Building from Source
+
+2.5 Documentation Dependencies
+==============================
+
+The following packages are used to build Gnash's documentation.
+
+*Documentation Dependency Table*
+
+Name Level Version DescriptionExplanationapt-get RPM/Yum
+ package packageBSD
+ package
+Docbook Required Docbook Gnash
`docbook-utils'`docbook-dtd41-sgml'
+
(http://http://docbook.sourceforge.net/)documentationand and
+ is is an is
`docbook-dsssl'`docbook-style-dsssl'docbook
+ industry-standardwritten
+ XML in
+ format Docbook.
+ for
+ technical
+ documentation.
+ You can
+ download
+ it from
+
http://sourceforge.net/project/showfiles.php?group_id=21935#files
+
(http://sourceforge.net/project/showfiles.php?group_id=21935#files).
+DocBook2X Optional This DocBook2X
`docbook2x'`docbook2x'`docbook2x'
+ software is
+ package required
+ converts to
+ Docbook produce
+ documents HTML and
+ to the Texinfo
+ traditionalformats.
+ man page
+ format,
+ GNU
+ Texinfo
+ format,
+ and HTML
+ (via
+ Texinfo)
+ format.
+ It is
+ available
+ at
+ http://docbook2x.sourceforge.net/
+ (http://docbook2x.sourceforge.net/).
+DocBook-utilsOptional This
DocBook-utils`docbook-utils'`docbook-utils'`docbook-utils'
+ software is
+ package required
+ converts to
+ Docbook produce
+ documents HTML and
+ to the Texinfo
+ traditionalformats.
+ man page
+ format,
+ GNU
+ Texinfo
+ format,
+ and HTML
+ (via
+ Texinfo)
+ format.
+Texinfo Possibly Texinfo Texinfo `texinfo'
`texinfo'`texinfo'
+ Required can be is
+ used to required
+ convert if you
+ DocBook2X wish to
+ output product
+ into GNU GNU info
+ info pages.
+ pages.
+ You can
+ download
+ it from
+ http://ftp.gnu.org/gnu/texinfo/
+ (http://ftp.gnu.org/gnu/texinfo/).
+FOP Optional 0.20.5 FormattingFOP is `fop' `fop'`fop'
+ Objects required
+ Processor for PDF
+ is a output.
+ print
+ formatter
+ driven by
+ XSL
+ formatting
+ objects.
+ It is a
+ Java
+ application
+ which can
+ output
+ PDF, PCL,
+ PS, SVG,
+ XML,
+ Print,
+ AWT, MIF,
+ and Text.
+ It is
+ available
+ at
+ http://xmlgraphics.apache.org/fop/
+ (http://xmlgraphics.apache.org/fop/).
+Java Possibly FOP Sun's Download Download
+(j2re) Required requires Java the the
+ Sun's runtime package package
+ Java (j2re) is from Sun from Sun
+ runtime required
(http://java.sun.com).(http://java.sun.com).
+ (GCJ does to use
+ not work FOP.
+ with
+ FOP).
+ You can
+ download
+ it from
+ http://java.sun.com
+ (http://java.sun.com).
+JAI Possibly Sun's JAI is Download Download
+ Required Java required the the
+ Advanced if you package package
+ Imaging wish to from Sun from Sun
+ API can include
(http://java.sun.com/products/java-media/jai/iio.html).(http://java.sun.com/products/java-media/jai/iio.html).
+ be graphics
+ downloaded in a PDF
+ from file being
+
http://java.sun.com/products/java-media/jai/iio.htmlgenerated
+
(http://java.sun.com/products/java-media/jai/iio.html).with FOP.
+
+ If you install j2re, set the _JAVA_HOME_ environment variable to the
+top directory of the j2re installation. If you encounter problems with
+the Java installation, you may also need to add this path to the
+_CLASSPATH_ environment variable.
+
+
+File: gnash_ref.info, Node: Configuring Gnash, Prev: Documentation
Dependencies, Up: Building from Source
+
+2.6 Configuring Gnash
+=====================
+
+Gnash, like most GNU projects, allows a user to select various options
+before compiling its source code. These options include selecting from
+the available features, specifying custom paths for installation, and
+cross compiling support uses GNU Autoconf
+(http://www.gnu.org/software/autoconf/) for configuration.
+
+ If you opted to download the development snapshot of Gnash, the
+_configure_ script will not be included. It can be created by running
+_autogen.sh_ from the source root directory:
+
+
+ ./autogen.sh
+
+Note that there are some dependencies (*note Code Dependencies::) for
+autogen.
+
+ All the standard `configure' options are available. In addition,
+Gnash has two types of options: those that enable or disable features
+(*note Features::), and those that specify custom paths for development
+packages (*note Specifying Custom Paths::) which are not found during
+the default search. A complete list of _all_ configuration options,
+including standard ones, can be seen by typing:
+
+
+ ./configure --help | less
+
+Read further for a more detailed explanation of Gnash-specific options.
+
+ The syntax for running _configure_ is as follows:
+
+
+ configure <options>
+
+The example below shows the `configure' options which create the
+smallest working standalone version of Gnash. In this example,
+`configure' is being run from the source root directory:
+
+
+ ./configure --disable-debugger --disable-cygnal \
+ --disable-plugin --enable-media=ffmpeg --enable-gui=sdl
+
+ By default, you shouldn't need to supply any options to configure.
+The configure script will attempt to determine what to build based on
+the development libraries you have installed. The default configuration
+for Gnash is both GTK and KDE GUIs, the AGG renderer, and Gstreamer for
+multimedia support, with no extensions built.
+
+ Being highly portable, Gnash has many configuration options
+available, and not all are supposed to work together. A common mistake
+when configuring Gnash is to supply too many options, overdriving
+Gnash's ability to do the right thing.
+
+* Menu:
+
+* Features::
+* Specifying Custom Paths::
+
+
+File: gnash_ref.info, Node: Features, Next: Specifying Custom Paths, Up:
Configuring Gnash
+
+2.6.1 Features
+--------------
+
+Some switches can be used during configuration to enable or disable
+features of Gnash. Some of the most important configuration options are:
+
+ * `--enable-gui' lets you specify your GUI of choice. The default
+ option is GTK.
+
+ * `--enable-renderer' allows a renderer to be chosen. The default
+ renderer is AGG.
+
+ * `--enable-media' permits a media handler to be selected. The
+ default is Gstreamer.
+
+ A complete list of available features follows.
+
+*Configuration Options - Features*
+
+Option Function
+`--enable-debugger' Enable support for the Flash
+ debugger. The debugger is mainly of
+ interest to Flash developers, and
+ is still under development.
+`--enable-lirc' Enable support for the LIRC remote
+ control protocol.
+`--enable-cygnal' Build the Cygnal streaming media
+ server.
+`--disable-menus' Disable building all the menus for
+ the GUI. THis is used by mobile
+ devices without as much screen
+ space.
+`--enable-docbook' Enable the generation of HTML,
+ INFO, and MAN versions of the
+ documentation from the Docbook XML.
+ You will then be able to use `make
+ html', `make info', and `make man'
+ commands. By default, man,info and
+ html pages are generated.
+`--enable-gui=gtk|sdl|kde|fltk|fb|hildon|alp'Select the Graphic User Interface
+ to use (choose one).?
+ [undisplayable block object]
+`--enable-i810-lod-bias' Enable fix for Intel 810 LOD bias
+ problem. Older versions of libMesa
+ on the Intel i810 or i815 graphics
+ processor need this flag or Gnash
+ will core dump. This has been fixed
+ in newer versions (summer 2005) of
+ libMesa.
+`--enable-media=ffmpeg|gst|none' Select the specified media decoder
+ and sound engine. FFMPEG uses the
+ SDL sound engine; GST uses its own.
+ `GST' is the default decoder. ?
+ [undisplayable block object] You
+ should only select one media
+ decoder.
+`--disable-nsapi'`--enable-nsapi' Force disable/enable building the
+ NPAPI plugin. By default the
+ Mozilla plugin is built if the GTK
+ gui is selected. Specify the
+ `--with-npapi-plugindir=' option to
+ specify where the plugin should be
+ installed.
+`--disable-kparts'`--enable-kparts' Force disable/enable building the
+ KPARTS plugin. By default the KDE
+ plugin is built if the kde gui is
+ selected. Specify the
+ `--with-kde-plugindir=' and
+ `--with-kde-servicesdir=' options
+ (or more generally the
+ `--with-kde-pluginprefix=' one) to
+ specify where the plugin should be
+ installed. The default installation
+ dir is extracted from kde-config.
+`--disable-plugins' Disable build of both kparts and
+ npapi plugins
+`--enable-renderer=opengl|cairo|agg' Enable support for the a graphics
+ backend. Currently only `opengl' and
+ `agg' 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.
+`--enable-sdk-install' Enable installing the libraries and
+ headers as an SDK.
+`--disable-shared' Enable installing the shared
+ libraries and headers. Note that
+ the extensions mechanism may not
+ work if shared libraries are
+ disabled.
+`--enable-strict' Turn verbose GCC compiler warnings.
+ By default only `-Wall' is used
+ with GCC.
+`--enable-fps-debug' Enable FPS debugging code. When
+ this feature is compiled in you can
+ use the -f switch of Gnash to have
+ FPS printed at regular intervals.
+`--enable-write' Makes the Mozilla plugin write the
+ currently playing SWF movie to
+ `/tmp'.
+`--disable-mit-shm' Disable support for the MIT-SHM X
+ extensions. Currently support is
+ only available using GTK gui and
+ AGG renderer. Keeping it enabled
+ is not a problem as it will not be
+ used if not available in the
+ current X session.
+
+
+File: gnash_ref.info, Node: Specifying Custom Paths, Prev: Features, Up:
Configuring Gnash
+
+2.6.2 Specifying Custom Paths
+-----------------------------
+
+By default, none of these options should be required unless you want
+Gnash to use a specific version of a development package, or if the
+configure test fails to find a component. Please report the problem
+(*note Reporting Bugs::) if a configure test fails.
+
+ The following custom path options are available:
+
+*Custom Path Options*
+
+Option Function
+`--x-includes=DIR' X include files are in DIR.
+`--x-libraries=DIR' X library files are in DIR.
+`--with-libxml=PFX' Prefix to where libxml is
+ installed.
+`--with-libxml-libraries=DIR' Directory where libxml library is
+ installed.
+`--with-libxml-includes=DIR' Directory where libxml header
+ files are installed.
+`--with-docbook=DIR' Directory where the DocBook
+ style-sheets are installed.
+`--with-sdl-prefix=PFX' Prefix where SDL is installed.
+`--with-zlib-incl' Directory where zlib header is
+ installed.
+`--with-zlib-lib' Directory where zlib library is
+ installed.
+`--with-jpeg-incl' Directory where jpeg header is
+ installed.
+`--with-jpeg-lib' Directory where jpeg library is
+ installed.
+`--with-png-incl' Directory where png header is
+ installed.
+`--with-png-lib' Directory where png library is
+ installed.
+`--with-qt-dir' Directory where QT is installed.
+ This is only used by the Klash
+ plugin.
+`--with-qt-includes' Directory where the QT header
+ files are installed. This is only
+ used by the Klash plugin.
+`--with-qt-libraries' Directory where the QT libraries
+ are installed. This is only used by
+ the Klash plugin.
+`--with-npapi-plugindir' This is the directory to install
+ the NPAPI (Mozilla) plugin in. By
+ default it goes to
+ ~/.mozilla/plugins.
+`--with-kde-pluginprefix' This option sets the default
+ install dir for all KPARTS (kde)
+ files. The plugin will be
+ installed in PREFIX/lib/kde3, use
+ `-with-kde-plugindir' to override.
+ The service file in
+ PREFIX/share/services, use
+ `--with-kde-servicesdir' to
+ override. The config file in
+ PREFIX/share/config, use
+ `--with-kde-configdir' to override.
+ The appdata file in
+ PREFIX/share/apps/klash, use
+ `--with-kde-appsdatadir' to
+ override.
+`--with-kde-plugindir' This is the directory to install
+ the KPARTS (kde) plugin in. By
+ default it is what's set by
+ -with-kde-pluginprefix or what's
+ returned by kde-config -install
+ module -expandvars, or
+ $(prefix)/share/services if
+ kde-config is not found.
+`--with-kde-servicesdir' This is the directory to install
+ the KPARTS (kde) service in. By
+ default it is what's set by
+ -with-kde-pluginprefix or what's
+ returned by kde-config -install
+ services -expandvars, or
+ $(libdir)/kde3 if kde-config is not
+ found.
+`--with-kde-configdir' This is the directory to install
+ the KPARTS (kde) config files in.
+ By default it is what's set by
+ -with-kde-pluginprefix or what's
+ returned by kde-config -install
+ config -expandvars, or
+ $(prefix)/share/config if
+ kde-config is not found.
+`--with-kde-appsdatadir' This is the directory to install
+ the KPARTS (kde) application data
+ files in. By default it is what's
+ set by -with-kde-pluginprefix or
+ what's returned by kde-config
+ -install data -expandvars, or
+ $(prefix)/share/apps if kde-config
+ is not found.
+`--with-ming' Ming is used to build test cases,
+ but not by the Gnash player itself.
+`--with-ogg_incl' Directory where the libogg headers
+ are installed.
+`--with-ogg_lib' Directory where the libogg library
+ is installed.
+`--with-gstreamer-incl' Directory where the Gstreamer
+ headers are installed. Gstreamer
+ version 0.10 or greater must be
+ used.
+`--with-gstreamer-lib' Directory where the Gstreamer
+ library is installed. Gstreamer
+ version 0.10 or greater must be
+ used.
+`--with-opengl-includes' Directory where OpenGL (libMesa)
+ headers are installed.
+`--with-opengl-lib' Directory where the OpenGL
+ (libMesa) library is installed.
+`--with-glext-incl' Directory where GtkGlExt headers
+ are installed.
+`--with-glext-lib' Directory where the GtkGlExt
+ library is installed.
+`--with-gtk2-incl' Directory where the Gtk2 headers
+ are installed.
+`--with-gtk2-lib' Directory where the Gtk2 library
+ is installed.
+`--with-cairo_incl' Directory where the Cairo headers
+ are installed.
+`--with-cairo-lib' Directory where the Cairo library
+ is installed.
+`--with-glib-incl' Directory where the Glib headers
+ are installed.
+`--with-glib-lib' Directory where the Glib library
+ is installed.
+`--with-pango-incl' Directory where the Pango headers
+ are installed.
+`--with-pango-lib' Directory where the Pango library
+ is installed.
+`--with-atk-incl' Directory where the ATK headers
+ are installed.
+`--with-atk-lib' Directory where the ATK library is
+ installed.
+`--with-pthread-incl' Directory where the Pthread
+ headers are installed.
+`--with-pthread-lib' Directory where the Pthread
+ library is installed.
+`--with-agg-incl' Directory where the AGG
+ (Antigrain) headers are installed.
+`--with-agg-lib' Directory where the AGG
+ (Antigrain) library is installed.
+`--with-ffmpeg-incl' Directory where the FFMPEG headers
+ are installed.
+`--with-ffmpeg-lib' Directory where the FFMPEG library
+ is installed.
+`--with-boost-incl' Directory where the Boost headers
+ are installed.
+`--with-boost-lib' Directory where the Boost library
+ is installed.
+`--with-curl-incl' Directory where the libCurl
+ headers are installed.
+`--with-curl-lib' Directory where the libCurl
+ library is installed.
+
+ Once you have Gnash configured, you are ready to build the code.
+Gnash is built using _GNU make_.
+
+* Menu:
+
+* Overview::
+* Getting The Source::
+* Code Dependencies::
+* Testing Dependencies::
+* Documentation Dependencies::
+* Configuring Gnash::
+* Compiling the Code::
+* Creating the Documentation::
+* Running the Tests::
+
+
+File: gnash_ref.info, Node: Compiling the Code, Next: Creating the
Documentation, Up: Building from Source
+
+2.7 Compiling the Code
+======================
+
+The most basic way to compile code is simply:
+
+
+ make
+
+If the compilation ends with an error, check the output of _configure_
+and ensure that you are not missing any required prerequisites. The
+output of `make' can be verbose; you may wish to pipe the output to a
+file.
+
+ The variables used by `make' can be redefined when the program is
+invoked, if you desire it. The most interesting flags are _CFLAGS_
+and _CXXFLAGS_, which are often used to enable debugging or turn of
+optimization. The default value for both of these variables is _-O2
+-g_. A list of influential environment variables can be seen in the
+configuration help:
+
+ ./configure --help
+
+ In the following example, debugging is enabled and optimization is
+disabled:
+
+ make CFLAGS=-g CXXFLAGS=-g
+
+
+File: gnash_ref.info, Node: Creating the Documentation, Next: Running the
Tests, Prev: Compiling the Code, Up: Building from Source
+
+2.8 Creating the Documentation
+==============================
+
+By default, documentation is not built when you install (*note
+Installation::) Gnash. This is because there are a number of
+dependencies for the documentation (*note Documentation
+Dependencies::). Documentation is built when it is specified with a
+specific target in the generated `Makefile' in the `doc/C'
+sub-directory. If you type `make install' in this directory, all
+documents will be built.
+
+ You must specify a target output format when you wish to create
+documentation. The available output formats are: `html', `pdf', `info',
+`man', and `alldocs'. It is also possible to output `GNOME help' if
+the configure option (*note Features::) `--enable-ghelp' was used. The
+`alldocs' target will build all output formats except _GNOME help_.
+For example, to create HTML output, type:
+
+
+ make html
+
+ Gnash also uses Doxygen
+(http://www.stack.nl/~dimitri/doxygen/index.html) to produce _HTML_
+documentation of Gnash internals. You must have Doxygen installed to
+produce this documentation, which is built from the `doc' directory
+with the command (documents will be placed in the subdirectory
+`apidoc/html'):
+
+
+ make apidoc
+
+
+File: gnash_ref.info, Node: Running the Tests, Prev: Creating the
Documentation, Up: Building from Source
+
+2.9 Running the Tests
+=====================
+
+Before beginning the potentially lengthy install, it is wise to test
+the installation. If a test fails, please report it by following the
+instructions for reporting a bug (*note Reporting Bugs::).
+
+* Menu:
+
+* Using DejaGnu::
+* Running The Tests Manually::
+* Installation::
+* Cross Configuring::
+
+
+File: gnash_ref.info, Node: Using DejaGnu, Next: Running The Tests Manually,
Up: Running the Tests
+
+2.9.1 Using DejaGnu
+-------------------
+
+The easiest way to run Gnash's test suite is to install _DejaGnu
+(http://www.gnu.org/software/dejagnu)_. After installing DejaGnu, run:
+
+
+ make check
+
+* Menu:
+
+* Increasing Verbosity::
+* Running Some Tests::
+
+
+File: gnash_ref.info, Node: Increasing Verbosity, Next: Running Some Tests,
Up: Using DejaGnu
+
+2.9.1.1 Increasing Verbosity
+............................
+
+If you encounter a problem with a test, increasing the verbosity may
+make the issue easier to spot. Additional details are visible when
+_RUNTESTFLAGS_ are used to add the _verbose_ and _all_ options. The
+`verbose' option prints more information about the testing process,
+while the `all' option includes details on passing tests.
+
+
+ make check RUNTESTFLAGS="-v -a"
+
+
+File: gnash_ref.info, Node: Running Some Tests, Prev: Increasing Verbosity,
Up: Using DejaGnu
+
+2.9.1.2 Running Some Tests
+..........................
+
+It is possible to run just a single test, or a subdirectory of tests,
+by specifying the directory or compiled test file.
+
+ Some tests rely on _testsuite/Dejagnu.swf_, which in turn relies on
+_Ming_. This file is created when you run `make check' for the entire
+testsuite, and can also be created on demand:
+
+
+ make -C testsuite Dejagnu.swf
+
+ In this example, the `clip_as_button2' test is compiled and run:
+
+
+ make -C testsuite/samples clip_as_button2-TestRunner
+ cd testsuite/samples && ./clip_as_button2-TestRunner
+
+This creates and runs all the tests in the directory `movies.all':
+
+
+ make -C testsuite/movies.all check
+
+
+File: gnash_ref.info, Node: Running The Tests Manually, Next: Installation,
Prev: Using DejaGnu, Up: Running the Tests
+
+2.9.2 Running The Tests Manually
+--------------------------------
+
+You may also run test cases by hand, which can be useful if you want to
+see all the debugging output from the test case. Often the messages
+which come from deep within Gnash are most useful for development.
+
+ The first step is to compile the test case, which can be done with
+`make XML-v#.swf' where the '#' is replaced with the _target_ SWF
+version or versions. For example:
+
+
+ make XML-v{5,6,7,8}.swf
+
+* Menu:
+
+* Movie tests::
+* ActionScript Unit Tests::
+
+
+File: gnash_ref.info, Node: Movie tests, Next: ActionScript Unit Tests, Up:
Running The Tests Manually
+
+2.9.2.1 Movie tests
+...................
+
+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 Gnash:
+
+
+ gnash -v XML-v6.swf
+
+
+File: gnash_ref.info, Node: ActionScript Unit Tests, Prev: Movie tests, Up:
Running The Tests Manually
+
+2.9.2.2 ActionScript Unit Tests
+...............................
+
+Unit tests for ActionScript classes in `testsuite/actionscript.all' are
+run without a graphical display:
+
+
+ gprocessor -v XML-v6.swf
+
+
+File: gnash_ref.info, Node: Installation, Next: Cross Configuring, Prev:
Running The Tests Manually, Up: Running the Tests
+
+2.9.3 Installation
+------------------
+
+Now that Gnash has been compiled and tested, use the following command
+to install it:
+
+
+ make install
+
+The above command installs the standalone player. If the correct files
+were found by `configure' and if the `--disable-plugin' option was not
+specified, the Gnash browser plugin is also installed.
+
+ Gnash installs a number of libraries (*note Libraries::), namely:
+_libgnashbase_, _libgnashamf_, _libgnashmedia_, _libserver_, and
+_libgnashplugin_. Executables (*note Executables::) consist of the
+(optional) plugin, `gprocessor', `cygnal', `dumpshm', `soldumper', and
+`gnash'. Documentation (*note Documentation::) may also be installed.
+The installation location is controlled with the _-prefix_ configure
+option (*note Specifying Custom Paths::), except for plugins, which are
+explicitly set with _-plugin-dir_.
+
+ Note that if you are using a single file-system _NFS_ mounted to
+multiple platforms, the configuration option (*note Specifying Custom
+Paths::) _-exec-prefix_ may be used to specify where platform-dependent
+executables and libraries are installed.
+
+* Menu:
+
+* Libraries::
+* Executables::
+* Documentation::
+
+
+File: gnash_ref.info, Node: Libraries, Next: Executables, Up: Installation
+
+2.9.3.1 Libraries
+.................
+
+Installed libraries are located in `/usr/local/lib' by default. If the
+_-prefix_ option was used during the configuration step, the libraries
+will be installed in the directory `lib' inside the path you specified.
+If the libraries are stored in a non-standard location, you must
+identify the path in one of two ways.
+
+ The traditional way to do this on UNIX platforms is to set the
+_LD_LIBRARY_PATH_ variable to the path plus `/lib'. For example, if you
+installed in `/home/gnash', the _LD_LIBRARY_PATH_ path would be
+`/home/gnash/lib'. Multiple paths are delimited with a colon (':').
+
+ GNU/Linux allows the custom path to be added to `/etc/ld.so.conf'.
+After adding the path, run _ldconfig_ as root to update the runtime
+cache.
+
+
+File: gnash_ref.info, Node: Executables, Next: Documentation, Prev:
Libraries, Up: Installation
+
+2.9.3.2 Executables
+...................
+
+The Mozilla plugin is built from headers (the Mozilla SDK) provided
+with Gnash and does not need extra development packages to be
+installed. By default, the plugin is installed to
+`~/.mozilla/plugins/'. To enable the plugin for other users, copy the
+file `libgnashplugin.so' to `.mozilla/plugins/' in their home directory.
+You may also specify the plugin installation directory by using the
+`--with-plugindir' option at configuration time (*note Specifying
+Custom Paths::).
+
+ These defaults are likely to change in future versions of Gnash.
+
+ The remaining executables are installed in the `bin' subdirectory of
+the directory specified by during configuration. If no path was
+specified, the default is `/usr/local/bin'.
+
+
+File: gnash_ref.info, Node: Documentation, Prev: Executables, Up:
Installation
+
+2.9.3.3 Documentation
+.....................
+
+Documentation is not built by default; please refer to the section on
+documentation (*note Creating the Documentation::) for more information
+on building documentation.
+
+ `man' and `info' are installed in `/usr/local/share/man' and
+`/usr/local/share/info' respectively, unless the `--mandir' or
+`--infodir' configuration options (*note Specifying Custom Paths::) are
+used.
+
+ _GNOME help_ documentation uses the directory
+`/usr/local/share/gnash/doc/gnash/C/' by default. A configuration file
+in the Gnash source tree, `doc/C/gnash.omf' is used to specify under
+which menu item Gnash appears in the _GNOME help_ system.
+
+
+File: gnash_ref.info, Node: Cross Configuring, Prev: Installation, Up:
Running the Tests
+
+2.9.4 Cross Configuring
+-----------------------
+
+To cross configure and compile Gnash, begin by building a target system
+on your workstation. This includes cross compilers for the target
+architecture, and some system headers. You will also need to cross
+compile all the dependencies (*note Documentation Dependencies::)
+normally needed to build Gnash. This can on occasion be a daunting
+process, as not all libraries will cross configure and cross compile.
+There is more information about cross compiling all the dependant
+packages on the http://www.gnashdev.org (http://www.gnashdev.org) web
+site.
+
+ If you need to build your own tool chain, that is beyond the scope
+of this manual. There are various resources on the web for howto's on
+building GCC based cross toolchains. Two popular sites are
+http://frank.harvard.edu/~coldwell/toolchain/
+(http://frank.harvard.edu/~coldwell/toolchain/) and
+http://www.kegel.com/crosstool/ (http://www.kegel.com/crosstool/). This
+can also be a very time consuming and frustrating process, even for
+experienced developers.
+
+ Because the process of building your own cross tool chain can be
+harder than one may wish, there are several other cross development
+environments that simulate a native environment to make it easier to
+develop. These also let you develop for both native and cross builds.
+Several popular ones are Access Linux Platform
+(http://www.access-company.com/products/linux/alp.html), Scratchbox
+(http://www.scratchbox.org/), Open Embedded
+(http://www.openembedded.org/), Maemo (http://maemo.org/).
+
+ To build for an ARM based system on an x86 based systems, configure
+like this using the traditional style cross toolchain, configure like
+this:
+
+
+ ../../gnash/configure --build=i686-pc-linux-gnu
+ --host=arm-linux --prefix=/usr/local/arm/oe --disable-nsapi
+ --disable-kparts --enable-gui=fb --enable-renderer=agg
+ --disable-shared --disable-menus
+
+ The important configuration options are the ones which specify the
+architecture for the build:
+
+-target
+ The target architecture, where the final executables are expected
+ to run.
+
+-host
+ The host architecture, where the executables are expected to run.
+ Usually this is the same as the _-target_, except when building a
+ compiler as a Canadian Cross. In this case, you might build a
+ cross compiler on a UNIX system which runs on a win32 machine,
+ producing code for a third architecture, such as ARM. In this
+ example, _-target_ would be 'arm-unknown-linux-gnu', while _-host_
+ would be 'win32'.
+
+-build
+ This is the system the build is running on.
+
+ The following example of _configure_ builds for an ARM system on an
+x86 system. It was run after an ARM system was built in `/usr/arm' and
+other required libraries were cross compiled.
+
+
+ ./configure -target=arm-unknown-linux-gnu --prefix=/usr/arm \
+ --host=arm-unknown-linux-gnu --build=i686-pc-linux-gnu
--disable-plugin
+
+
+File: gnash_ref.info, Node: Software Internals, Next: Reporting Bugs, Prev:
Building from Source, Up: Top
+
+3 Software Internals
+********************
+
+* Menu:
+
+* A Tour of Gnash::
+* Sound handling in Gnash::
+* Testing : Testing.
+* Adding New ActionScript Class::
+
+
+File: gnash_ref.info, Node: A Tour of Gnash, Next: Sound handling in Gnash,
Up: Software Internals
+
+3.1 A Tour of Gnash
+===================
+
+The top level of Gnash has several libraries, _libgnashbase_,
+_libgnashgeo_, _libgnashserver_, _libgnashasobjs_ and
+_libgnashbackend_. There are several utility programs included for
+debug parsing and processing of Flash movie files, and other useful
+utilitis for examining local Shared Objects and sniffingh
+LocalConnections.
+
+* Menu:
+
+* The Libraries::
+* The Applications::
+* The Plugin::
+* The Debug Logging System::
+
+
+File: gnash_ref.info, Node: The Libraries, Next: The Applications, Up: A
Tour of Gnash
+
+3.1.1 The Libraries
+-------------------
+
+* Menu:
+
+* libgnashbase::
+* libgnashgeo::
+* libgnashgui::
+* libgnashserver::
+* libgnashasobjs::
+* libgnashamf::
+* libgnashbackend::
+* libgnashplugin::
+* libklashpart::
+
+
+File: gnash_ref.info, Node: libgnashbase, Next: libgnashgeo, Up: The
Libraries
+
+3.1.1.1 libgnashbase
+....................
+
+Libgnashbase contains support classes used by the rest of the code.This
+library has no dependencies on any of the other Gnash libraries.
+
+ Gnash makes heavy use of smart pointers, so memory allocations are
+freed up automatically by the interpreter. Both STL and Boost smart
+pointers are used.
+
+
+File: gnash_ref.info, Node: libgnashgeo, Next: libgnashgui, Prev:
libgnashbase, Up: The Libraries
+
+3.1.1.2 libgnashgeo
+...................
+
+Libgnashgeo contains code for device independent graphics routines.
+
+
+File: gnash_ref.info, Node: libgnashgui, Next: libgnashserver, Prev:
libgnashgeo, Up: The Libraries
+
+3.1.1.3 libgnashgui
+...................
+
+Libgnashgui contains code for a portable GUI class that supports using
+GTK2, a framebuffer, SDL, or KDE, FLTK, or Aqua.
+
+
+File: gnash_ref.info, Node: libgnashserver, Next: libgnashasobjs, Prev:
libgnashgui, Up: The Libraries
+
+3.1.1.4 libgnashserver
+......................
+
+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.
+
+
+File: gnash_ref.info, Node: libgnashasobjs, Next: libgnashamf, Prev:
libgnashserver, Up: The Libraries
+
+3.1.1.5 libgnashasobjs
+......................
+
+Libgnashasobjs contains all the ActionScript classes used by the
+interpreter.
+
+
+File: gnash_ref.info, Node: libgnashamf, Next: libgnashbackend, Prev:
libgnashasobjs, Up: The Libraries
+
+3.1.1.6 libgnashamf
+...................
+
+AMF is the data format used internally by SWF files. This is Gnash's
+support library to handle AMF data. This is used by the ActionScript
+classes SharedObject and LocalConnection. This is also used by the
+NetStream class when using thre RTMP streaming network protocol.
+
+
+File: gnash_ref.info, Node: libgnashbackend, Next: libgnashplugin, Prev:
libgnashamf, Up: The Libraries
+
+3.1.1.7 libgnashbackend
+.......................
+
+Libgnashbackend is a library containing the rendering code that glues
+this display to the Gnash. Supported rendering backends are OpenGL,
+Cairo, and AGG.
+
+
+File: gnash_ref.info, Node: libgnashplugin, Next: libklashpart, Prev:
libgnashbackend, Up: The Libraries
+
+3.1.1.8 libgnashplugin
+......................
+
+Libgnashplugin is the Mozilla/Firefox plugin.
+
+
+File: gnash_ref.info, Node: libklashpart, Prev: libgnashplugin, Up: The
Libraries
+
+3.1.1.9 libklashpart
+....................
+
+Libklashpart is the Konqueror plugin.
+
+
+File: gnash_ref.info, Node: The Applications, Next: The Plugin, Prev: The
Libraries, Up: A Tour of Gnash
+
+3.1.2 The Applications
+----------------------
+
+There are currently a few standalone programs in Gnash, which serve to
+either assist with Gnash development or play flash movies.
+
+* Menu:
+
+* The Standalone Player::
+* Gprocessor::
+* SOLdumper::
+* Dumpshm::
+
+
+File: gnash_ref.info, Node: The Standalone Player, Next: Gprocessor, Up:
The Applications
+
+3.1.2.1 The Standalone Player
+.............................
+
+This is the standalone OpenGL back-end used to play movies. There are
+several command-line options and keyboard control keys used by Gnash.
+
+
+File: gnash_ref.info, Node: Gprocessor, Next: SOLdumper, Prev: The
Standalone Player, Up: The Applications
+
+3.1.2.2 Gprocessor
+..................
+
+Gprocessor is used to print out the actions (using the -va option) or
+the parsing (using the -vp option) of a flash movie. It is also used to
+produce the _.gsc_ files that Gnash uses to cache data, thereby
+speeding up the loading of files.
+
+
+File: gnash_ref.info, Node: SOLdumper, Next: Dumpshm, Prev: Gprocessor,
Up: The Applications
+
+3.1.2.3 SOLdumper
+.................
+
+SOLDumper is a utility program used to find and dump the content of
+_Local Shared Objects_, also called "Flash Cookies" by some.
+
+
+File: gnash_ref.info, Node: Dumpshm, Prev: SOLdumper, Up: The Applications
+
+3.1.2.4 Dumpshm
+...............
+
+Dumpshm is a program used to find and dump the contents of the
+_LocalConnection_ shared memory segment.
+
+
+File: gnash_ref.info, Node: The Plugin, Next: The Debug Logging System,
Prev: The Applications, Up: A Tour of Gnash
+
+3.1.3 The Plugin
+----------------
+
+The plugin is designed to work within Mozilla or Firefox, although
+there is Konqueror support as well. The plugin uses the Mozilla NSAPI
+plugin API to be cross platform, and is portable, as well as being well
+integrated into Mozilla based browsers.
+
+* Menu:
+
+* Current Status::
+* GUI Support::
+* Mozplugger::
+* Klash::
+
+
+File: gnash_ref.info, Node: Current Status, Next: GUI Support, Up: The
Plugin
+
+3.1.3.1 Current Status
+......................
+
+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.
+
+ As of Jan, 2007, streaming video, ala "YouTube" works, along with
+other video sharing sites.
+
+
+File: gnash_ref.info, Node: GUI Support, Next: Mozplugger, Prev: Current
Status, Up: The Plugin
+
+3.1.3.2 GUI Support
+...................
+
+Any plugin that wants to display in a browser window needs to be tied
+into the windowing system of the platform being used. On GNU/Linux
+systems, Firefox is a GTK2+ application. There is also KDE support
+through the use of the Klash plugin.
+
+ Gnash can use either several different GUI toolkits to create the
+window, and to handle events for the standalone player.
+
+ The SDL version is more limited, but runs on all platforms,
+including win32. It has no support for event handling, which means
+mouse clicks, keyboard presses, and window resizing doesn't work. I
+personally find the default event handler slow and unresponsive. Gnash
+has support to use fast events, (currently not enabled) which is an SDL
+hack using a background thread to pump events into the SDL event queue
+at a much higher rate.
+
+ There are a variety of development libraries that build a GUI widget
+system on top of SDL and OpenGL. The use of these to add menus and
+dialog boxes to the SDL version is being considered.
+
+ The GTK support is currently the most functional, and the best
+integrated into Firefox. The performance of this version is better than
+the SDL version because of the more efficient event handling within
+GTK. For the best end user experience, use the GTK enabled version.
+
+ GTK also allows Gnash to have menus and dialog boxes. Currently this
+is only being utilized in a limited fashion for now. There is a right
+mouse button menu that allows the user to control the movie being
+player the same way the existing keyboard commands do.
+
+
+File: gnash_ref.info, Node: Mozplugger, Next: Klash, Prev: GUI Support,
Up: The Plugin
+
+3.1.3.3 Mozplugger
+..................
+
+Mozplugger (http://mozplugger.mozdev.org/) is a _Mozilla/Firefox_
+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.
+
+ 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.
+
+ Use of MozPlugger is obsolete now that the Gnash plugin works.
+Still, this may be useful still on some platforms.
+
+ Add this to your _$(HOME)/.mozilla/mozpluggerrc_ file to enable this:
+
+
+ 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
+
+ Once this is added, you must delete the
+_$(HOME)/.mozilla/firefox/pluginreg.dat_ 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 _swf_ files after it
+is recreated. You will need to restart Firefox to recreate this file.
+
+ 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 _about:plugins_ 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.
+
+
+File: gnash_ref.info, Node: Klash, Prev: Mozplugger, Up: The Plugin
+
+3.1.3.4 Klash
+.............
+
+Klash is MozPlugger type support for KDE's Konqueror web browser. Klash
+makes Gnash a _kpart_, so it's integrated into KDE better than when
+using MozPlugger. Klash uses the standalone player, utilizing Gnash's
+"-x" window plugin command line option.
+
+ By default, Klash is not built. To enable building Klash, use the
+_-enable-klash_ option when configuring. Other than installing, there
+is nothing else that needs to be done to install Klash.
+
+
+File: gnash_ref.info, Node: The Debug Logging System, Prev: The Plugin, Up:
A Tour of Gnash
+
+3.1.4 The Debug Logging System
+------------------------------
+
+Gnash supports a debug logging system which supports both C and C++
+natively. This means you can use both _printf()_ style debug messages
+and C++ _iostreams_ style, where you can print C++ objects directly as
+you would when using _cout_.
+
+ 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
+_log_msg()_ and _log_error()_ functions, and used a callback to set
+them up.
+
+ If a filename is not specified at object construction time, a
+default name of _gnash-dbg.log_ is used. If Gnash is started from the
+command line, the debug log will be created in the current directory.
+When executing Gnash from a launcher under _GNOME_ or _KDE_ the debug
+file goes in your home directory, since that's considered the current
+directory.
+
+ 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 _-v_ options on the command line. You can also
+disable the creation of the debug log.
+
+ 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.
+
+* Menu:
+
+* Logging System C API::
+* Logging System C++ API::
+
+
+File: gnash_ref.info, Node: Logging System C API, Next: Logging System C++
API, Up: The Debug Logging System
+
+3.1.4.1 Logging System C API
+............................
+
+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.
+
+log_error(const char* fmt, ...)
+ 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.
+
+void log_unimpl
+ Displays a warning to the user about missing Gnash features. We
+ expect all calls to this function to disappear over time, as we
+ implement those features of Flash.
+
+void log_trace
+ Used only for explicit user traces
+
+void log_debug
+ Logs debug information.
+
+void log_action
+ Log action execution information. Wrap all calls to this function
+ (and other related statements) into an IF_VERBOSE_ACTION macro, so
+ to allow completely removing all the overhead at compile time and
+ reduce it at runtime.
+
+void log_parse
+ Log SWF parsing Wrap all calls to this function (and other
+ related statements) into an IF_VERBOSE_PARSE macro, so to allow
+ completely removing all the overhead at compile time and reduce it
+ at runtime.
+
+void log_security
+ Display a message with security related information.
+
+void log_swferror
+ This indicates an error in how the binary SWF file was
+ constructed, i.e.probably a bug in the tools used to build the SWF
+ file. Wrap all calls to this function (and other related
+ statements) into an IF_VERBOSE_MALFORMED_SWF macro, so to allow
+ completely removing all the overhead at compile time and reduce it
+ at runtime.
+
+log_warning(const char* fmt, ...)
+ 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.
+
+
+File: gnash_ref.info, Node: Logging System C++ API, Prev: Logging System C
API, Up: The Debug Logging System
+
+3.1.4.2 Logging System C++ API
+..............................
+
+This is the new C++ streams based API that can be used to print C++
+objects natively. All output lines are timestamped.
+
+ 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 _GNASH_REPORT_RETURN_ at the end of a
+function to display the function returning message.
+
+GNASH_REPORT_FUNCTION;
+ 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.
+
+GNASH_REPORT_RETURN;
+ This is used by C functions to print the returning from function
+ debug message. For C++, this macro is executed automatically by
+ the destructor.
+
+ This is the main API for the logging system. By default everything
+is setup to write to the default _gnash-dbg.log_ file whenever a
+verbose option is supplied. Optionally it is possible to open a log
+file with a specified name, allowing multiple output files.
+
+closeLog(void)
+ Close a debug log. The disk file remains.
+
+removeLog(void)
+ Delete the debug log file from disk.
+
+setVerbosity(void)
+ Increment the verbosity level.
+
+setVerbosity(int)
+ Set the verbosity level.
+
+setStamp(bool flag)
+ If _flag_ is _true_, then print a timestamp prefixed to every
+ output line. If _flag_ is _false_, then don't print a timestamp.
+
+setWriteDisk(bool flag)
+ If _flag_ is _true_, then create the disk file. If _flag_ is
+ _false_, then don't create the disk file.
+
+
+File: gnash_ref.info, Node: Sound handling in Gnash, Next: Testing, Prev: A
Tour of Gnash, Up: Software Internals
+
+3.2 Sound handling in Gnash
+===========================
+
+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.
+
+ There are two different settings related to sound support:
+_pluginsound_ and _sound_. This was done in order to allow the plugin
+to be independently configured, for instance to block sound from
+advertisements.
+
+* Menu:
+
+* Sound types::
+* Sound parsing::
+* Sound playback::
+* The SDL sound backend::
+* The Gstreamer backend::
+* Future audio backends::
+* Detailed description of the Gstreamer backend::
+
+
+File: gnash_ref.info, Node: Sound types, Next: Sound parsing, Up: Sound
handling in Gnash
+
+3.2.1 Sound types
+-----------------
+
+Sounds can be divided into two groups: event-sounds and soundstreams.
+Event-sounds are contained in a single SWF frame, but the playtime can
+span multiple frames. Soundstreams can be (and normally are) divided
+between the SWF frames the soundstreams spans. This means that if a
+gotoframe-action jumps to a frame which contains data for a soundstream,
+playback of the stream can be picked up from there.
+
+
+File: gnash_ref.info, Node: Sound parsing, Next: Sound playback, Prev:
Sound types, Up: Sound handling in Gnash
+
+3.2.2 Sound parsing
+-------------------
+
+When Gnash parses a SWF-file, it creates a sound handler if possible
+and hands over the sounds to it. Since the event-sounds are contained
+in one frame, the entire event-sound is retrieved at once, while a
+soundstream maybe not be completely retrieved before the entire
+SWF-file has been parsed. But since the entire soundstream doesn't need
+to be present when playback starts, it is not necessary to wait.
+
+
+File: gnash_ref.info, Node: Sound playback, Next: The SDL sound backend,
Prev: Sound parsing, Up: Sound handling in Gnash
+
+3.2.3 Sound playback
+--------------------
+
+When a sound is about to be played Gnash calls the sound handler, which
+then starts to play the sound and return. All the playing is done by
+threads (in both SDL and Gstreamer), so once started the audio and
+graphics are not sync'ed with each other, which means that we have to
+trust both the graphic backend and the audio backend to play at correct
+speed.
+
+
+File: gnash_ref.info, Node: The SDL sound backend, Next: The Gstreamer
backend, Prev: Sound playback, Up: Sound handling in Gnash
+
+3.2.4 The SDL sound backend
+---------------------------
+
+The current SDL sound backend has replaced the original sound handler,
+based on SDL_mixer, which by design had some limitations, making it
+difficult to implement needed features such as support for soundstreams.
+The SDL sound backend supports both event-sounds and soundstreams,
+using Gnash's internal ADPCM, and optionally MP3 support, using 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...
+
+
+File: gnash_ref.info, Node: The Gstreamer backend, Next: Future audio
backends, Prev: The SDL sound backend, Up: Sound handling in Gnash
+
+3.2.5 The Gstreamer backend
+---------------------------
+
+The Gstreamer backend, though not complete, supports both soundstreams
+and event-sounds. When receiving sound data it stores it compressed,
+unless if it's ADPCM event-sounds, which it decodes by the parser.
+When the playback starts, the backend sets up a Gstreamer bin
+containing a decoder (and other things needed) and places it in a
+Gstreamer pipeline, which plays the audio. All the sound data is not
+passed at once, but in small chunks, and via callbacks the pipeline
+gets fed. The advantages of the Gstreamer backend is that it supports
+both kinds of sound, it avoids all the legal MP3-stuff, and it should
+be relatively easy to add VORBIS support. The drawbacks are that it has
+longer "reply delay" when starting the playback of a sound, and it
+suffers under some bugs in Gstreamer that are yet to be fixed.
+
+
+File: gnash_ref.info, Node: Future audio backends, Next: Detailed
description of the Gstreamer backend, Prev: The Gstreamer backend, Up: Sound
handling in Gnash
+
+3.2.6 Future audio backends
+---------------------------
+
+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.
+
+
+File: gnash_ref.info, Node: Detailed description of the Gstreamer backend,
Prev: Future audio backends, Up: Sound handling in Gnash
+
+3.2.7 Detailed description of the Gstreamer backend
+---------------------------------------------------
+
+Gstreamer uses pipelines, bins and elements. Pipelines are the main
+bin, where all other bins or elements are places. Visually the audio
+pipeline in Gnash looks like this:
+
+
+ ___
+ |Bin|_
+ |___| \
+ ___ \ _____ ____________
+ |Bin|___|Adder|_____|Audio output|
+ |___| |_____| |____________|
+ ___ /
+ |Bin|_/
+ |___|
+
+ There is one bin for each sound which is being played. If a sound is
+played more the once at the same time, multiple bins will be made. The
+bins contains:
+
+
+
+
|source|---|capsfilter|---|decoder|---|aconverter|---|aresampler|---|volume|
+
+ In the source element we place parts of the undecoded sound data, and
+when playing the pipeline will pull the data from the element. Via
+callbacks it is refilled if needed. In the capsfilter the data is
+labeled with the format of the data. The decoder (surprise!) decodes
+the data. The audioconverter converts the now raw sound data into a
+format accepted by the adder, all input to the adder must in the same
+format. The audio re-sampler re-samples the raw sound data into a sample
+accepted by the adder, all input to the adder must in the same sample
+rate. The volume element makes it possible to control the volume of
+each sound.
+
+ When a sound is done being played it emits a End-Of-Stream-signal
+(EOS), which is caught by an event-handler-callback, which then makes
+sure that the bin in question is removed from the pipeline. When a
+sound is told by Gnash to stop playback before it has ended playback,
+we do something (not yet finally implemented), which makes the bin emit
+an EOS, and the event-handler-callback will remove the sound from the
+pipeline. Unfortunately Gstreamer currently has a bug which causes the
+entire pipeline to stop playing when unlinking an element from the
+pipeline; so far no fix is known.
+
+ Gstreamer also contains a bug concerning linking multiple elements to
+the adder in rapid succession, which causes to adder to "die" and stop
+the playback.
+
+
+File: gnash_ref.info, Node: Testing, Next: Adding New ActionScript Class,
Prev: Sound handling in Gnash, Up: Software Internals
+
+3.3 Testing
+===========
+
+Instructions on running tests (*note Running the Tests::) can be found
+in the section on building Gnash.
+
+* Menu:
+
+* Testing Tools::
+* Test Cases::
+* Writing ActionScript Tests::
+* Writing Ming-based self-contained SWF tests::
+* Writing self-contained SWF tests with other compilers::
+* Writing Test Runners::
+
+
+File: gnash_ref.info, Node: Testing Tools, Next: Test Cases, Up: Testing
+
+3.3.1 Testing Tools
+-------------------
+
+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.
+
+ The primary compiler used at this time is Ming (http://ming.sf.net).
+Since release 0.3, _Ming_ includes a command-line compiler, _makeswf_.
+This allows test case development to be done entirely with free tools.
+
+ The other tools are optional. DejaGnu
+(http://www.gnu.org/software/dejagnu) is used to run multiple test
+cases in an automated manner. _DejaGnu_ is used by many other GNU
+(http://www.gnu.org) projects like GCC (http://gcc.gnu.org) and Samba
+(http://www.samba.org).
+
+
+File: gnash_ref.info, Node: Test Cases, Next: Writing ActionScript Tests,
Prev: Testing Tools, Up: Testing
+
+3.3.2 Test Cases
+----------------
+
+ActionScript test cases are located under testsuite/actionscript.all/;
+these are organized in one file for the ActionScript class. Other
+Ming-generated tests are under testsuite/ming-misc.all/; these are
+typically used to test specific tag types. Full movies are located in
+testsuite/movies.all/ and sample movies are found in testsuite/samples/.
+Other directories in testsuite/ are (or shall be) used for other kind
+of tests.
+
+
+File: gnash_ref.info, Node: Writing ActionScript Tests, Next: Writing
Ming-based self-contained SWF tests, Prev: Test Cases, Up: Testing
+
+3.3.3 Writing ActionScript Tests
+--------------------------------
+
+Writing ActionScript tests is very simple. The _makeswf_ compiler makes
+use of the C preprocessor, thus allowing the inclusion of definitions
+for macros and external files. We use these feature to provide common
+utilities for test units.
+
+ Each test unit sets an _rcsid_ variable, includes the _check.as_
+file and performs some checks using the provided macros. Here is an
+example:
+
+
+
+ // This variable will be used by check.as
+ // to show testcase info as part of the test runs.
+ rcsid="Name and version of this testcase, usually the RCS id";
+
+ #include "check.as"
+
+ // Test object creation
+ check(new Object() instanceOf Object);
+
+ // Test parseInt
+ check(isNaN(parseInt('none')));
+
+ // Test assignment
+ var a = 1;
+ check_equals(a, 1);
+
+ // .. your tests here ...
+
+ The check(expr) macro will _trace_ PASSED or FAILED together with
+the expression being evaluated and the line number of the check. This
+is the format expected by DejaGnu.
+
+ The _check_equals(obtained, expected)_ macro uses equality operator
+_==_ to check for equality. When possible, use of the _check_equals()_
+macro is preferred over _check()_ because it shows what the actual
+result was in case of a failure.
+
+ Additionally, the check.as file provides a transparent way to send
+results to a TextField rather then using trace. This is very useful
+when you use a flash player without tracing support.
+
+ Test units are built by running _make TestName-v#.swf_. This will
+use TestName.as as source and the value of # as target version.
+Allowed target version are from 5 to 8 (inclusive).
+
+ Note that if you get a syntax error from the compiler, the line
+number will refer to the pre-processed file. This file is called
+_TestName.as.pp_ or _TestName-v#.swf.frame#.pp_ (depending on Ming
+version) and it's not thrown away by _makeswf_ to make debugging easier.
+
+ Sometimes an expression is only supported by a specific SWF version,
+or it's evaluated differently by different SWF versions. For this
+purpose the framework provides an OUTPUT_VERSION macro that you can use
+to switch code based on output version. For example:
+
+
+
+ #if OUTPUT_VERSION >= 7
+ check(_root.getSWFVersion == OUTPUT_VERSION);
+ #endif
+
+
+File: gnash_ref.info, Node: Writing Ming-based self-contained SWF tests,
Next: Writing self-contained SWF tests with other compilers, Prev: Writing
ActionScript Tests, Up: Testing
+
+3.3.4 Writing Ming-based self-contained SWF tests
+-------------------------------------------------
+
+Ming-based test cases are located in testsuite/misc-ming.all and
+contain a test generator and a test runner. The test generator
+(usually a C program) is used to produce the SWF file, while the test
+runner (a C++ program) will run it using a MovieTester class. Note
+that only the test generator needs Ming, not the test runner, so if
+Ming isn't installed on the user's host, the test cases can still be
+run as long as SWF has been distributed.
+
+ Producing tests using Ming has the advantage that you can easily see
+and modify the full source code for the SWF movie, and you can use some
+facilities (*note Using Ming-based test generators facilities::)
+provided by the Gnash testing framework to easily run tests.
+
+ For generic Ming API documentation, see http://www.libming.org
+(http://www.libming.org/).
+
+* Menu:
+
+* Using Ming-based test generators facilities::
+
+
+File: gnash_ref.info, Node: Using Ming-based test generators facilities, Up:
Writing Ming-based self-contained SWF tests
+
+3.3.4.1 Using Ming-based test generators facilities
+...................................................
+
+Ming-based test generator facilities, which might be moved into a
+loadable SWF in the future, can be currently used by your test
+generator by including the ming_utils.h file and calling the
+appropriate functions.
+
+ The most useful facility provided for Ming-based SWF test generators
+is a Dejagnu-like TestState ActionScript class. In order to use this
+facility you must call 'add_dejagnu_functions()' right after Movie
+creation. The function takes an SWFMovie object and some parameters
+specifying depth and location of the "visual" trace textfield; it
+instantiates a global 'TestState' ActionScript object to keep track of
+test's state.
+
+ You will _not_ need to directly invoke the TestState object created
+by the 'add_dejagnu_functions()' routine, rather you will be using C
+macros hiding its complexity:
+
+
+
+ check(SWFMovie mo, const char* expr)
+
+ Evaluate an ActionScript expression.
+
+ xcheck(SWFMovie mo, const char* expr)
+
+ Evaluate an ActionScript expression.
+ A failure is expected
+ (for cases where the call exposes a known bug).
+
+ check_equals(SWFMovie mo, const char* obtained, const char* expected)
+
+ Evaluate an ActionScript expression against an expected output.
+
+ xcheck_equals(SWFMovie mo, const char* obtained, const char* expected)
+
+ Evaluate an ActionScript expression against an expected output.
+ A failure is expected (for cases where the call exposes a known
bug).
+
+ print_tests_summary(SWFMovie mo)
+
+ This will print a summary of tests run, and should be
+ called as the last step in your SWF generator.
+
+ Test cases generated using Ming and the provided facilities (*note
+Using Ming-based test generators facilities::) will be self-contained,
+which means they can be used as tests by simply running them with
+whatever Player you might have. Any 'check' or 'check_equals' result
+will be both traced and printed in a textfield. You can use 'gprocessor
+-v' to have Gnash use them as tests.
+
+ See section Writing Test Runners (*note Writing Test Runners::) for
+information about writing SWF test runners.
+
+
+File: gnash_ref.info, Node: Writing self-contained SWF tests with other
compilers, Next: Writing Test Runners, Prev: Writing Ming-based
self-contained SWF tests, Up: Testing
+
+3.3.5 Writing self-contained SWF tests with other compilers
+-----------------------------------------------------------
+
+If you want/need to use a different compiler for your test cases
+(there's plenty of open source tools for generating SWF out there), you
+can still make use of a loadable SWF utility provided as part of the
+Gnash testsuite to let your test consistent with the rest of the suite.
+
+ The loadable module is called _Dejagnu.swf_ and is built during
+_make check_ under testsuite/misc-ming.all. In order to use it you will
+need to load it into your SWF. We currently load it with an IMPORT tag
+for our ActionScript based test cases, but you can probably also use
+loadMovie or whatever works in the target SWF you're generating. Just
+make sure that the module is initialized before using it. You can check
+this by inspecting the _dejagnu_module_initialized_ variable, which will
+be set to 'true' when all initialization actions contained in the
+_Dejagnu.swf_ file are executed.
+
+ Once the module is loaded you will be able to invoke the following
+functions, all registered against the __root_ sprite (effects of
+__lockroot_ untested):
+
+
+
+ check(expression, [message]);
+
+ Evaluate the expression.
+ Trace result (PASSED: expression / FAILED: expression).
+ If fails, *visually* trace the failure.
+ If second argument is given, it will be used instead of
+ 'expression' for printing results.
+
+ check_equals(obtained, expected)
+
+ Evaluate an expression against an expected output.
+ Trace result (PASSED: obtained == expected / FAILED: expected X,
obtained Y)
+ If fails, *visually* trace the failure.
+
+ xcheck(expression, [message]);
+
+ Evaluate the expression.
+ Trace result (XPASSED: expression / XFAILED: expression).
+ If fails, *visually* trace the failure.
+ If second argument is given, it will be used instead of
+ 'expression' for printing results.
+
+ xcheck_equals(obtained, expected)
+
+ Evaluate an expression against an expected output.
+ Trace result (XPASSED: obtained == expected / XFAILED: expected X,
obtained Y)
+ If fails, *visually* trace the failure.
+
+ note(string)
+
+ Print string, both as debugging and *visual* trace.
+
+ totals()
+
+ Print a summary of tests run, both as debugging and *visual* traces.
+
+ Visual traces are lines of text pushed to a textarea defined by the
+_Dejagnu.swf_ module. The textarea is initially placed at _0, 50_ and is
+_600x800_ in size. You can resize/move the clip after loading it. Also,
+you can completely make the clip invisible if that bothers you. The
+important thing is the _debugging_ trace (call to the trace function).
+The latter will be used by the testing framework.
+
+ See section Writing Test Runners (*note Writing Test Runners::) for
+information about writing a test runners for your self-contained tests.
+
+
+File: gnash_ref.info, Node: Writing Test Runners, Prev: Writing
self-contained SWF tests with other compilers, Up: Testing
+
+3.3.6 Writing Test Runners
+--------------------------
+
+Test runners are executables that run one or more tests, writing
+results in Dejagnu form to standard output.
+
+ The Dejagnu form uses a standard set of labels when printing test
+results. These are:
+
+Label Meaning
+PASSED The test succeeded.
+FAILED The test failed.
+XPASSED The test succeeded, but was
+ expected to fail.
+XFAILED The test failed, and was expected
+ to fail.
+UNRESOLVED The results of the test could not
+ be automatically parsed.
+UNTESTED This test case is not complete.
+UNSUPPORTED The test case relies on a
+ conditional feature which is not
+ present in your environment.
+
+ The following labels may also appear:
+
+Label Meaning
+ERROR There was a serious error in
+ running the test.
+WARNING There may have been a problem with
+ running the test.
+NOTE There was some additional
+ information given about the test.
+
+* Menu:
+
+* Using the generic test runner for self-contained SWF tests::
+* Writing Movie testers::
+
+
+File: gnash_ref.info, Node: Using the generic test runner for self-contained
SWF tests, Next: Writing Movie testers, Up: Writing Test Runners
+
+3.3.6.1 Using the generic test runner for self-contained SWF tests
+..................................................................
+
+The simplest test runner is one that simply invokes Gnash in verbose
+mode against a self-contained SWF test movie. Self-contained SWF test
+movies are the ones that print the PASSED/FAILED etc. lines using
+ActionScript (traces). By invoking Gnash in verbose mode this movie
+will behave as a compliant "Test Runner".
+
+ A generator for simple test runners can be found in
+_testsuite/generic-testrunner.sh_. The script can be invoked by
+passing it _$(top_builddir)_ as the first argument and the name of the
+SWF file (without the path) as the second argument. This will create a
+specific runner for your test in the current build directory. A simple
+Makefile.am rule for doing this follows:
+
+
+ MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
+ sh $(srcdir)/../generic-testrunner.sh $(top_builddir) MyTest.swf >
$@
+ chmod +x $@
+
+ By default, the generated test runner will play the movie up to the
+last frame. If you want the movie to be played more then once (maybe
+because you're exactly testing loop features) you can use the -r switch
+to the generic-testrunner.sh call. The following will create a runner
+playing the movie twice:
+
+
+ MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
+ sh $(srcdir)/../generic-testrunner.sh -r2 $(top_builddir)
MyTest.swf > $@
+ chmod +x $@
+
+ In case your test movie stops before the last frame, or you want to
+control the exact number of times to call the frame advancement
+routine, you can use the -f switch to control that.
+
+
+ MyTest-Runner: $(srcdir)/../generic-testrunner.sh MyTest.swf
+ sh $(srcdir)/../generic-testrunner.sh -f10 $(top_builddir)
MyTest.swf > $@
+ chmod +x $@
+
+When both -f and -r are given, the first exit condition reached will
+take effect.
+
+
+File: gnash_ref.info, Node: Writing Movie testers, Prev: Using the generic
test runner for self-contained SWF tests, Up: Writing Test Runners
+
+3.3.6.2 Writing Movie testers
+.............................
+
+There are some parts of Gnash that can NOT be tested by only using
+ActionScript tests. Examples include: frame advancements, actual
+actions execution, gui events and so on.
+
+ In this case you might want to use the MovieTester class to
+implement a C++ test runner. Be aware that you can _mix_ tests in the
+MovieTester-based class with _self-contained_ tests in the SWF file as
+long as you activate verbosity for the debug logfile. This is done, for
+example, for the DefineEditTextVariableNameTest.swf file. The
+corresponding test runner (DefineEditTextVariableNameTest-Runner) is a
+C++ runner based on MovieTester class. If you run the runner you see
+two kinds of test results: the ones coming from the ActionScript
+engine, and the ones coming from the test runner. You can distinguish
+between the two because the former contains an additional timestamp and
+the latter does not. Also, you'll see two final summaries for the two
+test sets. The 'make check' rule, which uses the testsuite/simple.exp
+output parser as its work-horse, will count test results from both test
+sets.
+
+ Movie testers are executables which load an SWF, generate events
+(both user or system) on it, and check its state using a standard
+interface.
+
+ To help this process a MovieTester class is defined in the
+testsuite/MovieTester.{h,cpp} files; see Doxygen documentation for more
+information.
+
+ Note that you do NOT need access to the SWF source code in order to
+implement a Movie tester for it. Some knowledge about the expected
+behavior suffices.
+
+
+File: gnash_ref.info, Node: Adding New ActionScript Class, Prev: Testing,
Up: Software Internals
+
+3.4 Adding New ActionScript Class
+=================================
+
+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.
+
+ 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.
+
+ 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 _Boolean.cpp_ for the Boolean
+class.
+
+* Menu:
+
+* Prototype::
+* Declaration::
+* Instantiation::
+* Methods::
+* Dynamic Properties::
+* The as_value Object Type::
+* Object ActionScript Class::
+
+
+File: gnash_ref.info, Node: Prototype, Next: Declaration, Up: Adding New
ActionScript Class
+
+3.4.1 Prototype
+---------------
+
+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.
+
+ In Gnash, the prototype of an ActionScript object is implemented as
+an _as_object_. At startup, the methods and properties of the
+ActionScript class are attached to the _as_object_. The following
+example demonstrates how methods can be attached:
+
+
+ static void
+ attachBooleanInterface(as_object& o) {
+ o.init_member("toString", new builtin_function(boolean_tostring));
+ o.init_member("valueOf", new builtin_function(boolean_valueof));
+ }
+
+ Static properties can also be added to the ActionScript prototype
+(dynamic properties (*note Dynamic Properties::) are addressed later).
+They are attached in a similar way:
+
+
+ o.init_member("myProperty", as_value("HelloWorld"));
+
+ 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 _makeswf_ compiler demonstrates:
+
+
+ // Get the value of the myProperty property
+ if (node.myProperty == "HelloWorld") {
+ trace("MATCHED");
+ }
+
+
+File: gnash_ref.info, Node: Declaration, Next: Instantiation, Prev:
Prototype, Up: Adding New ActionScript Class
+
+3.4.2 Declaration
+-----------------
+
+A new class should derive from _as_object_, which is the base class of
+every ActionScript object in Gnash.
+
+
+File: gnash_ref.info, Node: Instantiation, Next: Methods, Prev:
Declaration, Up: Adding New ActionScript Class
+
+3.4.3 Instantiation
+-------------------
+
+When a new object is needed, instance data is added to the methods and
+properties inherited from the prototype.
+
+ The init method should be called in the constructor in _Global.cpp_,
+where all other ActionScript classes are similarly referenced. This
+method constructs a prototype, which is implemented as an _as_object_.
+In addition, the method registers the constructor to be used for future
+object creation, and attaches methods and properties to the prototype.
+
+
+File: gnash_ref.info, Node: Methods, Next: Dynamic Properties, Prev:
Instantiation, Up: Adding New ActionScript Class
+
+3.4.4 Methods
+-------------
+
+Every method you implement and attach (*note Prototype::) will receive
+an _fn_call_ data structure as an argument when it is called.
+
+* Menu:
+
+* Accessing Arguments::
+* Returning a Value to ActionScript::
+* Additional fn_call Members::
+
+
+File: gnash_ref.info, Node: Accessing Arguments, Next: Returning a Value to
ActionScript, Up: Methods
+
+3.4.4.1 Accessing Arguments
+...........................
+
+The arguments stored in _fn_call_ should be accessed using _arg()_. For
+instance, the first element can be popped with _fn.arg(0)_.
+
+ The element popped off the stack is an _as_value_ object (*note The
+as_value Object Type::).
+
+
+File: gnash_ref.info, Node: Returning a Value to ActionScript, Next:
Additional fn_call Members, Prev: Accessing Arguments, Up: Methods
+
+3.4.4.2 Returning a Value to ActionScript
+.........................................
+
+The return value should be an _as_value_ object (*note The as_value
+Object Type::). For example:
+
+
+ return as_value('Goodbye, cruel world.');
+
+
+File: gnash_ref.info, Node: Additional fn_call Members, Prev: Returning a
Value to ActionScript, Up: Methods
+
+3.4.4.3 Additional fn_call Members
+..................................
+
+There are two other useful members of the _fn_call_ structure, namely
+_this_ptr_ and _nargs_. The former points to the class which is
+invoking this method, while the latter is a count of the number of
+arguments in the stack (*note Accessing Arguments::).
+
+ You may also see instances of the _env_ pointer being used. This
+is being deprecated. Instances which could be replaced with _arg()_
+(*note Accessing Arguments::) are already deprecated; other uses will
+be deprecated in the near future.
+
+ Beyond the _arg() (*note Accessing Arguments::)_ method, there is
+one method of note. _dump_args()_ can be used in debugging to output
+the entire argument stack.
+
+
+File: gnash_ref.info, Node: Dynamic Properties, Next: The as_value Object
Type, Prev: Methods, Up: Adding New ActionScript Class
+
+3.4.5 Dynamic Properties
+------------------------
+
+This section describes accessors to dynamic properties. Read-only
+properties are described in the prototype (*note Prototype::) section.
+
+ Accessors should be written as a single get/set method. Previously
+this was done by overriding _get_member()_ and _set_member()_, but this
+practice is deprecated.
+
+ The accessor is written so that it sets the property if it is called
+with an argument, and puts the property in the _fn_call_ (*note
+Methods::) result pointer (*note Returning a Value to ActionScript::).
+For instance:
+
+
+ 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);
+ }
+
+ It has not yet been decided whether properties should be set in the
+exported interface (*note Prototype::) or attached to instances of the
+class. A property is attached in the following manner:
+
+
+ boost::intrusive_ptr<builtin_function> gettersetter;
+ gettersetter = new builtin_function(&MyClass::myProperty_getset, NULL);
+ o.init_property("myProperty", *gettersetter, *gettersetter);
+
+
+File: gnash_ref.info, Node: The as_value Object Type, Next: Object
ActionScript Class, Prev: Dynamic Properties, Up: Adding New ActionScript
Class
+
+3.4.6 The as_value Object Type
+------------------------------
+
+The _as_value_ class is used throughout the interpreter to create
+generic objects to hold data.
+
+* Menu:
+
+* Data Types::
+* Determining the Type::
+* Fetching the Value::
+* Setting the Value and Type::
+* Further Reading::
+
+
+File: gnash_ref.info, Node: Data Types, Next: Determining the Type, Up: The
as_value Object Type
+
+3.4.6.1 Data Types
+..................
+
+The following data types are supported: _NULLTYPE_, _BOOLEAN_, _STRING_,
+_NUMBER_, _OBJECT_, _AS_FUNCTION_, and _MOVIECLIP_ (sprite). The type
+_C_FUNCTION_ is being deprecated.
-START-INFO-DIR-ENTRY
-* Gnash Reference Manual: (gnash_ref). [MISSING TEXT]
-END-INFO-DIR-ENTRY
+
+File: gnash_ref.info, Node: Determining the Type, Next: Fetching the Value,
Prev: Data Types, Up: The as_value Object Type
+
+3.4.6.2 Determining the Type
+............................
+
+Several methods allow you to determine if a value stored in _as_value_
+is of a specific type. These follow the form of _is_TYPE_, for example
+_is_as_function()_ and _is_number()_. In general, the type names match
+the data types (*note Data Types::) listed above, with the exception of
+the type _MOVIECLIP_ which has a method _is_sprite()_.
-File: gnash_ref.info, Node: Top, Next: Introduction, Up: (dir)
+File: gnash_ref.info, Node: Fetching the Value, Next: Setting the Value and
Type, Prev: Determining the Type, Up: The as_value Object Type
-Gnash Reference Manual
-**********************
+3.4.6.3 Fetching the Value
+..........................
+
+Another set of methods will return a representation of the value as a
+particular type. They follow the _to_TYPE_ naming convention. Examples
+are _to_number()_ and _to_bool()_. The type names are as listed (*note
+Data Types::) earlier, except for _MOVIECLIP_, which uses _to_sprite()_.
+
+
+File: gnash_ref.info, Node: Setting the Value and Type, Next: Further
Reading, Prev: Fetching the Value, Up: The as_value Object Type
+
+3.4.6.4 Setting the Value and Type
+..................................
+
+Finally, there is the _set_TYPE_ 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 _=_ operator. Again, type names match those named
+earlier (*note Data Types::), except in the case of _MOVIECLASS_. Its
+method is called _set_sprite()_.
+
+
+File: gnash_ref.info, Node: Further Reading, Prev: Setting the Value and
Type, Up: The as_value Object Type
+
+3.4.6.5 Further Reading
+.......................
+
+Please refer to _as_value.h_ 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 _as_value_ object.
+
+
+File: gnash_ref.info, Node: Object ActionScript Class, Prev: The as_value
Object Type, Up: Adding New ActionScript Class
+
+3.4.7 Object ActionScript Class
+-------------------------------
+
+This class implements an Object object.
* Menu:
-* Introduction::
-* RTMP Protocol::
-* Authors::
-* GNU Free Documentation License::
+* The Methods of the Class::
+* The Properties of the Object Class::
+* Object Class Conformance::
---- The Detailed Node Listing ---
+
+File: gnash_ref.info, Node: The Methods of the Class, Next: The Properties
of the Object Class, Up: Object ActionScript Class
-Introduction
+3.4.7.1 The Methods of the Class
+................................
-* Audience::
-* What Is Supported ?::
+addProperty()
-RTMP Protocol
+registerClass()
-* AMF Format::
+toString()
-GNU Free Documentation License
+unwatch()
-* 0. PREAMBLE: 0_ PREAMBLE.
-* 1. APPLICABILITY AND DEFINITIONS: 1_ APPLICABILITY AND DEFINITIONS.
-* 2. VERBATIM COPYING: 2_ VERBATIM COPYING.
-* 3. COPYING IN QUANTITY: 3_ COPYING IN QUANTITY.
-* 4. MODIFICATIONS: 4_ MODIFICATIONS.
-* 5. COMBINING DOCUMENTS: 5_ COMBINING DOCUMENTS.
-* 6. COLLECTIONS OF DOCUMENTS: 6_ COLLECTIONS OF DOCUMENTS.
-* 7. AGGREGATION WITH INDEPENDENT WORKS: 7_ AGGREGATION WITH INDEPENDENT WORKS.
-* 8. TRANSLATION: 8_ TRANSLATION.
-* 9. TERMINATION: 9_ TERMINATION.
-* 10. FUTURE REVISIONS OF THIS LICENSE: 10_ FUTURE REVISIONS OF THIS LICENSE.
-* Addendum::
+valueOf()
+
+watch()
+
+Sharedclear()
+
+Sharedflush()
+
+SharedgetLocal()
+
+SharedgetSize()
-File: gnash_ref.info, Node: Introduction, Next: RTMP Protocol, Prev: Top,
Up: Top
+File: gnash_ref.info, Node: The Properties of the Object Class, Next: Object
Class Conformance, Prev: The Methods of the Class, Up: Object ActionScript
Class
-1 Introduction
-**************
+3.4.7.2 The Properties of the Object Class
+..........................................
-Gnash is a free SWF movie player. It is available as a stand-alone
-application or as a plugin for several popular web browsers. It
-supports playing media from a disk or streaming over a network
-connection. Some popular video sharing sites like YouTube are supported
-from a wide vaariety of devices from embedded ones to modern desktops.
+constructor
- Gnash has a better focus on security, allowing the user tight
-control of all network or disk based I/O. Gnash also supports extending
-ActionScript by creating your own. You can write wrappers for any
-development library, and import them into the player much like perl or
-python does.
+__proto__
+
+__resolve
+
+Shareddata
+
+SharedonStatus
+
+
+File: gnash_ref.info, Node: Object Class Conformance, Prev: The Properties
of the Object Class, Up: Object ActionScript Class
+
+3.4.7.3 Object Class Conformance
+................................
+
+Class Name Conformance
+addProperty() This method has an unknown status.
+registerClass() This method has an unknown status.
+toString() This method has an unknown status.
+unwatch() This method has an unknown status.
+valueOf() This method has an unknown status.
+watch() This method has an unknown status.
+Sharedclear() This method has an unknown status.
+Sharedflush() This method has an unknown status.
+SharedgetLocal() This method has an unknown status.
+SharedgetSize() This method has an unknown status.
+constructor This property has an unknown
+ status.
+__proto__ This property has an unknown
+ status.
+__resolve This property has an unknown
+ status.
+Shareddata This property has an unknown
+ status.
+SharedonStatus This property has an unknown
+ status.
+
+
+File: gnash_ref.info, Node: Reporting Bugs, Next: Gnash Extensions, Prev:
Software Internals, Up: Top
+
+4 Reporting Bugs
+****************
+
+The Gnash project relies on the community of Gnash users to test the
+player, feedback is critical to any successful project. Not only does
+it let us know that people use Gnash, but it helps us understand the
+community's needs. Gnash uses a bug tracker on
+`http://savannah.gnu.org' to manage these reports.
+
+ When filing a report, please follow the guidelines below. The better
+your bug report is, the easier it will be for the developers to address
+the issue. Bug reports without enough information will initially be
+asked to provide this information anyway. Adding critical details, like
+the Operating System you are on, it's version, and any relevant error
+messages from Gnash that you get.
* Menu:
-* Audience::
-* What Is Supported ?::
+* Get a Fresh Binary Package::
+* Determine if the bug was previously reported::
+* Review the bug writing guidelines::
+* Filing a bug report::
-File: gnash_ref.info, Node: Audience, Next: What Is Supported ?, Up:
Introduction
+File: gnash_ref.info, Node: Get a Fresh Binary Package, Next: Determine if
the bug was previously reported, Up: Reporting Bugs
-1.1 Audience
-============
+4.1 Get a Fresh Binary Package
+==============================
-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.
+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.
+
+ You can get a fresh binary package of Gnash, as well as recent
+source packages from http://www.getgnash.org/packages
+(http://www.getgnash.org/packages/).
-File: gnash_ref.info, Node: What Is Supported ?, Prev: Audience, Up:
Introduction
+File: gnash_ref.info, Node: Determine if the bug was previously reported,
Next: Review the bug writing guidelines, Prev: Get a Fresh Binary Package,
Up: Reporting Bugs
-1.2 What Is Supported ?
+4.2 Determine if the bug was previously reported
+================================================
+
+Search the Gnash bug tracker
+(https://savannah.gnu.org/bugs/?group=gnash) to see if the bug has
+already been identified.
+
+ If the issue has already been reported, you should not file a bug
+report. However, you may add some additional information to the ticket
+if you feel that it will be beneficial to the developers. For
+instance, if someone reported a memory issue on Ubuntu GNU/Linux, and
+you noticed the same problem on OpenBSD, your stacktrace would be
+useful. Conversely, adding a "me too" note to a feature request is not
+helpful.
+
+
+File: gnash_ref.info, Node: Review the bug writing guidelines, Next: Filing
a bug report, Prev: Determine if the bug was previously reported, Up:
Reporting Bugs
+
+4.3 Review the bug writing guidelines
+=====================================
+
+A good bug report should be precise, explicit, and discrete. This
+means that there should be just one bug per ticket, and that a ticket
+should contain the following information:
+
+ * An overview of the problem;
+
+ * Instructions on how to replicate the bug;
+
+ * A description of what happened when you performed the steps to
+ replicate the bug, and what you expected to happen;
+
+ * Your system information: operating system name and version, as
+ well as the versions of major development dependencies;
+
+ * The release number or checkout timestamp for the version of Gnash
+ where you observe the problem;
+
+ * The file `config.log', which should be attached as a file;
+
+ * A descriptive title.
+
+ Include any additional information that you feel might be useful to
+the developers.
+
+
+File: gnash_ref.info, Node: Filing a bug report, Prev: Review the bug
writing guidelines, Up: Reporting Bugs
+
+4.4 Filing a bug report
=======================
-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 know to run on are Ubuntu, Fedora, Debian,
-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.
+After following the steps described above, you can file a bug report at
+`https://savannah.gnu.org/bugs/?group=gnash'.
- Gnash is a capable of reading up to SWF v9 files and opcodes, but
-primarily supports SWF v7, with better SWF v8 and v9 support under
-heavy developement. 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.
+
+File: gnash_ref.info, Node: Gnash Extensions, Next: RTMP Protocol, Prev:
Reporting Bugs, Up: Top
- Gnash has implemented about 80% of ActionScript v. 2.0, and has
-begun implementing ActionScript v. 3.0. Gnash supports the majority of
-Flash opcodes up to SWF version 9, and a wide sampling of ActionScript
-classes for SWF version 8.
+5 Gnash Extensions
+******************
- As ActionsScript 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.
+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.
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 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..
- Gnash has included video support since early 2007, but this is an
-every 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: http://www.gnashdev.org/dev_snapshots
-(http://www.gnashdev.org/dev_snapshots/).
+* Menu:
- 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.
+* Creating A New Extension::
+* Debugging An Extension::
+* Included Extensions::
+
+
+File: gnash_ref.info, Node: Creating A New Extension, Next: Debugging An
Extension, Up: Gnash Extensions
+
+5.1 Creating A New Extension
+============================
+
+Each new extension should live in it's own directory. The extensions
+included in Gnash are all in the _gnash/extensions_ directory. Creating
+an extension requires a Makefile.am,
+
+ If you are adding this extension to the Gnash source tree itself,
+then you need to make two changes to add the new extension.
+
+ The first change is to add the directory to the list in
+extensions/Makefile.am. This can be done either by adding the new
+directory to the SUBDIRS setting, or by wrapping it in a conditional
+test.
+
+ The other change is to add it to the AC_OUTPUT list in
+_configure.ac_ so the new directory will be configured along with the
+rest of Gnash.
+
+ Each extension should have an ActionScript source file included that
+tests the new class, and this file should be referenced in the new
+Makefile.am in the _check_PROGRAMS_ variable so that "make check" works.
+
+ When creating an extension that is a wrapper for an existing
+development library API, it's often better to make this a thin layer,
+than to get carried away with creating beautiful abstractions.
+Higher-level classes that offer a lot of new functionality are fine,
+but is different than wrapping a library so it can be used from within
+Gnash.
+
+* Menu:
+
+* Crafting an Extension::
+
+
+File: gnash_ref.info, Node: Crafting an Extension, Up: Creating A New
Extension
+
+5.1.1 Crafting an Extension
+---------------------------
+
+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.
+
+ The first function is commonly called _attachInterface_, 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 _init_member()_ to set a C function pointer to the string value
+used in the Flash movie.
+
+
+ // 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);
+ }
+
+ The second function is commonly called _getInterface()_, 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.
+
+
+ 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();
+ }
+
+ 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 _DummyExt_, and has two methods, _func1_ and _func2_.
+
+
+ static as_value
+ dummyext_ctor(const fn_call& fn)
+ {
+ DummyExt *obj = new DummyExt(); // will setup prototypes
+
+ return as_value(obj);
+ }
+
+ 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.
+
+
+ class DummyExt : public as_object
+ {
+ public:
+ DummyExt()
+ :
+ as_object(getInterface()) // returns the static prototype
+ {}
+
+ };
+
+ 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 _dummyext_, which also matches the
+file name of the extension. Gnash uses the name of the extension file
+itself when looking for the init function.
+
+
+ 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
+
+ The callbacks are all C functions. Like all the other code that
+implements ActionScript, parameters to the function are passed in using
+the _fn_call_ data structure. The return code, if any, is also returned
+using this data structure. _this_ptr_ is the object that the method is
+a member of.
+
+
+ // 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);
+ }
+ }
+
+
+File: gnash_ref.info, Node: Debugging An Extension, Next: Included
Extensions, Prev: Creating A New Extension, Up: Gnash Extensions
+
+5.2 Debugging An Extension
+==========================
+
+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 _after_ the extension has been
+loaded into Gnash's VM. The easy solution is to use the Gnash debugger.
+
+ 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 _c_ (for continue) command to the Gnash console.
+
+
+ // Get the debugger instance
+ static Debugger& debugger = Debugger::getDefaultInstance();
+
+ // Enable the debugger
+ debugger.enabled(true);
+ // Stop and drop into a console
+ debugger.console();
+
+ 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 _^C_ to drop into the GDB command
+console.
+
+
+ bool stall = true;
+ while (stall) {
+ sleep 1;
+ }
+
+ Once you have set the breakpoints you want, reset the value of the
+_stall_ variable to break out of the loop, and the Flash movie will
+then continue playing.
+
+
+ (gdb) set variable stall = false;
+ continue
+
+
+File: gnash_ref.info, Node: Included Extensions, Prev: Debugging An
Extension, Up: Gnash Extensions
+
+5.3 Included Extensions
+=======================
+
+Gnash has some extensions included in the distribution. This is mostly
+because they were written by the Gnash team. Extensions can be external
+to gnash, Gnash needs no compiled in knowledge to load an extension
+file.
+
+* Menu:
+
+* Gtk Extension::
+* File I/O Extension::
+* MySQL Extension::
+
+
+File: gnash_ref.info, Node: Gtk Extension, Next: File I/O Extension, Up:
Included Extensions
+
+5.3.1 Gtk Extension
+-------------------
+
+The GTK ActionScript class follows the same API as Gtk2, even down to
+the same arguments to the same function names. This means you're
+actually programming GTK,you're just using ActionScript instead of
+python, perl, or C. This extension makes it possible to write Flash
+movies that use the Gtk2 widgets for user interface components.
+
+window_new
+ Create a new window.
+
+signal_connect
+ Add an event handler to a widget.
+
+container_set_border_width
+ Set the width of the window border.
+
+button_new_with_label
+ Create a new button and give it the specified label.
+
+signal_connect_swapped
+ Swap signals. Commonly used for _delete_ event handling.
+
+container_add
+ Add one widget to another as a child.
+
+widget_show
+ Display the widget on the screen.
+
+main
+ Start the main GTK event loop. This function does not return.
+
+
+File: gnash_ref.info, Node: File I/O Extension, Next: MySQL Extension,
Prev: Gtk Extension, Up: Included Extensions
+
+5.3.2 File I/O Extension
+------------------------
+
+Flash movies are traditionally forbidden from accessing the filesystem,
+but this may be necessary for some embedded applications. Especially in
+the case of a user console, currently there is no way to get input into
+a Flash movie but through a TextField.
+
+fopen
+ Open the file.
+
+fread
+ Read a series of bytes from the opened file.
+
+fgetc
+ Read a single byte from the opened file.
+
+fgets
+ Read a single line until a Carriage Return from the opened file.
+
+gets
+ Read a single line from the standard in.
+
+getchar
+ Read a single character from the standard in.
+
+fwrite
+
+fputc
+ Write a single character to the opened file.
+
+fputs
+ Write a single line to the opened file.
+
+puts
+ Write a single line to standard out..
+
+putchar
+ Write a single character to standard out..
+
+fflush
+ Flush the current opened file to disk.
+
+fseek
+ Seek to a location within the opened file.
+
+ftell
+ Report the current position within the opened file.
+
+fclose
+ Close the opened file.
+
+
+File: gnash_ref.info, Node: MySQL Extension, Prev: File I/O Extension, Up:
Included Extensions
+
+5.3.3 MySQL Extension
+---------------------
+
+The MySQL ActionScript class follows the same API as MySQL, even down
+to the same arguments to the same function names. This enables a Flash
+movie to have direct access to a MySQL database. Traditionally Flash
+movies have had no database support, they either had to use arrays, or
+use XML to communicate to an application specific external database
+daemon.
+
+connect
+ Connect to a MySQL database.
+
+qetData
+ Get data from the database.
+
+disconnect
+ Disconnect from a MySQL database.
+
+query
+ Execute an SQL query to the database.
+
+fetch_row
+ Fetch a row from the query results.
+
+num_fields
+
+free_result
+ Free the results of a query.
+
+store_results
+ Store the results of a query.
-File: gnash_ref.info, Node: RTMP Protocol, Next: Authors, Prev:
Introduction, Up: Top
+File: gnash_ref.info, Node: RTMP Protocol, Next: Mozilla/Firefox NPAPI
Plugin, Prev: Gnash Extensions, Up: Top
-2 RTMP Protocol
+6 RTMP Protocol
***************
This document is based mostly on my own reverse engineering of the RTMP
@@ -401,7 +3737,7 @@
File: gnash_ref.info, Node: AMF Format, Up: RTMP Protocol
-2.1 AMF Format
+6.1 AMF Format
==============
The AMF format is used in the LocalConnection, SharedObject,
@@ -432,9 +3768,323 @@
the length is specified.
-File: gnash_ref.info, Node: Authors, Next: GNU Free Documentation License,
Prev: RTMP Protocol, Up: Top
+File: gnash_ref.info, Node: Mozilla/Firefox NPAPI Plugin, Next: Appendix,
Prev: RTMP Protocol, Up: Top
+
+7 Mozilla/Firefox NPAPI Plugin
+******************************
+
+The Mozilla SDK has two API layers for plugins. The older layer is
+documented in the Geeko Plugin API Reference
+(http://www.gnu.org/software/gnash/manual/plugin.pdf), and the newer
+layer doesn't appear to be documented. The new API is simpler, and is
+portable across multiple versions of Mozilla or Firefox. The new API is
+just a layer on top of the older one, so this manual still applies.
+
+ Most of the programming of a plugin is filling in real emphasis for
+the standard API functions and methods. Firefox uses these to create
+the plugin, and to send it data.
+
+ When initializing or destroying a plugin, no matter how many
+instances are being used, the C API is used. These functions are
+typically called once for each plugin that is loaded.
+
+* Menu:
+
+* Plugin C API::
+* Plugin C++ API::
+* OpenGL and Threads::
+* Plugin Event Handling::
+
+
+File: gnash_ref.info, Node: Plugin C API, Next: Plugin C++ API, Up:
Mozilla/Firefox NPAPI Plugin
-3 Authors
+7.1 Plugin C API
+================
+
+The lower layer is a C based API which is used by Firefox to initialize
+and destroy a plugin. This is so a plugin can be portable across
+multiple systems, since C++ emphasis is not portable between most C++
+compilers. This is where most of the behind the scenes work is done in
+a plugin. For Gnash, the sources this lower layer are in
+_plugin/mozilla-sdk_. They were added to the Gnash source tree so it
+wouldn't be necessary to have the Mozilla development packages
+installed to compile the Gnash plugin.
+
+ This is also the older API used for plugins, so is usually the one
+used if you dig around for plugin examples on the web. These are the
+main functions which have to be implemented in a plugin for it to be
+recognized by the browser, and to be initialized and destroyed.
+
+NS_PluginInitialize
+ This C function gets called once when the plugin is loaded,
+ regardless of how many instantiations there are actually playing
+ movies. So this is where all the one time only initialization
+ stuff goes that is shared by all the threads.
+
+NS_NewPluginInstance
+ This instantiates a new object for the browser. Returning a
+ pointer to the C++ plugin object is what ties the C++ and C
+ emphasis parts of the API together.
+
+NS_DestroyPluginInstance
+ This destroys our instantiated object when the browser is done.
+
+NS_PluginShutdown
+ This is called when a plugin is shut down, so this is where all
+ the one time only shutdown stuff goes.
+
+NPP_GetMIMEDescription
+ This is called to get the MIME types the plugin supports.
+
+NS_PluginGetValue
+ This is used by Firefox to query information from the plugin, like
+ the supported MIME type, the version number, and a description.
+
+
+File: gnash_ref.info, Node: Plugin C++ API, Next: OpenGL and Threads, Prev:
Plugin C API, Up: Mozilla/Firefox NPAPI Plugin
+
+7.2 Plugin C++ API
+==================
+
+The higher level layer is the one we are most concerned with. This is
+an instantiation of the _nsPluginInstanceBase_ class, as defined by the
+Mozilla SDK, for our plugin. With this API, a plugin is mostly defining
+the standard entry points for Firefox, and the emphasis that implements
+the glue between the Firefox and our plugin.
+
+ These are called for each instantiation of plugin. If there are
+three Flash movies on a web page, then three instances are created.
+Unfortunately for plugin programmers, these functions may randomly be
+called more than once, so it's good to use initialization flags for
+things that should only be done one per thread. For instance,
+_nsPluginInstance::init()_ and _nsPluginInstance::SetWindow()_ are
+called more than once, so the plugin must protect against actions that
+could be destructive.
+
+nsPluginInstance::nsPluginInstance
+ Create a new plugin object.
+
+nsPluginInstance::init
+ This methods initializes the plugin object, and is called for
+ every movie which gets played. This is where the thread-specific
+ information goes.
+
+nsPluginInstance::SetWindow
+ This sets up the window the plugin is supposed to render into.
+ This calls passes in various information used by the plugin to
+ setup the window. This may get called multiple times by each
+ instantiated object, so it can't do much but window specific setup
+ here. This is where the main emphasis is that sets up the window
+ for the plugin.
+
+nsPluginInstance::NewStream
+ Opens a new incoming data stream, which is the flash movie we want
+ to play. A URL can be pretty ugly, like in this example:
+
http://www.sickwave.com/swf/navbar/navbar_sw.swf?atfilms=http%3a//www.atm.com/af/home/&shickwave=http%3a//www.sickwave.com&gblst=http%3a//gbst.sickwave.com/gb/gbHome.jsp&known=0
+
../flash/gui.swf?ip_addr=foobar.com&ip_port=3660&show_cursor=true&path_prefix=../flash/&trapallkeys=true"
+ So this is where we parse the URL to get all the options passed in
+ when invoking the plugin.
+
+nsPluginInstance::Write
+ Read the data stream from Mozilla/Firefox. For now we read the
+ bytes and write them to a disk file.
+
+nsPluginInstance::WriteReady
+ Return how many bytes we can read into the buffer.
+
+nsPluginInstance::DestroyStream
+ Destroy the data stream we've been reading. For Gnash, when the
+ stream is destroyed means we've grabbed the entire movie. So we
+ signal the thread to start reading and playing the movie.
+
+nsPluginInstance::shut
+ This is where the movie playing specific shutdown emphasis goes.
+
+nsPluginInstance::~nsPluginInstance
+ This destroys our plugin object.
+
+NS_PluginInitialize::initGL
+ This is a Gnash internal function that sets up OpenGL.
+
+NS_PluginInitialize::destroyContext
+ This is a Gnash internal function that destroys a GLX context.
+
+nsPluginInstance::getVersion
+ This returns the version of Mozilla this plugin supports.
+
+nsPluginInstance::GetValue
+ This returns information to the browser about the plugin's name
+ and description.
+
+nsPluginInstance::URLNotify
+
+
+File: gnash_ref.info, Node: OpenGL and Threads, Next: Plugin Event Handling,
Prev: Plugin C++ API, Up: Mozilla/Firefox NPAPI Plugin
+
+7.3 OpenGL and Threads
+======================
+
+Neither OpenGL nor X11 has any built-in support for threads. Most
+actions aren't even atomic, so care has to be made to not corrupt any
+internal data. While it is difficult to render OpenGL from multiple
+threads, it can be done with the proper locking. The downside is the
+locking adds a performance hit, since all the threads will have to have
+the access synchronized by using mutexes.
+
+ The X11 context is maintained one per instantiation of the plugin.
+It is necessary to lock access to the X11 context when using threads by
+using _XLockDisplay()_ and _XUnlockDisplay()_. A connection to the X11
+server is opened for every instantiation of the plugin using
+_XOpenDisplay()_.
+
+ The _GLX Context_ is maintained one per instantiation of the plugin
+for a web page. If there are more than one Flash movie, there is more
+than one GLX Context. A GLX context can be created by using
+_glXCreateContext()_, and then later destroyed by using
+_glXDestroyContext()_. When swapping threads, the context is changed
+using _glXMakeCurrent()_.
+
+ All the emphasis that directly accesses a GLX context or the X11
+display must be wrapped with a mutex.
+
+
+File: gnash_ref.info, Node: Plugin Event Handling, Prev: OpenGL and Threads,
Up: Mozilla/Firefox NPAPI Plugin
+
+7.4 Plugin Event Handling
+=========================
+
+Firefox on most UNIX systems is a GTK+ application, so it is possible
+to have the plugin hook into the X11 event handling via GLX or GTK.
+Since Firefox uses GTK, so does Gnash. This also allows the addition of
+a right-click mouse menu for controlling the player. The GTK build of
+Gnash offers the best browsing experience as it's more functional than
+the SDL version.
+
+ It is also possible to disable the _GTK_ support so only the older
+_SDL_ support is used. In this case Gnash can't support event handling
+within the browser. This means that when using the SDL of the plugin,
+mouse clicks and keys pressed get ignored. Windows also can't be
+resized, and sometimes they overrun their boundaries as well. To
+disable the GTK support and force SDL to be used anyway, configure with
+_-disable-glext_
+
+
+File: gnash_ref.info, Node: Appendix, Next: Authors, Prev: Mozilla/Firefox
NPAPI Plugin, Up: Top
+
+8 Appendix
+**********
+
+* Menu:
+
+* Code Style::
+
+
+File: gnash_ref.info, Node: Code Style, Up: Appendix
+
+8.1 Code Style
+==============
+
+I know any discussion of coding styles leads to strong opinions, so
+I'll state simply I follow the GNU Coding Standards
+(http://www.gnu.org/prep/standards/standards.html). Where there is some
+flexibility as to the location of braces, I prefer mine on the end of a
+line when using an _if_, _while_, or _do_ statement. I find this more
+compact style easier to read and parse by eye. I'm also a big fan of
+always using braces around _if_ statements, even if they're one liners.
+
+ Here's my tweaked style settings for _Emacs_, the one true editor to
+rule them all.
+
+
+ (defconst my-style
+ '((c-tab-always-indent . t)
+ (c-auto-newline . t)
+ (c-hanging-braces-alist . (
+ (brace-list-intro)
+ (namespace-open)
+ (inline-open)
+ (block-open)
+ (brace-list-open)
+ (brace-list-close)
+ (brace-entry-open)
+ (brace-else-brace)
+ (brace-elseif-brace)
+ (class-open after)
+ (class-close)
+ (defun-open after)
+ (defun-close)
+ (extern-lang-open)
+ (inexpr-class-open)
+ (statement-open)
+ (substatement-open)
+ (inexpr-class-close)))
+ (c-hanging-colons-alist . ((member-init-intro before)
+ (inher-intro)
+ (case-label after)
+ (label after)
+ (access-label after)))
+ (c-offsets-alist . (
+ (innamespace . 0)
+ (case-label . 2)
+ ))
+ (c-cleanup-list . (
+ (scope-operator)
+ (empty-defun-braces)
+ (brace-else-brace)
+ (brace-elseif-brace)
+ (defun-close-semi)
+ (list-close-comma)
+ )
+ )
+ ;; no automatic newlines after ';' if following line non-blank or
inside
+ ;; one-line inline methods
+ (add-to-list 'c-hanging-semi&comma-criteria
+ 'c-semi&comma-no-newlines-before-nonblanks)
+ (add-to-list 'c-hanging-semi&comma-criteria
+ 'c-semi&comma-no-newlines-for-oneline-inliners)
+ ; (knr-argdecl-intro . -)
+ (c-echo-syntactic-information-p . t)
+ )
+ "My GNU Programming Style")
+
+ Another coding consideration: comments are good! Over commenting
+isn't good. Here is an over commented example:
+
+
+ counter++; // increment counter
+
+Gnash also uses Doxygen (http://www.doxygen.org) style comments. These
+are processed by Doxygen when building a cross reference of all the
+classes, and is a good way to help push internals documentation from
+the depths of the code into documentation where it can be seen by
+others.
+
+ _Doxygen_ style comments for _C++_ code involves simply using three
+slashes _///_ instead of the standard two slashes _//_ used for C++
+comments. Here's a short comment block for the _XML::cloneNode()_
+method:
+
+
+ /// \brief copy a node
+ ///
+ /// Method; constructs and returns a new XML node of the same type,
+ /// name, value, and attributes as the specified XML object. If deep
+ /// is set to true, all child nodes are recursively cloned, resulting
+ /// in an exact copy of the original object's document tree.
+ XMLNode &
+ XML::cloneNode(XMLNode &newnode, bool deep) {
+ ...
+ }
+
+ The _\brief_ keyword means that the text becomes associated when
+listing all the classes on the generated web pages. The text after the
+blank link becomes the detailed description which appears on the
+generated web page for that class and method.
+
+
+File: gnash_ref.info, Node: Authors, Next: GNU Free Documentation License,
Prev: Appendix, Up: Top
+
+9 Authors
*********
Gnash is maintained by Rob Savoye. Other active developers are: Sandro
@@ -898,32 +4548,149 @@
Tag Table:
-Node: Top175
-Node: Introduction1113
-Node: Audience1907
-Node: What Is Supported ?2235
-Node: RTMP Protocol4767
-Node: AMF Format14538
-Node: Authors15514
-Node: GNU Free Documentation License16215
-Node: 0_ PREAMBLE16978
-Node: 1_ APPLICABILITY AND DEFINITIONS18284
-Ref: fdl-document18509
-Ref: fdl-modified18800
-Ref: fdl-secondary18987
-Ref: fdl-invariant19632
-Ref: fdl-cover-texts19881
-Ref: fdl-transparent20094
-Ref: fdl-title-page21384
-Node: 2_ VERBATIM COPYING21773
-Node: 3_ COPYING IN QUANTITY22753
-Node: 4_ MODIFICATIONS25110
-Node: 5_ COMBINING DOCUMENTS31170
-Node: 6_ COLLECTIONS OF DOCUMENTS32667
-Node: 7_ AGGREGATION WITH INDEPENDENT WORKS33558
-Node: 8_ TRANSLATION34786
-Node: 9_ TERMINATION35689
-Node: 10_ FUTURE REVISIONS OF THIS LICENSE36344
-Node: Addendum37484
+Node: Top168
+Node: Introduction1999
+Node: Audience2800
+Node: What Is Supported ?3128
+Node: Building from Source5660
+Node: Overview6040
+Node: Getting The Source7082
+Node: Releases7288
+Node: CVS Access7656
+Node: Code Dependencies8368
+Ref: Code Dependency Table9065
+Node: Testing Dependencies34580
+Ref: Testing Dependency Table34888
+Node: Documentation Dependencies38812
+Ref: Documentation Dependency Table39081
+Node: Configuring Gnash48149
+Node: Features50443
+Ref: Configuration Options - Features51043
+Node: Specifying Custom Paths57373
+Ref: Custom Path Options57843
+Node: Compiling the Code67466
+Node: Creating the Documentation68407
+Node: Running the Tests69753
+Node: Using DejaGnu70207
+Node: Increasing Verbosity70570
+Node: Running Some Tests71106
+Node: Running The Tests Manually71926
+Node: Movie tests72588
+Node: ActionScript Unit Tests72942
+Node: Installation73259
+Node: Libraries74572
+Node: Executables75428
+Node: Documentation76298
+Node: Cross Configuring77053
+Node: Software Internals80133
+Node: A Tour of Gnash80402
+Node: The Libraries80969
+Node: libgnashbase81272
+Node: libgnashgeo81696
+Node: libgnashgui81911
+Node: libgnashserver82180
+Node: libgnashasobjs82551
+Node: libgnashamf82787
+Node: libgnashbackend83210
+Node: libgnashplugin83525
+Node: libklashpart83731
+Node: The Applications83901
+Node: The Standalone Player84268
+Node: Gprocessor84566
+Node: SOLdumper84960
+Node: Dumpshm85227
+Node: The Plugin85446
+Node: Current Status85924
+Node: GUI Support86482
+Node: Mozplugger88163
+Node: Klash90054
+Node: The Debug Logging System90604
+Node: Logging System C API92165
+Node: Logging System C++ API94369
+Node: Sound handling in Gnash96210
+Node: Sound types96953
+Node: Sound parsing97490
+Node: Sound playback98058
+Node: The SDL sound backend98588
+Node: The Gstreamer backend99907
+Node: Future audio backends100923
+Node: Detailed description of the Gstreamer backend101413
+Node: Testing103664
+Node: Testing Tools104135
+Node: Test Cases104967
+Node: Writing ActionScript Tests105546
+Node: Writing Ming-based self-contained SWF tests108049
+Node: Using Ming-based test generators facilities109206
+Node: Writing self-contained SWF tests with other compilers111566
+Node: Writing Test Runners114691
+Node: Using the generic test runner for self-contained SWF tests116440
+Node: Writing Movie testers118530
+Node: Adding New ActionScript Class120270
+Node: Prototype121450
+Node: Declaration122867
+Node: Instantiation123132
+Node: Methods123759
+Node: Accessing Arguments124150
+Node: Returning a Value to ActionScript124546
+Node: Additional fn_call Members124925
+Node: Dynamic Properties125779
+Node: The as_value Object Type127284
+Node: Data Types127722
+Node: Determining the Type128043
+Node: Fetching the Value128575
+Node: Setting the Value and Type129065
+Node: Further Reading129659
+Node: Object ActionScript Class130074
+Node: The Methods of the Class130414
+Node: The Properties of the Object Class130753
+Node: Object Class Conformance131068
+Node: Reporting Bugs132607
+Node: Get a Fresh Binary Package133600
+Node: Determine if the bug was previously reported134378
+Node: Review the bug writing guidelines135196
+Node: Filing a bug report136247
+Node: Gnash Extensions136530
+Node: Creating A New Extension138800
+Node: Crafting an Extension140218
+Node: Debugging An Extension144522
+Node: Included Extensions146214
+Node: Gtk Extension146658
+Node: File I/O Extension147645
+Node: MySQL Extension148831
+Node: RTMP Protocol149682
+Node: AMF Format159478
+Node: Mozilla/Firefox NPAPI Plugin160454
+Node: Plugin C API161472
+Node: Plugin C++ API163331
+Node: OpenGL and Threads166595
+Node: Plugin Event Handling167923
+Node: Appendix168892
+Node: Code Style169044
+Node: Authors172874
+Node: GNU Free Documentation License173570
+Node: 0_ PREAMBLE174333
+Node: 1_ APPLICABILITY AND DEFINITIONS175639
+Ref: fdl-document175864
+Ref: fdl-modified176155
+Ref: fdl-secondary176342
+Ref: fdl-invariant176987
+Ref: fdl-cover-texts177236
+Ref: fdl-transparent177449
+Ref: fdl-title-page178739
+Node: 2_ VERBATIM COPYING179128
+Node: 3_ COPYING IN QUANTITY180108
+Node: 4_ MODIFICATIONS182465
+Node: 5_ COMBINING DOCUMENTS188525
+Node: 6_ COLLECTIONS OF DOCUMENTS190022
+Node: 7_ AGGREGATION WITH INDEPENDENT WORKS190913
+Node: 8_ TRANSLATION192141
+Node: 9_ TERMINATION193044
+Node: 10_ FUTURE REVISIONS OF THIS LICENSE193699
+Node: Addendum194839
End Tag Table
+
+
+Local Variables:
+coding: US-ASCII
+End:
Index: gnash_user.info.in
===================================================================
RCS file: /sources/gnash/gnash/doc/C/preformatted/gnash_user.info.in,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- gnash_user.info.in 2 Mar 2008 16:32:21 -0000 1.1
+++ gnash_user.info.in 2 Mar 2008 17:54:16 -0000 1.2
@@ -1,8 +1,7 @@
-This is gnash_user.info, produced by makeinfo version 4.8 from
-gnashuser.texi.
-
START-INFO-DIR-ENTRY
-* Gnash User Manual: (gnash_user). [MISSING TEXT]
+This is gnash_user.info, produced by makeinfo version 4.11 from
gnash_user.texi.
+
+* Gnash User Manual: (gnash_user). Gnash
END-INFO-DIR-ENTRY
@@ -179,175 +178,175 @@
PNG
-
IHDR 6 ÀSh pHYs : Êduh tIMEÕ EöH
IDATxÚì}ydU}ïï,w¿µvWwÏ* à ì*EÑã.F1Ä$ïÅ|address@hidden
Am¥g¦»Ö»õýQÝ=5ÝUÕÕQôþ>ý©S·îrÎ=ç{¾¿åü ñYÏ;ÿíÇà yð=6mA Ðü?¹äK.CEÖ öìÙ}ü¶Í«»ÎÃ=pç7+¥Æø}øè9ç½hzú C©É
øìnáÆF¥±ãÓ$ñIC±¶íUã(ô=+XóÀ°Kq^Ê dÍbµË¥R)¬" ~µ+j
+
IHDR 6 ÀSh pHYs : Êduh tIMEÕ EöH
IDATxÚì}ydU}ïï,w¿µvWwÏ*
à ì*EÑã.F1Ä$ïÅ|address@hidden>ý©S·îrÎ=ç{¾¿åü ñYÏ;ÿíÇà yð=6mA Ðü?¹äK.CEÖ öìÙ}ü¶Í«»ÎÃ=pç7+¥Æø}øè9ç½hzú C©É
øìnáÆF¥±ãÓ$ñIC±¶íUã(ô=+XóÀ°Kq^Ê dÍbµË¥R)¬" ~µ+j
¢c
½,iËÕ8a1vüb%I2HÈ×/%Ij+*Yd¹Å4Ir
ÛÏÒص-& 1¼,<address@hidden:,<ßg\!jì°4,)2
lÎ"×-0&
-LÁcÛñV)Ór9ãER%Rj:3Ó Ra-3B-ÎiR(%8³,SH
6ÏlÛR!-42¤È,ËæBaèiZBJ´¢$£%
$`-9¡¦¤4ÖcbH))ÁJ#ÆT*A
Q¨Rª4Rª%!D+
a$&D)Ý´Va¥Âz¾ZBZk47Ui 4ÿï¾zèÇóçv»îÜõAkèw»ù¢Âé
¢Rw-Tg¡vRPÚSwÉ©aJ©R Ý¢!¥ojN
C
-5×Ôb)kj!(%J#&¦àÜ4
©æÞ¬äe[Bj¤¹F¦à©m»\HEIT`HZ¶Ã¸ X+ R¤¦åpÆ¥&J$é2Y&
+LÁcÛñV)Ór9ãER%Rj:3Ó Ra-3B-ÎiR(%8³,SH
6ÏlÛR!-42¤È,ËæBaèiZBJ´¢$£%
$`-9¡¦¤4ÖcbH))ÁJ#ÆT*A
Q¨Rª4Rª%!D+
a$&D)Ý´Va¥Âz¾ZBZk47Ui 4ÿï¾zèÇóçv»îÜõAkèw»ù¢Âé
¢Rw-Tg¡vRPÚSwÉ©aJ©R Ý¢!¥ojN
C
+5×Ôb)kj!(%J#&¦àÜ4
©æÞ¬äe[Bj¤¹F¦à©m»\HEIT`HZ¶Ã¸ X+ R¤¦åpÆ¥&J$é2Y&
kÃeYbÛÝnì²,ò\ T
Äaiäû
K¬S
B1ͦͳÐóiÆ
,%s(Í,
B
¶[Lı
DñÈ´I{®ÅÒ"¢f!IÂïeL0õ¸ÓÂDEøIܪVÇ¢DP$ò³¸Y®Ö¢851ತU,EQbQɵÅÓãã$5ÊÂ=o}Í`f¶Î[Ô]&jãa Àþ¥ºÒ
·Ýò¾ÿ·Ðóιàò±8
-Î:ã$4Oº½4K³[¿ßDöÏ×ßÂ,î|/0Çâötu|¢ÙN}+¤t¦ËcSÍVXrU¦,Ú_ªlh¶ÚåIËãýÅʦf«9V²ÌRÉ~¿²¹Õ¬ÝNJ«ÛÅ
A{¶Rò; Ù1ÝZÔË¥b'Äت$a£T*u"nLÓR×ÅJe!$òYÒðÕ0J<rDÚpca\JS¦M§0
AÁ3nhÖ´½ñ(êø0D`8å4<ÏI2À:&V1×sLQ!ê±4t7ɤAÆÈBÛñÒT+°mÇO3f
´!ydÙ~f¶E¸$ZDUȲԶ(address@hidden)2Ã0¹P+address@hidden
+Î:ã$4Oº½4K³[¿ßDöÏ×ßÂ,î|/0Çâötu|¢ÙN}+¤t¦ËcSÍVXrU¦,Ú_ªlh¶ÚåIËãýÅʦf«9V²ÌRÉ~¿²¹Õ¬ÝNJ«ÛÅ
A{¶Rò; Ù1ÝZÔË¥b'Äت$a£T*u"nLÓR×ÅJe!$òYÒðÕ0J<rDÚpca\JS¦M§0
AÁ3nhÖ´½ñ(êø0D`8å4<ÏI2À:&V1×sLQ!ê±4t7ɤAÆÈBÛñÒT+°mÇO3f
´!ydÙ~f¶E¸$ZDUȲԶ(address@hidden)2Ã0¹P+address@hidden
!AJ2B-)%Xj¬#ÔB»Ð±!¥$w7ÂT)I0V BD+0Öº5´BÍÍõC+=wÐóX¥»Ð3ÁnqávswÇK¥1Ò]$"Ì(Å
5¤Òd¡v 9Ww[fR"ŵ8ç¦AÐSKpfÀÀ55WKÀ¦`©iYKB¦äe9ã&Õ
ÉcËò2Y*v!MÇ¢L-BÓ.¦Iì:fÊR1µ
Y¹rÀ:%¥ëºI&
Äú,鸤Ü$Bc¥×+ÄIfJ"W¤-Ç+GqâÙ)[¦
§0
a·«¬ájaÐ.ì(#7-¿RÁ
SUÛpÆã°Y*úA¬]
AQNÂÙR©Ú
Sײh¦Xªµ¨àèLû<:P¬LµÚ²Obáîn6ÆËv'3U²ß¯li5fjU¿cÄgâævóÀxµÔ4MÓßÐi«VÚ¤b³$£]¿öº:ö)'n÷<·jÀmwÞkÛ^Ggzi~ëæ;ÇÇkïÿ¿N.xÑKN:å
Ç&_ɸT
KAixr÷^ÏóôÀ®N¤ÇiÌãrÐ.Ç6"×ÈR]Zû
-åÙgËûI0í'gê¢;©
ûâÔìl½\0!âýVaC}v¦\rê!Ré,u'RÁ«ñ6²ÆÚÍBÁ¯w8Ñ¡¢å
=ëùÅz;3PÊ ³WntðTºiT·Ýr³Ù¸ÅuÓ©4Ûkã ¥,iP§Ún·]v"±«íNËuÌNkQ
-íXHi)âGaDzìN,Jr(0,'8δÅ5 Ω4²4 F)Á:å¥!6¼0Jbx"âØ
address@hidden f&Ð$Zq¡h%Ó$Z®ËÀFq
ÌX
+åÙgËûI0í'gê¢;©
ûâÔìl½\0!âýVaC}v¦\rê!Ré,u'RÁ«ñ6²ÆÚÍBÁ¯w8Ñ¡¢å
=ëùÅz;3PÊ ³WntðTºiT·Ýr³Ù¸ÅuÓ©4Ûkã ¥,iP§Ún·]v"±«íNËuÌNkQ
+íXHi)âGaDzìN,Jr(0,'8δÅ5 Ω4²4 F)Á:å¥!6¼0J
bx"address@hidden f&Ð$Zq¡h%Ó$Z®ËÀFq
ÌX
address@hidden
YÆ ÀyªfÓ Lh!Ô$c\0®àRcƹÖÝ¢1.¤F+!¥
¸PB*!µè~/r¡ÔBj!UÏR)
TBRHÅ¥B
©º'Î5â¼{1Î¥FJI.cL>Tä1®µf-Ô æën¦iJî6Ef£i)3
F¦$SZ2Æ¡¦Ö\(¥1&FrÐ)ÊÒQ+J2T&K#L(I F Ç,ë¾èØ4H!ÈðÃ(2
¦ZñP/
CÓ4ÃDi+ìFÑB¿Êr¨mZn'Êp¦$n¶ßRÈTØiÔ4íb;,"n²¸a8åV;pmÒIHSmµZ¾gµ"¤²&¶ÇÚ¦ïÙÍPhQ
ÚuÏsÀ*P¤´ë_¨·3%£ÎçëØ¢,U^Ì8~µÞ\K
ÜÍÂN¡6Ûh]ÜN-îw
-fêõJÁªGTÄÓvqóÌÌÁjÙé Íf
oC}v¥\iK,ÈjÖ§Ëåòl[QJÀÐÑé'=3K[·d¬Ûs@(-¥Vfëu)address@hidden
TiÄÁR]ÛÓ
òÄL=(Ø*â^ì÷³õVÉÅíÔæѧ85;Û(ÌFDU|Àò7Ôë³;
Èf©;ÑlÌ^=PX´5ÖiÍ
FGPIRÛ³¾_l´3g
+fêõJÁªGTÄÓvqóÌÌÁjÙé Íf
oC}v¥\iK,ÈjÖ§Ëåòl[QJÀÐÑé'=3K[·d¬Ûs@(-¥Vfëu)address@hidden iÄÁR]ÛÓ
òÄL=(Ø*â^ì÷³õVÉÅíÔæѧ85;Û(ÌFDU|Àò7Ôë³; Èf©;ÑlÌ^=PX´5ÖiÍ
FGPIRÛ³¾_l´3g
IXw½R³[D¤ÒÍ¢åíÈ1uÄ-4L§Üê´iØN»ã9´`5SítÚcubмR´ÇìD
d¤Û²X`Jä¤QÇ´ì0b8?V"I§a(Ñ)'<áFQbR0$X©G±Iqâ7c$SZ¤YiSBLiÉYb$© -2X"b$ B¥iÆ4ó.Zq
$x¦e¼Vgq Ä8Φq
À¹RH
ù<ZI)¥B\s©RRJ%¥BJ¥
ÐBuÁKJµªæqM*!ô¡S¤BIBH¥K-e÷ús·RJÕ-¢îÝ
Ds
s¡çLÉ ¹ Á3 ±¹ÊÎ×=Ãe¤È42³4#§Lk)0³4#¤Ljɤ6²4Å&©oê3NÉáY©$
ÂYÜE+!å¸ûf£(6)2,D
eÐ(address@hidden
-Ë 2ÑØ£À:¼_YD gÚNã¶ey 1Ì%-Ó.vØ6
æOSnwææ`6©]m·ÛÏlEH³&±«V£àÙÍP#Ñ£´¾ï5Iu¤h9ìÔ}¿Ðh3§âάëĦ<U~̺~¥Ñ
=KGÜaáAǯÕí¢KÚ©)¢vaª^¯W
-f=¢*9`ùfgÝ6 ¡îÆìj¥8ÓT6=ÙjLW+åÙ3!P´mÛq%6
º{¸:z½uý×nþôg¯ÿþ]?VJõ¥>ôçúo_üf¥\ܲibÓÆ×$µÆa,LÌ8xi0S*UÖã%ªÂý¥Jíàl§ìéû29P(OÎÖ[Õi'Îx¥©úl}¬d7BùA»8U©U½ÙP9Kü©Vcv¬â϶¥
°kæL¹\¬·¹Mb+i{¶T*5Úc0¦<õåF;ö,JO¦u·PiµÂ"f)Öp¼J»<¤xÓò*v§è#Ñ4ݱN«U*ØíH]vÁs:¡¢(QF1
Úçv"nb&'¢ãxAÈ-*rdÚ±/2ËЩ0-Ë¢Ä6QÊ©¡1W$q #jyQ;¶eUD
address@hidden,address@hidden SBÍ,åBÆ ¨S3K¡q abÊQ3®æ11ãi0QJ`
ThΪÕ-J4gfc¥Õ\¤A£®Mj¾ØWº&°EWÐ
-c$¤D °Öc,D×¢µæÁF fSÁÁÀ8Í0¡YÆ)A£neÓ43(I bb±45)M2
kbÉ$5L¤
!±%ÓÄ0Í$t¾©MÃLNbÂP"6,;NI!TØ°8N-%
¨åÆQlÛ4Î ÉX~®c":Õ¦GëXa,)dúiÔq'¸¹
®:ëuÂÌ¢+G¤mÇõ;aj*¶bmÛ-vȳQÄLÍ[[î´ß¥ABhXnµÝjv3DD5±3Öi5KE§hmWv³TòaáXârÚ®KÅF;shÆuuê
R¹Ñ}K¦Òçɬ_¬4aÑ
¹*ñJµz£U)Ðvb qõz}¼ÜÂâÆúìÁ1ÿ`L5CýÍÙµ±âÁ°Q[;address@hidden>I¨ÞhÝsïOºHtÎÙ'~/`ÕÆË[7M>úøî^üJ
îéa¸÷Ó¶£¶\yŶl¸üÒópìi--*z2ëT*v]®HE$«cí
®4d³åêd§Ó/D:Ï*SN«V±CnP9ë7íæä¸×I°©Nq*îÔkc~'¦WË¢ÆXµ&Ò¥1±ª<iV*å0æ¾É-ª¬Y*W¢8+ÚJaO³V¡Tã¤äam¿PMâ¸ì&M"Ûn¡Æa¥`¦RÕqü±4îTKv°
¡åUxNÊÁ" µ27eÊ¡¾âï{®):
"Ïó箥[HÅ®ëqÎ<+0°Jl×<ó"H-Ç<ó]C(L!5m_ÔsL¡¹aºJd®cJ©M,iÊÇJYTj"address@hidden
L±f¦e)--"qÃ4µ¦ ¸aZËÄEa¢HRJ(bbMÁh¡`õ\ !cM Ƹ{a
` address@hidden&c¬ç¾ÄzþúhþvceP6àîýEIîÂ#ahi0ÆóµM¢QÄÓÒ;U
Ì©aiÅlÛP" address@hidden&¨ÛÔ¶)´uf;Â1Å:µGæÚX%:±WòÌs
©Ñ©éø%Ïä(5l_²Ø÷l&ÀÄZ¾äQÁw2¡lʱáén¿bÂ5%¢¡ï²yÖȺ~1MÓ¶°
\¿%QɧLTµ,IÂjÉ6¡m{ãiÜ®Ý8C·ÊâVµìGrHL2OZr1
g2dDÚ*WÊa©¯²F©\¢¤ìñF±R`¬HaÑ('Nk¢bYwoÛõ©ß±
u»¸1ìÌLÕH»¤møSIpp¢Vm²`Ä®±h¶\*Å©°(7sjDQôã<ü£ûþñOîòbt°P³Ù¦\ýúËw>ú¤V
+f=¢*9`ùfgÝ6 ¡îÆìj¥8ÓT6=ÙjLW+åÙ3!P´mÛq%6
º{¸:z½uý×nþôg¯ÿþ]?VJõ
¥>ôçúo_üf¥\ܲibÓÆ×$µÆa,LÌ8xi0S*UÖã%ªÂý¥Jíàl§ìéû29P(OÎÖ[Õi'Îx¥©úl}¬d7BùA»8U©U½ÙP9Kü©Vcv¬â϶¥
°kæL¹\¬·¹Mb+i{¶T*5Úc0¦<õåF;ö,JO¦u·PiµÂ"f)Öp¼J»<¤xÓò*v§è#Ñ4ݱN«U*ØíH]vÁs:¡¢(QF1
Úçv"nb&'¢ãxAÈ-*rdÚ±/2ËЩ0-Ë¢Ä6QÊ©¡1W$q #jyQ;¶eUD
address@hidden,address@hidden SBÍ,åBÆ ¨S3K¡q abÊQ3®æ11ãi0QJ`
ThΪÕ-J4gfc¥Õ\¤A£®Mj¾ØW º&°EWÐ
+c$¤D °Öc,D×¢µæÁF fSÁÁÀ8Í0¡YÆ)A£neÓ43(I bb±45)M2
kbÉ$5L¤
!±%ÓÄ0Í$t¾©MÃLNbÂP"6,;NI!TØ°8N-%
¨åÆQlÛ4Î ÉX~®c":Õ¦GëXa,)dúiÔq'¸¹
®:ëuÂÌ¢+G¤mÇõ;aj*¶bmÛ-vȳQÄLÍ[[î´ß¥ABhXnµÝjv3DD5±3Öi5KE§hmWv³TòaáXârÚ®KÅF;shÆuuê
R¹Ñ}K¦Òçɬ_¬4aÑ
¹*ñJµz£U)Ðvb qõz}¼ÜÂâÆúìÁ1ÿ`L5CýÍÙµ±âÁ°Q[;address@hidden>I¨ÞhÝsïOºHtÎÙ'~/`ÕÆË[7M>úøî^üJ
îéa¸÷Ó¶£¶\yŶl¸üÒópìi--*z2ëT*v]®HE$«cí
®4d³åêd§Ó/D:Ï*SN«V±CnP9ë7íæä¸×I°©Nq*îÔkc~'¦WË¢ÆXµ&Ò¥1±ª<iV*å0æ¾É-ª¬Y*W¢8+ÚJaO³V¡Tã¤äam¿PMâ¸ì&M"Ûn¡Æa¥`¦RÕqü±4îTKv°
¡åUxNÊÁ" µ27eÊ¡¾âï{®):
"Ïó箥[HÅ®ëqÎ<+0°Jl×<ó"H-Ç<ó]C(L!5m_ÔsL¡¹aºJd®cJ©M,iÊÇJYTj"address@hidden
L±f¦e)--"qÃ4µ¦ ¸aZËÄEa¢HRJ(bbMÁh¡`õ\ !cM Ƹ{a
address@hidden&c¬ç¾ÄzþúhþvceP6àîýEIîÂ#ahi0ÆóµM¢QÄÓÒ;U
Ì©aiÅlÛP" address@hidden&¨ÛÔ¶)´uf;Â1Å:µGæÚX%:±WòÌs
©Ñ©éø%Ïä(5l_²Ø÷l&ÀÄZ¾äQÁw2¡lʱáén¿bÂ5%¢¡ï²yÖȺ~1MÓ¶°
\¿%QɧLTµ,IÂjÉ6¡m{ãiÜ®Ý8C·ÊâVµìGrHL2OZr1
g2dDÚ*WÊa©¯²F©\¢¤ìñF±R`¬HaÑ('Nk¢bYwoÛõ©ß±
u»¸1ìÌLÕH»¤møSIpp¢Vm²`Ä®±h¶\*Å©°(7sjDQôã<ü£ûþñO îòbt°P³Ù¦\ýúËw>ú¤V
õP,ô¦·¼ëõo~ÅbÛÑÛº<m¤!)åÍ·Ý511ùÏ×ßê)®ëvÂÔ5À¥,)UÆZ¤`Ë
-"®JãNXòP"ÕÝbÓîFÄ,`u»8Ñi·ªE§,?v×êuÆã°Q*úX(Æf%
b1¸M"·üB1cJ<¶]¿F©gÓ¶Ê:¶W¢ØwH*MÍ;[£ØwiÂi׬ġïZ1CX
½P¢lX¹®Óµ²õx9dÒÄBa[²Ø²
(±i¹YÆ»Vv-bÃr³Y&æL©é2Ù&aϳ̶h6gew8Ë,²9Ó¯-xfúÝ4¹i¨¬ke'æ\ÔRR¤Æ
address@hidden<gt_deD´Rc5ç¬ìÝ"address@hidden< 5`zÎ_
jávî®Â4`Ða¢Â´Æ »îQI0R½u§HªnÑSJ¬"¦Ì KÀÐ[ì6µ!ë65EJ!CÌ0-Æ
A´CÔ0mƸIÐÝ7ë0Æ,ðCo6ul#åëËÇ6S2D]Åm¥LSĺ"ìù~¥±#Xd;n2j,É"Ûñ$³MàÚÒ<°b$®M2AASãÐwÍ$Ã-'aPôí0CD
Ô.'Q§XpD#«EíBÁbiLÓÛ
B!c
+"®JãNXòP"ÕÝbÓîFÄ,`u»8Ñi·ªE§,?v×êuÆã°Q*úX(Æf%
b1¸M"·üB1cJ<¶]¿F©gÓ¶Ê:¶W¢ØwH*MÍ;[£ØwiÂi׬ġïZ1CX
½P¢lX¹®Óµ²õx9dÒÄBa[²Ø²
(±i¹YÆ»Vv-bÃr³Y&æL©é2Ù&aϳ̶h6gew8Ë,²9Ó¯-xfúÝ4¹i¨¬ke'address@hidden<gt_deD´Rc5ç¬ìÝ"address@hidden<
5`zÎ_ jávî®Â4`Ða¢Â´Æ »îQI0R½u§HªnÑSJ¬"¦Ì
KÀÐ[ì6µ!ë65EJ!CÌ0-Æ
A´CÔ0mƸIÐÝ7ë0Æ,ðCo6ul#åë
ËÇ6S2D]Åm¥LSĺ"ìù~¥±#Xd;n2j,É"Ûñ$³MàÚÒ<°b$®M2AASãÐwÍ$Ã-'aPôí0CD
Ô.'Q§XpD#«EíBÁbiLÓÛ
B!c
|6=¿D©g)®]5]¿Ú £¢aiÖtýñNÐ)ûfÈ(â
Ûì´ce§"êVaªÓªWüf¦nSw"lÏV+ÅV(m"k,ër9
EP_EOþÚë.è´Ï=ëT)address@hidden
óV«®·þøjããùÂ-®Ø¤Ì"Ba/
R¥$¥òXÒ,« ò)G¦M¯0Ö
¢GajÖtüZ´K¾1xÛòÇÃN«\t
-
§bÁE!!f)Û
&ÂD
,i{^!JM¥Ä®H;®WÔ1¥X`»Å(N\3ejZn1cϦ
ZF¦]LâÈsÍcaÒ8ô\+auBÌK#DZS¦pLÅí¤LR, ÛÇådL¤ë9J-ËÎ0(HMµH
Ëɳ(hRc¡O#P6ce\R¶`Ì4)s#Jf
+
§bÁE!!f)Û
&ÂD
,i{^!JM¥Ä®H;®WÔ1¥X`»Å(N\3ej Zn1cϦ
ZF¦]LâÈsÍcaÒ8ô\+auBÌK#DZS¦pLÅí¤LR, ÛÇådL¤ë9J-ËÎ0(HMµH
Ëɳ(hRc¡O#P6ce\R¶`Ì4)s#Jf
#ØÔRa¤ J2B
)ÆZéúà¥#X+A!¤8î@%!X*z® V
-!h×
§4 wðÒ`.v#¤æâ
Ûuô¡" 4 ÑáøÕu("@zñ)z"æ!5WÄZ˹èîѹg/%ÆDI
1RR
-J°Téù"ÅR"¤9"¦Ü DH@ 6¤à¥Bj$`C F©Á¥"address@hidden WTF
±Ì6)©.cmk¤1\%mf\à:"KlÛîíW¶å¤D+dIY¶¦eÔ¦äåøi:fÊÐ<4bÄm¤L»ÄïÙqDÅÔ.&qPð(ÓT§Ø,dIÇ÷¼(ÊágIà{^p
-
=v\¿Ec*ÈÚ®W£Øs0b-ǯaXtiÂ
Í[?tZ墦åOF¹ä1Ý1ñ0hTJ
v$Ma«õR¹Ü¸E8¢>gN÷¿íõ/ît:µ²iâ:}bo¡X£pã1BÈaGütçµüä_¡_ûõß¹æí¿¥µÞ7½ÑäH¬À§þùdod\QÄõXÒö
(fÚ(dQÓ/¢Ù¦ÈcqÓ+£(qm$´ÍÓëWÂ(*84S¦H?
AÑ·Nk[n5o'
!N9ϵÓy4IÀs»Q¥ãzi&"address@hidden'SHÔ¶
Tñ°ëvmI¬ElX~&¶m2JçûÅÆ!êXŸÂH"l
-Ÿ¤XkdH¦Í¹0(( =E¤4"5LsfX*¢eF[pfD*¤#t¾(ÀØR#P©ÚããçR©y¿
Êy2¢À.EÅyn¥0FZ£CÌ!
æCP÷hUuÁfQj-±h-¥»ÁX ÁüÝ Ò ÝH1¬ ®UKIL°RzPe
¡óáèð"ÌÑL)!JA·©¥ä´^ݦ],S¨ÌcµZ#*EF
KpA)hM¥è¾h>÷f»1z,3M*ÒrË,ò9,sK-Ëàz¾_$Ø<mÛÎ4ÒÈâ,²m7eÜ¢
Á,²l/Ímb¡¨ä¡å¤ÛâéÓ8v]ñ®&QÏ ò³$t]'address@hidden,±0]
SdCØL8UYËöÇ¢
],ºqìN%ÛÅ¥èÅ,,Ûî4|÷Õ/ÙcÙâ8¬A) ì?0#¥Xttã)address@hidden)rÁ\rÉe¬û¨]y±|×åÜűM;ïtñ'¦r뺲K³6=bcñü36nüþíôë+
ÀyÈ%\Ö&·ÿÍêÎÿëÁ9ï½÷¶"ÎÛ0\ryºHX¹äKX¹äK.9`åK.9`åK.¹äK.¹äV.¹äV.¹äKX¹äK.9`åK.9`åK.¹äK.¹äV.¹äV.¹äKX¹äK.9`åK.9`åK.¹äK.¹ä2м
FøÜ^CÙ@(¡ÃÁÄP2 ¨Ú+Ø+\rÀúE¥¡×¾if ÔÜ! Ì$p ¡ÊL
- address@hidden@iD0R¦Â ³)<ÖDH¡©
;îOÀp<BHÐé Åsw
b9V¡¤¥´Åhm9MlZ®§{åI¥ë)h2Î
+!h×
§4 wðÒ`.v#¤æâ
Ûuô¡" 4 ÑáøÕu("@zñ)z"æ!5WÄZ˹èîѹg/%ÆDI
1RR
+J°Téù"ÅR"¤9"¦Ü DH@ 6¤à¥Bj$`C F©Á¥"address@hidden WTF
±Ì6)©.cmk¤1\%mf\à:"KlÛîíW¶å¤D+dI
Y¶¦eÔ¦äåøi:fÊÐ<4bÄm¤L»ÄïÙqDÅÔ.&qPð(ÓT§Ø,dIÇ÷¼(ÊágIà{^p
+
=v\¿Ec*ÈÚ®W£Øs0b-ǯaXtiÂ
Í[? tZ墦åOF¹ä1Ý1ñ0hTJ
v$Ma«õR¹Ü¸E8¢>gN÷¿íõ/ît:µ²iâ:}bo¡X£pã1BÈaGütçµüä_¡_ûõß¹æí¿¥µÞ7½ÑäH¬À§þùdod\QÄõXÒö
(fÚ(dQÓ/¢Ù¦ÈcqÓ+£(qm$´ÍÓëWÂ(*84S¦H?
AÑ·Nk[n5o'
!N9ϵÓy4IÀs»Q¥ãzi&"address@hidden'SHÔ¶
Tñ°ëvmI¬ElX~&¶m2JçûÅÆ!êXŸÂH"l
+Ÿ¤XkdH¦Í¹0(( =E¤4"5LsfX*¢eF[pfD*¤#t¾(ÀØR#P©ÚããçR©y¿
Êy2¢À.EÅyn¥0FZ£CÌ!
æCP÷hUuÁfQj-±h-¥»ÁX ÁüÝ Ò ÝH1¬ ®UKIL°RzPe
¡óáèð"ÌÑL)!JA·©¥ä´^ݦ],S¨ÌcµZ#*EF
KpA)hM¥è¾h>÷f»1z,3M*ÒrË,ò9,sK-Ëàz¾_$Ø<mÛÎ4ÒÈâ,²m7eÜ¢
Á,²l/Ímb¡¨ä¡å¤ÛâéÓ8v]ñ®&QÏ ò³$t]'address@hidden,±0]
SdCØL8UYËöÇ¢
],ºqìN%ÛÅ¥èÅ,,Ûî4|÷Õ/ÙcÙâ8¬A) ì?0#¥Xttã)ÐßýÍGél£ýà#»qÚFY°´»{
address@hidden)rÁ\rÉe¬û¨]y±|×åÜűM;ïtñ'¦r뺲K³6=bcñü36nüþíôë+
ÀyÈ%\Ö&·ÿÍêÎÿëÁ9ï½÷¶"ÎÛ0\ryºHX¹äKX¹äK.9`åK.9`åK.¹äK.¹äV.¹äV.¹äKX¹äK.9`åK.9`åK.¹äK.¹äV.¹äV.¹äKX¹äK.9`åK.9`åK.¹äK.¹ä2м
FøÜ^CÙ@(¡ÃÁÄP2 ¨Ú+Ø+\rÀúE¥¡×¾if ÔÜ! Ì$p ¡ÊL
address@hidden@iD0R¦Â ³)<ÖDH¡©
;îOÀp<BHÐé Åsw
b9V¡¤¥´Åhm9MlZ®§{åI¥ë)h2Î
¶Q¶Àæ!æcé¨ÈÔ¬b
¡æªAP4¡fEò×KX?Orx"Zpÿ,úò
åPdxEÛ¶)¥éÁ$bÓ°s0©¹ª´¥µ'% B)¥ À Â5M«Þ ]BlÎßÜ*Óp4BÈÖz!e»_ö
address@hidden £QI¢ò<¯[´gf'address@hidden:H»fs®p ÀRíW¢CÙ¦Ï_GJ
hi)ÕÞùHøø dl*ùH«(¡ @êìÛ¾(Qª¸0 B.1G
address@hidden,0,%J&L:P2¡fCÁÌR.9`YbÓ142x°:address@hidden)¢Á
nc!Dñêí~Ç÷Úö
¯z&>ü5 Ùý¿öÐNMH/}ÍaD
u È4hгÏ9=:b+ ( ¡µPªÙjeiÚh4 h·Z õ®ÝÆ Pz !àDíÕRmRóÏÄÛ
ÂðÍÇèc6T-¨ÙPÌá,°zeo?EÖäS0Ká) S®h
cÝÝöqè|Ùå8J ðÓ@;²êýÞ d
p». 0õÃ{á÷.w{HSç6zás+ÖOêIP(Üõ}ÉvM)ÕF*$J Ũvm³f«s'D mrÁ
le+¹üBÖ!|áIszê쪷á)ë
Ss:°2u«Wúú7ùË^Á >ZP}Quþãñâ>%1&´Ô
nÄÐÖj÷âq-ïCJ-A& gÚ)RÐ6GýÊ&½¹¤Um% ¹+;§;`íáÏîEb¿wéy]ø®wáñq à=?H{>ϼåM
õZnWúÖƾéCãPÈf«ÇQÐ ×õ}oçÎGâ8"=¼Ì²R±4¬£Þ1 IDAT7È VR9>|§Ô²¨
,@E{¡Psþ3гjÎð^ÃØ4·ã»©¨DãdZÿT
address@hidden<¯[´gf'address@hidden:H»fs®p ÀRíW¢CÙ¦Ï_GJ hi)ÕÞùHøø
dl*ùH«(¡ @êìÛ¾(Qª¸0 B.1G
address@hidden,0,%J&L:P2¡fCÁÌR.9`YbÓ142x°:address@hidden)¢Á
nc!Dñêí~Ç÷Úö
¯z&>ü5 Ùý¿öÐNMH/}ÍaD
u È4hгÏ9=:b+ ( ¡µPªÙjeiÚh4 h·Z õ®ÝÆ Pz !àDíÕRmRóÏÄÛ
ÂðÍÇèc6T-¨ÙPÌá,°zeo?EÖäS0Ká) S®h
cÝÝöqè|Ùå8J ðÓ@;²êýÞ d
p». 0õÃ{á÷.w{HSç6zás+ÖOêIP(Üõ}ÉvM)ÕF*$J Ũvm³f«s'D mrÁ
le+¹üBÖ!|áIszê쪷á)ë
Ss:°2u«Wúú7ùË^Á >ZP}Quþãñâ>%1&´Ô
nÄÐÖj÷âq-ïCJ-A& gÚ)RÐ6GýÊ&½¹¤Um% ¹+;§;`íáÏîEb¿wéy]ø®wáñq à=?H{>ϼåM
õZnWúÖƾéCãPÈf«ÇQÐ ×õ}oçÎGâ8"=¼Ì²R±4¬£Þ1 IDAT7È VR9>|§Ô²¨
,@E{¡Psþ3гjÎð^ÃØ4·ã»©¨DãdZÿT
`"GÔ06
-ÐÏØ[H BVÑ! ݯq«µÔÀößPÊ`êQ²OÉûÜäz¡Hkâè~öÛùÍëi%4áïvw?ÂG{§
bÜú=ù?2ª×Tª®Õí
ZK ¥5 D'¿ïVK Bf³I)å·Ûmq8;3Mc|è˨¥(471¥Ck! BZk<1_JiÁ2º#¼ .@)
¸ûQH¹P;-A(address@hiddenzB*¢¡¢´uÅ×UÐ6º
+ÐÏØ[H BVÑ! ݯq«µÔÀößPÊ`êQ²OÉûÜäz¡Hkâè~öÛùÍëi%4áïvw?ÂG{§
bÜú=ù?2ª×Tª®Õí
ZK ¥5 D'¿ïVK Bf³I)å·Ûmq8;3Mc|è˨¥(471¥
Ck! BZk<1_JiÁ2º#¼ .@) ¸ûQH¹P;-A(address@hiddenzB*¢¡¢´uÅ×UÐ6º
â8Æ&