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)
- See
This section is not yet available, see roadmap for details.
Block Storage (BST)
- See
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.
- See
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 |
|
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
| Field | Type | Count | Description |
|---|---|---|---|
magic |
int64 |
1 |
The magic value |
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.
| 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 |
if parts >= 0 |
A bitmask that carries the following information:
|
||
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 |
1 |
Embedded Batch block for IModelPart.Batch |
|
- |
int8 |
1 |
Not used, should be |
else-if parts < 0 |
Number of subsequent embedded Part blocks, encoded as: |
||
flags |
varint |
1 |
A bitmask that carries the following information: |
part |
count |
Embedded Part blocks for IModel.PartAt. |
|
end-if |
|||
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 |
||
repeat count times |
|||
child |
int64 |
1 |
Byte offset of index-th child Model block |
matrix |
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 |
||
repeat count times |
|||
child |
int64 |
1 |
Byte offset of index-th child Model block |
translation |
1 |
Translation from child to parent |
|
rotation |
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
This section is not yet available, see roadmap for details.
Batch
This section is not yet available, see roadmap for details.
Collider
This section is not yet available, see roadmap for details.
Geometry
This section is not yet available, see roadmap for details.
Material
This section is not yet available, see roadmap for details.
Texture
This section is not yet available, see roadmap for details.
Compiled Shape (CSH)
- See
This section is not yet available, see roadmap for details.
Digitally Licensed Content (LIC)
This section is not yet available, see roadmap for details.
Heightmap Cache (HGC)
- See
This section is not yet available, see roadmap for details.
Heightmap Dataset (HGT)
This section is not yet available, see roadmap for details.
Pixel Buffer (PXB)
- See
This section is not yet available, see roadmap for details.
Pixel Pyramid Cache (PYC)
See: PyramidFileCache
This section is not yet available, see roadmap for details.
Pixel Pyramid Dataset (PYR)
This section is not yet available, see roadmap for details.
Terrain Database (TDB)
Texel Buffer (TXB)
This section is not yet available, see roadmap for details.