SWF10翻译

SWF_FILE_FORMAT_SPEC_V10文档翻译

Chapter 1 Basic Data Types

Coordinates and twips

The SWF file format stores all x-y coordinates as integers, usually in a unit of measurement

called a twip. In the SWF format, a twip is 1/20th of a logical pixel. A logical pixel is the same

as a screen pixel when the file is played at 100%—that is, without scaling.

坐标及twips单位

SWF文件的X,Y坐标是以整型格式进行存储，通常以twips作为一个量度单位，以SWF格式来说，

一个twip就相当于是一个逻辑像素的1/20，在没有缩放，即100%比例进行播放时，一个SWF文件

逻辑像素就是一个屏幕像素。

 

Integer types and byte order

The SWF file format uses 8-bit, 16-bit, 32-bit, 64-bit, signed, and unsigned integer types. All

integer values are stored in the SWF file by using little-endian byte order: the least significant

byte is stored first, and the most significant byte is stored last, in the same way as the Intel x86

architecture. The bit order within bytes in the SWF file format is big-endian: the most

significant bit is stored first, and the least significant bit is stored last.

 

整型类型及字节序

SWF文件格式使用8位，16为，32为，64位，有符号及无符号整型类型，在SWF文件中，所有以整型

方式存储的值都是使用little-endian 字节序，即低字节存储在低位，高字节存储在高位。Intel x86架构

采用得就是这种方式，而对于一个字节内位顺序采用的是big-endian方式，及高位先存储，然后再存低位。

MATRIX record

The MATRIX record represents a standard 2x3 transformation matrix of the sort commonly

used in 2D graphics. It is used to describe the scale, rotation, and translation of a graphic

object. The MATRIX record must be byte aligned.

MATRIX record表示的是标准的2×3排序变换矩阵，通常应用于2D，用来完成缩放，旋转及图形图像变换

MATRIX record必须是字节对齐的。

Field	Type	Comment
HasScale	UB[1]	Has
NScaleBits If HasScale = 1	UB[5] Bits in each scale value field	NScaleBits If HasScale = 1
ScaleX	If HasScale = 1, FB[NScaleBits] x scale value	ScaleX If HasScale = 1
ScaleY	If HasScale = 1, FB[NScaleBits] y scale value	ScaleY If HasScale = 1
HasRotate	UB[1]	Has rotate and skew values if equal to 1
NRotateBits	If HasRotate = 1,UB[5] Bits in each rotate value field	NRotateBits If HasRotate = 1
RotateSkew0	If HasRotate = 1, FB[NRotateBits]	First rotate and skew value
RotateSkew1	If HasRotate = 1, FB[NRotateBits]	Second rotate and skew value
NTranslateBits	UB[5]	Bits in each translate value field
TranslateX	SB[NTranslateBits]	x translate value in twips
TranslateY	SB[NTranslateBits]	y translate value in twips

 

Chapter 2 SWF Structure Summary

 

The SWF header+SWF file structure

 

SWF File Header

Field             Type    Comment                                            Bytes

Signature         UI8                    Signature byte:                                        1 

                                                “F” indicates uncompressed

                                                “C” indicates compressed (SWF 6 and later only)

Signature         UI8                    Signature byte always “W”                               1

Signature         UI8                    Signature byte always “S”

Version             UI8                    Single byte file version (for example, 0x06 for SWF 6)          1 

FileLength       UI32        Length of entire file in bytes                              4 

FrameSize    RECT    Frame size in twips                                     由表示最大数所需要位来决定

(前五位用来标识用多少位表示，因为UB[5]

,注意单位是twips,换算成像素，还要除以20)

FrameRate      UI16        Frame delay in 8.8 fixed number of frames per second         2

FrameCount   UI16        Total number of frames in file                             2

 

SWF file structure

Following the header is a series of tagged data blocks. All tags share a common format, so any

program parsing a SWF file can skip over blocks it does not understand. Data inside the block

can point to offsets within the block, but can never point to an offset in another block. This

ability enables tags to be removed, inserted, or modified by tools that process a SWF file.

The FileAttributes tag is only required for SWF 8 and later.

 

|Header | FileAttributes tag | Tag | Tag | Tag | End tag

 

Tag format

