@kognifai/cogsengine
    Preparing search index...

    Cogs Model Format

    Version 1.0

    See CogsModel.h.

    • Performance
      • Reduced loading times
        • Zero processing overhead
        • Zero parsing overhead
        • Improved rendering performance
        • Memory friendly
          • Minimize number of allocations during loading
        • Concurrency possible
    • Maintenance
      • Simple specification
      • Simple implementation
      • Easy to implement exporters/importers/tools
    • Features
      • Most common formats are either way under- or over-specified
      • Support the features we need
        • Geometry
        • Materials
        • PBR
    • Ready-to-render
      • Require minimal or no processing during load
      • Binary data directly mappable to GPU
    • Animation
    • Compression
    • LODs
    • Streaming LODs
    • Embedded textures
    • Section/structure over alignment

    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.