View source for HMD Library (libhmd)

You do not have permission to edit this page. Log in to edit.
---
title: HMD Library (libhmd)
type: component
summary: Provides functions and definitions for handling the HMD format.
category: Psy-Q
info: Library = libhmd.lib
info: Header File = libhmd.h, libgs.h
info: SDK = Psy-Q
---

## Overview

The HMD file format integrates several types of data, including modeling, animation, texture and MIMe data, and the HMD Library (libhmd) provides the functions and structures for using it. libhmd uses the jump table method that [libgs](/sdk/psy-q/libgs/) uses for TMD data. HMD data consists of primitive types, and each type has a primitive driver, a function that handles the data.[^o18-3]

SCE provides standard primitive drivers for modeling data with hierarchical structures, one-skin models, key-frame animation and vertex and joint MIMe. The primitive drivers are called through standard public APIs within the HMD framework, so a game can define its own drivers for optimization and expansion. In library versions 4.0 to 4.2 the HMD functions were part of libgs and libgte, and they are now a separate library. The environment map primitive is a Beta version that SCE does not support.[^o18-3]

A program that uses libhmd links with libhmd.lib. Because libhmd depends on libgs, the program also links libgs.lib, and it includes libhmd.h and libgs.h.[^o18-3]

This library is part of the run-time library that Sony distributed with the [Psy-Q](/sdk/psy-q/) development tools.[^ptcd]

## Basic Architecture

HMD has three layers. The framework layer is provided by libhmd. A standardized API joins it to the primitive driver layer, so user-defined and third-party primitive drivers can be used, and the data format layer is the set of formats built from combinations of primitive drivers. The framework maps HMD data loaded in memory, scans the data to bind each primitive type to its driver and sorts the data by traversing it and calling the drivers.[^o18-3]

Part of the HMD data format is defined by the framework and cannot be changed by the user. The other part is defined by the primitive drivers and can be defined freely within the rules of the framework. The general-purpose polygon drivers of SCE, for example, may not be fast enough for a title, and a driver written for the title can improve performance.[^o18-4]

## Hierarchical Structures

In the TMD and PMD formats of libgs, a hierarchical structure has to be described in the program code. TOD can represent one, but it increases code size and makes communication between designers and programmers more difficult. HMD therefore implements the hierarchical structure in the data format itself.[^o18-4]

## Polygon and Mesh

The polygon and MESH primitives are a superset of what TMD and PMD provided, and they also describe polygons as a strip mesh. Four separate triangles need 4 x 3 = 12 coordinate transformations and 12 vertex indexes, while a strip mesh of four triangles needs only 6 of each. A more complex figure saves more speed and memory. Rendering is also faster, because the GPU packets are generated as triangles that share edges.[^o18-5]

## Shared Polygons

HMD can place a polygon across the coordinate systems of the hierarchy, which represents a one-skin model and gives smoother figures at the joints. For example, a triangle with two vertices in coordinate system A and one in coordinate system C is shared between A and C. Because each vertex follows its own coordinate system, the coordinate systems can move without the polygons losing their connection.[^o18-6]

## Animation and MIMe

Key-frame animation uses three types of interpolation curve: linear, Bezier and B-spline. Several motions can be stored in the HMD data and switched during execution. Besides coordinate data, the animation can drive any value in memory, such as MIMe parameters and polygon colors.[^o18-6]

MIMe combines several key frames by the fast multi-layer interpolation of the GTE, which suits facial animation. HMD includes vertex and normal MIMe and also joint MIMe, which interpolates joint angles with less data and more speed than vertex MIMe. Vertex and joint MIMe together express movements such as the muscle of a bending elbow. The basic form, the angle differential and the vertex differential are specified in the HMD data, and the weights are controlled by the application or by HMD animation.[^o18-6][^o18-7]

libhmd also provides camera and light primitives. Its experimental primitives include ground primitives for terrain and a simulated environment map (Beta version). Sample source code of primitive drivers is provided as a reference for user-defined primitives.[^o18-7]

## Process Flow

Primitive sets are of two kinds. Non-rendering primitive sets perform work that generates no GPU packets. Loading animation or texture data into VRAM is work of this kind. Rendering primitive sets generate GPU packets from the results of the non-rendering sets or from values in the data and enter them in an ordering table.[^o18-8]

