A C Library for Writing Flash Movies

Paul Haeberli
Silicon Graphics
paul@sgi.com
Version 0.99
10 Feb 1999

This document describes the C interface to libswf.a, and gives some clues on how to use the library. To use this library, you must include the file swf.h. In addition you should be aware of this additional information. If you have comments or questions, please send 'em my way.

This work is based on the documents that Macromedia made available in April of 1998.

File Management

void swf_openfile(char *name, float xsize, float ysize , float framerate, float r, float g, float b)

This is the first function you should call to open a .swf file. If you want to write the output to a file, the filename should end in ".swf". If you want to write to stdout, give the special file name of "STDOUT". The xsize and ysize are the dimensions of the Flash movie in pixels. framerate specifies the frame rate in frames per second. The last three arguments r, g, and b select a color to be used for the backgound of the Flash movie.

void swf_closefile(void)

Closes the .swf file.

Managing the Contents of the Current Frame

void swf_labelframe(char *name)

This adds a string label to the current frame. This is only needed if you want to use swf_actionGoToLabel to get to this frame in future. If you want to put a secret message into your flash files, this is where to do it!

void swf_showframe(void)

Finish the current frame and start adding commands to the next frame.

void swf_setframe(int fromeno)

Selects the specified frame number for adding commands to.

int swf_getframe(void)

Returns the frame number of the current frame. The first frame is frame 0.

Setting the Current Color

void swf_mulcolor(float r, float g, float b, float a)

Sets the global multiply color to the rgba value specified. This color is used implicitly by swf_placeobject, swf_modifyobject and swf_addbuttonrecord. The color of the object will be multiplied by the values given when it is drawn. These values can be positive or negative.

void swf_addcolor(float r, float g, float b, float a)

Sets the global add color to the rgba value specified. This color is used implicitly by swf_placeobject, swf_modifyobject and swf_addbuttonrecord. This color is added to the original color of the object when it is drawn. These values can be positive or negative.

Placing and Removing Objects

void swf_placeobject(int objid, int depth)

Places the object identified by objid in the current frame at the given depth. objids must be between in the range [1..65535], while depths must be between in the range [1..65535]. This uses the current mulcolor and addcolor and matrix to position and color the object. Full RGBA colors are supported.

void swf_modifyobject(int depth, int how)

Updates the position and or color of the object at the specified depth. how determines what things are modified using the values MOD_MATRIX, MOD_COLOR or MOD_COLOR|MOD_MATRIX. This uses the current mulcolor and addcolor and matrix to position and color the object. Full RGBA colors are supported.

void swf_removeobject(int depth)

Removes the object at the specified depth.

int swf_nextid(void)

Returns a free objid. this makes it easier to manage the object ids used.

Defining an Action List for the Current Frame

An action list is described by a sequence of calls as shown here:

swf_startdoaction();
    swf_actionGotoFrame(143);
    swf_actionPlay();
swf_enddoaction();


You can put lots and lots of actions between swf_startdoaction and swf_enddoaction to create an actionlist. All the actions are performed in sequence after the current frame is drawn.

void swf_startdoaction(void)

This starts the description of an action list for the current frame. There should be only one action list associated with a single frame in the Flash movie.

void swf_enddoaction(void)

Ends the list of actions to perform for the current frame.

The Action Elements

void swf_actionGotoFrame(int frameno)

Causes the Flash movie to display the specified frame and stop.

void swf_actionGetURL(char *url, char *target)

Gets the specified URL. target indicates what to do with the content from the URL. If target is "_level0", data from the URL will replace the current Flash movie. If target is "_level1", The new URL will displayed on top of the current Flash movie.

void swf_actionNextFrame(void)

Goes forward one frame.

void swf_actionPrevFrame(void)

Goes backward one frame.

void swf_actionPlay(void)

Starts playing the Flash movie from the current frame.

void swf_actionStop(void)

Stops playing the Flash movie at the current frame.

