# &app; Manual V&manrevision;

2005
Rob Savoye
GNOME Documentation Project

&legal;

Rob
Savoye

    	    rob@senecass.com

&appname; Manual V&manrevision;
&date;

Rob Savoye rob@senecass.com

Free Software Foundation

This manual describes version &appversion; of &appname;.

## Introduction

Gnash is a Free Flash movie player, which works either standalone, or as a Firefox/Mozilla plugin.

### Gnash Overview

Currently Gnash only has working support for the standalone Flash movie player. Development of the plugin is under heavy development at this time. The only difference between the plugin and the standalone player is that one is rendered in the browser window, instead of a separate window.

Gnash currently has two backends for graphic display. The only one currently used by Gnash is the OpenGL one. There is an XBox backend, but as I don't own an XBox, I can't verify if it even works anymore.

The plugin uses the OpenGL backend still, it's just captured within the window allocated for the plugin's display within the browser window. The plugin code is mostly the same as the standalone except for event handling and the drawing window.

Gnash supports the current Shockwave format, version 7. While all the ActionScript classes exist, not all of the methods defined by the SWF format documentation are implemented however, so not all flash movies work 100% if they utilize any of the unimplemented methods. This is one of the areas to work on to achieve full version 7 compliance.

Included in the Gnash is an XML based messaging system, as specified in the Flash specification. This lets a flash movie communicate over a TCP/IP socket, and parse the incoming XML message. This lets a movie be a remote control for other devices or applications.

## Gnash Usage

Currently only the standalone player is fully operational. You can execute any flash movie from the command line by just supplying the file name. No command line options are required to just play the movie using the default actions. So if you type:

`gnash samples/car_smash.swf`

It'll create a window and play this movie. In this case it's a simple animation of a car driving and swerving and finally crashing.

### Gnash Command Line Options

While by default no options are necessary, there are options that can be used to change `gnash's` basic behavior.

gnash [options] file

-h

  Print usage info.

-s factor

  Scale the movie up/down by the specified factor.

-c

  Produce a core file instead of letting SDL trap it. By default, SDL traps all signals, but sometimes a core file is desired to assist with debugging.

-d num

  Number of milli-seconds to delay in main loop. The main loop polls continuously with a delay to adjust how long `gnash` sleeps between iterations of the loop. The smaller the number, the higher the CPU load gets, and of course, you get more iterations of the main command loop.

-p

  Run full speed (no sleep) and log frame rate.

-a

  Turn anti-aliasing on/off. (obsolete)

-v

  Be verbose; i.e. print debug messages to stdout

-va

  Be verbose about movie Actions.

-vp

  Be verbose about parsing the movie. Warning, this can generate a lot of text, and can affect the performance of the movie you are playing.

-ml bias

  Specify the texture LOD bias (float, default is -1) This effects the fuzziness of small objects, especially small text.

-e

  Use SDL Event thread. This uses a separate thread to make the event loop more event driven than polling. This can improve performance for some types of movies.

-1

  Play once; exit when/if movie reaches the last frame. This is the default.

-r [0|1|2]

  0 disables rendering and sound (good for batch tests)

  1 enables rendering and sound (default setting)

  2 enables rendering and disables sound.

-t sec

  Timeout and exit after the specified number of seconds. This is useful for movies that repeat themselves.

-b bits

  Bit depth of output window (16 or 32, default is 16)

### Gnash Interactive Control Keys

While a movie is playing, there are several control keys. These can be used to step through frames, pause the playing, and other actions.

CTRL-Q

  Quit/Exit

CTRL-W

  Quit/Exit

ESC

  Quit/Exit

CTRL-P

  Toggle Pause

CTRL-R

  Restart the movie

CTRL-[ or kp-

  Step back one frame

CTRL-] or kp+

  Step forward one frame

CTRL-A

  Toggle anti-aliasing (doesn't work)

CTRL-T

  Debug. Test the set_variable() function

CTRL-G

  Debug. Test the get_variable() function

CTRL-M

  Debug. Test the call_method() function

CTRL-B

  Toggle background color

## Code Overview

The top level of Gnash has three libraries, `libbase`, `libgeometry`, and `libserver`. There are two utility programs included for debug parsing and processing of Flash movie files to test the Actionscript interpreter. There is also a standalone flash movie player.

### The Libraries

#### libbase

Libbase contains support classes used by the rest of the code. Among these classes is a small and efficient STL library clone that uses smart pointers. This helps isolate the problems that arise when using non GNU C Compilers that aren't compliant with the ANSI C++ standard.

Gnash makes heavy use of smart pointers, so memory allocations are freed up automatically by the interpreter.

#### libgeometry

Libgeometry contains code for device independant graphics routines.

#### libserver

Libserver is the guts of the interpreter itself. This is where all the new ActionScript classes get defined, and the main code for the interpreter lives.

### The Applications

There are currently a few standalone programs in Gnash to assist with Gnash development, and to play a flash movie.

#### Gnash

This is the standalone OpenGL backend used to play movies. There are several command line options and keyboard control keys used by Gnash that are documented here.

#### Gparser

Gparser use the Gnash parser to dissamble the flash movie, and dumps the object types, the depth, and other information to make sure Gnash is parsing the file correctly.

#### Gprocesser

Gprocesser 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.

### The Plugin

The plugin is designed to work within Mozilla or Firefox. It currently doesn't use the latest plugin API additions, so it should work in older versions as well. The plugin uses the Mozilla plugin API to be cross platform, and portable.

One future thought for the plugin is to use the new Firefox 1.5 or greater version of Firefox. This version has added a drawable canvas window that support hardware acceleration, and is desgined to support things like rendering diretly into the canvas without needing OpenGL.

## Authors

Gnash is maintained by Rob Savoye rob@senecass.com. Please send all comments, suggestions, and bug reports to gnash@gnu.org, or use the Bug Tracking system on The Free Software Foundation's Savannah host. http://savannah.gnu.org/projects/gnash I am available for consulting on a variety of renewable energy and open source technologies. More details at http://www.senecass.com

The following people all contributed code to GameSWF, which was the original code base for Gnash. I was also a GameSWF contributor. The primary author of GameSWF is Thatcher Ulrich tu@tulrich.com. Other individuals that contributed code are: Mike Shaver, Thierry Berger-Perrin, Ignacio Castaño, Willem Kokke, Vitaly Alexeev, Alexander Streit.

&fdl-app;