File Formats

This page describes the proprietary binary file formats that are used by the Tinman 3D SDK.

Basic Data Types

In the following descriptions, the type names int8, int16, int32, int64 refer to signed integer types and the types uint8, uint16, uint32 refer to unsigned integer types.

Floating-point types are indicated by float32 and float64 (IEEE 754).

Unless stated otherwise in the description, multi-byte values use little-endian encoding. In specific cases, big-endian may be indicated by the type suffix _be and _little-endian_ may be indicated by _le.

The type bool is an 8-bit integer which represents either true (0) or false (~0).

Fixed-length array types have a [] suffix. Array elements are stored sequentially, without padding.

The type varint refers to the variable-length integer type, see SystemUtil.VarIntRead and SystemUtil.VarIntWrite.

Binary Config Documentation (BCD)

hourglass This section is not yet available, see roadmap for details.

Block Storage (BST)

hourglass This section is not yet available, see roadmap for details.

Compiled Model Hierarchy (CMH)

This is a self-contained file format for 3D models, which aggregates all model data in a single file, while allowing lazy-loading of specific data at runtime; for example vertex buffers, index buffers and textures.

This file format is backward compatible, i.e. files in an older format can always be loaded with the current SDK version.

When writing a file, the smallest file version is chosen that is capable of carrying all information, which makes it possible to generate files that may be consumed by an older SDK version.

History

Table 1. CMH file format history
Changed Released [1] Preview [2] Version Description

2023/03/07

2023/03/07

2023/03/07

v5

Added new material properties to IMaterial, to support the glTF 2.0 specification.

The IMaterial.BaseColor, IMaterial.Emissive, IMaterial.Reflectivity and IMaterial.Translucency properties may now carry HDR color values.

Added base vertex for indexed geometry to PrimitiveBatch.

Added the ModelFlags.Terrain, ModelPartFlags.Opaque and ModelVertexFormat.TextureCoordsExtra flags.

Added support for re-using IModel and IModelPart objects at multiple places in the model hierarchy.

Replaced ModelFlags.Lighting with ModelPartFlags.NoLighting.

2023/02/10

2023/02/10

2023/02/10

v4

Added level-of-detail control, see IModel.FadeIn / IModel.FadeOut.

2023/02/06

-

-

v3

Added surface layers, see IModelPart.Layer.

2021/05/24

2021/09/10

2021/09/10

v3

Added embedded spatial acceleration structures, see ModelFlags.ComplexGeometry.

2020/07/28

2021/01/10

2021/01/10

v2

Added model parts, see IModelPart.

Added 64-bit precision for child-to-parent transforms, see IModel.ChildTransformAt.

2020/07/06

-

-

v2

Added ModelVertexFormat.PositionExtra.

2019/12/21

-

-

v1

Removed model animation frames.

2017/03/23

2017/04/28

2017/04/28

v1

Added unit of measure, see IModel.Unit.

2017/03/21

-

-

-

Initial version (unreleased).

Specification

This is the binary file format specification of the CMH file format.

Byte offsets are always interpreted relative to the beginning of the file.

Header

Table 2. Header block
Field Type Count Description

magic

int64

1

The magic value 0x0A1A0A0D686D6389, which identifies the CMH file format

version

varint

1

The file version number; file format features that depend on specific version numbers are annotated with @ version <> N.

root

int64

1

Byte offset of root Model block

Model

This block encodes the data of IModel objects.

Table 3. Model block
Field Type Count Description

name_length

varint

1

Length of name field, in array elements

name

uint8[]

1

The UTF-8 byte sequence of the model name

parts

varint

1

Number of subsequent Part blocks
- or -
Flags of model and part

if parts >= 0

A bitmask that carries the following information:

0x000001 (bit 0)

Include ModelPartFlags.NoLighting @ version > 4
Exclude ModelPartFlags.NoLighting @ version < 5

0x000002 (bit 1)

ModelPartFlags.FrontFaces

0x000004 (bit 2)

ModelPartFlags.BackFaces

0x000008 (bit 3)

ModelPartFlags.Transparent

0x000010 (bit 4)

ModelPartFlags.VertexColorIsBaseColor

0x000020 (bit 5)

ModelPartFlags.VertexAlphaIsOcclusion

0x000040 (bit 6)

ModelFlags.ComplexGeometry @ version > 2

0x000080 (bit 7)

ModelFlags.Group

0x000100 (bit 8)

ModelFlags.NoSpatialQuery

0x07FE00 (bits 9..18)

IModelPart.Layer, encoded as a 10-bit signed integer

0x080000 (bit 19)

ModelFlags.Terrain @ version > 4

0x100000 (bit 20)

ModelPartFlags.Opaque @ version > 4

geometry

int64

1

Byte offset to the Geometry block for IModelPart.Geometry

material

int64

1

Byte offset to the Material block for IModelPart.Material

unit

object

1

Serialized UnitOfMeasure object for IModel.Unit

batch

Batch

1

Embedded Batch block for IModelPart.Batch

-

int8

1

Not used, should be 0 and must be ignored.

else-if parts < 0

Number of subsequent embedded Part blocks, encoded as: count = -1-parts @ version > 1

flags

varint

1

A bitmask that carries the following information:

part

Part

count

Embedded Part blocks for IModel.PartAt.

end-if

collider

Collider

1

The pre-computed spatial acceleration structure @ version > 2

fade

object

2

Serialized Fade values for IModel.FadeIn and IModel.FadeOut, in that order @ version > 3

children

varint

1

Number of subsequent Model blocks.

if children >= 0

Number of child models with 32-bit floating-point transformations, encoded as count = children

repeat count times

child

int64

1

Byte offset of index-th child Model block

matrix

Mat4F

1

The affine matrix that transforms from child to parent

end-repeat

else-if children < 0

Number of child models with 64-bit floating-point transformations, encoded as count = -1-children @ version > 1

repeat count times

child

int64

1

Byte offset of index-th child Model block

translation

Vec3D

1

Translation from child to parent

rotation

Mat3D

1

Rotation from child to parent (may include axis flip)

scaling

float64

1

The uniform scale factor from child to parent

end-repeat

…​

…​

…​

…​

end-if

Part

hourglass This section is not yet available, see roadmap for details.

Batch

hourglass This section is not yet available, see roadmap for details.

Collider

hourglass This section is not yet available, see roadmap for details.

Geometry

hourglass This section is not yet available, see roadmap for details.

Material

hourglass This section is not yet available, see roadmap for details.

Texture

hourglass This section is not yet available, see roadmap for details.

Compiled Shape (CSH)

hourglass This section is not yet available, see roadmap for details.

Digitally Licensed Content (LIC)

hourglass This section is not yet available, see roadmap for details.

Heightmap Cache (HGC)

hourglass This section is not yet available, see roadmap for details.

Heightmap Dataset (HGT)

hourglass This section is not yet available, see roadmap for details.

Pixel Buffer (PXB)

hourglass This section is not yet available, see roadmap for details.

Pixel Pyramid Cache (PYC)

hourglass This section is not yet available, see roadmap for details.

Pixel Pyramid Dataset (PYR)

hourglass This section is not yet available, see roadmap for details.

Serialized Object (SER)

hourglass This section is not yet available, see roadmap for details.

Terrain Database (TDB)

hourglass This section is not yet available, see roadmap for details.

hourglass This section is not yet available, see roadmap for details.

Texel Buffer (TXB)

hourglass This section is not yet available, see roadmap for details.


1. The official release that includes the change
2. The stable preview that includes the change