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 on a wide variety of devices from embedded ones to modern desktops. Gnash has a better focus on security, allowing the user tight control of all network or disk based I/O. Gnash also supports extending ActionScript by creating your own classes. You can write wrappers for any development library, and import them into the player much like Perl or Python does. * 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 known to run on are Ubuntu, Fedora, Debian, Mandriva, OpenBSD, NetBSD, FreeBSD, Win32, and Darwin (OSX) primarily. Occasionally other platforms are built, primarily by those distribution maintainers. This includes BeOS, Haiku, Syllable, OS/2, Solaris, Slackware, and Gentoo. Gnash is capable of reading up to SWF v9 files and opcodes, but primarily supports SWF v7, with better SWF v8 and v9 support under heavy development. 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 v2.0, and has begun implementing ActionScript v3.0. Gnash supports the majority of Flash opcodes up to SWF v9, and a wide sampling of ActionScript classes for SWF v8. As ActionScript 3 is a more developed version of ActionScript 2, many of the same classes work for both. Support has been added to Gnash's ActionScript library to support the new ActionScript 3 filters, which get applied to every class. Implementing ActionScript 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 ever changing field of reverse engineering. Many of the popular video sharing sites use SWF v8 or v9, which Gnash still has imperfect support for. This is improving all the time, so often builds from a development snapshot will work when using the older release packaged in your distribution doesn't. You can find daily snapshots of the latest CVS tree at: 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:anonymous@cvs.sv.gnu.org:/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 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_, _libgnashserver_, _libgnashasobjs_ and _libgnashbackend_. There are several utility programs included for debug parsing and processing of Flash movie files, and other useful utilities for examining local Shared Objects and sniffing LocalConnections. * 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:: * libgnashgui:: * libgnashserver:: * libgnashasobjs:: * libgnashamf:: * libgnashbackend:: * libgnashplugin:: * libklashpart::  File: gnash_ref.info, Node: libgnashbase, Next: libgnashgui, 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: libgnashgui, Next: libgnashserver, Prev: libgnashbase, Up: The Libraries 3.1.1.2 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.3 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.4 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.5 libgnashamf ................... AMF is the data format used internally by SWF files. This is Gnash's support library to handle AMF data. This is used by the ActionScript classes SharedObject and LocalConnection. This is also used by the NetStream class when using thre RTMP streaming network protocol.  File: gnash_ref.info, Node: libgnashbackend, Next: libgnashplugin, Prev: libgnashamf, Up: The Libraries 3.1.1.6 libgnashbackend ....................... Libgnashbackend is a library containing the rendering code that glues this display to the Gnash. Supported rendering backends are OpenGL, Cairo, and AGG.  File: gnash_ref.info, Node: libgnashplugin, Next: libklashpart, Prev: libgnashbackend, Up: The Libraries 3.1.1.7 libgnashplugin ...................... Libgnashplugin is the Mozilla/Firefox plugin.  File: gnash_ref.info, Node: libklashpart, Prev: libgnashplugin, Up: The Libraries 3.1.1.8 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 either to assist with Gnash development or to 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 backend 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 NPAPI 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 ptr = ensureType(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 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.  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: Fetching the Value, Next: Setting the Value and Type, Prev: Determining the Type, Up: The as_value Object Type 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: * The Methods of the Class:: * The Properties of the Object Class:: * Object Class Conformance::  File: gnash_ref.info, Node: The Methods of the Class, Next: The Properties of the Object Class, Up: Object ActionScript Class 3.4.7.1 The Methods of the Class ................................ addProperty() registerClass() toString() unwatch() valueOf() watch() Sharedclear() Sharedflush() SharedgetLocal() SharedgetSize()  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 3.4.7.2 The Properties of the Object Class .......................................... constructor __proto__ __resolve Shareddata SharedonStatus  File: gnash