psx.wiki

TOD (Animation Data)

Frame-by-frame animation data for 3D objects of the extended graphics library (libgs).

TOD (Animation Data)
Extension.TOD
File ID0x50

This is an old revision of this page, as edited by RemmyLee at 02:47, 23 October 2026. Edit this revision | Latest revision

Overview

The TOD format specifies information along the flow of time for 3D objects, and it corresponds to the extended graphics library (libgs). For each frame of a 3D animation, a TOD file describes the data of the objects that are to be created or modified or erased in that frame. The frames are then arranged in time order, so a TOD file consists of a file header followed by frame data.1

At the top of the TOD file there is a 2-word (64-bit) header, which holds four items. Resolution is the time for which one frame is displayed, and it is counted in ticks of 1/60 second.1

Table 1: TOD file header
Word Bits Field Contents
0 0..7 File ID Identifies an animation file. The value is 0x50.
0 8..15 Version Animation version. The value starts at 0x00.
0 16..31 Resolution Time one frame is displayed, in ticks (1 tick = 1/60 second)
1 0..31 Number of frames Number of frames in the file

Frame

The frames follow the header in time order. Each frame consists of a 2-word frame header followed by its packets:2

Table 2: TOD frame header
Word Bits Field Contents
0 0..15 Frame size Frame length in words, including the header
0 16..31 Number of packets Number of packets
1 0..31 Frame number Frame number

Packet

Each packet consists of a one-word packet header followed by packet data. There are several kinds of packets, and the size of the packet data differs between kinds. Even packets of the same kind can have packet data of different sizes.2

Table 3: TOD packet header
Bits Field Contents
0..15 Object ID The object to be handled
16..19 Packet type The type of packet data
20..23 Flag Meaning depends on the packet type
24..31 Packet length Size of the packet in words (4 bytes), including the header

The object is a 3D object (a GsDOBJ2 structure) of libgs, and the packet data is applied to that object. The packet type gives the classification of the packet data, and the meaning of the flag therefore varies with the packet type:3

Table 4: Packet type values and packet data contents
Packet type Packet data
0000 Attribute
0001 Coordinate (RST)
0010 TMD data ID
0011 Parent object ID
0100 Matrix value
0101 TMD data
0110 Light source
0111 Camera
1000 Object control
1001..1101 User defined
1110 System reserved
1111 Special commands

Packet Data

Attribute

When the packet type is 0000, the packet data sets the attribute of the GsDOBJ structure and the flag is not used. The packet data is 2 words. The first word is a mask in which a 0 bit marks an item that changes and a 1 bit marks an item that does not. The second word holds the new data in the bits of the changing items and 0 in the other bits.4

The default for unchanged bits is therefore 1 in the first word but 0 in the second. The bits of the second word are as follows:45

Table 5: Packet data bit-by-bit breakdown
Bit Item Values
0..2 Material damping 0 to 3: material damping 0 to 3
3 Lighting mode, part 1 0 fog off, 1 fog on
4 Lighting mode, part 2 0 material on, 1 material off
5 Lighting mode, part 3 0 use lighting mode, 1 use default lighting mode
6 Light source 0 light-source calculation off, 1 forced light-source calculation on
7 NearZ overflow handling 0 z overflow clip, 1 z overflow not clip
8 Back clipping status 0 valid, 1 invalid
9..27 Reserved Initialized at 0
28..29 Semi-transparency rate 00 50% back + 50% polygon, 01 100% back + 100% polygon, 10 100% back - 100% polygon, 11 50% back + 25% polygon
30 Semi-transparency 0 off, 1 on
31 Display 0 display, 1 no display

For example, to switch forced light-source calculation on, bit 6 of the first word is 0 and the other bits are 1, so the first word is 0xffbf. Bit 6 of the second word is 1 and the other bits are 0, so the second word is 0x0040.5

