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:27, 23 October 2026. Edit this revision | Latest revision

Overview

The TOD format describes a 3D object along the flow of time. It is used with the extended graphics library (libgs).1

For each frame of a 3D animation, a TOD file holds the data for objects that are created, changed or erased.1

The frames are arranged in time order.1

A TOD file has a file header followed by frame data.1

The header is 2 words (64 bits):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 has a frame header followed by packets.2

The frame header is 2 words: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 has a one-word packet header followed by packet data.2

The size of the packet data differs between kinds of packets. It can also differ between packets of the same kind.2

The packet header is as follows:

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. The packet data is applied to that object.3

The packet type gives the kind of data in the packet: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

Packet type 0000 holds the attribute of the GsDOBJ structure. The flag is not used.4

The packet data is 2 words. The first word is a mask, and the second holds the new value.4

In the mask a 0 bit marks an item that changes. A 1 bit marks an item that does not change.4

In the new value the bits of changing items hold the new data. The other bits are 0.4

The bits of the attribute 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

To switch forced light-source calculation on, the mask is 0xffbf and the new value is 0x0040.5

Coordinate (RST)

Packet type 0001 sets the coordinates of the GsDOBJ structure.5

The flag bits are as follows:56

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 packet data holds the R, S and T values whose flags are set. They appear in the order R, S, T.6

The values are as follows:

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)

Each R value takes one word. Sx and Sy share one word, and Sz takes the low half of the next.6

TMD Data ID

Packet type 0010 holds the modeling data ID (TMD data) of the object. The ID is 2 bytes. The flag is not used.6

Parent Object ID

Packet type 0011 holds the ID of the parent object. The ID is 2 bytes. The flag is not used.7

Matrix Value

Packet type 0100 holds the coord members of the GsCOORDINATE2 structure that the GsDOBJ2 structure points to. The flag is not used.7

TMD Data Body

Packet type 0101 holds TMD data. This type is not supported at present.7

Light Source

Packet type 0110 sets a light source. The object ID becomes a light source ID. Light source IDs are separate from the normal object IDs.7

The flag bits are as follows:

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

Each axis of the direction takes one word. The color takes one word.8

Camera

Packet type 0111 sets the viewpoint. The object ID becomes a camera ID. Camera IDs are separate from the normal object IDs.8

Bit 0 of the flag is the camera type. The meaning of the other bits depends on it.8

The flag bits are as follows:

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. TRx, TRy and TRz are the close-up position, and Z is the angle.9

With camera type 1, Rx, Ry and Rz are the rotation. Tx, Ty and Tz are the translation.9

Object Control

Packet type 1000 has no packet data.9

The flag gives the operation:

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

Packet type 1111 controls the animation. The details of these special commands were not final in the manual.9

References

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

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

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

  4. ^ a b c d e 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. ^ a b c d Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-45, Figure 88.

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

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

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

Categories: File formats