Macromedia Flash File Format (SWF)

recompiled with RAW HTWL

The Display List

Introduction	Basic Types	Display List	Control Tags
Shapes	(Examples Shapes)	Gradients	Buttons
Sprites	Fonts and Text	Shape Morphing	Bitmap
Sounds	Actions	ActionScripts	Reference

The Display List Contents

The Display List
Clipping Layers
Using the Display List
PlaceObject
PlaceObject2
RemoveObject
RemoveObject2
ShowFrame

The Display List

Displaying a frame of a Macromedia Flash movie is a three-stage process:

Objects are defined with definition tags such as DefineShape , DefineSprite etc. Each object is given a unique ID called a character—, and stored in a repository called the dictionary.
Selected characters are copied from the dictionary and placed on the display list. This is the list of the characters that will be displayed in the next frame.
Once complete, the contents of the display list are rendered to the screen with ShowFrame

Each character on the display list is assigned a depth value. The depth determines the stacking order of the character. Characters with lower depth values are displayed underneath characters with higher depth values. A character with a depth value of 1 is displayed at the bottom of the stack. A character may appear more than once in the display list, but at different depths. There can be only one character at any given depth.

In Macromedia Flash (SWF) 1 and 2, the display list was a flat list of the objects that are present on the screen at any given point in time. In Macromedia Flash (SWF) 3 and later the display list is a hierarchical list where an element on the display can have a list of child elements. (see DefineSprite )

There are five tags used to control the display list:

PlaceObject — Adds a character to the display list. PlaceObject2 — Adds a character to the display list, or modifies the character at the specified depth. RemoveObject — Removes the specified character from the display list. RemoveObject2 — Removes the character at the specified length. ShowFrame — Renders the contents of the display list to the display.

Note: The older tags, PlaceObject and RemoveObject, are rarely used from SWF 3 onwards.

The diagram below illustrates the display process. First, three objects are defined; a shape, a text object and a sprite. These objects are given CharacterId’s and stored in the Dictionary. Character 1 (the shape) is then placed at depth 1, the bottom of the stack, and will be obscured by all other characters when the frame is rendered. Character 2 (the text) is placed twice; once at depth 2, and once at depth 4, the top of the stack. Character 3 (the sprite) is placed at depth 3.

Clipping Layers

Flash supports a special kind of object in the Display List called a clipping layer. A character placed as a clipping layer is not displayed, rather it clips (or masks) the characters placed above it. The ClipDepth field in PlaceObject2 specifies the top-most depth that will be masked by the clipping layer.

For example, say a shape was placed at depth 1 with a ClipDepth of 4. All depths above 1, up to and including depth 4, will be masked by the shape placed at depth 1. Characters placed at depths above 4, will not be masked.

Using the Display List

The following is a step-by-step procedure for creating and displaying a Macromedia Flash animation:

Define each object with a DefineShape , DefineText , DefineSprite or DefineMorphShape tag. Each object is given a unique character ID, and added to the dictionary.
Add each character to the display list with a PlaceObject2 tag. Each PlaceObject2 tag specifies the character to be displayed, plus the following attributes:
1. A depth value. This controls the stacking order of the character being placed. Characters with lower depth values appear to be underneath characters with higher depth values. A depth value of 1 means the character is displayed at the bottom of the stack. There can be only one character at any given depth.
2. A transformation matrix. This determines the position, scale, factor, and angle of rotation of the character being placed. The same character may be placed more than once (at different depths) with a different transformation matrix.
3. An optional color transform. This specifies the color effect applied to the character being placed. Color effects include transparency and color shifts.
4. An optional name string. This identifies the character being placed for SetTarget actions. SetTarget is used to perform actions inside sprite objects.
5. An optional ClipDepth value. This specifies the top-most depth that will be masked by the character being placed.
6. An optional ratio value. This controls how a morph character is displayed when placed. A ratio of zero displays the character at the start of the morph. A ratio of 65535 displays the character at the end of the morph.
Render the contents of the display list to the screen with a ShowFrame tag.
Modify each character on the Display List with a PlaceObject2 tag. Each PlaceObject2 assigns a new transformation matrix to the character at a given depth. (The character ID is not specified because there can be only one character for each depth).
Display the characters in their new positions with a ShowFrame tag. Repeat steps 4 and 5 for each frame of the animation. Note: if a character does not change from frame to frame, there is no need to re-place the unchanged character after each frame.
Remove each character from the display list with a RemoveObject2 tag. Only the depth value is required to identify the character being removed.

