HMD (Hierarchical 3D Model and Animation Data)

Integrated format for model and image and animation data.

This is an old revision of this page, as edited by RemmyLee at 02:47, 23 October 2026. Edit this revision | Latest revision

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

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

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.¹²

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

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.²³⁴

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.³⁴

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

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

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:³⁶

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.⁶⁷

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

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

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.⁶⁵

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

Type Field

The type field is 32 bits in four parts, and its upper 8 bits contain data that is common to all categories:⁸⁹

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:⁸¹⁰⁹

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

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.¹¹⁷

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

The DRIVER bits of a polygon primitive change the behavior of its driver. For example, they can enable polygon subdivision:¹²⁹

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:¹²¹³

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.¹³¹⁴

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. The flat no-texture triangle, type 0x00000008, has the following PACKET:¹⁴

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:¹⁵¹⁴

In the preset model data the packet holds a DMAtag and the screen coordinates for two packets ahead of the vertex indexes.¹⁶

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.¹⁷

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.¹⁸¹⁹

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.¹⁸¹⁹

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:¹⁹²⁰

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.²¹

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 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.²⁰²²

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.²³

The DRIVER bits of an image type are currently all 0, and DATA TYPE gives the kind of image:²³²⁴

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.²⁴²⁵²⁶

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.²⁶²⁷²⁸

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:²⁷²⁹

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.²⁹³⁰

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:³¹³²³³

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.³²³³³⁴

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.³³²⁸

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:²⁸³⁵

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.³⁵

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.³⁶

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).³⁷³⁸

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.³⁵³⁸

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:³⁹⁴⁰

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.³⁹⁴⁰

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.³⁹

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.⁴¹⁴²

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.⁴³

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.⁴⁴⁴⁵

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:¹⁰⁴⁶

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.¹⁰

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

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.³⁴

References