Version 1.0
See CogsModel.h.
Overall file structure:
Each line in the overall file structure is referred to as a section.
CogsHeader header;
CogsDescriptor descriptor;
uint8_t stringBytes[descriptor.numStringBytes];
CogsString strings[descriptor.numStrings];
uint8_t propertyBytes[descriptor.numPropertyBytes];
CogsProperty properties[descriptor.numProperties];
CogsStream streams[descriptor.numStreams];
CogsMesh meshes[descriptor.numMeshes];
CogsMaterial materials[descriptor.numMaterials];
CogsBounds nodeBounds[descriptor.numNodes];
CogsNode nodes[descriptor.numNodes];
uint8_t data[descriptor.dataSize];
Each section in the file must be aligned by the value defined by CogsSectionAlignment, which for version 1.0 is set to 16.
To obtain aligned section pointers from a raw memory pointer (assumed to be over-aligned):
// base is byte pointer (char*)
auto dataPtr = base + sizeof(CogsHeader) + sizeof(CogsDescriptor);
for each section {
const auto currentAlignment = static_cast(dataPtr) % CogsSectionAlignment;
const auto offset = CogsSectionAlignment - currentAlignment;
dataPtr = dataPtr + offset;
// Use/copy section data from dataPtr
// ....
dataPtr += descriptor.num... * sizeof(Cogs... or uint8_t);
}
The header contains information to identify and distinguish different Cogs model format versions and variants.
struct CogsHeader
{
uint32_t magic;
uint32_t version;
uint32_t length;
uint32_t flags;
};
magic
magic contains the four-byte identifier 0xC065C065.
version
version contains the version of the model file. The version must be use to select a suitable way to read the file contents. All structures except CogsHeader may change between versions.
length
length contains the number of bytes making up the model.
flags
flags contains flags used to select parsing features.
Reserved for future use.
The descriptor contains information about all the subsequent sections. The size of each section may be calculated from the number of objects in the section and the size of the corresponding object (stream, mesh, node etc.).
struct CogsDescriptor
{
uint32_t firstMetadataProperty;
uint32_t numMetadataProperties;
uint32_t numStringBytes;
uint32_t numStrings;
uint32_t numPropertyBytes;
uint32_t numProperties;
uint32_t numStreams;
uint32_t numMeshes;
uint32_t numMaterials;
uint32_t numNodes;
uint32_t dataSize;
uint32_t reserved;
};
firstMetadataProperty
firstMetadataProperty contains the index of the first metadata property. See Properties.
numMetadataProperties
numMetadataProperties contains the total number of metadata properties. See Properties.
numStringBytes
numStringBytes contains the total number of bytes contained in the stringBytes section.
numStrings
numStrings contains the total number of CogsString structures in the strings section.
numPropertyBytes
numPropertyBytes contains the total number of property bytes contained in the propertyBytes section.
numProperties
numProperties contains the total number of CogsProperty structures in the properties section.
numStreams
numStreams contains the total number of CogsStream structures in the streams section.
numMeshes
numMeshes contains the total number of CogsMesh structures in the meshes section.
numMaterials
numMaterials contains the total number of CogsMaterial structures in the materials section.
numNodes
numNodes contains the total number of CogsNode structures in the nodes section.
dataSize
dataSize contains the total number of bytes contained in the data section.
reserved
This field is reserved.
The string structure defines a single string as a view to actual string data, packed in the stringBytes section.
struct CogsString
{
uint32_t start;
uint32_t length;
};
start
start contains the index of the first byte belonging to this string.
length
length contains the length of the string, not including any \0 byte termination.
The property structure defines a single key:value property.
struct CogsProperty
{
uint16_t keyType;
uint16_t valueType;
uint32_t key;
uint32_t value;
};
keyType
The keyType field must be one of the types contained in the CogsPropertyKeyType enumeration.
enum CogsPropertyKeyType
{
Index,
String
};
valueType
The valueType field must be one of the types contained in the CogsPropertyFormat enumeration.
enum CogsPropertyFormat
{
Int,
Int2,
Int3,
Int4,
UInt,
UInt2,
UInt3,
UInt4
Float,
Float2,
Float3,
Float4,
String,
Variant,
Permutation
};
key
If the keyType field is CogsPropertyKeyType::Index, key is a context dependent index. For example, a material may specify that a property with key == 0 represents its specular power value.
If the keyType field is CogsPropertyKeyType::String, key is an index of a string instance in the strings section.
value
If the valueType field is any of the integral, scalar, or vector values, the value field contains the offset in bytes used to calculate the location of the property value in the property data.
For example, given a CogsProperty instance property, with valueType = float, and value = 0x1234, the property value may be calculated as follows:
float propertyValue = *reinterpret_cast(propertyData + property.value);
Properties of type Variant and Permutation are key/value string pairs. Usage is implementation-defined.
The usage of variants and permutations may be formalized along with the possible keys and values for material types and properties.
The stream structure defines a single data stream with vertex or index data.
struct CogsStream
{
uint32_t format;
uint32_t offset;
uint32_t size;
};
format
format must be one of the data formats defined in the CogsVertexFormat enumeration.
enum CogsVertexFormat
{
Positions3f,
Normals3f,
Tangents3f,
TexCoordsf,
Color4f,
Indexes16,
Indexes32
};
offset
offset contains the offset in bytes from the start of the data section to the stream data.
size
size contains the size in bytes of the stream data found at offset.
To obtain the number of vertex data or index data elements the size field must be divided by the size of an individual element with the streams format.
const size_t numPositionElements = positionStream.size / sizeof(float3);
The mesh structure defines a single mesh instance, containing a number of streams holding vertex and optional index data.
Mesh data winding order is by default counter-clockwise. Winding order may be switched by setting the CogsMeshFlags::ClockwiseWinding flag.
struct CogsMesh
{
uint32_t nameIndex;
uint16_t primitiveTopology;
uint16_t flags;
uint32_t firstStream;
uint32_t lastStream;
float[3] boundsMin;
float[3] boundsMax;
};
nameIndex
nameIndex contains an index into the strings section to a string containing the name of the mesh. If no name string is present, nameIndex is set to uint32_t(-1);
primitiveTopology
primitiveTopology contains the primitive topology type used to rasterize the mesh data.
Valid primitive topology values are specified in the CogsPrimitiveTypes enumeration:
enum CogsPrimitiveTopology
{
PointList
LineList,
LineStrip,
TriangleList,
TriangleStrip
LineListAdjacency,
LineStripAdjacency,
TriangleListAdjacency,
TriangleStripAdjacency,
ControlPointPatchList0
...
ControlPointPatchListN
}
flags
flags contains mesh flags specifying how to interpret the mesh data, e.g. winding order.
Valid flags are specified in the CogsMeshFlags enumeration:
enum CogsMeshFlags
{
None,
ClockwiseWinding
}
firstStream
firstStream contains the index of the first data stream in the streams section belonging to the mesh. All following streams indexes up to and including lastStream belong to the same mesh.
lastStream
lastStream contains the index of the last data stream in the streams section belonging to the mesh.
boundsMin
boundsMin contains [x, y, z] coordinates in model space for the min corner of an axis-aligned bounding box surrounding all vertex positions of the mesh.
boundsMax
boundsMin contains [x, y, z] coordinates in model space for the max corner of an axis-aligned bounding box surrounding all vertex positions of the mesh.
The material structure defines a single material instance. A material instance is an instance created from a material type (also called template), with associated property values.
The types of materials, material flags, and properties is implementation defined for version 1.0.
struct CogsMaterial
{
uint32_t type;
uint32_t flags;
uint32_t firstProperty;
uint32_t lastProperty;
};
type
type contains the index of the string in the strings section with the material type name.
flags
flags contains bit flags controlling material instance behavior.
firstProperty
firstProperty contains the index of the first property in the properties section belonging to the material. All following properties up to and including lastProperty belongs to the same material instance.
lastProperty
lastProperty contains the index of the last property in the properties section belonging to the material.
The bounds structure defines bounding coordinates of an object.
struct CogsBounds
{
glm::vec3 min;
glm::vec3 max;
};
min
Minimum coordinates.
max
Maximum coordinates.
The node structure defines a single node instance in the model hierarchy, with transform and hierarchy data, and optional mesh and material data.
struct CogsNode
{
uint32_t parent;
uint32_t nameIndex;
uint32_t meshIndex;
uint16_t materialIndex;
uint16_t flags;
uint32_t startIndex;
uint32_t vertexCount;
uint32_t boundsIndex;
uint32_t reserved;
glm::vec4 translation;
glm::quat rotation;
glm::vec4 scale;
};
parent
parent contains an index into the nodes section to the parent node of this instance. If the node is at root level and has no parent the field must be set to uint32_t(-1).
nameIndex
nameIndex contains an index into the strings section to the string containing the name of the node. If the node has no name, nameIndex must be uint32_t(-1).
meshIndex
meshIndex contains an index into the meshes section to a mesh attached to the node. The mesh should be rendered using the material specified by the materialIndex field.
If no mesh is attached, meshIndex must be uint32_t(-1).
materialIndex
materialIndex contains an index into the materials section to the material used to render the attached mesh.
If no mesh is attached, materialIndex must be uint32_t(-1), otherwise it must point to a valid material.
flags
flags specifies behavior for the node.
Reserved for future use.
startIndex
Starting vertex index in the corresponding mesh to begin rendering at.
If the assigned mesh is indexed, this field is an offset in the index array, otherwise it is an offset into the vertex stream(s).
vertexCount
The number of vertexes/indexes to render.
boundsIndex
boundsIndex contains an index into the nodeBounds section to bounds data for the node.
translation
translation contains [x, y, z] coordinates used to translate the node relative to its parent transform.
rotation
rotation contains a quaternion [x, y, z, w] used to rotate the node relative to its parent transform.
scale
scale contains [x, y, z] coordinates used to scale the node relative to its parent transform.