Each tag begins with a tag type and a length. The tag-header formats can be either short or

long. Short tag headers are used for tags with 62 bytes of data or less. Long tag headers, with a

signed 32-bit length field, can be used for any tag size up to 2GB, far larger than is presently

practical.

每一个tag都是以tag type+长度方式开始的，tag-header格式可以是 short 或 long 类型。Short

Tag headers 用来表示长度小于等于62字节的tag.Long tag headers是一个有符号的32-bit字段，

最大能存储2GB长度Tag,这远比目前实际大得多。

RECORDHEADER (short)

Field	Type	Comment
TagCodeAndLength	UI16	Upper 10 bits: tag type Lower 6 bits: tag length

The length specified in the TagCodeAndLength field does not include the

RECORDHEADER that starts a tag.

在TagCodeAndLength字段中所标明的标签的长度是不包含RECORDHEADER部分的，

If the tag is 63 bytes or longer, it is stored in a long tag header. The long tag header consists of

a short tag header with a length of 0x3f, followed by a 32-bit length.

如果tag是63字节或更长，它以long tag header方式来存储，log tag header由一个shrot tag header+0x3f+32-bit length来组成。

RECORDHEADER (long)

Field	Type	Comment
TagCodeAndLength	UI16	Tag type and length of 0x3F Packed together as in short header
Length	SI32	Length of tag

 

 

Definition and control tags

The two categories of tags in a SWF file are as follows:

"Definition tags" And "Control tags"

 

Definition tags -- define the content of the SWF file—the shapes, text, bitmaps, sounds, and so

                              on. Each definition tag assigns a unique ID called a character ID to the content it defines.

                              Flash Player then stores the character in a repository called the dictionary. Definition tags, by

                              themselves, do not cause anything to be rendered

Definition tags -- 定义SWF文件的内容--形状，文本，位图，声音等等，每一个 definition tag被分配一个唯一

                              的ID好来表明一个已定义的内容，之后Flash Player将其存放在一个叫做“字典”的容器中，

                              Definition tag其自身不会被渲染。

 

Control tags -- create and manipulate rendered instances of characters in the dictionary, and

                       control the flow of the file.

Control tags -- 创建并操作字典中已渲染的角色实例，并控制文件数据流。

 

Tag ordering in SWF files（SWF文件中tag规则）

Generally speaking, tags in a SWF can occur in any order. However, you must observe the

following rules:

■ The FileAttributes tag must be the first tag in the SWF file for SWF 8 and later.

■ A tag should only depend on tags that come before it. A tag should never depend on a tag

that comes later in the file.

■ A definition tag that defines a character must occur before any control tag that refers to

that character.

   一个定义了角色的definition tag必须出现在任何与该角色相关control tag之前。

■ Streaming sound tags must be in order. Out-of-order streaming sound tags result in the

sound being played out of order.

          流声音tag必须是有序的，无序的流声音tag会导致播放时无序

■ The End tag is always the last tag in the SWF file.

 

The dictionary

The dictionary is a repository of characters that are defined, and are available for control tags

to use. The process of building and using the dictionary is as follows:

字典是所有被定义角色容器，为control tags所用，建立及使用字典步骤如下：

1. The definition tag defines some content, such as a shape, font, bitmap, or sound.

2. The definition tag assigns a unique CharacterId to the content.

3. The content is saved in the dictionary under the CharacterId.

4. A control tag uses the CharacterId to retrieve the content from the dictionary, and performs

some action on the content, such as displaying a shape, or playing a sound.

 

Every definition tag must specify a unique ID. Duplicate IDs are not allowed. Typically, the

first CharacterId is 1, the second CharacterId is 2, and so on. The number zero (0) is special

and is considered a null character.

每一个定义的 definition tag 必须制定一个唯一的ID, 负责IDs 是不允许的，通常，第一个角色ID为1，其次为2，以此类推。

0用来表明空角色ID标识。

 

Control tags are not the only tags that reference the dictionary. Definition tags can use

characters from the dictionary to define more complex characters. For example, the

DefineButton and DefineSprite tags refer to other characters to define their contents. The

DefineText tag can refer to font characters to select different fonts for the text.

不仅仅Control tag能引用字典，definition tags也可以从字典中使用角色来定义更复杂的角色。例如：...

 

