Back to the SSWF project home page

Reference to the SWF library

(Written by Alexis Wilke in 2002-2007)

Contents


This project license

The entire SSWF project is covered by the following license:

Copyright (c) 2002-2007 Made to Order Software Corp.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


About this library

In order to create something useful, I thought of creating a totally seperate SWF library so it can be reused by other tools, not only the SSWF scripting language.

The main goal was to allow the end user to make easy calls to the library without having to know precisly how things will be encoded in the final SWF file.

At the time of writing, only the Save() process is really available in the library. Note that you can still look at the result and dump others SWF files using the swf_dump tool.

Alexis Wilke
the author


The library structure

The library is defined in three main parts: some utility functions, the common objects and the tags. The tags are themselves defined in two main groups: the tags without a unique identifier and those with a unique identifier. There are also two categories of tags: those which can include other tags (the TagHeader and TagSprite) and the others. Finally, there are tags which can reference other(s) using either a name or the unique identifier.

The utility functions are primarilly for use by the library. You can use them if you wish but they may change a lot with time.

The common objects will be used to declare some parameters of the different tags such as the color, bounding box, matrix, etc. It is crucial to have these lower level objects to quickly build a complete tag. There are also objects such as the vectors list, item base and memory manager which are used by any of the other objects to manage lists and memory without having to reinvent the wheel in each object.

The tags are all derived from the TagBase class, itself derived from the ItemBase class so any tag can be inserted in an array of vectors. Tags with a unique identifier are all derived from the TagBaseID. This is important so each tag receives a different identifier (NOTE: there is a special case in the SWF format which is the DefineFont and DefineFontInfo which both have to receive the same identifier; this is, however, taken care of internally as you can't define a font information object yourself).


The common objects

The common objects are used by some of the tag objects. It is often necessary for you to create one of these objects (possibly on the stack) in order to initialize a tag object properly.

Color

The color object defines an RGB or RGBA color. A color is taken as an RGBA when the alpha channel isn't set to 255. The IsSolid() function will return true when a color is an RGB color and false when the color is RGBA.

ColorTransform

The TagPlace uses a color transformation definition in order to affect the input color. It is possible, by setting all the scaling factors to 0.0 and the bias to a specific color value to change a shape to a specific color (however limited to a range of 0 to 128).

Data

The Data object is a memory file manager. You can write, read and seek within the data saved in this object just as you would do with a file.

Edges

The Edges are the basic element of the SWF format as these are used to draw the shapes in the output screen. It is a set of line and curve coordinates. A line has no control point.

To define an edge you ether need to specify its coordinates or you can declare a variable of type sswf::Edges::edge_t. This structure is defined below.

Edges in SWF are defined as lists of offsets. The very first coordinate is defined in a shape. Then each edge is an offset from the previous edge.

For example, when you want to draw a line, you need two points: A and B. The shape specifies the position of the point A. Then you need one edge with coordinates:

	edge.f_x = B.x - A.x;
	edge.f_y = B.y - A.y;

Similarly, when you want to draw a curve, you need three points: A, B and C. If we consider the point B as being the control point, then we can infer that: the shape specifies the position of the point A and one edge is defined with a control as follow:

	edge.f_ctrl_x = B.x - A.x
	edge.f_ctrl_y = B.y - A.y
	edge.f_x = C.x - C.x;
	edge.f_y = C.y - C.y;

Note that we first go to the control point then on to the 2nd anchor.

All the coordinates are taken to be TWIPs.

Matrix

There are several tags in which one can define a Matrix. These use this object.

Rectangle

The rectangle object is used in many places most of the time to declare a bounding box.

State

Whenever you define a button you need to define a state. A button state includes a reference to an object, a depth (called layer here), a matrix and a set of flags.

Style

The style object will be used to create a fill or line style later included in a shape.

Vectors

A Vectors object is a dynamic array of pointers to other objects. It is used to generate the different lists of tags, actions, styles, edges, etc. The objects pointed to must be derived from the ItemBase class. This class is empty, it is just used to be able to cast the pointers to objects instead of using void * (which wouldn't be clean in C++). Thus, a class such as the styles is derived from the ItemBase as follow:

class Style : public ItemBase { ... };

Then later we can have a list of styles since a style is a valid vector item.


The tag objects

All the tag objects need to have a parent except the TagHeader. In order to insert objects in a sprite, that sprite will be given as the parent object. At this time, only a header and a sprite can be a parent object. At this time, definition tags can't be included in a sprite or an error will be generated.

A TagBase object is not an object. Instead, all the other objects are based on this one. You can't create a TagBase directly. Because all the other tags are based on this one, it is described first. All the virtual functions are not explained in the other objects though they all are available.

TagBase

All the other tag objects are derived from this one. It is important since most of the functions are virtual functions.

NOTE: at this time, there are only two levels (well, three for objects with an ID), the TagBase object and the derived object (in case of objects with an ID, you also have a TagBaseID). It doesn't look to me like it will be necessary to have any more derivation.

class TagBase : public MemoryManager

All the tags inherit the memory manager of the TagBase class.

TagButton

Create a button object to offer interactivity in an SWF movie file. A button is composed of states with corresponding shapes and a list of actions to execute when the end user clicks on the button.

A button is a definition tag and it has an identifier.

class Button : public TagBaseID;

TagDoAction

TagEditText

TagEnd

TagFont

TagHeader

TagImage

TagInfo

TagPlace

TagProtect

TagRemove

TagSetBackgroundColor

TagShape

TagShowFrame

TagSprite

TagText


The utility functions

The common objects are used by some of the tag objects. It is often necessary for you to create one of these objects (possibly on the stack) in order to initialize a tag object properly.

Class less functions

inline void assert(int cond, const char *format, ...);
extern const char *sswf_version(void);
extern void swap(void *s1, void *s2, size_t size);

MemoryManager

The memory manager is an object used to allocate and free memory. It will ensure that any memory block allocated gets freed upon the deletion of the object allocating that memory. Also it ensures that freed memory buffers were actually allocated.

In order to use a memory manager, you need to derive your object(s) from it. One should rarely use the memory manager of another object. A function in that object should be defined in order to attach or allocate new blocks of memory.

The memory manager makes use of the class Buffer object in order to keep track of all the memory buffers allocated at any one time. This object is not described here since it is really low level and may evolve as the memory manager requires. You shouldn't directly use a buffer object.

class MemoryManager;

This document was last modified on Mar 30 2007.