psx.wiki

TMD (Modeling Data for OS Library)

3D modeling data for the extended graphics library (libgs).

TMD (Modeling Data for OS Library)
Extension.TMD
ID0x00000041
Created byRSDLINK

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 TMD format contains 3D modeling data that is compatible with the PlayStation extended graphics library (libgs). TMD data is loaded into memory and passed as an argument to the functions of libgs. TMD files are created by the RSDLINK utility, which reads an RSD file made by the SCE 3D Graphics Tool or a comparable program.1

The data in a TMD file is a set of graphics primitives, such as polygons and lines, that make up a 3D object. A single TMD file can contain one or more 3D objects.1

Coordinate Values

Coordinate values in a TMD file follow the 3D coordinate space of the 3D graphics library. The positive X axis points right, the positive Y axis points down and the positive Z axis points into the depth. Each spatial coordinate is a signed 16-bit integer from -32768 to +32767.1

At design time and in the RSD format, vertices are stored as floating point values. Conversion from RSD to TMD therefore converts and scales the vertex values as needed, and the scale used is recorded in the object structure. This value can serve as an index for mapping from object to world coordinates. However, the current version of libgs ignores it.1

File Format

A TMD file has 4 blocks. A table of 3D objects is followed by the three kinds of data that make up the objects: PRIMITIVE, VERTEX and NORMAL.1

The header is three words (12 bytes) of data about the structure of the file:2

Table 1: TMD header
Field Contents
ID Version of the TMD file, 32 bits. The current version is 0x00000041.
FLAGS 32 bits. Bit 0 is FIXP. The other bits are reserved and zero.
NOBJ Number of objects

The FIXP bit shows whether the pointers in the OBJECT structures are real addresses. A value of 1 means a real address, and a value of 0 means an offset from the start.2

Obj Table

The OBJ TABLE is a table of structures, each of which points to the place where the data of one object is stored. The object structure has the following configuration:2

Table 2: Object structure
Member Type Contents
vert_top u_long * Start address of the vertices
n_vert u_long Number of vertices
normal_top u_long * Start address of the normals
n_normal u_long Number of normals
primitive_top u_long * Start address of the primitives
n_primitive u_long Number of primitives
scale long Scaling factor

The meaning of the three pointers depends on the FIXP bit in the header. If FIXP is 1 they are actual addresses, and if FIXP is 0 they are relative addresses that take the top of the OBJECT block as address 0.2

The scaling factor is a signed long, and the scale value is 2 raised to its power. A factor of 0 therefore gives a scale of 1, a factor of 2 gives 4 and a factor of -1 gives 1/2. With this value the model can be returned to its scale at design time.3

Primitive

The PRIMITIVE section is an arrangement of drawing packets in which one packet stands for one primitive of the object. TMD primitives differ from the drawing primitives handled by libgpu. A TMD primitive is converted to a drawing primitive by the perspective transformation that libgs performs.3

Each packet has a variable length, and its size and structure depend on the primitive type. A packet holds the following items:34

Table 3: Drawing packet items
Item Size Contents
Mode 8 bits Type of primitive and its attributes
Flag 8 bits Options for rendering
Ilen 8 bits Length of the packet data section in words
Olen 8 bits Word length of the 2D drawing primitive made by intermediate processing
Packet data Ilen words Vertex and normal parameters

The top 3 bits of Mode are CODE, which gives the kind of entity. The other bits of Mode depend on CODE and are listed with the packet configurations below.3

Table 4: Mode CODE values
CODE Primitive
001 Polygon (triangle, quadrilateral)
010 Straight line
011 Sprite

Flag carries option information for rendering:34

Table 5: Flag bits
Bit Name Contents
0 LGT 1 light source calculation not carried out, 0 light source calculation carried out
1 FCE 1 double-faced polygon, 0 single-faced polygon. Valid only for polygons.
2 GRD 1 gradation polygon, 0 single-color polygon. Valid only for an untextured polygon with light source calculation.
3..7 0

Vertex

The vertex section is a set of vertex structures. In each structure VX, VY and VZ are the x, y and z coordinates of the vertex as 16-bit integers:4

Table 6: Vertex structure
Word Upper 16 bits Lower 16 bits
0 VY VX
1 VZ

Normal

The normal section is a set of normal structures with the same layout. NX, NY and NZ are signed 16-bit fixed-point values in which 4096 is 1.0, so a normal component has 1 sign bit, 3 integer bits and 12 fraction bits.4