The rate for value 11 is "50% back + 25% polygon" in this table, while the TMD section of the manual gives "100% back + 25% polygon".56

Coordinate (RST)

When the packet type is 0001, the packet data sets the coordinates of the GsDOBJ structure. The flag then has the following meaning:57

Table 6: Flag when Coordinate (RST)
Bit Flag Values
0 Matrix type 0 absolute value, 1 differential matrix from the preceding frame
1 Rotation (R) 0 none, 1 has
2 Scaling (S) 0 none, 1 has
3 Translation (T) 0 none, 1 has

The configuration of the packet data depends on the rotation, scaling and translation bits of the flag. The data holds only the values whose flags are set, in the order R, S, T. Each R value takes one word, Sx and Sy share one word and Sz takes the low half of the next, and each T value takes one word.7

Table 7: RST values
Values Contents Format
Rx, Ry, Rz X, Y and Z components of the angle of rotation. One degree is 4096. Fixed point (1, 19, 12)
Sx, Sy, Sz X, Y and Z components of the scaling Fixed point (1, 3, 12)
Tx, Ty, Tz X, Y and Z components of the translation Integer (1, 31, 0)

TMD Data ID and Parent Object ID

When the packet type is 0010, the packet data holds the modeling data ID (TMD data ID) of the real object. When the packet type is 0011, it holds the ID of the parent object. Both IDs are 2 bytes, and in both cases the flag is not used.78

Matrix Value and TMD Data Body

When the packet type is 0100, the packet data holds the coord members of the GsCOORDINATE2 structure that the GsDOBJ2 structure points to, and the flag is not used. Packet type 0101 holds TMD data. However, this type is not supported at present.8

Light Source

When the packet type is 0110, the packet data sets a light source. In this case the object ID becomes a light source ID that is separate from the normal object IDs. The flag has the following meaning:8

Table 8: Flag when Light Source Packet
Bit Flag Values
0 Data type 0 absolute value, 1 difference from the preceding frame
1 Direction 0 none, 1 has
2 Color 0 none, 1 has

The configuration of the packet data depends on the direction and color bits. The direction takes three words for X, Y and Z, and the color takes one word with B, G and R.89

Camera

When the packet type is 0111, the packet data sets the viewpoint, and the object ID becomes a camera ID that is separate from the normal object IDs. Bit 0 of the flag is the camera type. Care is needed because the meaning of the other bits changes with this bit:9

Table 9: Flag for Camera
Bit Camera type 0 Camera type 1
1 Data type: 0 absolute, 1 difference from the preceding frame Data type: 0 absolute, 1 difference from the preceding frame
2 Position and reference position: 0 none, 1 has Rotation (R): 0 none, 1 has
3 Reference angle (z angle): 0 none, 1 has Translation (T): 0 none, 1 has

With camera type 0, Tx, Ty and Tz are the camera position and TRx, TRy and TRz are the close-up position, and Z is the angle. With camera type 1, Rx, Ry and Rz are the rotation and Tx, Ty and Tz are the translation.10

Object Control

When the packet type is 1000 there is no packet data, and the flag gives the operation:10

Table 10: Flag for Object Control
Flag Meaning
0 Create
1 Kill
0010..1111 System reserved

Extended and Special Commands

Packet type 1110 holds extended commands. Packet type 1111 performs animation control, but the details of these special commands had not been finalized when the manual was published.10

References

  1. ^ a b Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-40, Figure 81.

  2. ^ a b Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-41, Figure 82.

  3. ^ Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-42, Figures 83 and 84.

  4. ^ a b Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-43, Figure 85 and Table 2-3.

  5. ^ a b c d Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-44, Figures 86 and 87.

  6. ^ Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-28, Figure 63.

  7. ^ a b c Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-45, Figure 88.

  8. ^ a b c d Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-46, Figures 89 to 92.

  9. ^ a b Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-47, Figures 93 and 94.

  10. ^ a b c Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-48, Figures 95 to 97.

Categories: File formats