psx.wiki

HMD (Hierarchical 3D Model and Animation Data): Difference between revisions

Revision as of 02:46, 23 October 2026
RemmyLee
(SPU and CD-ROM at register depth; CPU overview rewritten)		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
−HMD is a generic graphics format. Model data, texture data and animation data are handled within one framework.[^ff249]+HMD is a generic graphics format in which model data, texture data and animation data are handled within one integrated framework. It can be extended to new kinds of data through a unique identification code known as a type. A program that plays back HMD data is called a primitive driver, and primitive drivers are linked to HMD data through their type. Sony Computer Entertainment made a set of standard primitive drivers for libgs with standardized interfaces, so users and middleware companies can also build their own.[^ff249]
−HMD is extended to new kinds of data through a unique identification code called a type.[^ff249]+The HMD format is supported by Library Version 4.0 and later. Up to library 4.2 the HMD functions were part of libgs and libgte. They have since been removed from those libraries and their header files, and the HMD library (libhmd) with libhmd.h should now be used. The environment map is only a beta version in this release, because later releases may change its format.[^ff249]
−A program that plays back HMD data is called a primitive driver. Primitive drivers are linked to HMD data through their type.[^ff249]
−
−Sony Computer Entertainment made a set of standard primitive drivers for libgs. The drivers have standard interfaces, so users and middleware companies can write their own.[^ff249]
−
−The HMD format is supported by Library Version 4.0 and later.[^ff249]
−
−Up to library 4.2 the HMD functions were part of libgs and libgte. They are now in the separate library libhmd. Its header file is libhmd.h.[^ff249]
−
−The environment map was a beta version in this release. Its format could change.[^ff249]
−
## Structure## Structure
−HMD data has two main parts:[^ff249]+HMD data is divided into the HMD header and the HMD body, and the body is made up of areas known as sections. The primitive section and the primitive header section are always required. Other sections are included only when the type needs them. A model, for example, also has a coordinate section.[^ff249][^ff250]
−- The HMD header+Pointer values in HMD data are converted at run time into real addresses in memory. This process is known as mapping and is performed by GsMapUnit(), and HMD data can be used only after its addresses are mapped. Before mapping, the value of a pointer is the number of 32-bit words from the top of the HMD data.[^ff250]
−- The HMD body
−The HMD body is made of sections. The primitive section and the primitive header section are always required.[^ff249]
−
−Other sections are present only when the type needs them. A model can also have a coordinate section.[^ff249][^ff250]
−
−### Pointers
−
−Pointer values are converted into real memory addresses at run time. This step is called mapping, and GsMapUnit() performs it.[^ff250]
−
−HMD data can be used only after its addresses are mapped.[^ff250]
−
−The initial value of a pointer is a count of 32-bit words from the top of the HMD data.[^ff250]
−
### HMD Header### HMD Header
−The HMD header holds the following fields:[^ff250][^ff251]+The HMD header contains the version ID, MAP FLAG, the pointer to the primitive header section and the number of primitive blocks. A list of pointers to the primitive blocks follows. In model data there is one block for each coordinate, and there is also a PRE-PROCESS block and a POST-PROCESS block. The block count is therefore the number of coordinates + 2.[^ff250][^ff251][^ff257]
Table: HMD header sectionTable: HMD header section
Line 53:Line 30:
| --- | --- || --- | --- |
| Version ID | 0x00000050 || Version ID | 0x00000050 |
−| MAP FLAG | 1 after GsMapUnit() has mapped the data, otherwise 0 |+| MAP FLAG | Shows whether GsMapUnit() has mapped the data. GsMapUnit() reads and changes this field. |
−| Primitive header section pointer | Start of the primitive header section |+| Primitive header section pointer | Start of the primitive header section. The MSB is 1 after the section has been mapped. |
| Number of blocks | Number of primitive block pointers || Number of blocks | Number of primitive block pointers |
| Pointer to the primitive block 0..n | One pointer for each primitive block || Pointer to the primitive block 0..n | One pointer for each primitive block |
−GsMapUnit() reads and changes MAP FLAG.[^ff251]+Page 2-51 gives MAP FLAG as 1 when mapped and 0 otherwise, while page 2-57 gives 0x00000000 when mapped and 0x00000001 when unmapped.[^ff251][^ff257]
−## Primitives+The first block is used for PRE-PROCESS and has no coordinate, and the last block is used for POST-PROCESS. The blocks between them correspond to the coordinates in order:[^ff257]
−The primitive section is a collection of primitive blocks.[^ff251]+Table: Primitive pointer table
−A primitive block is a chain of one or more primitives. Pointers join the primitives of the chain.[^ff251]+| Block | Coordinate | Primitive | Process |
+| --- | --- | --- | --- |
+| BLOCK 0 | | PRIM 0 | PRE-PROCESS |
+| BLOCK 1 | COORDINATE0 | PRIM 1 | Block 1 process |
+| BLOCK 2 | COORDINATE1 | PRIM 2 | Block 2 process |
+| BLOCK N | COORDINATE N-1 | PRIM N | Block N process |
+| BLOCK N+1 | | PRIM N+1 | POST-PROCESS |
−A primitive has a control section and one or more data sections.[^ff251]+### Coordinate Section
−The parts are as follows:+The coordinate section contains the coordinate system data for each block. Its first word is the number of coordinates, and each coordinate is in GsCOORDUNIT format. The rot and matrix members must be kept consistent when HMD data is constructed.[^ff258]
+Table: GsCOORDUNIT
+
+| Member | Type |
+| --- | --- |
+| flg | unsigned long |
+| matrix | MATRIX |
+| workm | MATRIX |
+| rot | SVECTOR |
+| super | struct GsCOORDUNIT * |
+
+## Primitives
+
+The primitive section is a collection of primitive blocks, and a primitive block is a chain of one or more primitives joined by pointers. A primitive consists of a control section and one or more data sections. The parts are as follows:[^ff251][^ff252]
+
Table: Primitive structureTable: Primitive structure
| Part | Field | Contents || Part | Field | Contents |
| --- | --- | --- || --- | --- | --- |
−| Control section | Next Prim pointer | Header of the next primitive in the chain. 0xFFFFFFFF ends the chain. |+| Control section | Next Prim pointer | Header of the next primitive in the chain. 0xFFFFFFFF marks the last primitive. |
| Control section | Primitive header pointer | The primitive header of this primitive || Control section | Primitive header pointer | The primitive header of this primitive |
| Control section | Type count | Number of data sections. The MSB is 1 while the pointers are unmapped and 0 after mapping. || Control section | Type count | Number of data sections. The MSB is 1 while the pointers are unmapped and 0 after mapping. |
Line 81:Line 78:
| Data section | Data | The data, in a format set by type || Data section | Data | The data, in a format set by type |
+A single type generally processes several sets of data, so the data count gives the number of times the processing is repeated. In a polygon primitive the MSB of the count shows whether a SCAN has been performed.[^ff252][^ff259]
+
### SCAN### SCAN
−A SCAN overwrites each type field with the start address of its primitive driver.[^ff252]+The primitive driver is identified by the type field, which is overwritten with the starting address of the driver. This process is known as a SCAN. GsScanUnit() extracts the address and value of the type field of each primitive, and the starting address of the driver can then be written into the field. Because each type is unique within HMD, changing the value of type also changes the contents of the data and its driver.[^ff252]
−GsScanUnit() finds the address and value of the type field of each primitive. The driver address can then be written into the type field.[^ff252]
−
−Changing the value of type changes the meaning of the data and its driver.[^ff252]
−
### Primitive Header### Primitive Header
−The primitive headers are grouped in the primitive header section. The HMD header points to that section.[^ff252]+The primitive headers are grouped together in the primitive header section, and a pointer to that section is saved in the HMD header. There is one primitive header for each primitive block. Its first word is its size in words, and the pointers to the sections that the block refers to follow.[^ff252]
−There is one primitive header for each primitive block. Its first word is its size in words, and pointers to the sections follow.[^ff252]+A word with the MSB set to 1 is a pointer to a section. A word with the MSB 0 is interpreted as a numeric value. These unmapped values can therefore be used as parameters for a primitive driver.[^ff252][^ff258]
−A word with the MSB set is a pointer to a section.[^ff252]+When a primitive driver is called, GsSortUnit() copies the primitive header into a variable transfer area, which also holds the OT and packet area values. The driver can therefore reach the vertex and normal sections through the pointers in the copied header:[^ff258]
−A word with the MSB clear is a numeric value. It can serve as a parameter to the primitive driver.[^ff252]+Table: Variable transfer area
+| Item |
+| --- |
+| primtop |
+| Tag (OT) |
+| Shift (OT) |
+| Offset (OT) |
+| OUTP (packet area) |
+| Primitive header |
+
## Type Field## Type Field
−The type field is 32 bits in four parts:[^ff260][^ff2131]+The type field is 32 bits in four parts, and its upper 8 bits contain data that is common to all categories:[^ff260][^ff2131]
Table: Type fieldTable: Type field
Line 112:Line 116:
| 0..15 | PRIMITIVE TYPE | Bit assignment depends on the primitive type || 0..15 | PRIMITIVE TYPE | Bit assignment depends on the primitive type |
−A developer with a unique ID can use the other bits freely.[^ff260]+A total of 16 developer IDs are available. A developer whose ID is unique may use the other bits freely. The 16 categories include the following:[^ff260][^ff2128][^ff2131]
−The categories are as follows:[^ff260][^ff2128][^ff2131]
−
Table: HMD categoriesTable: HMD categories
Line 129:Line 131:
| 7 | Device primitives (camera and light) || 7 | Device primitives (camera and light) |
−The manual gives the type 0x00100008 as an example. It is developer SCE, category CTG_POLY, driver bit BOT (double-sided) and primitive type TRI (triangle).[^ff2131]+The manual writes types in HMD assembler (labp) format. In its example DEV_ID(SCE)|CTG(CTG_POLY)|DRV(BOT)|PRIM_TYPE(TRI) is the bit pattern 0x00100008. This type is a double-sided triangle of the standard driver. The name of the driver function is "GsU_" followed by the bit pattern. The list of installed primitive drivers is a spreadsheet in the HMD chapter of the Library Overview.[^ff2131]
−The name of the driver function is "GsU_" followed by the bit pattern.[^ff2131]+## Polygon Data (Category 0)
−## Categories+Model data must contain the HMD header, primitive header, coordinate, primitive, polygon and vertex sections, and it can also contain normal and image sections. Model data consists of several coordinate systems, and each coordinate system is assigned to its own primitive block. For model data the first primitive of a block is used for non-shared vertex data and the next for shared vertex data.[^ff253][^ff259]
−### Model Data (Category 0)+### Polygon Primitive
−Model data must have the HMD header, primitive header, coordinate, primitive, polygon and vertex sections. It can also have normal and image sections.[^ff253]+The first three words of a polygon primitive are the control section. The data section is organized in three-word units of a type field, the polygon count and size, and POLYGON IDX, which points to the polygon data. The upper 8 bits of POLYGON IDX can serve as a parameter for the primitive driver. In the current implementation they hold the number of polygon divisions for the DIV and ADV driver bits. The allowed values are GsUNIT_DIV1 to GsUNIT_DIV5 in libgs.h. Other values should not be used, and a value of 0 stops the driver from functioning.[^ff259]
−Each coordinate system of a model is assigned to its own primitive block.[^ff253]+The DRIVER bits of a polygon primitive change the behavior of its driver. For example, they can enable polygon subdivision:[^ff261][^ff2131]
−The DIV bit of the polygon driver enables polygon subdivision. The FOG bit turns fog on.[^ff261]+Table: Polygon primitive DRIVER bits
−### Shared Primitives (Category 1)+| Bit | Name | Contents |
+| --- | --- | --- |
+| 16 | DIV | 0 disable subdivision, 1 perform subdivision |
+| 17 | FOG | 0 fog off, 1 fog on |
+| 18 | LGT | 0 perform light-source calculation, 1 disable light-source calculation |
+| 19 | ADV | 0 no automatic division, 1 perform automatic division |
+| 20 | BOT | 0 single-sided polygon, 1 double-sided polygon |
+| 21 | STP | 0 keep the semi-transparency of each polygon, 1 make all polygons semi-transparent |
+| Upper | INI | 0 do not initialize, 1 initialize |
−Shared primitives use two kinds of driver: PRE-CALCULATION drivers and shared drivers.[^ff290]+The type values of the manual place LGT at bit 18 and BOT at bit 20, and the other positions follow the order of Figure 108. When INI is set, an initialization function sets up the environment before the SCAN is performed. The PRIMITIVE TYPE bits describe the polygon:[^ff261][^ff262]
−A PRE-CALCULATION driver converts a 3D shared vertex array into a perspective-transformed 2D vertex array. For normals it calculates vertex colors.[^ff290]+Table: Polygon PRIMITIVE TYPE bits
−A shared driver takes the calculated vertices and builds GPU packets into the OT. It is chained to the POST-PROCESS primitive block so that it runs last.[^ff290]+| Bit | Name | Contents |
+| --- | --- | --- |
+| 0 | TME | 0 no texture mapping, 1 texture mapping |
+| 1 | COL | 0 one material color for identical polygons, 1 a separate color for each vertex |
+| 2 | IIP | 0 flat-shaded polygon, 1 Gouraud-shaded polygon |
+| 3..5 | CODE | Shape: 1 triangle, 2 quadrangle, 3 strip mesh. 0 and 4 to 7 are reserved. |
+| 6 | LMD | 0 has normals, 1 has no normals |
+| 7 | MIP | MIP-mapping (not implemented) |
+| 8 | PST | 0 no presets, 1 preset packet available |
+| 9 | TILE | 0 no tiled texture information, 1 tiled texture information |
−### Image Data (Category 2)+The bit positions above follow from the type values in the table of polygon types below. The PRIMITIVE TYPE figure also lists MIMe (0 normal polygon, 1 MIMe polygon), which is not implemented.[^ff262][^ff263]
−HMD can hold image data as a primitive. Model, image and animation data can then be managed together.[^ff292]+### Polygon Section
−Image data can also stay outside HMD in [TIM](/formats/tim/) files.[^ff293]+The polygon section holds the polygon connection information as PACKETs, which are classified by type. A PACKET refers to its NORMAL and VERTEX data by index and holds RGB values directly. For a MESH, the first num field gives the number of connections. The symbols are the same as in [TMD](/formats/tmd/). The flat no-texture triangle, type 0x00000008, has the following PACKET:[^ff263]
−### Animation Data (Category 3)+Table: Flat no-texture triangle PACKET
−An animation primitive section has five subsections:[^ff295]+| Word | Contents |
+| --- | --- |
+| 0 | B(r) B(g) B(b) B(0x20) |
+| 1 | H(norm0) H(vert0) |
+| 2 | H(vert1) H(vert2) |
−- Animation primitive header section+A packet for tiled textures has a repetition parameter at its beginning and a reset parameter at its end, so tiled and non-tiled textures can coexist. TUM and TVM are 5-bit tiling masks for U and V, and TUA and TVA are the 5-bit upper addresses of U and V. At reset all four are zero. The manual lists the following polygon types:[^ff274][^ff263]
−- Sequence pointer section
−- Interpolation function table section
−- Sequence control section
−- Parameter section
−### MIMe Data (Category 4)+Table: HMD polygon primitive types
−The MIMe primitive is described in the libgs reference. The MIMe types are joint MIMe and vertex or normal MIMe. Each type also has a reset form.[^ff2118]+| Group | Polygon | type | DRV | PRIM_TYPE | Driver |
+| --- | --- | --- | --- | --- | --- |
+| With light-source calculation | Flat No-Texture Triangle | 0x00000008 | 0 | TRI | GsUF3 |
+| With light-source calculation | Gouraud No-Texture Triangle | 0x0000000c | 0 | TRI IIP | GsUG3 |
+| With light-source calculation | Colored Flat No-Texture Triangle | 0x0000000a | 0 | TRI COL | GsUCF3 |
+| With light-source calculation | Colored Gouraud No-Texture Triangle | 0x0000000e | 0 | TRI IIP COL | GsUCG3 |
+| With light-source calculation | Flat Texture Triangle | 0x00000009 | 0 | TRI TME | GsUFT3 |
+| With light-source calculation | Gouraud Texture Triangle | 0x0000000d | 0 | TRI IIP TME | GsUGT3 |
+| With light-source calculation | Colored Flat Texture Triangle | 0x0000000b | 0 | TRI COL TME | GsUCFT3 |
+| With light-source calculation | Colored Gouraud Texture Triangle | 0x0000000f | 0 | TRI IIP COL TME | GsUCGT3 |
+| With light-source calculation | Flat No-Texture Quad | 0x00000010 | 0 | QUAD | GsUF4 |
+| With light-source calculation | Gouraud No-Texture Quad | 0x00000014 | 0 | QUAD IIP | GsUG4 |
+| With light-source calculation | Colored Flat No-Texture Quad | 0x00000012 | 0 | QUAD COL | GsUCF4 |
+| With light-source calculation | Colored Gouraud No-Texture Quad | 0x00000016 | 0 | QUAD IIP COL | GsUCG4 |
+| With light-source calculation | Flat Texture Quad | 0x00000011 | 0 | QUAD TME | GsUFT4 |
+| With light-source calculation | Gouraud Texture Quad | 0x00000015 | 0 | QUAD IIP TME | GsUGT4 |
+| With light-source calculation | Colored Flat Texture Quad | 0x00000013 | 0 | QUAD COL TME | GsUCFT4 |
+| With light-source calculation | Colored Gouraud Texture Quad | 0x00000017 | 0 | QUAD IIP COL TME | GsUCGT4 |
+| With light-source calculation | Flat No-Texture Mesh | 0x00000018 | 0 | MESH | GsUMF3 |
+| With light-source calculation | Gouraud No-Texture Mesh | 0x0000001c | 0 | MESH IIP | GsUMG3 |
+| With light-source calculation | Colored Flat No-Texture Mesh | 0x0000001a | 0 | MESH COL | |
+| With light-source calculation | Colored Gouraud No-Texture Mesh | 0x0000001e | 0 | MESH IIP COL | |
+| With light-source calculation | Flat Texture Mesh | 0x00000019 | 0 | MESH TME | GsUMFT3 |
+| With light-source calculation | Gouraud Texture Mesh | 0x0000001d | 0 | MESH IIP TME | GsUMGT3 |
+| With light-source calculation | Colored Flat Texture Mesh | 0x0000001b | 0 | MESH COL TME | |
+| With light-source calculation | Colored Gouraud Texture Mesh | 0x0000001f | 0 | MESH IIP COL TME | |
+| Without light-source calculation (model data without normals) | Flat No-Texture Triangle | 0x00040048 | LGT | LMD TRI | GsUNF3 |
+| Without light-source calculation (model data without normals) | Gouraud No-Texture Triangle | 0x0004004c | LGT | LMD TRI IIP | GsUNG3 |
+| Without light-source calculation (model data without normals) | Flat Texture Triangle | 0x00040049 | LGT | LMD TRI TME | GsUNFT3 |
+| Without light-source calculation (model data without normals) | Gouraud Texture Triangle | 0x0004004d | LGT | LMD TRI IIP TME | GsUNGT3 |
+| Without light-source calculation (model data without normals) | Flat No-Texture Quad | 0x00040050 | LGT | LMD QUAD | GsUNF4 |
+| Without light-source calculation (model data without normals) | Gouraud No-Texture Quad | 0x00040054 | LGT | LMD QUAD IIP | GsUNG4 |
+| Without light-source calculation (model data without normals) | Flat Texture Quad | 0x00040051 | LGT | LMD QUAD TME | GsUNFT4 |
+| Without light-source calculation (model data without normals) | Gouraud Texture Quad | 0x00040055 | LGT | LMD QUAD IIP TME | GsUNGT4 |
+| Without light-source calculation (model data without normals) | Flat No-Texture Mesh | 0x00040058 | LGT | LMD MESH | GsUMNF3 |
+| Without light-source calculation (model data without normals) | Gouraud No-Texture Mesh | 0x0004005c | LGT | LMD MESH IIP | GsUMNG3 |
+| Without light-source calculation (model data without normals) | Flat Texture Mesh | 0x00040059 | LGT | LMD MESH TME | GsUMNFT3 |
+| Without light-source calculation (model data without normals) | Gouraud Texture Mesh | 0x0004005d | LGT | LMD MESH IIP TME | GsUMNGT3 |
+| Tiled textures with light-source calculation | Flat Texture Triangle | 0x00000209 | 0 | TILE TRI TME | GsUTFT3 |
+| Tiled textures with light-source calculation | Gouraud Texture Triangle | 0x0000020d | 0 | TILE TRI IIP TME | GsUTGT3 |
+| Tiled textures with light-source calculation | Colored Flat Texture Triangle | 0x0000020b | 0 | TILE TRI COL TME | |
+| Tiled textures with light-source calculation | Colored Gouraud Texture Triangle | 0x0000020f | 0 | TILE TRI IIP COL TME | |
+| Tiled textures with light-source calculation | Flat Texture Quad | 0x00000211 | 0 | TILE QUAD TME | GsUTFT4 |
+| Tiled textures with light-source calculation | Gouraud Texture Quad | 0x00000215 | 0 | TILE QUAD IIP TME | GsUTGT4 |
+| Tiled textures with light-source calculation | Colored Flat Texture Quad | 0x00000213 | 0 | TILE QUAD COL TME | |
+| Tiled textures with light-source calculation | Colored Gouraud Texture Quad | 0x00000217 | 0 | TILE QUAD IIP COL TME | |
+| Tiled textures with light-source calculation | Flat Texture Mesh | 0x00000219 | 0 | TILE MESH TME | |
+| Tiled textures with light-source calculation | Gouraud Texture Mesh | 0x0000021d | 0 | TILE MESH IIP TME | |
+| Tiled textures with light-source calculation | Colored Flat Texture Mesh | 0x0000021b | 0 | TILE MESH COL TME | |
+| Tiled textures with light-source calculation | Colored Gouraud Texture Mesh | 0x0000021f | 0 | TILE MESH IIP COL TME | |
+| Tiled textures without light-source calculation | Flat Texture Triangle | 0x00040249 | LGT | TILE LMD TRI TME | |
+| Tiled textures without light-source calculation | Gouraud Texture Triangle | 0x0004024d | LGT | TILE LMD TRI IIP TME | |
+| Tiled textures without light-source calculation | Flat Texture Quad | 0x00040251 | LGT | TILE LMD QUAD TME | |
+| Tiled textures without light-source calculation | Gouraud Texture Quad | 0x00040255 | LGT | TILE LMD QUAD IIP TME | |
+| Tiled textures without light-source calculation | Flat Texture Mesh | 0x00040259 | LGT | TILE LMD MESH TME | |
+| Tiled textures without light-source calculation | Gouraud Texture Mesh | 0x0004025d | LGT | TILE LMD MESH IIP TME | |
+| Preset model data | Flat No-Texture Triangle | 0x00040148 | LGT | PST LMD TRI | GsUPNF3 |
+| Preset model data | Gouraud No-Texture Triangle | 0x0004014c | LGT | PST LMD TRI IIP | GsUPNG3 |
+| Preset model data | Flat Texture Triangle | 0x00040149 | LGT | PST LMD TRI TME | GsUPNFT3 |
+| Preset model data | Gouraud Texture Triangle | 0x0004014d | LGT | PST LMD TRI IIP TME | GsUNGT3 |
+| Preset model data | Flat No-Texture Quad | 0x00040150 | LGT | PST LMD QUAD | GsUPNF4 |
+| Preset model data | Gouraud No-Texture Quad | 0x00040154 | LGT | PST LMD QUAD IIP | GsUPNG4 |
+| Preset model data | Flat Texture Quad | 0x00040151 | LGT | PST LMD QUAD TME | GsUPNFT4 |
+| Preset model data | Gouraud Texture Quad | 0x00040155 | LGT | PST LMD QUAD IIP TME | GsUPNGT4 |
+| Preset model data | Flat No-Texture Mesh | 0x00040158 | LGT | PST LMD MESH | |
+| Preset model data | Gouraud No-Texture Mesh | 0x0004015c | LGT | PST LMD MESH IIP | |
+| Preset model data | Flat Texture Mesh | 0x00040159 | LGT | PST LMD MESH TME | |
+| Preset model data | Gouraud Texture Mesh | 0x0004015d | LGT | PST LMD MESH IIP TME | |
−### Ground Data (Category 5)+In the preset model data the packet holds a DMAtag and the screen coordinates for two packets ahead of the vertex indexes.[^ff282]
−A ground primitive generates packets at run time from the width and height of a grid and the number of grids.[^ff2125]+### Vertex and Normal Sections
−This method reduces the amount of HMD data.[^ff2125]+The VERTEX and NORMAL sections place the non-shared and shared and calculated-shared entries one after another. A non-shared primitive can therefore also reach a shared vertex.[^ff256]
−### Device Primitives (Category 7)+## Shared Primitives (Category 1)
−Device primitives hold camera (viewpoint) and light (light source) settings that applications used to make in code.[^ff2128]+Shared primitives use two kinds of primitive driver: PRE-CALCULATION drivers and shared drivers. For vertices, a PRE-CALCULATION driver converts the 3D shared vertex array into a perspective-transformed 2D array, and for normals it calculates the vertex colors. Because it must be called for each coordinate, a PRE-CALCULATION driver is chained to each primitive block. Its type is 0x01000000.[^ff290][^ff291]
−Camera primitives set the projection and the camera position and direction.[^ff2128]+A shared driver takes the vertices that a PRE-CALCULATION driver has already calculated and builds GPU packets that it enters into the OT. Shared drivers must be called last, so they are chained to the POST-PROCESS primitive block. The DRIVER bits of a shared driver are all 0. Its PRIMITIVE TYPE has TME, COL (not implemented), IIP and CODE as in category 0, although the strip mesh is not implemented.[^ff290][^ff291]
+The connection data that a shared driver refers to has the same format as a non-shared polygon PACKET. The calculated area has the following format:[^ff291][^ff292]
+
+Table: Calculated area for shared polygons
+
+| Area | Word 0 | Word 1 |
+| --- | --- | --- |
+| VERTEX | H(vx) H(vy) | H(otz) H(p) |
+| NORMAL | H(r) H(g) | H(b) H(0) |
+
+A shared primitive header gives the shared VERTEX and NORMAL counts with source and destination offsets for each. The two buffers for input and output are defined independently, so shared primitives can be reused.[^ff255]
+
+## Image Data (Category 2)
+
+The HMD format can represent image data as a primitive, so modeling data, image data and animation data can be managed together. Image data can also be set up separately in a [TIM](/formats/tim/) file, and an HMD file can hold only image data. The image header section has a header size of 2 with an IMAGE TOP pointer and a CLUT TOP pointer.[^ff292][^ff293]
+
+Image primitives are linked to the PRE-PROCESS at the beginning of the coordinate section of the HMD, and a VRAM transfer function is called during the SCAN. Once the transfer is complete, a NULL driver (type 0x00000000) can be set in the type field. The transfer to VRAM is therefore performed only once.[^ff294]
+
+The DRIVER bits of an image type are currently all 0, and DATA TYPE gives the kind of image:[^ff294][^ff295]
+
+Table: Image primitives
+
+| type | Primitive | Driver | Data |
+| --- | --- | --- | --- |
+| 0x02000000 | Non-CLUT primitive (NOCLUT) | GsUIMG0 | H(dx) H(dy), H(w) H(h), image_idx |
+| 0x02000001 | Primitive with CLUT (WITHCLUT) | GsUIMG1 | H(dx) H(dy), H(w) H(h), image_idx, then H(dx) H(dy), H(w) H(h), clut_idx |
+
+## Animation Data (Category 3)
+
+An animation primitive section is divided into five subsections. The animation header section holds pointers to the interpolation function table, the sequence control section, the parameter section and the section to be updated. When a COORDINATE is rewritten, for example, COORDINATE TOP is saved there, and VERTEX TOP is saved when a vertex is rewritten.[^ff295][^ff296][^ff297]
+
+Table: Animation sections
+
+| Section | Contents |
+| --- | --- |
+| Animation primitive header | Header size (5) and the section pointers |
+| Sequence pointer | The sequence pointer and the information for each sequence |
+| Interpolation function table | Type fields of the interpolation functions that the sequence descriptors use |
+| Sequence control | The list of sequence descriptors |
+| Parameter | The key frame parameters, in any format |
+
+The interpolation function table holds the type fields in an array, and a sequence descriptor selects its interpolation method by an index into this array. GsScanAnim() must first SCAN the table to obtain the starting address of each driver. The first word of the table is the number of types, and its uppermost bit is 1 until the SCAN has been performed.[^ff297][^ff298][^ff2104]
+
+### Animation Type
+
+The animation type field has category 3. Its INI bit is 1 when the interpolation table still needs a SCAN, and its CAT field selects the frame update driver. CAT 0 is the standard driver. TGT selects the update target. With TGT 0 the COORDINATE section is updated, and the lower 16 bits give the rotation order and the interpolation of scaling, rotation and translation:[^ff298][^ff299]
+
+Table: Type field when TGT=0
+
+| Field | Values |
+| --- | --- |
+| ROT ORDER | 0 XYZ, 1 XZY, 2 YXZ, 3 YZX, 4 ZXY, 5 ZYX. Valid only when ROT INTR is not 0. |
+| SCAL INTR | 0 none, 1 LINEAR, 2 BEZIER, 3 B-SPLINE, 4 beta-SPLINE, 9 LINEAR (one parameter), A BEZIER (one parameter), B B-SPLINE (one parameter) |
+| ROT INTR | 0 none, 1 LINEAR, 2 BEZIER, 3 B-SPLINE |
+| TRNS INTR | 0 none, 1 LINEAR, 2 BEZIER, 3 B-SPLINE, 9 LINEAR (short), A BEZIER (short), B B-SPLINE (short) |
+
+With ROT ORDER 0 (XYZ), the rotation is carried out about the Z axis, then the Y axis and then the X axis. With TGT 1 the update is general purpose. LENGTH gives the unit size (0 32 bits, 1 16 bits, 2 8 bits), the 4-bit WRITE field selects up to 4 units to update, and INTR ALG selects linear, Bezier or B-spline interpolation.[^ff299][^ff2100]
+
+### Sequence Pointer
+
+The sequence pointer holds the state of a sequence during playback, and one sequence pointer is assigned to each sequence that plays at the same time. The program controls real-time playback through its members, which the interpolation driver reads continuously. Some members are written in the HMD data and the others are work areas:[^ff2101][^ff2102][^ff2103]
+
+Table: Sequence pointer members
+
+| Member | Contents |
+| --- | --- |
+| Update index | Target address of the update. Upper 8 bits: section offset into the list of section addresses. Lower 24 bits: offset in words within the section. |
+| Sequence count / size | Upper 16 bits: number of sequences managed by this pointer. Lower 16 bits: words until the next sequence pointer. |
+| INTR IDX | Index of the key frame that holds the parameters after interpolation. 0xffff stops updates. |
+| A FRAME | Total frame count of the sequence. 0 stops the sequence, and 0xffff means no limit. |
+| SRC INTR IDX | Work area for INTR IDX |
+| SPEED | Update speed, a two's complement fixed-point number with 1 sign bit, 3 integer bits and 4 fraction bits |
+| STREAM ID | 7-bit stream ID (0 to 127). Sequence jumps take place only when stream IDs match. |
+| TFRAME | Time between key frames, in frames, with 0x10 as one frame |
+| RFRAME | Time from the original key frame, with 0x10 as one frame |
+| TCTR IDX | Index of the target key frame |
+| CTR IDX | Index of the original key frame |
+| START IDX | Starting index of a sequence |
+| START SID | Stream ID of the sequence to be started |
+| TRAVELING | Cleared to 0 when the key frame is switched. The programmer can use it freely. |
+
+To rewrite the second coordinate, for example, the offset within the section is sizeof(GsCOORDUNIT)/4+1, because the first word of the coordinate section is the coordinate count. A negative SPEED plays the animation in reverse. Page 2-103 gives the range of SPEED as up to 7 times faster and down to 1/15, while page 2-133 gives up to 8 times and down to 1/16.[^ff2102][^ff2103][^ff2133]
+
+STREAM ID 0 matches any stream ID, and stream ID 127 should not be used as the condition of a jump. To start a sequence, the program copies START IDX into TCTR IDX and START SID into the stream ID, and sets RFRAME to 0.[^ff2103][^ff2104]
+
+### Sequence Descriptors
+
+A sequence is represented in the sequence control section as an array of sequence descriptors. The uppermost bits of a descriptor select its kind:[^ff2104][^ff2105]
+
+Table: Sequence descriptors
+
+| Kind | Bits 31..30 | Fields |
+| --- | --- | --- |
+| Normal (key frame) | 0 | TYPE IDX (7 bits, up to 128 interpolation functions), TFRAME (frame number of the next descriptor), PARAMETER IDX |
+| Jump | 1 0 | SID DST (7 bits), SID CND (7 bits), SEQUENCE IDX of the destination |
+| Control | 1 1 | CODE, P1, P2 |
+
+A jump is taken only when SID CND matches the current stream ID, and SID CND 0 matches any stream ID. When SID DST is not 0, the stream ID is set to SID DST after the jump. The control code 0x01 is END, which halts the sequence if P1 matches the current stream ID. The code 0x02 is WORK, which marks the work area that BSPLINE interpolation needs, with P1 fixed at 127 and P2 the offset in the parameter section.[^ff2105]
+
+The interpolation function can change at each key frame, but the parameters of the source and destination key frames must then have the same format. A descriptor with TFRAME 0 can be added to convert the format between them. The interpolation driver is called even when TFRAME is 0, so every interpolation driver must return without interpolating in that case.[^ff2106]
+
+### Interpolation
+
+Animation primitives are placed in the PRE-PROCESS area at the beginning of the coordinate section, and their frame update driver is called each time GsSortUnit() is called. The frame update driver provided by Sony Computer Entertainment has type 0x03000000. It calls the interpolation driver with a pointer sp to a parameter area that holds base (the sequence pointer), src and dst (the two key frames) and intr (where the result is saved, or 0).[^ff2107][^ff2108]
+
+Three interpolation algorithms are available. LINEAR interpolates between the source and destination key frames with T = (TFRAME - RFRAME) / TFRAME. BEZIER uses control points 0 to 2 of the source key frame together with control point 0 of the destination key frame. BSPLINE needs the WORK area of the sequence pointer.[^ff2105][^ff2108]
+
+## MIMe Data (Category 4)
+
+The MIMe primitive is described in the libgs reference. Joint MIMe (JntMIMe) and vertex/normal MIMe (VNMIMe) each have a reset form, and the PRIMITIVE TYPE field selects among them:[^ff2118][^ff2119]
+
+Table: MIMe types
+
+| CODE0 | CODE1 | Type | Reset type |
+| --- | --- | --- | --- |
+| 0 (JntMIMe) | 0 | JntAxesMIMe (rotation-axes interpolation) | RstJntAxesMIMe |
+| 0 (JntMIMe) | 1 | JntRPYMIMe (roll-pitch-yaw interpolation) | RstJntRPYMIMe |
+| 1 (VNMIMe) | 0 | VtxMIMe (vertex) | RstVtxMIMe |
+| 1 (VNMIMe) | 1 | NrmMIMe (normal) | RstNrmMIMe |
+
+The RST bit is 1 for a reset primitive, and the DRIVER bits are always 0x01. MIMe primitives need a MIMe DIFF section, an ORGSVN section for VtxMIMe and NrmMIMe, and a MIMEPR area when the HMD contains MIMEPR. Up to 32 MIMe differences can be used for one primitive.[^ff2118][^ff2119]
+
+JntMIMe shares its primitive block with RstJntMIMe, but VNMIMe and RstVNMIMe use their own primitives. When two or more JntMIMe primitives act on one joint, the reset functions must be called in reverse order. Otherwise the state is not correct.[^ff2118]
+
+In the MIMe DIFF section, dflags has a bit set for each MIMe key that has differences. When keys 0, 1, 3 and 8 have differences, dflags is therefore 0x0000010B. The differences must follow the order of the dflags bits.[^ff2121][^ff2122]
+
+## Ground Data (Category 5)
+
+A ground primitive generates packets at run time from the width and height of a grid and the number of grids, which reduces the amount of HMD data. Its primitive header is 4 words without texture and 5 words with texture. DATA TYPE is 0 for flat and 1 for flat texture, and the DRIVER bits are all 0 in this version.[^ff2125]
+
+The primitive points into a polygon section, a grid section and a vertex section. The polygon section holds the information needed to generate the polygons, and the grid section holds the normal indexes and the RGB or UV of each grid. The vertex section holds information such as the Z value of each vertex, and the UV section holds the texture UV values that the grid section refers to.[^ff2126][^ff2127]
+
+## Device Primitives (Category 7)
+
+Device primitives perform settings such as the camera (viewpoint) and the light (light source). Applications previously made these settings in their own code. Except in certain cases, device primitives should be placed in the standard preprocess. DATA TYPE 0x0100 is a camera primitive and 0x0200 is a light primitive, and DRIVER selects the operation:[^ff2128][^ff2129]
+
+Table: Device primitive operations
+
+| DRIVER | Camera primitive | Light primitive |
+| --- | --- | --- |
+| 0x00 | Projection | Ambient color |
+| 0x01 | WORLD camera | WORLD light |
+| 0x02 | FIX camera | FIX light |
+| 0x03 | AIM camera | AIM light |
+
+Projection adjusts the field of view as the distance from the viewpoint to the projection plane. The size of the plane is set by the resolution given to GsInitGraph(). A WORLD camera sets the camera position in the WORLD coordinate system and calculates WSMATRIX, while a FIX camera does the same in another coordinate system. An AIM camera calculates WSMATRIX from a position in one coordinate system seen from a camera position in another. The light primitives set the ambient color or a flat light source in the same three ways.[^ff2128]
+
+## Animation Playback
+
+HMD holds coordinate information, so the motion of a hierarchical model can be described. HMD animation can switch between several predefined motion sequences at any time with the Realtime Motion Switch. Entities are not repeated in the data because everything is referenced by indexes and pointers. The memory used for animation data is therefore kept to a minimum. Because the interpolation method is managed by HMD type, a new method can be defined by adding a type.[^ff2131]
+
+The frame update driver GsU_03000000() of libgs 4.0 provides the Realtime Motion Switch with forward, reverse, slow and fast playback. The Realtime Motion Switch can switch sequences at key frames by stream ID. It can also switch them immediately during interpolation.[^ff2133]
+
## References## References
Line 190:Line 428:
[^ff252]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-52, Figure 102.[^ff252]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-52, Figure 102.
[^ff253]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-53.[^ff253]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-53.
+[^ff255]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-55.
+[^ff256]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-56.
+[^ff257]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-57, Figure 104 and Table 2-4.
+[^ff258]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-58, Figure 105.
+[^ff259]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-59, Figure 106.
[^ff260]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-60, Figure 107.[^ff260]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-60, Figure 107.
[^ff261]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-61, Figure 108.[^ff261]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-61, Figure 108.
+[^ff262]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-62, Figures 109 and 110.
+[^ff263]: Sony Computer Entertainment Inc. File Formats. November 1998. Pages 2-63 to 2-90, polygon types.
+[^ff274]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-74.
+[^ff282]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-82.
[^ff290]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-90.[^ff290]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-90.
−[^ff292]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-92.+[^ff291]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-91, Figures 111 and 112.
+[^ff292]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-92, Figure 113.
[^ff293]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-93.[^ff293]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-93.
+[^ff294]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-94, Figures 114 and 115.
[^ff295]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-95.[^ff295]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-95.
+[^ff296]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-96, Figure 116.
+[^ff297]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-97, Figure 117.
+[^ff298]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-98, Figure 118.
+[^ff299]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-99, Figure 119.
+[^ff2100]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-100, Figure 120.
+[^ff2101]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-101, Figures 125 and 126.
+[^ff2102]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-102, Figures 127 and 128.
+[^ff2103]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-103, Figure 129.
+[^ff2104]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-104, Figures 130 and 131.
+[^ff2105]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-105, Figures 132 and 133.
+[^ff2106]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-106.
+[^ff2107]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-107, Figure 134.
+[^ff2108]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-108.
[^ff2118]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-118.[^ff2118]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-118.
−[^ff2125]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-125.+[^ff2119]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-119, Figures 138 to 140.
+[^ff2121]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-121, Figure 141.
+[^ff2122]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-122.
+[^ff2125]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-125, Figure 142.
+[^ff2126]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-126.
+[^ff2127]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-127.
[^ff2128]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-128.[^ff2128]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-128.
+[^ff2129]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-129, Figure 143.
[^ff2131]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-131.[^ff2131]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-131.
+[^ff2133]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-133.