void swf_actionToggleQuality(void)

Toggles between high and low quality.

void swf_actionStopSounds(void)

Stops playing sound.

void swf_actionWaitForFrame(int frame, int skipcount)

If the specified frame has not been loaded, skip the specified number of actions in the action list. This can be used to show an animation while frames are being loaded.

void swf_actionSetTarget(char *target)

Set the context for actions. This can be used to control other Flash movies that are playing.

void swf_actionGoToLabel(char *label)

Causes the Flash movie to display the frame with the given label, and stop.

Defining Shapes

Defining Simple Shapes

void swf_defineline(int objid, float x1, float y1, float x2, float y2, float width)

Defines a line segment from x1,y1 to x2,y2 with the given line width.

void swf_definerect(int objid, float x1, float y1, float x2, float y2, float width)

Defines an outlined rectangle from x1,y1 to x2,y2 with the given line width. If width is 0.0, the rectangle is filled instead of stroked.

void swf_definepoly(int objid, float coords[][2], int npoints, float width)

Defines a polygon with npoints with the specified line width. If width is 0.0, the polygonal shape is filled instead of stroked.

Defining Complex Shapes

void swf_startshape(int objid)

Starts the definition of a complex shape. An object with the specified objid will be created.

void swf_shapelinesolid(float r, float g, float b, float a, float width);

Sets the current line style. The color is given by r, g, b, and a. width specifies the thickness of the line. If a width of 0.0 is given, no lines are drawn.

void swf_shapefilloff(void)

Turns off filling.

void swf_shapefillsolid(float r, float g, float b, float a)

Sets the current fill style to a solid fill with the the specified color.

void swf_shapefillbitmapclip(int bitmapid)

Sets the current fill mode clipped bitmap fill. Pixels from the previously defined bitmapid will be used to fill areas.

void swf_shapefillbitmaptile(int bitmapid)

Sets the current fill mode tiled bitmap fill. Pixels from the previously defined bitmapid will be used to fill areas. The image will repeat across the area.

void swf_shapemoveto(float x, float y)

This moves the current position to the given x,y.

void swf_shapelineto(float x, float y)

Draws a line from the current position to x,y. Then the current position is set to x,y.

void swf_shapecurveto(float x1, float y1, float x2, float y2)

Draws a quadradic bezier curve starting at the current position using x1,y1 as an off curve control point and using x2,y2 as the end point. Then the current position is set to x2,y2.

void swf_shapecurveto3(float x1, float y1, float x2, float y2, float x3, float y3)

Draws a cubic bezier curve starting at the current position using x1,y1 and x2,y2 as off curve control points and using x3,y3 as the end point. Then the current position is set to x3,y3. The cubic bezier curve is converted to the quadradic beziers used internally by Flash.

void swf_shapearc(float x, float y, float r, float ang1, float ang2)

Draws a circular arc from ang1 to ang2. The center of the circle is given by x, and y. r specifies the radius of the arc.

void swf_endshape(void)

Completes the definition of the current shape.

Defining Fonts and Text

void swf_definefont(int fontid, char *name)

Defines a font. name specifies the PostScript name of the font to use. This font also becomes the current font.

void swf_setfont(int fontid)

Sets the current font to the font indicated by fontid.

void swf_fontsize(float height)

Sets the current font size to the height indicated.

void swf_fontslant(float slant)

Sets the current font slant to the slant angle indicated. Positive values slant forward, negative values slant backwards.

void swf_fonttracking(float track)

Sets the current font tracking to the specified value. The is used to adjust the spacing between letters in text. Positive values increase the amount of space, while negative numbers decrease the amount of space. A tracking value of 1.0 will add the currenet font height's worth of space between letters.

void swf_getfontinfo(float *Aheight, float *xheight)

Returns the height of the capital A and lower case x using the current font and fontsize.

void swf_definetext(int objid, char *str, int docenter)