The pointers to the primitive sets are placed near the top of the HMD data. The first word is the number of pointers. A value of N + 2 means N primitive sets for N coordinate systems together with one set for pre-processing and one for post-processing. Loading textures is pre-processing and rendering shared polygons is post-processing. Primitive sets can point to the next primitive set. Different types of set can therefore run one after another in one coordinate system. The coordinate system data points to the parent coordinates and links the hierarchy to its primitives.[^o18-8]

HMD data is used in three operations. Mapping converts the offsets in the data into real addresses once after the data is loaded (GsMapUnit()). Scanning replaces the 32-bit primitive types with pointers to their driver functions once after mapping (GsScanUnit()). Sorting with GsSortUnit() calls the drivers and normally takes place at each VSync.[^o18-9]

## Primitives

The primitive is the smallest unit of the HMD format. Its first word is a 32-bit value that holds the primitive type and other data, and scanning replaces it with a pointer to the primitive driver. This word contains the following fields:[^o18-10]

Table: Primitive type word

| Field | Size | Contents |
| --- | --- | --- |
| DEV_ID | 4 bits | Vendor that defined the primitive. 0x0 and 0x1 are SCE and 0xf is for user-defined primitives. |
| CTG | 4 bits | Major category of the primitive |
| DRV | 8 bits | Changes the action without changing the data structure, such as single or double-sided polygons |
| PRIM_TYPE | 16 bits | Primitive type |

The categories of the SCE standard primitives are the following:[^o18-10]

Table: Primitive categories

| Category | Value |
| --- | --- |
| CTG_POLY (polygons) | 0 |
| CTG_SHARED (shared polygons) | 1 |
| CTG_IMAGE (images) | 2 |
| CTG_ANIM (animation) | 3 |
| CTG_MIME (MIMe) | 4 |
| CTG_GND (ground) | 5 |
| CTG_EQUIP (equipment) | 7 |

The primitive type word is followed by a 16-bit size and 15 bits of data for the driver. The high bit of the data changes from 1 to 0 during scanning to prevent double scanning, so only the low 15 bits are valid. The size gives the number of data words that follow. A driver is called at least once for each primitive, so one primitive holds many polygons. Twenty primitives of one polygon each would waste instruction cache hits and memory accesses.[^o18-10]

## Primitive Sets and Headers

A primitive set contains several primitives. It holds a pointer to the next primitive set, or TERMINATE (0xffffffff) at the end, a pointer to a primitive header in the format of its primitive type, and the number of primitives. Links between primitive sets can reduce the data by instancing. The high bits of the first two words are set to 0 when they are mapped, which prevents double mapping.[^o18-11]

A primitive header is a series of 32-bit words whose format depends on the primitive driver. Its first word, hdr_size, gives the size of the header in words. Each following word whose high bit is 1 is a pointer to a section, which is mapped, and each word whose high bit is 0 is a numeric value, which is not.[^o18-11]

A section groups data of other types, and a primitive header is itself a section. For example, primitive set 1 may hold N primitives that refer to primitive header 1, and header 1 points to sections 1 and 2. A second primitive set reached through the next pointer of set 1 may refer to a different header 2.[^o18-12][^o18-13]

## Primitive Drivers

The primitive drivers are called during sorting. A driver receives a copy of the primitive header, pointers to the primitive data and a pointer to the ordering table given to GsSortUnit(), in which a rendering driver registers its GPU packets. The driver returns a pointer to the next primitive, which it finds from the size of the primitive. A driver whose primitives always have size 2 can return the pointer without reading the size.[^o18-13]

## Migrating from TMD

GsSortUnit() replaces the GsSortObject functions, and the object handler changes from the GsDOBJ structures to GsUNIT. The behavior of a primitive is selected by switching to a different primitive driver instead of by attributes. A GsUNIT has two members: coord points to the coordinate system and primtop to the start of the primitive block. As before, the local-world matrix is calculated from coord and set in the GTE before GsSortUnit() is called with primtop. GsMapUnit() converts the pointers in the HMD data to real addresses. GsScanUnit() returns the addresses and types of the primitives, and the application sets the driver for each type. When the INI bit of a type is on, a function that initializes locally defined sections, such as GsMapCoordUnit(), is called.[^o18-18]

## Structures

In the tables below, Introduced is the run-time library version that added the item.[^refs173]

libhmd has the following structures:[^refs173]

Table: libhmd structures