Processing a SWF file(SWF文件的处理)

Flash Player processes all of the tags in a SWF file until a ShowFrame tag is encountered. At

this point, the display list is copied to the screen and Flash Player is idle until it is time to

process the next frame. The contents of the first frame are the cumulative effect of performing

all of the control tag operations before the first ShowFrame tag. The contents of the second

frame are the cumulative effect of performing all of the control tag operations from the

beginning of the file to the second ShowFrame tag, and so on.

Flash Player在遇到 ShowFrame tag之前会处理所有的control tag,正因为如此，显示列表中的信息会被拷贝到屏幕上同时

Flash Player处于闲置状态，直到遇到下一个ShowFrame tag出现。每个ShowFrame tag中取出的control tag在显示的时候

呈现叠加效果

 

Summary

A SWF file is made up of a header, followed by a number of tags. The two types of tags are

definition tags and control tags. Definition tags define the objects known as characters,

which are stored in the dictionary. Control tags manipulate characters, and control the flow

of the file.

小结：

一个SWF文件由 header+ much more tags 组成，tags有两种类型：definition tags 和 control tags,

Definition tags定义角色对象，并存储在字典中，Control tags操作角色，并且控制文件数据流。

 

Chapter 3 The Display List(第三章，显示列表)

Displaying a frame of a SWF file is a three-stage process:

1. Objects are defined with definition tags such as DefineShape, DefineSprite, and so on.

Each object is given a unique ID called a character, and is stored in a repository called the

dictionary.

2. Selected characters are copied from the dictionary and placed on the display list, which 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.

显示一个swf 文件的一帧数据需要经历三个步骤：

1：用definition tags（诸如defineShape, DefineSprite）等对对象进行定义，每一个对象分配一个唯一的ID标识一个角色并存储在字典中

2：所选择的角色从字典中拷贝出来并放置在显示列表中，以方便下一帧显示

3：完成以后，显示列表中的信息就会在遇到ShowFrame标签时进行渲染。

 

A depth value is assigned to each character on the display list. 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 can appear more than once in the display list, but at different

depths. Only one character can be 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 time. In SWF 3 and later versions, the display list is a hierarchical list where an

element on the display can have a list of child elements. For more information, see

DefineSprite.

depth 值被分配给显示列表中的每个角色，这个 depth 值决定角色的栈顺序，角色的depth值越小，出现的就越晚。

最小的之为1，放置在栈底，一个角色可以在显示列表中出现多次，但是有不同的depths，一个角色对应一个给定的depth

,在SWF1和2版本中，显示列表是对象平坦列表被展现在屏幕上，SWF3及后续版本改用继承的方式，详见DefineSprite.

 

The following six tags are used to control the display list:

■ PlaceObject： Adds a character to the display list.

■ PlaceObject2 & PlaceObject3： 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 in SWF 3 and

         later versions.

 

Clipping layers[裁剪层]

Flash Player 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 the

clipping layer masks.

For example, if a shape was placed at depth 1 with a ClipDepth of 4, all depths above 1, up to

and including depth 4, are masked by the shape placed at depth 1. Characters placed at depths

above 4 are not masked.

Flash Player在显示列表中提供了一种特殊的对象类型叫裁剪层，一个角色放置在裁剪层中是不会被显示的，而是裁剪

（或遮盖）放置在其上的对象，在PlaceObject2就有一个ClipDepth字段用来表明裁剪的最大层级数。

 

Using the display list[显示列表的使用]

The following procedure creates and displays an animation:

接下来的步骤是创建及显示一个动画

1. Define each character with a definition tag.

Each character is given a unique character ID, and added to the dictionary.

为每一个角色分配一个definition tag，每一个角色分配一个唯一ID,并放置在字典中

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:

A depth value, which 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. Only one

character can be at any given depth.

A transformation matrix, which determines the position, scale, factor, and angle of

rotation of the character being placed. The same character can be placed more than once

(at different depths) with a different transformation matrix.

变换矩阵，决定位置，缩放，比例，旋转角度，同样的角色可以放置不同的变换矩阵。

An optional color transform, which specifies the color effect applied to the character

being placed. Color effects include transparency and color shifts.

An optional name string, which identifies the character being placed for SetTarget