Defines a text string using the current font, current fontsize and current font slant. If docenter is 1, the word is centered in x.

float swf_textwidth(char *s)

Returns the width of the string using the current font and current fontsize and current font slant.

Defining Bitmaps

void swf_definebitmap(int objid, char *imgname)

Defines a bitmap given the name of a .gif .rgb .jpeg or .fi image. The image will be converted into Flash jpeg or Flash color map format.

int swf_getbitmapinfo(int bitmapid, int *xsize, int *ysize)

Returns the size of a previously defined bitmap. xsize and ysize are the width and height in pixels.

Defining Symbols

void swf_startsymbol(int objid)

Symbols are tiny Flash movies that can be played simultaneously. To define a symbol, call this function with the objid that you want to use to identify the symbol.

void swf_endsymbol(void)

Completes the symbol.

Defining Buttons

Buttons provide the interaction in Flash movies. The functions below are used to define the appearance and behavior of a button. In typical application, a complete button will look something like this:

swf_startbutton(objid,TYPE_MENUBUTTON);
    swf_addbuttonrecord(BSHitTest|BSDown|BSOver|BSUp,RECTFILLID,3000,&mat);
    swf_oncondition(MenuEnter);
        swf_actionGetURL("overlay.swf","_level1");
    swf_oncondition(MenuExit);
        swf_actionGetURL("","_level1");
swf_endbutton();


A button definition always starts with swf_startbutton and ends with swf_endbutton. There should be one or more swf_addbuttonrecord calls, and zero or more calls to swf_oncondition followed by action elements. To make a button appear on the screen, you will have to use placeobject to position it in a frame.

void swf_startbutton(int objid, int type)

Starts the definition of a button with the specified object id. type can have the value TYPE_MENUBUTTON or TYPE_PUSHBUTTON. this will select whether focus can move from the button while the mouse is down. If type is TYPE_MENUBUTTON, focus travels, while if type is TYPE_PUSHBUTTON, focus stays with the button.

void swf_addbuttonrecord(int state, int objid, int depth)

Controls the location, appearance and active area of the current button. There must be one or more calls to this function to indicate what object to associate with BSHitTest (the button hit test area) and BSUp, BSOver and BSDown (the three button state bits). This uses the current mulcolor, addcolor and matrix to position and color the specified object. There can be any number of button records in a single button.

void swf_oncondition(int transitions)

Describes a transition used to trigger an action list.

These transitions apply to buttons of type TYPE_MENUBUTTON:

IdletoOverUp
OverUptoIdle
OverUptoOverDown
OverDowntoOverUp

IdletoOverDown
OutDowntoIdle

MenuEnter = (IdletoOverUp|IdletoOverDown)
MenuExit = (OverUptoIdle|OverDowntoIdle)


These transitions apply to buttons of type TYPE_PUSHBUTTON:

IdletoOverUp
OverUptoIdle
OverUptoOverDown
OverDowntoOverUp

OverDowntoOutDown
OutDowntoOverDown
OutDowntoIdle

ButtonEnter = (IdletoOverUp|OutDowntoOverDown)
ButtonExit = (OverUptoIdle|OverDowntoOutDown)


The call to swf_oncondition should be followed by one or more action elements as described above.

void swf_endbutton(void)

Completes the definition of a button.

Defining Sounds

void swf_soundrate(int rate);

Sets the sample rate for future sound definitions to the specified value. The only rates supported are 5500, 11000, 22000 and 44000 sampels pre second.

void swf_soundcomp(int nbits);

Selects the number of bits that sound samples should be compressed to when sounds are defined. The only values supported are 0, 2, 3, 4 and 5. The value of 0 is used to create sounds with no compression. NB: It looks like the Flash plugin on some PC's have trouble playing uncompressed sound.

void swf_definesound(int objid, short *samples, int nsamples);

Defines a sound. samples points to an array of signed shorts that contain a waveform. nsamples indicates how many samples are in the sound.

