View source for HMD (Hierarchical 3D Model and Animation Data)

← HMD (Hierarchical 3D Model and Animation Data)
You do not have permission to edit this page. Log in to edit.
---
title: HMD (Hierarchical 3D Model and Animation Data)
type: format
summary: Integrated format for model and image and animation data.
category: File formats
info: Extension = .HMD
info: Version ID = 0x00000050
info: Library = libhmd
---

## Overview

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]

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]

## Structure

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]

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]

### HMD Header

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 section

| Field | Contents |
| --- | --- |
| Version ID | 0x00000050 |
| 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. The MSB is 1 after the section has been mapped. |
| Number of blocks | Number of primitive block pointers |
| Pointer to the primitive block 0..n | One pointer for each primitive block |

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]

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]

Table: Primitive pointer table

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

### Coordinate Section

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 structure

| Part | Field | Contents |
| --- | --- | --- |
| 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 | Type count | Number of data sections. The MSB is 1 while the pointers are unmapped and 0 after mapping. |
| Data section | type | Identifier of the data |
| Data section | Data count / size | Upper 16 bits: number of data sets. Lower 16 bits: size of one data section in words. |
| 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

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]

### Primitive Header

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]

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]

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]

Table: Variable transfer area

| Item |
| --- |
| primtop |
| Tag (OT) |
| Shift (OT) |
| Offset (OT) |
| OUTP (packet area) |
| Primitive header |

## Type Field

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 field

| Bits | Field | Contents |
| --- | --- | --- |
| 28..31 | DEVELOPER ID | ID of the developer of the format. 0x0 is SCE, 0xf is user defined. |
| 24..27 | CATEGORY | Category of the data |
| 16..23 | DRIVER | Bits that change the behavior of the primitive driver |
| 0..15 | PRIMITIVE TYPE | Bit assignment depends on the primitive type |

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]

Table: HMD categories

| Category | Data |
| --- | --- |
| 0 | Polygon data |
| 1 | Shared polygon data |
| 2 | Image data |
| 3 | Animation data |
| 4 | MIMe data |
| 5 | Ground data |
| 6 | Pseudo-environment map (beta, library 4.2) |
| 7 | Device primitives (camera and light) |

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]

## Polygon Data (Category 0)

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]

### Polygon Primitive

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]

The DRIVER bits of a polygon primitive change the behavior of its driver. For example, they can enable polygon subdivision:[^ff261][^ff2131]

Table: Polygon primitive DRIVER bits

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

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]

Table: Polygon PRIMITIVE TYPE bits

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

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]

### Polygon Section

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]

Table: Flat no-texture triangle PACKET

| Word | Contents |
| --- | --- |
| 0 | B(r) B(g) B(b) B(0x20) |
| 1 | H(norm0) H(vert0) |
| 2 | H(vert1) H(vert2) |

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]

Table: HMD polygon primitive types

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

In the preset model data the packet holds a DMAtag and the screen coordinates for two packets ahead of the vertex indexes.[^ff282]

### Vertex and Normal Sections

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]

## Shared Primitives (Category 1)

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]

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

[^ff249]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-49.
[^ff250]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-50, Figures 98 and 99.
[^ff251]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-51, Figures 100 and 101.
[^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.
[^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.
[^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.
[^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.
[^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.
[^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.
[^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.
[^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.
[^ff2133]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-133.