[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnash-commit] gnash/doc/C opcodes.xml plugin.xml object.xml m...
|
From: |
Rob Savoye |
|
Subject: |
[Gnash-commit] gnash/doc/C opcodes.xml plugin.xml object.xml m... |
|
Date: |
Sat, 01 Mar 2008 18:46:48 +0000 |
CVSROOT: /sources/gnash
Module name: gnash
Changes by: Rob Savoye <rsavoye> 08/03/01 18:46:47
Removed files:
doc/C : opcodes.xml plugin.xml object.xml mysqlext.xml
logging.xml extensions.xml
Log message:
Moved to refmanual.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/opcodes.xml?cvsroot=gnash&r1=1.3&r2=0
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/plugin.xml?cvsroot=gnash&r1=1.10&r2=0
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/object.xml?cvsroot=gnash&r1=1.1&r2=0
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/mysqlext.xml?cvsroot=gnash&r1=1.2&r2=0
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/logging.xml?cvsroot=gnash&r1=1.6&r2=0
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/extensions.xml?cvsroot=gnash&r1=1.5&r2=0
Patches:
Index: opcodes.xml
===================================================================
RCS file: opcodes.xml
diff -N opcodes.xml
--- opcodes.xml 17 Sep 2006 19:45:59 -0000 1.3
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,127 +0,0 @@
- <sect2 id="op codes">
- <title>Flash Opcodes</title>
-
- <para>
- There are many opcodes in Flash, and Gnash implements the
- majority of them up to version 7 of the Flash format. Gnash will
- print an "unimplemented" message whenever it sees an opcode that
- isn't implemented. If you try to play a movie and it doesn't
- appear to be executing properly, run <emphasis>gnash</emphasis> or
- <emphasis>gprocessor</emphasis> with the <emphasis>-v</emphasis> option
to see
- the debug messages. You can also use the <emphasis>-w</emphasis> option
- to <emphasis>gnash</emphasis> to write the debug messages to disk.
- </para>
-
- <sect3 id="missops">
- <title>Unimplemented Opcodes</title>
-
- <para>
- As of March, 2006, these are the few opcodes that haven't been
- implemented for full SWF version 7 compliance. SWF version 8
- adds a few more that currently aren't listed here.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>0x2A Throw</term>
- <listitem>
- <para>
- Throw an error that can be caught by a <emphasis>catch</emphasis>
statement.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x2C Implements</term>
- <listitem>
- <para>
- Specifies that a subclass must define all the derived methods.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x69 Extends</term>
- <listitem>
- <para>
- Define a subclass of a class.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x55 enum_object</term>
- <listitem>
- <para>
- Push the name of each member of an enum on the stack.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x8F Try</term>
- <listitem>
- <para>
- Protect a block of code during which an error may occur.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x53 new_method</term>
- <listitem>
- <para>
- Get the name of a method.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x31 md length</term>
- <listitem>
- <para>
- Get the length of a multi-byte string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x35 md substring</term>
- <listitem>
- <para>
- Get a substring from a multi-byte string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x37 md chr</term>
- <listitem>
- <para>
- Get a single character from a multi-byte string.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x3A delete</term>
- <listitem>
- <para>
- Delete an object.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>0x45 get target</term>
- <listitem>
- <para>
- Return the path to a sprite.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- </sect2>
-
-
Index: plugin.xml
===================================================================
RCS file: plugin.xml
diff -N plugin.xml
--- plugin.xml 12 Apr 2007 08:55:53 -0000 1.10
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,353 +0,0 @@
-<sect4 id="mozplugin">
- <title>Mozilla/Firefox Plugin</title>
-
- <para>
- The Mozilla SDK has two API layers for plugins. The older layer is
- documented in the <ulink type="http"
- url="http://www.gnu.org/software/gnash/manual/plugin.pdf";>
- Geeko Plugin API Reference</ulink>, 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <sect5 id="plugincapi">
- <title>Plugin C API</title>
-
- <para>
- 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 <emphasis>plugin/mozilla-sdk</emphasis>. 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>NS_PluginInitialize</term>
- <listitem>
- <para>
- 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.
- </para>
-
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NS_NewPluginInstance</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NS_DestroyPluginInstance</term>
- <listitem>
- <para>
- This destroys our instantiated object when the browser is
- done.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NS_PluginShutdown</term>
- <listitem>
- <para>
- This is called when a plugin is shut down, so this is
- where all the one time only shutdown stuff goes.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NPP_GetMIMEDescription</term>
- <listitem>
- <para>
- This is called to get the MIME types the plugin supports.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NS_PluginGetValue</term>
- <listitem>
- <para>
- This is used by Firefox to query information from the
- plugin, like the supported MIME type, the version number,
- and a description.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect5>
-
- <sect5 id="plugincppapi">
- <title>Plugin C++ API</title>
-
- <para>
- The higher level layer is the one we are most concerned
- with. This is an instantiation of the
- <emphasis>nsPluginInstanceBase</emphasis> 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.
- </para>
-
- <para>
- 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, <emphasis>nsPluginInstance::init()</emphasis> and
- <emphasis>nsPluginInstance::SetWindow()</emphasis> are called more than
- once, so the plugin must protect against actions that could be
- destructive.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>nsPluginInstance::nsPluginInstance</term>
- <listitem>
- <para>
- Create a new plugin object.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::init</term>
- <listitem>
- <para>
- This methods initializes the plugin object, and is
- called for every movie which gets played. This is where
- the thread-specific information goes.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::SetWindow</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::NewStream</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::Write</term>
- <listitem>
- <para>
- Read the data stream from Mozilla/Firefox. For now we
- read the bytes and write them to a disk file.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::WriteReady</term>
- <listitem>
- <para>
- Return how many bytes we can read into the buffer.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::DestroyStream</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::shut</term>
- <listitem>
- <para>
- This is where the movie playing specific shutdown emphasis goes.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::~nsPluginInstance</term>
- <listitem>
- <para>
- This destroys our plugin object.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NS_PluginInitialize::initGL</term>
- <listitem>
- <para>
- This is a Gnash internal function that sets up OpenGL.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>NS_PluginInitialize::destroyContext</term>
- <listitem>
- <para>
- This is a Gnash internal function that destroys a GLX
- context.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::getVersion</term>
- <listitem>
- <para>
- This returns the version of Mozilla this plugin supports.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::GetValue</term>
- <listitem>
- <para>
- This returns information to the browser about the plugin's
- name and description.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>nsPluginInstance::URLNotify</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect5>
-
- <sect5 id="glthread">
- <title>OpenGL and Threads</title>
- <para>
- 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.
- </para>
-
- <para>
- 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 <emphasis>XLockDisplay()</emphasis> and
- <emphasis>XUnlockDisplay()</emphasis>. A connection to the X11
- server is opened for every instantiation of the plugin using
- <emphasis>XOpenDisplay()</emphasis>.
- </para>
-
- <para>
- The <emphasis>GLX Context</emphasis> 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 <emphasis>glXCreateContext()</emphasis>,
- and then later destroyed by using
<emphasis>glXDestroyContext()</emphasis>.
- When swapping threads, the context is changed using
- <emphasis>glXMakeCurrent()</emphasis>.
- </para>
-
- <para>
- All the emphasis that directly accesses a GLX context or the X11
- display must be wrapped with a mutex.
- </para>
-
- </sect5>
-
- <sect5 id="eventhandle">
- <title>Plugin Event Handling</title>
- <para>
- 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.
- </para>
-
- <para>
- It is also possible to disable the <emphasis>GTK</emphasis> support so
- only the older <emphasis>SDL</emphasis> 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
- <emphasis>--disable-glext</emphasis>
- </para>
-
- <para>
-
- </para>
-
- </sect5>
-</sect4>
Index: object.xml
===================================================================
RCS file: object.xml
diff -N object.xml
--- object.xml 31 Jan 2006 02:52:59 -0000 1.1
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,318 +0,0 @@
-<sect4 id="asobject">
- <title>Object ActionScript Class</title>
-
- <para>
- This class implements an Object object.
- </para>
-
- <sect5 id="objectmethods">
- <title>The Methods of the Class</title>
- <para>
- <variablelist>
-
- <varlistentry>
- <term>addProperty()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>registerClass()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>toString()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>unwatch()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>valueOf()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>watch()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Sharedclear()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Sharedflush()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SharedgetLocal()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SharedgetSize()</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </sect5>
- <sect5 id="objectprops">
- <title>The Properties of the Object Class</title>
-
- <para>
- <variablelist>
-
- <varlistentry>
- <term>constructor</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>__proto__</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>__resolve</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>Shareddata</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>SharedonStatus</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </sect5>
-
- <sect5 id="objectconf">
- <title>Object Class Conformance</title>
-
- <para>
- <informaltable frame="all">
- <?dbhtml table-width="75%" ?>
- <tgroup cols="2">
- <thead>
- <row>
- <entry valign="top">
- <para>Class Name</para>
- </entry>
- <entry valign="top">
- <para>Conformance</para>
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry valign="top" align="left">
- <para>addProperty()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>registerClass()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>toString()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>unwatch()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>valueOf()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>watch()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>Sharedclear()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>Sharedflush()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>SharedgetLocal()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>SharedgetSize()</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This method has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>constructor</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This property has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>__proto__</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This property has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>__resolve</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This property has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>Shareddata</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This property has an unknown status.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top" align="left">
- <para>SharedonStatus</para>
- </entry>
- <entry valign="top" align="center">
- <para>
- This property has an unknown status.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
- </sect5>
-</sect4>
Index: mysqlext.xml
===================================================================
RCS file: mysqlext.xml
diff -N mysqlext.xml
--- mysqlext.xml 22 Feb 2007 19:23:59 -0000 1.2
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,88 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<sect3 id="mysqlext">
- <title>MySQL Extension</title>
-
- <para>
- 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.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>connect</term>
- <listitem>
- <para>
- Connect to a MySQL database.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>qetData</term>
- <listitem>
- <para>
- Get data from the database.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>disconnect</term>
- <listitem>
- <para>
- Disconnect from a MySQL database.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>query</term>
- <listitem>
- <para>
- Execute an SQL query to the database.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>fetch_row</term>
- <listitem>
- <para>
- Fetch a row from the query results.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>num_fields</term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>free_result</term>
- <listitem>
- <para>
- Free the results of a query.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>store_results</term>
- <listitem>
- <para>
- Store the results of a query.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
-</sect3>
Index: logging.xml
===================================================================
RCS file: logging.xml
diff -N logging.xml
--- logging.xml 4 Dec 2006 18:38:53 -0000 1.6
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,207 +0,0 @@
-<sect2 id="logging">
- <title>The Debug Logging System</title>
-
- <para>
- Gnash supports a debug logging system which supports both C and C++
- natively. This means you can use both <emphasis>printf()</emphasis> style
- debug messages and C++ <emphasis>iostreams</emphasis> style, where you can
- print C++ objects directly as you would when using
- <emphasis>cout</emphasis>.
- </para>
-
- <para>
- 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 <emphasis>log_msg()</emphasis> and <emphasis>log_error()</emphasis>
functions,
- and used a callback to set them up.
- </para>
-
- <para>
- It became apparent one day the callback was never needed, and I
- got tired of having to use <emphasis>c_str()</emphasis> on string data
- just to print them out.
- </para>
-
- <para>
- If a filename is not specified at object construction time, a
- default name of <emphasis>gnash-dbg.log</emphasis> 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
- <emphasis>GNOME</emphasis> or <emphasis>KDE</emphasis> the debug file goes
in your
- home directory, since that's considered the current directory.
- </para>
-
- <para>
- 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 <emphasis>-v</emphasis> options on the
- command line. You can also disable the creation of the debug log.
- </para>
-
- <sect3 id="capi">
- <title>Logging System C API</title>
-
- <para>
- 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.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>void log_msg(const char* fmt, ...)</term>
- <listitem>
- <para>
- Display a message if verbose output is enabled. By default
- the messages are always written to the disk file, but
- optionally displayed in the terminal.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>log_error(const char* fmt, ...)</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>log_warning(const char* fmt, ...)</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
-
- <sect3 id="cppapi">
- <title>Logging System C++ API</title>
-
- <para>
- This is the new C++ streams based API that can be used to print
- C++ objects natively. All output lines are timestamped.
- </para>
-
- <para>
- 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
- <emphasis>GNASH_REPORT_RETURN</emphasis> at the end of a function to
- display the function returning message.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>GNASH_REPORT_FUNCTION;</term>
- <listitem>
- <para>
- 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.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>GNASH_REPORT_RETURN;</term>
- <listitem>
- <para>
- This is used by C functions to print the returning from
- function debug message. For C++, this macro is executed
- automatically by the destructor.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- This is the main API for the logging system. By default
- everything is setup to write to the default
- <emphasis>gnash-dbg.log</emphasis> file whenever a verbose option is
- supplied. Optionally it is possible to open a log file with a
- specified name, allowing multiple output files.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>openLog(const char *filespec)</term>
- <listitem>
- <para>
- Open the debug file with the name specified by
- <emphasis>filespec</emphasis>. This file goes in the current
- directory, or your home directory if using a menu based
- launcher.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>closeLog(void)</term>
- <listitem>
- <para>
- Close a debug log. The disk file remains.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>removeLog(void)</term>
- <listitem>
- <para>
- Delete the debug log file from disk.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>setVerbosity(void)</term>
- <listitem>
- <para>
- Increment the verbosity level.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>setVerbosity(int)</term>
- <listitem>
- <para>
- Set the verbosity level.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>setStamp(bool flag)</term>
- <listitem>
- <para>
- If <emphasis>flag</emphasis> is <emphasis>true</emphasis>, then
print a
- timestamp prefixed to every output line. If
- <emphasis>flag</emphasis> is <emphasis>false</emphasis>, then don't
print
- a timestamp.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>setWriteDisk(bool flag)</term>
- <listitem>
- <para>
- If <emphasis>flag</emphasis> is <emphasis>true</emphasis>, then
create the
- disk file. If <emphasis>flag</emphasis> is
<emphasis>false</emphasis>,
- then don't create the disk file.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </sect3>
-
-</sect2>
Index: extensions.xml
===================================================================
RCS file: extensions.xml
diff -N extensions.xml
--- extensions.xml 18 Dec 2007 22:05:14 -0000 1.5
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,319 +0,0 @@
-<sect1 id="extensions">
- <title>Gnash Extensions</title>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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..
- </para>
-
- <para>
- </para>
-
- <sect2 id="newext">
- <title>Creating A New Extension</title>
-
- <para>
- Each new extension should live in it's own directory. The
- extensions included in Gnash are all in the
- <code>gnash/extensions</code> directory. Creating an extension
- requires a Makefile.am,
- </para>
-
- <para>
- If you are adding this extension to the Gnash source tree
- itself, then you need to make two changes to add the new
- extension.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- The other change is to add it to the AC_OUTPUT list in
- <emphasis>configure.ac</emphasis> so the new directory will be
- configured along with the rest of Gnash.
- </para>
-
- <para>
- 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 <emphasis>check_PROGRAMS</emphasis>
- variable so that "make check" works.
- </para>
-
- <para>
- 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.
- </para>
-
- <sect3 id="craftext">
- <title>Crafting an Extension</title>
-
- <para>
- 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.
- </para>
-
- <para>
- The first function is commonly called
- <emphasis>attachInterface</emphasis>, 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 <emphasis>init_member()</emphasis> to set a C
- function pointer to the string value used in the Flash movie.
- </para>
-
- <programlisting>
- // Attach DummyClass 'func1' and 'func2' methods to the given object
- static void
- attachInterface(as_object& obj)
- {
- obj.init_member("func1", &ext_func1);
- obj.init_member("func2", &ext_func2);
- }
- </programlisting>
-
- <para>
- The second function is commonly called
- <emphasis>getInterface()</emphasis>, 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.
- </para>
- <programlisting>
- static as_object*
- getInterface()
- {
- static boost::intrusive_ptr<as_object> o;
- if (o == NULL) {
- o = new as_object();
- VM::get().addStatic(o);
- attachInterface(*o);
- }
- return o.get();
- }
- </programlisting>
-
- <para>
- 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 <emphasis>DummyExt</emphasis>,
- and has two methods, <emphasis>func1</emphasis> and
- <emphasis>func2</emphasis>.
- </para>
- <programlisting>
- static as_value
- dummyext_ctor(const fn_call& fn)
- {
- DummyExt *obj = new DummyExt(); // will setup prototypes
-
- return as_value(obj);
- }
- </programlisting>
-
- <para>
- 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.
- </para>
- <programlisting>
- class DummyExt : public as_object
- {
- public:
- DummyExt()
- :
- as_object(getInterface()) // returns the static prototype
- {}
-
- };
- </programlisting>
-
- <para>
- 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
- <emphasis>dummyext</emphasis>, which also matches the file
- name of the extension. Gnash uses the name of the extension
- file itself when looking for the init function.
- </para>
- <programlisting>
- extern "C" {
- void
- dummyext_class_init(as_object &obj)
- {
- static builtin_function* cl=NULL;
- if (!cl)
- {
- // Create a builtin function using the given constructor
- // to instanciate objects and exporting the given interface
- cl = new builtin_function(&dummyext_ctor,
getInterface());
- VM::get().addStatic(cl); // will forbid to collect the class
- }
-
- obj.init_member("DummyExt", cl);
- }
- } // end of extern C
- </programlisting>
-
- <para>
- The callbacks are all C functions. Like all the other code
- that implements ActionScript, parameters to the function are
- passed in using the <emphasis>fn_call</emphasis> data
- structure. The return code, if any, is also returned using
- this data structure. <emphasis>this_ptr</emphasis> is the
- object that the method is a member of.
- </para>
- <programlisting>
- // Creates a new button with the label as the text.
- as_value func1(const fn_call& fn)
- {
- // Following line will ensure 'func1' is called for a DummyExt
instance,
- // or would throw an exception which should behave as if we
returned the
- // undefined value.
- boost::intrusive_ptr<DummyExt> ptr =
ensureType<DummyExt>(fn.this_ptr);
-
- if (fn.nargs > 0) {
- std::string label = fn.arg(0).to_string();
- bool ret = ptr->dummy_text_label(label);
- return as_value(ret);
- }
- }
- </programlisting>
-
- </sect3>
-
- </sect2>
-
- <sect2 id="debuext">
- <title>Debugging An Extension</title>
-
- <para>
- 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
- <emphasis>after</emphasis> the extension has been loaded into
- Gnash's VM. The easy solution is to use the Gnash debugger.
- </para>
-
- <para>
- 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 <emphasis>c</emphasis>
- (for continue) command to the Gnash console.
- </para>
- <programlisting>
- // Get the debugger instance
- static Debugger& debugger = Debugger::getDefaultInstance();
-
- // Enable the debugger
- debugger.enabled(true);
- // Stop and drop into a console
- debugger.console();
- </programlisting>
-
- <para>
- 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
- <emphasis>^C</emphasis> to drop into the GDB command console.
- </para>
- <programlisting>
- bool stall = true;
- while (stall) {
- sleep 1;
- }
- </programlisting>
-
- <para>
- Once you have set the breakpoints you want, reset the value of
- the <emphasis>stall</emphasis> variable to break out of the
- loop, and the Flash movie will then continue playing.
- </para>
- <programlisting>
- (gdb) set variable stall = false;
- continue
- </programlisting>
-
- </sect2>
-
- <sect2 id="inclext">
- <title>Included Extensions</title>
-
- <para>
- 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.
- </para>
-
- >k;
- &file;
- &mysql;
-
- </sect2>
-
-</sect1>
-
-
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gnash-commit] gnash/doc/C opcodes.xml plugin.xml object.xml m...,
Rob Savoye <=