actions. SetTarget is used to perform actions inside sprite objects.

An optional ClipDepth value, which specifies the top-most depth that will be masked by

the character being placed.

An optional ratio value, which 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. Use a ShowFrame tag to render the contents of the display list to the screen.

4. Use a PlaceObject2 tag to modify each character on the display List.

Each PlaceObject2 assigns a new transformation matrix to the character at a given depth.

The character ID is not specified because each depth can have only one character.

使用PlaceObject2 tag来修改显示列表中的每一个角色

每一个PlaceObject2分配一个新的变换矩阵给指定depth的角色

角色ID是不能指定的，因为每一个depth只能对应一个角色。

5. Use a ShowFrame tag to display the characters in their new positions.

Repeat steps 4 and 5 for each frame of the animation.

6. Use a RemoveObject2 tag to Remove each character from the display list.

Only the depth value is required to identify the character being removed.

 

Display list tags

Display list tags are used to add character and character attributes to a display list.

 

PlaceObject2

The PlaceObject2 tag extends the functionality of the PlaceObject tag. The PlaceObject2 tag

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 changed slightly from SWF 4 to SWF 5. In

SWF 5, clip actions were added.

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, Name, and

ClipActions. 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. Any given depth can have only one

character. This means a character that is already on the display list can be identified by its

depth alone (that is, a CharacterId is not required).

The PlaceFlagMove and PlaceFlagHasCharacter tags 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

■ 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

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

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 Flash Player interpolates between the start and end shapes, and displays an inbetween

shape.

■ The ClipDepth field specifies the top-most depth that will be masked by the character

being added. A ClipDepth of zero indicates that this is not a clipping character.

■ 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 file (or other sprites) to perform actions inside the sprite (see

“Sprites and Movie Clips” on page 231).

■ The ClipActions field, which is valid only for placing sprite characters, defines one or

more event handlers to be invoked when certain events occur.

 

Chapter 4  Control  tags

Control tags manage some overall aspects of files, frames, and playback in SWF files.

Control tags是针对SWF文件帧，回放等宏观，全局的一些方面进行管理

包含的tag如下：

SetBackgroundColor

FrameLabel

Protect

End

ExportAssets  

ImportAssets

EnableDebugger

EnableDebugger2

ScriptLimits

SetTabIndex

FileAttributes

Field	Type	Comment
UseGPU (see note following table)	UB[1]	If 1, the SWF file uses GPU compositing features when drawing graphics, where such acceleration is available. If 0, the SWF file will not use hardware accelerated graphics facilities. Minimum file version is 10.

ImportAssets2

SymbolClass

Metadata

DefineScalingGrid

DefineSceneAndFrameLabelData

Chapter 5 Actions

Actions are an essential part of an interactive SWF file. Actions allow a file to react to events

such as mouse movements or mouse clicks. The SWF 3 action model and earlier supports a

simple action model. The SWF 4 action model supports a greatly enhanced action model that

includes an expression evaluator, variables, and conditional branching and looping. The

SWF 5 action model adds a JavaScript-style object model, data types, and functions.

行为对于相与SWF文件进行互动是必须的一部分，行为允许SWF文件对事件作出反应(如鼠标移动或鼠标点击事件)，SWF 3 action model以及早期版本支持一些简单的行为模型，SWF 4 action model支持的行为模型有了很大增强，包括表达式计算，变量，条件分支及循环，SWF 5 action model 还添加了java script风格的脚本，数据类型及函数

 

SWF 3 action model

The SWF 3 action model consists of eleven instructions for Flash Player:

Instruction	See	Description
Play	ActionPlay	Start playing at the current frame
Stop	ActionStop	Stop playing at the current frame
NextFrame	ActionNextFrame	Go to the next frame
PreviousFrame	ActionPreviousFrame	Go to the previous frame
GotoFrame	ActionGotoFrame	Go to the specified frame
GotoLabel	ActionGoToLabel	Go to the frame with the specified label
WaitForFrame	ActionWaitForFrame	Wait for the specified frame
GetURL	ActionGetURL	Get the specified URL
StopSounds	ActionStopSounds	Stop all sounds playing
ToggleQuality	ActionToggleQuality	Toggle the display between high and low quality
SetTarget	ActionSetTarget	Change the context of subsequent actions to a named object

 