void swf_definebuttonsound(int objid, int outid, int overid, int downid);

Associates sounds with an already defined button. outid, overid and downid can be previously defined sounds, or 0 if no sound should be playd for the particular transition.

int swf_soundstream(short *samples, int nsamples);

Adds the samples to the movie starting at the current frame. The number of frames that the sound plays for is returned.

void swf_startsound(int soundid);

Starts playing the sound defined by soundid.

Geometry Functions

void swf_viewport(double xmin, double xmax, double ymin, double ymax)

Selects an area on the drawing surface for future drawing. This defaults to the screen area of the Flash movie.

void swf_ortho2(double xmin, double xmax, double ymin, double ymax)

Defines a 2D orthographic mapping of user coordinates onto the current viewport. This defaults to be a one to one mapping with the area of the Flash movie. If a perspective transformation is desired, swf_perspective may be used.

void swf_perspective(double fovy, double aspect, double near, double far)

Define a perspective projection transformation. Fovy selects the field-of-view angle in the y direction. Aspect should be set to the aspect ratio of the viewport we're drawing into. The near and far clipping planes are specified by near and far. Various distortion artifacts may appear when using a perspective projection, since Flash players only have a 2D matrix. Some of these can be quite disturbing.

void swf_polarview(double dist, double azimuth, double incidence, double twist)

Defines the viewer's position in polar coordinates. dist selects the distance from the viewpoint to the world space origin. Azimuth defines the azimuthal angle in the x-y plane, measured from the y axis. Incidence specifies the angle of incidence in the y-z plane, measured from the z axis. The incidence angle is the angle of the viewport relative to the z axis. Twist defines the amount that the viewpoint is to be rotated around the line of sight using the right-hand rule.

void swf_lookat(double vx, double vy, double vz, double px, double py, double pz, double twist)

Defines a viewing transformation by giving the view position vx, vy, vz, and the coordinates of a reference point in the scene at px, py, pz. Twist controls a rotation along the viewer's z axis.

void swf_pushmatrix(void)

Push the current transformation matrix onto the stack.

void swf_popmatrix(void)

Restore a previous transformation matrix.

void swf_scale(double x, double y, double z)

Scale the current transformation.

void swf_translate(double x, double y, double z)

Translate the current transformation.

void swf_rotate(double angle, char axis)

Rotate the current transformation by the given angle about x, y, or z axis. The axis may be 'x', 'y', or 'z'.

void swf_posround(int doit)

This enables or disables rounding of the translation when objects are places or moved. There are times when text can be made more readable if position rounding is turned on.

CGI Support

The following functions support writing simple cgi programs that synthesize flash files on the fly. To understand how these functions work, let's first look at the httprequest data structure:

typedef struct httprequest {
    int content_length;
    char *auth_type;
    char *gateway_interface;
    char *http_accept;
    char *http_accept_charset;
    char *http_accept_language;
    char *http_connection;
    char *http_host;
    char *http_pragma;
    char *http_user_agent;
    char *path;
    char *query_string;
    char *remote_addr;
    char *remote_host;
    char *remote_user;
    char *request_method;
    char *request_uri;
    char *script_filename;
    char *script_name;
    char *server_name;
    char *server_port;
    char *server_protocol;
    char *server_software;
    char *tz;
    char *vserver_name;
} httprequest;

When the functions cgi_getrequest or cgi_getfullrequest are called with a pointer to an httprequest structure, then various kinds of information are returned.

cgi_getrequest(httprequest *req)

This will return in the CGI query string in the structure field req->query_string. This is done by doing a getenv on the environment variable "QUERY_STRING".

cgi_getfullrequest(httprequest *req)

This will return the content length as an integer in structure field req->content_length. All the rest of the environment variables will be examined and if they are set, returned in the appropriate fields.

cgi_putmimeheader(char *str)

This writes a mime header. For a program that generates Flash data, this should be called with the string "application/x-shockwave-flash".