Table 7: Normal structure
Word Upper 16 bits Lower 16 bits
0 NY NX
1 NZ
Table 8: Fixed-point format
Bits Part
15 Sign (1 bit)
12..14 Integral part (3 bits)
0..11 Decimal part (12 bits)

Packet Data

The packet data section holds the following parameters. Without light source calculation the predetermined brightness must be entered in Rn, Gn and Bn.5

Table 9: Packet data parameters
Parameter Contents
Vertex(n) 16-bit index of a vertex, counted from the start of the object's vertex section
Normal(n) 16-bit index of a normal, counted in the same way
Un, Vn X and Y coordinates of each vertex in the texture source space
Rn, Gn, Bn Polygon color as unsigned 8-bit integers
TSB Texture page and sprite pattern information
CBA Position of the CLUT in VRAM

TSB

TSB carries the texture page number and the modes used with it. ABR is valid only when ABE is 1.5

Table 10: TSB fields
Field Contents
TPAGE Texture page number (0 to 31)
ABR Semi-transparency rate (mixture rate)
TPF Color mode: 00 4-bit, 01 8-bit, 10 15-bit
Table 11: ABR semi-transparency rates
ABR Mixture
00 50% back + 50% polygon
01 100% back + 100% polygon
10 100% back - 100% polygon
11 100% back + 25% polygon

CBA

CBA gives the position where the CLUT is stored in VRAM. CLX holds only the upper 6 bits of the 10-bit X coordinate, so a CLUT starts on a multiple of 16 pixels in X.5

Table 12: CBA fields
Bits Field Contents
0..5 CLX Upper 6 bits of the 10-bit X coordinate of the CLUT
6..14 CLY 9-bit Y coordinate of the CLUT

Primitive Types

Polygons

From the MSB, the Mode of a polygon has the bits 0 0 1 IIP Q TME ABE TGE, where bit 3 (Q) is set for a 4-vertex polygon. The other bits select shading, texture and translucency as follows:67

Table 13: Polygon mode bits
Bit Name Contents
0 TGE Brightness calculation at texture mapping: 0 on, 1 off (draws the texture as is)
1 ABE Translucency processing: 0 off, 1 on
2 TME Texture: 0 off, 1 on
3 1 for a 4-vertex primitive
4 IIP Shading mode: 0 flat, 1 Gouraud
5..7 CODE 001

A packet with light source calculation holds one normal in flat mode and a normal for each vertex in Gouraud mode. The manual gives the following header values for a single-faced 3-vertex polygon without semi-transparency processing:7

Table 14: 3-vertex polygon packets with light source calculation
Packet Mode Flag Ilen Olen
Flat, no texture (solid) 0x20 0x00 0x03 0x04
Gouraud, no texture (solid) 0x30 0x00 0x04 0x06
Flat, no texture (gradation) 0x20 0x04 0x05 0x06
Gouraud, no texture (gradation) 0x30 0x04 0x06 0x06
Flat, texture 0x24 0x00 0x05 0x07
Gouraud, texture 0x34 0x00 0x06 0x09

A packet without light source calculation holds no normals. In this case it holds the color to draw with instead.8

Straight Line

From the MSB, the Mode of a straight line has the bits 0 1 0 IIP 0 0 ABE 0. IIP turns gradation on and ABE turns translucency processing on. The manual gives the following line packet headers:910

Table 15: Straight line packets
Packet Mode Flag Ilen Olen
Gradation off 0x40 0x01 0x02 0x03
Gradation on 0x50 0x01 0x03 0x04

3D Sprite

A 3D sprite is a sprite with 3D coordinates, and its drawing content is the same as a normal sprite. From the MSB its Mode has the fields 0 1 1 SIZ 1 ABE 0, where SIZ sets the sprite size:10

Table 16: 3D sprite SIZ values
SIZ Sprite size
00 Free size (specified by W, H)
01 1 x 1
10 8 x 8
11 16 x 16

References

  1. ^ a b c d e Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-24.

  2. ^ a b c d Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-25, Figures 55 and 56.

  3. ^ a b c d e Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-26, Figures 58 and 59.

  4. ^ a b c d Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-27, Figures 60 to 62.

  5. ^ a b c Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-28, Figures 63 and 64.

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

  7. ^ a b Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-30, Figures 66 and 67.

  8. ^ Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-32, Figure 70.

  9. ^ Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-33, Figure 73.

  10. ^ a b Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-34, Figures 74 and 75.

Categories: File formats