PlaceObject

The PlaceObject tag adds a character to the display list. The CharacterId identifies the character to be added. The Depth field specifies the stacking order of the character. The Matrix field specifies the position, scale and rotation of the character. If the length of the record indicates a size that exceeds the end of the transformation matrix, it is assumed that ColorTransform field is appended to the record. This specifies the color effect (such as transparency) that is applied to the character. The same character can be added more than once to the display list with a different depth and transformation matrix.

Note: PlaceObject is rarely used from Macromedia Flash (SWF) 3 onwards, it has been superseded by PlaceObject2.

     PlaceObject

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 4

     CharacterId           UI16           ID of character to place

     Depth           UI16           Depth of character

     Matrix           MATRIX           Transform matrix data

     ColorTransform (optional)           CXFORM           Color transform data

SwfJava v0.0: how to create a PlaceObject tag

new PlaceObject ( int characterID, int depth, Matrix matrix ); new PlaceObject ( int characterID, int depth, Matrix matrix, CXForm cxForm );

XWF v0.0: how to declare a PlaceObject tag

<PlaceObject ref="(ID)" depth="(int)" > [<Matrix ... />] [<ColorTransform ... />] </PlaceObject>

PlaceObject2

The PlaceObject2 tag extends the functionality of PlaceObject. PlaceObject2 can both add a character to the display list, and modify the attributes of a character that is already on the display list. The PlaceObject2 tag has changed slightly from Flash 4 to Flash 5.

The tag begins with a group of flags that indicate which fields are present in the tag. The optional fields are CharacterId, Matrix, ColorTransform, Ratio, ClipDepth and Name. The Depth field is the only field that is always required.

The depth value determines the stacking order of the character. Characters with lower depth values are displayed underneath characters with higher depth values. A depth value of 1 means the character is displayed at the bottom of the stack. There can be only one character at any given depth. This means a character that is already on the display list can be identified by its depth alone. (i.e. a CharacterId is not required).

PlaceFlagMove and PlaceFlagHasCharacter indicate whether a new character is being added to the display list, or a character already on the display list is being modified. The meaning of the flags is as follows:

PlaceFlagMove = 0 and PlaceFlagHasCharacter = 1

A new character (with ID of CharacterId) is placed on the display list at the specified Depth. Other fields set the attributes of this new character.
PlaceFlagMove = 1 and PlaceFlagHasCharacter = 0

The character at the specified Depth is modified. Other fields modify the attributes of this character. Because there can be only one character at any given depth, no CharacterId is required.
PlaceFlagMove = 1 and PlaceFlagHasCharacter = 1

The character at the specified Depth is removed, and a new character (with ID of CharacterId) is placed at that depth. Other fields set the attributes of this new character.

For example, a character that is moved over a series of frames has PlaceFlagHasCharacter set in the first frame, and PlaceFlagMove set in subsequent frames. The first frame places the new character at the desired depth, and sets the initial transformation matrix. Subsequent frames simply replace the transformation matrix of the character at the desired depth.

The optional fields in PlaceObject2 have the following meaning:

