TMD (Modeling Data for OS Library): Difference between revisions
| Revision as of 02:27, 23 October 2026 RemmyLee (File format pages from the Sony File Formats manual) | Revision as of 02:47, 23 October 2026 RemmyLee (Formats: Sony paragraph voice; HMD, RSD extended files, full BS code book; sprite editor formats) | ||
| Line 11: | Line 11: | ||
| ## Overview | ## Overview | ||
| − | The TMD format holds 3D modeling data for the PlayStation extended graphics library (libgs).[^ff224] | + | 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](/formats/rsd/) file made by the SCE 3D Graphics Tool or a comparable program.[^ff224] |
| − | TMD data is loaded into memory and passed as an argument to libgs functions.[^ff224] | + | 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.[^ff224] |
| − | The RSDLINK utility creates TMD files. It reads an RSD file made by the SCE 3D Graphics Tool or a comparable program.[^ff224] | ||
| − | |||
| − | A TMD file holds the polygons and lines that make up a 3D object. One TMD file can hold one or more objects.[^ff224] | ||
| − | |||
| ## Coordinate Values | ## Coordinate Values | ||
| − | TMD coordinates follow the 3D coordinate space of the 3D graphics library.[^ff224] | + | 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.[^ff224] |
| − | The positive X axis points right. The positive Y axis points down, and the positive Z axis points into the depth.[^ff224] | + | 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.[^ff224] |
| − | Each spatial coordinate is a signed 16-bit integer from -32768 to +32767.[^ff224] | ||
| − | |||
| − | RSD stores vertices as floating point values. Conversion from RSD to TMD scales the vertex values as needed.[^ff224] | ||
| − | |||
| − | The scale used is stored in the object structure. The current version of libgs ignores it.[^ff224] | ||
| − | |||
| ## File Format | ## File Format | ||
| − | A TMD file has 4 blocks. An object table is followed by three kinds of data: PRIMITIVE, VERTEX and NORMAL.[^ff224] | + | 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.[^ff224] |
| ### Header | ### Header | ||
| − | The header is three words (12 bytes) of data about the structure.[^ff225] | + | The header is three words (12 bytes) of data about the structure of the file:[^ff225] |
| − | The header fields are as follows: | ||
| − | |||
| Table: TMD header | Table: TMD header | ||
| Line 49: | Line 37: | ||
| | NOBJ | Number of objects | | | NOBJ | Number of objects | | ||
| − | FIXP sets whether the pointers in the OBJECT structures are real addresses. 1 is a real address, and 0 is an offset from the start.[^ff225] | + | 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.[^ff225] |
| ### Obj Table | ### Obj Table | ||
| − | The OBJ TABLE is a table of object structures. Each one points to the data of one object.[^ff225] | + | 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:[^ff225] |
| − | The object structure is as follows: | ||
| − | |||
| Table: Object structure | Table: Object structure | ||
| Line 69: | Line 55: | ||
| | scale | long | Scaling factor | | | scale | long | Scaling factor | | ||
| − | With FIXP 1 the three pointers are real addresses. With FIXP 0 they are relative to the top of the OBJECT block.[^ff225] | + | 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.[^ff225] |
| − | The scale value is 2 raised to the scaling factor. A factor of 0 gives 1, a factor of 2 gives 4, and -1 gives 1/2.[^ff226] | + | 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.[^ff226] |
| − | The scale value returns the model to its scale at design time.[^ff226] | ||
| − | |||
| ### Primitive | ### Primitive | ||
| − | The PRIMITIVE section is a list of drawing packets. One packet is one primitive.[^ff226] | + | 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.[^ff226] |
| − | TMD primitives differ from the drawing primitives of libgpu. libgs converts a TMD primitive to a drawing primitive by perspective transformation.[^ff226] | + | Each packet has a variable length, and its size and structure depend on the primitive type. A packet holds the following items:[^ff226][^ff227] |
| − | Each packet has a variable length. Its size and structure depend on the primitive type.[^ff226] | ||
| − | |||
| − | A packet holds the following items: | ||
| − | |||
| Table: Drawing packet items | Table: Drawing packet items | ||
| Line 95: | Line 75: | ||
| | Packet data | Ilen words | Vertex and normal parameters | | | Packet data | Ilen words | Vertex and normal parameters | | ||
| − | The top 3 bits of Mode are CODE. CODE gives the entity type.[^ff226] | + | 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.[^ff226] |
| − | The CODE values are as follows: | ||
| − | |||
| Table: Mode CODE values | Table: Mode CODE values | ||
| Line 107: | Line 85: | ||
| | 011 | Sprite | | | 011 | Sprite | | ||
| − | The Flag bits are as follows:[^ff226] | + | Flag carries option information for rendering:[^ff226][^ff227] |
| Table: Flag bits | Table: Flag bits | ||
| Line 113: | Line 91: | ||
| | Bit | Name | Contents | | | Bit | Name | Contents | | ||
| | --- | --- | --- | | | --- | --- | --- | | ||
| − | | 0 | LGT | 1 no light source calculation, 0 light source calculation | | + | | 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. | | | 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. | | | 2 | GRD | 1 gradation polygon, 0 single-color polygon. Valid only for an untextured polygon with light source calculation. | | ||
| Line 120: | Line 98: | ||
| ### Vertex | ### Vertex | ||
| − | The vertex section is a list of vertex structures.[^ff227] | + | 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:[^ff227] |
| Table: Vertex structure | Table: Vertex structure | ||
| Line 129: | Line 107: | ||
| | 1 | | VZ | | | 1 | | VZ | | ||
| − | VX, VY and VZ are the x, y and z coordinates of the vertex as 16-bit integers.[^ff227] | ||
| − | |||
| ### Normal | ### Normal | ||
| − | The normal section is a list of normal structures.[^ff227] | + | 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.[^ff227] |
| Table: Normal structure | Table: Normal structure | ||
| Line 142: | Line 118: | ||
| | 1 | | NZ | | | 1 | | NZ | | ||
| − | NX, NY and NZ are signed 16-bit fixed-point values in which 4096 is 1.0.[^ff227] | ||
| − | |||
| − | The fixed-point format is as follows: | ||
| − | |||
| Table: Fixed-point format | Table: Fixed-point format | ||
| Line 156: | Line 128: | ||
| ## Packet Data | ## Packet Data | ||
| − | The packet data section holds the following parameters:[^ff228] | + | The packet data section holds the following parameters. Without light source calculation the predetermined brightness must be entered in Rn, Gn and Bn.[^ff228] |
| Table: Packet data parameters | Table: Packet data parameters | ||
| Line 169: | Line 141: | ||
| | CBA | Position of the CLUT in VRAM | | | CBA | Position of the CLUT in VRAM | | ||
| − | Without light source calculation, Rn, Gn and Bn must hold the brightness to draw with.[^ff228] | ||
| − | |||
| ### TSB | ### TSB | ||
| − | TSB holds the texture page and its modes.[^ff228] | + | TSB carries the texture page number and the modes used with it. ABR is valid only when ABE is 1.[^ff228] |
| Table: TSB fields | Table: TSB fields | ||
| Line 180: | Line 150: | ||
| | --- | --- | | | --- | --- | | ||
| | TPAGE | Texture page number (0 to 31) | | | TPAGE | Texture page number (0 to 31) | | ||
| − | | ABR | Semi-transparency rate. Valid only when ABE is 1. | | + | | ABR | Semi-transparency rate (mixture rate) | |
| | TPF | Color mode: 00 4-bit, 01 8-bit, 10 15-bit | | | TPF | Color mode: 00 4-bit, 01 8-bit, 10 15-bit | | ||
| − | The ABR values are as follows:[^ff228] | ||
| − | |||
| Table: ABR semi-transparency rates | Table: ABR semi-transparency rates | ||
| Line 196: | Line 164: | ||
| ### CBA | ### CBA | ||
| − | CBA gives the position of the CLUT in VRAM.[^ff228] | + | 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.[^ff228] |
| Table: CBA fields | Table: CBA fields | ||
| Line 209: | Line 177: | ||
| ### Polygons | ### Polygons | ||
| − | From the MSB, a polygon Mode has the bits 0 0 1 IIP Q TME ABE TGE. Q (bit 3) is set for a 4-vertex polygon.[^ff229][^ff230] | + | 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:[^ff229][^ff230] |
| − | The polygon mode bits are as follows: | ||
| − | |||
| Table: Polygon mode bits | Table: Polygon mode bits | ||
| Line 224: | Line 190: | ||
| | 5..7 | CODE | 001 | | | 5..7 | CODE | 001 | | ||
| − | The manual gives header values for 3-vertex polygons with light source calculation.[^ff230] | + | 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:[^ff230] |
| − | The values are as follows: | ||
| − | |||
| Table: 3-vertex polygon packets with light source calculation | Table: 3-vertex polygon packets with light source calculation | ||
| Line 239: | Line 203: | ||
| | Gouraud, texture | 0x34 | 0x00 | 0x06 | 0x09 | | | Gouraud, texture | 0x34 | 0x00 | 0x06 | 0x09 | | ||
| − | These values are for a single-faced polygon without semi-transparency processing.[^ff230] | + | A packet without light source calculation holds no normals. In this case it holds the color to draw with instead.[^ff232] |
| − | A packet with light source calculation holds a normal for each vertex in Gouraud mode and one normal in flat mode.[^ff230] | ||
| − | |||
| − | A packet without light source calculation holds no normals. It holds the color to draw with.[^ff232] | ||
| − | |||
| ### Straight Line | ### Straight Line | ||
| − | From the MSB, a line Mode has the bits 0 1 0 IIP 0 0 ABE 0.[^ff233] | + | 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:[^ff233][^ff234] |
| − | The line mode bits are as follows: | ||
| − | |||
| − | Table: Straight line mode bits | ||
| − | |||
| − | | Bit | Name | Contents | | ||
| − | | --- | --- | --- | | ||
| − | | 1 | ABE | Translucency processing: 0 off, 1 on | | ||
| − | | 4 | IIP | Gradation: 0 off (monochrome), 1 on | | ||
| − | |||
| − | The manual gives the following line packet headers:[^ff234] | ||
| − | |||
| Table: Straight line packets | Table: Straight line packets | ||
| Line 269: | Line 218: | ||
| ### 3D Sprite | ### 3D Sprite | ||
| − | A 3D sprite has 3D coordinates. It draws the same as a normal sprite.[^ff234] | + | 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:[^ff234] |
| − | From the MSB, the 3D sprite Mode has the fields 0 1 1 SIZ 1 ABE 0.[^ff234] | ||
| − | |||
| − | The SIZ values are as follows: | ||
| − | |||
| Table: 3D sprite SIZ values | Table: 3D sprite SIZ values | ||