The Display List

The Display List Contents

The Display List Contents.............................................................................................................................. 1

The Display List.................................................................................................................................................... 1

Clipping Layers..................................................................................................................................................... 2

Using the Display List........................................................................................................................................... 3

PlaceObject............................................................................................................................................................ 3

PlaceObject2.......................................................................................................................................................... 4

RemoveObject........................................................................................................................................................ 6

RemoveObject2...................................................................................................................................................... 6

ShowFrame............................................................................................................................................................ 6

The Display List

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

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

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

3. 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 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 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 depth.

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.

CharacterId = 1

Depth = 1

Bottom

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.

CharacterId = 2

Depth = 2

CharacterId = 1

Depth = 1

ClipDepth = 4

Bottom

Using the Display List

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

1. Define each object with a DefineShape, DefineText, DefineSprite or DefineMorphShape tag. Each object is given a unique character ID, and added to the dictionary.

2. Add each character to the display list with a PlaceObject2 tag. Each PlaceObject2 tag specifies the character to be displayed, plus the following attributes:

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

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

iii. An optional color transform. This specifies the color effect applied to the character being placed. Color effects include transparency and color shifts.

iv. An optional name string. This identifies the character being placed for SetTarget actions. SetTarget is used to perform actions inside sprite objects.

v. An optional ClipDepth value. This specifies the top-most depth that will be masked by the character being placed.

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

3. Render the contents of the display list to the screen with a ShowFrame tag.

4. 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).

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

6. 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 species 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 SWF3 onwards, it has been superceded by PlaceObject2.

(See class FCTPlaceObject in the Flash File Format SDK)

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

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

(See class FCTPlaceObject2 in the Flash File Format SDK)

PlaceObject2
Field	Type	Comment
Header	RECORDHEADER	Tag ID = 26
PlaceFlagsReserved	UB[1]	Reserved
PlaceFlagsHasDefineClip	UB[1]	0 = no clip specified 1 = clip is specified
PlaceFlagHasName	UB[1]	0 = no name specified 1 = name is specified
PlaceFlagHasRatio	UB[1]	0 = no ratio specified 1 = ratio is specified
PlaceFlagHasColorTransform	UB[1]	0 = no color transform. 1 = includes color transform
PlaceFlagHasMatrix	UB[1]	0 = no matrix specified 1 = matrix is specified
PlaceFlagHasCharacter	UB[1]	0 = no character specified 1 = character is specified
PlaceFlagMove	UB[1]	0 = placing new character 1 = changes the transform of a character that is already on the display list.
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	Morph ratio
ClipDepth	If PlaceFlagHasDefineClip = 1 UI16	Clipping data?
Name	If PlaceFlagHasName = 1 STRING	Name of character

RemoveObject

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

(See class FCTRemoveObject in the Flash File Format SDK)

RemoveObject
Field	Type	Comment
Header	RECORDHEADER	Tag ID = 5
CharacterId	UI16	ID of character to remove
Depth	UI16	Depth of character

RemoveObject2

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

(See class FCTRemoveObject2 in the Flash File Format SDK)

RemoveObject2
Field	Type	Comment
Header	RECORDHEADER	Tag ID = 28
Depth	UI16	Depth of character

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.

(See class FCTShowFrame in the Flash File Format SDK)

ShowFrame
Field	Type	Comment
Header	RECORDHEADER	Tag ID = 1