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

This is an old revision of this page, as edited by RemmyLee at 02:46, 23 October 2026. Publishing it replaces the current version.
← 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. Model data, texture data and animation data are handled within one framework.[^ff249]

HMD is extended to new kinds of data through a unique identification code called a type.[^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

HMD data has two main parts:[^ff249]

- The HMD header
- 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

The HMD header holds the following fields:[^ff250][^ff251]

Table: HMD header section

| Field | Contents |
| --- | --- |
| Version ID | 0x00000050 |
| MAP FLAG | 1 after GsMapUnit() has mapped the data, otherwise 0 |
| Primitive header section pointer | Start of the primitive header section |
| Number of blocks | Number of primitive block pointers |
| Pointer to the primitive block 0..n | One pointer for each primitive block |

GsMapUnit() reads and changes MAP FLAG.[^ff251]

## Primitives

The primitive section is a collection of primitive blocks.[^ff251]

A primitive block is a chain of one or more primitives. Pointers join the primitives of the chain.[^ff251]

A primitive has a control section and one or more data sections.[^ff251]

The parts are as follows:

Table: Primitive structure

| Part | Field | Contents |
| --- | --- | --- |
| Control section | Next Prim pointer | Header of the next primitive in the chain. 0xFFFFFFFF ends the chain. |
| 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 |

### SCAN

A SCAN overwrites each type field with the start address of its primitive 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

The primitive headers are grouped in the primitive header section. The HMD header points to that section.[^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 is a pointer to a section.[^ff252]

A word with the MSB clear is a numeric value. It can serve as a parameter to the primitive driver.[^ff252]

## Type Field

The type field is 32 bits in four parts:[^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 developer with a unique ID can use the other bits freely.[^ff260]

The categories are as follows:[^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 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 name of the driver function is "GsU_" followed by the bit pattern.[^ff2131]

## Categories

### Model Data (Category 0)

Model data must have the HMD header, primitive header, coordinate, primitive, polygon and vertex sections. It can also have normal and image sections.[^ff253]

Each coordinate system of a model is assigned to its own primitive block.[^ff253]

The DIV bit of the polygon driver enables polygon subdivision. The FOG bit turns fog on.[^ff261]

### Shared Primitives (Category 1)

Shared primitives use two kinds of driver: PRE-CALCULATION drivers and shared drivers.[^ff290]

A PRE-CALCULATION driver converts a 3D shared vertex array into a perspective-transformed 2D vertex array. For normals it calculates vertex colors.[^ff290]

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]

### Image Data (Category 2)

HMD can hold image data as a primitive. Model, image and animation data can then be managed together.[^ff292]

Image data can also stay outside HMD in [TIM](/formats/tim/) files.[^ff293]

### Animation Data (Category 3)

An animation primitive section has five subsections:[^ff295]

- Animation primitive header section
- Sequence pointer section
- Interpolation function table section
- Sequence control section
- Parameter section

### MIMe Data (Category 4)

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]

### 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.[^ff2125]

This method reduces the amount of HMD data.[^ff2125]

### Device Primitives (Category 7)

Device primitives hold camera (viewpoint) and light (light source) settings that applications used to make in code.[^ff2128]

Camera primitives set the projection and the camera position and direction.[^ff2128]

## 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.
[^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.
[^ff290]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-90.
[^ff292]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-92.
[^ff293]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-93.
[^ff295]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-95.
[^ff2118]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-118.
[^ff2125]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-125.
[^ff2128]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-128.
[^ff2131]: Sony Computer Entertainment Inc. File Formats. November 1998. Page 2-131.