An action (or list of actions) can be triggered by a button state transition, or by SWF 3

actions. The action is not executed immediately, but is added to a list of actions to be

processed. The list is executed on a ShowFrame tag, or after the button state has changed. An

action can cause other actions to be triggered, in which case, the action is added to the list of

actions to be processed. Actions are processed until the action list is empty.

By default, Timeline actions such as Stop (see ActionStop), Play (see ActionPlay), and

GoToFrame (see ActionGotoFrame) apply to files that contain them. However, the SetTarget

action (see ActionSetTarget), which is called Tell Target in the Adobe Flash user interface, can

be used to send an action command to another file or sprite (see DefineSprite).

 

行为（或行为列表）可以通过按钮状态转换或 SWF 3 actions 进行触发，行为不是立即被执行，而是被添加到行为列表中执行，行为列表在遇到 ShowFrame tag或按钮状态转换后时执行，这种情况下，被添加到行为列表中待执行的行为会被全部处理直到行为列表为空为止，

默认情况下，时间性行会作用于包含他们的文件，如（Stop, Play, GoToFrame等），SetTarget行为或接口名TellTarget,可以被用来给另一个SWF文件或sprite发送action command.

SWF 3 actions

The actions in this section are available in SWF 3.[行为仅适用于SWF 3版本]

ActionSetTarget

ActionSetTarget instructs Flash Player to change the context of subsequent actions, so they

apply to a named object (TargetName) rather than the current file.

For example, the SetTarget action can be used to control the Timeline of a sprite object. The

following sequence of actions sends a sprite called "spinner" to the first frame in its

Timeline:

1. SetTarget "spinner"

2. GotoFrame zero

3. SetTarget " " (empty string)

4. End of actions. (Action code = 0)

All actions following SetTarget “spinner” apply to the spinner object until SetTarget “”,

which sets the action context back to the current file. For a complete discussion of target

names see DefineSprite.

ActionSetTartget 行为

ActionSetTarget 行为表明Flash Player要去改变后续actions的上下文，因此比较适合应用于named object(TargetName)而不是当前SWF文件。

例如：他和SetTarget action可以用于控制sprite object 的生命线，一下行为流程是将一个叫做spinner的Sprite发送给他生命线的第一帧上。

 

接着SetTarget “spinner”以下的所有行为都将作用于spinner object直到遇到 Set Target “”,  Set Target “”的作用是将行为上下文返回当前文件，对于target names 的详细讨论请参见DefineSprite.

 

SWF 4 action model

The SWF 4 file format supports a greatly enhanced action model that includes an expression

evaluator, variables, conditional branching and looping.

Flash Player 4 incorporates a stack machine that interprets and executes SWF 4 actions. The

key SWF 4 action is ActionPush. This action is used to push one or more parameters onto the

stack. Unlike SWF 3 actions, SWF 4 actions do not have parameters embedded in the tag,

rather they push parameters onto the stack, and pop results off the stack.

The expression evaluator is also stack based. Arithmetic operators include ActionAdd,

ActionSubtract, ActionMultiply, and ActionDivide. The Flash authoring tool converts

expressions to a series of stack operations. For example, the expression 1+x*3 is represented as

the following action sequence:

ActionPush "x"

ActionGetVariable

ActionPush "3"

ActionMultiply

ActionPush "1"

ActionAdd

The result of this expression is on the stack.

SWF 4与之前最大的不同就是可以将参数压入栈，像表达式计算就是基于栈来实现的。

Movie control [移动控制流]

ActionGetProperty

ActionGetProperty does the following:

1. Pops index off the stack.

2. Pops target off the stack.

3. Retrieves the value of the property enumerated as index from the movie clip with target

path target and pushes the value to the stack.

ActionGetProperty按一下方式执行：

1：从栈中弹出索引值

2：从栈中弹出target.

3:根据target path从影片剪辑中以枚举索引值方式来获取相关属性值，并将结果压入栈中。

The following table lists property index values. The _quality, _xmouse, _ymouse and _rotation 10

properties are available in SWF 5 and later.

以下列表中列出了属性索引值，像质量，鼠标x,y坐标及旋转。这些在swf5及后续版本中支持。