The CharacterId field specifies the character to be added to the display list. It only used only when a new character is being added. If a character that is already on the display list is being modified, the CharacterId field is absent.
The Matrix field specifies the position, scale and rotation of the character being added or modified.
The ColorTransform field specifies the color effect applied to the character being added or modified.
The Ratio field specifies a morph ratio for the character being added or modified. This field applies only to characters defined with DefineMorphShape , and controls how far the morph has progressed. A ratio of zero displays the character at the start of the morph. A ratio of 65535 displays the character at the end of the morph. For values between zero and 65535 the player interpolates between the start and end shapes, and displays an ‘in-between’ shape.
The ClipDepth field specifies the top-most depth that will be masked by the character being added. A ClipDepth of zero indicates no clipping.
The Name field specifies a name for the character being added or modified. This field is typically used with sprite characters , and is used to identify the sprite for SetTarget actions. It allows the main movie (or other sprites) to perform actions inside the sprite.

     PlaceObject2

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 26

     PlaceFlagHasClipActions           UB[1]           Has Clip Actions (added to Flash 5)

     PlaceFlagReserved           UB[1]           Reserved Flags

     PlaceFlagHasName           UB[1]           Has name

     PlaceFlagHasRatio           UB[1]           Has ratio

     PlaceFlagHasColorTransform           UB[1]           Has color transform

     PlaceFlagHasMatrix           UB[1]           Has matrix

     PlaceFlagHasCharacter           UB[1]           Places a character

     PlaceFlagMove           UB[1]           Defines a character to be moved

     Depth           UI16           Depth of character

     CharacterId           If PlaceFlagHasCharacter = 1 UI16           ID of character to place

     Matrix           If PlaceFlagHasMatrix = 1 MATRIX           Transform matrix data

     ColorTransform           If PlaceFlagHasColorTransform = 1 CXFORM           Color transform data

     Ratio           If PlaceFlagHasRatio = 1 UI16

     Name           If PlaceFlagHasName = 1 STRING           Name of character

     ClipActions           If PlaceFlagHasClipActions = 1 ClipActions           Clip Actions Data

SwfJava v0.0: how to create a PlaceObject2 tag

new PlaceObject2 ( int depth, boolean hasMove, int characterID (may be zero), String name, Matrix matrix, CXFormWithAlpha cxFormwithAlpha, boolean hasRatio, int ratio, ClipActions clipActions );

XWF v0.0: how to declare a PlaceObject2 tag

<PlaceObject2 ref="(ID)" depth="(int)" [name="(string)"] [ratio="(int)"] > [<Matrix ... />] [<ColorTransformWithAlpha ... />] [<ClipActions ... />] </PlaceObject2>

personal note: it seems that PlaceObject2 uses CXFormWithAlpha instead of CXForm.

RemoveObject

The RemoveObject tag removes the specified character (at the specified depth) from the display list.

     RemoveObject

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 5

     CharacterId           UI16           ID of character to remove

     Depth           UI16           Depth of character

SwfJava v0.0: how to create a RemoveObject tag

new RemoveObject ( int characterID, int depth );

XWF v0.0: how to declare a RemoveObject tag

<RemoveObject ref="(ID)" depth="(int)" />

RemoveObject2

The RemoveObject tag removes the character at the specified depth from the display list.

     RemoveObject2

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 28

     Depth           UI16           Depth of character

SwfJava v0.0: how to create a RemoveObject2 tag

new RemoveObject2 ( int depth );

XWF v0.0: how to declare a RemoveObject tag

<RemoveObject2 depth="(int)" />

ShowFrame

The ShowFrame tag instructs the player to display the contents of the display list. The movie is paused for the duration of a single frame.

     ShowFrame

     Field           Type           Comment

     Header           RECORDHEADER           Tag ID = 1

SwfJava v0.0: how to create a ShowFrame tag

new ShowFrame(); new ShowFrame ( int duration );

XWF v0.0: how to declare a ShowFrame tag

<ShowFrame [duration="(int)"] />

Introduction	Basic Types	Display List	Control Tags
Shapes	(Examples Shapes)	Gradients	Buttons
Sprites	Fonts and Text	Shape Morphing	Bitmap
Sounds	Actions	ActionScripts	Reference