| Structure | Introduced | Purpose |
| --- | --- | --- |
| `GsARGUNIT` | 4.0 | Primitive driver argument area. |
| `GsARGUNIT_ANIM` | 4.0 | Animation driver argument area. |
| `GsARGUNIT_GND...` | 4.1 | HMD ground primitive driver argument area. |
| `GsARGUNIT_IMAGE` | 4.0 | Image primitive driver argument area. |
| `GsARGUNIT_JntMIMe` | 4.0 | Joint MIMe primitive driver argument area. |
| `GsARGUNIT_NORMAL` | 4.0 | Independent primitive driver argument area. |
| `GsARGUNIT_RstJntMIMe` | 4.0 | Joint mime reset primitive driver argument area. |
| `GsARGUNIT_RstVNMIMe` | 4.0 | Argument area of vertex normal MIMe reset primitive driver. |
| `GsARGUNIT_SHARED` | 4.0 | Shared primitive driver argument area. |
| `GsARGUNIT_VNMIMe` | 4.0 | Vertex normal mime primitive driver argument area. |
| `GsCOORDUNIT` | 4.0 | Matrix type coordinate system. |
| `GsRVIEWUNIT` | 4.0 | HMD viewpoint position (Reference type). |
| `GsSEH` | 4.0 | HMD animation sequence header. |
| `GsSEQ` | 4.0 | HMD animation sequence pointer. |
| `GsTYPEUNIT` | 4.0 | Type storage area. |
| `GsUNIT` | 4.0 | Three-dimensional object handler for GsSortUnit(). |
| `GsVIEWUNIT` | 4.0 | HMD viewpoint position (matrix type). |
| `GsWORKUNIT` | 4.0 | Calculation result storage area for shared primitive. |

## Functions

libhmd has the following functions:[^reff1723]

Table: libhmd functions

| Function | Introduced | Purpose |
| --- | --- | --- |
| `GsGetHeadpUnit` | 4.0 | Obtain current HMD header address. |
| `GsGetLsUnit` | 4.0 | Calculate a local screen matrix. |
| `GsGetLwsUnit` | 4.0 | Calculate local world and local screen matrices. |
| `GsGetLwUnit` | 4.0 | Calculate local world matrix. |
| `GsInitRstNrmMIMe` | 4.1 | Initialize HMD normal MIMe driver. |
| `GsInitRstVtxMIMe` | 4.1 | Initialize HMD vertex MIMe driver. |
| `GsLinkAnim` | 4.0 | Link GsSEQ array and HMD data. |
| `GsMapCoordUnit` | 4.0 | Map COORDINATE within the HMD data to actual address. |
| `GsMapUnit` | 4.0 | Map HMD data offset to actual address. |
| `GsScanAnim` | 4.0 | Perform SCAN for HMD animation. |
| `GsScanUnit` | 4.0 | Examine types within HMD data. |
| `GsSetRefViewLUnit` | 4.0 | Set HMD viewpoint position (High precision). |
| `GsSetRefViewUnit` | 4.0 | Set HMD viewpoint position. |
| `GsSetViewUnit` | 4.0 | Set HMD viewpoint. |
| `GsSortUnit` | 4.0 | Allocate an object to the ordering table. |
| `GsU_...` | 4.0 | GsSortUnit() primitive driver group (Polygon, Shared Polygon, Image, Ground). |
| `GsU_03000000` | 4.0 | HMD animation frame update driver. |
| `GsU_03000001...` | 4.0 | HMD animation interpolation function (alignment, COORDINATE). |
| `GsU_03010110...` | 4.1 | HMD animation interpolation function (general). |
| `GsU_040100...` | 4.0 | HMD MIMe driver. |

## References

[^o18-3]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-3.
[^o18-4]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-4.
[^o18-5]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-5.
[^o18-6]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-6.
[^o18-7]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-7.
[^o18-8]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-8.
[^o18-9]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-9.
[^o18-10]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-10.
[^o18-11]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-11.
[^o18-12]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-12.
[^o18-13]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-13.
[^o18-18]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 18-18.
[^refs173]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 17-3 to 17-22.
[^reff1723]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 17-23 to 17-45.
[^ptcd]: Sony Computer Entertainment Inc. Programmer Tools CD (DTL-S2002), README.TXT. 11/26/96. Section "CD-ROM Contents - Highlights", directories \PSX and \PSYQ.