field counting rules

Introduction

Different field values exist in different amounts. For example mesh will usually have different amount of vertices and faces.

field types can be divided into counting groups based on amount of data they will output.

Counting groups:

• per scene:

  • per mesh:

    • per indice: (per face)

      • i, indice - indice (index of the vertex in face)

    • per vertex:

      • v, vertex - vertex
      • n, normal - normal
      • t, tangent - tangent
      • b, bitangent - bitangent
      • uv, tc, tex_coord, texture_coordinate - texture coordinate / uv set
      • vertex_color - vertex color _{^{since v1.1.0}}
      • bone_id _{^{since v2.1.0}}
      • bone_weight _{^{since v2.1.0}}

    • per mesh bone:

      • m_offset_matrix _{^{since v2.2.0}}

      • m_bone_parent _{^{since v2.3.0}}

      • per mesh bone child:

        • m_bone_child _{^{since v2.3.0}}

  • per skeleton:

    • per bone:

      • offset_matrix _{^{since v2.0.0}}

      • bone_parent _{^{since v2.3.0}}

      • per bone child:

        • bone_child _{^{since v2.3.0}}

  • per animation:

    • duration _{^{since v2.0.0}}

    • ticks per second _{^{since v2.0.0}}

    • per animation channel:

      • per position key frame:

        • position_key_timestamp _{^{since v2.0.0}}
        • position_key _{^{since v2.0.0}}

      • per rotation key frame:

        • rotation_key_timestamp _{^{since v2.0.0}}
        • rotation_key _{^{since v2.0.0}}

      • per scale key frame:

        • scale_key_timestamp _{^{since v2.0.0}}
        • scale_key _{^{since v2.0.0}}

Counting groups are defined in hierarchical manner. (eg. per vertex is child or sub counting group of per mesh counting group, per skeleton is a parent counting group of per bone counting group)

Fields of different counting groups cannot be present in the same buffer definition.
Fields that have different parent counting groups cannot be present in the same unit.

Constants do not collide with any counting group and can be added freely to any buffer definition. With only restriction that buffer must contain at least one filed that has a counting group in order to determine how many times to repeat the constant.

For example: Buffers with field definitions from per vertex group will write to output file as many entries as there are vertices.

Unit counting group

Units have implicitly assigned counting groups based on what field types and unit references where defined inside the unit.

If a field value or unit reference was defined in any of the buffers' field definitions, unit will have assigned a parent counting group of that field.
If there is a unit reference in any of the preambles, unit will have counting group of the referenced unit.

Example:

begin mesh

fieldb ; vertex
end

begin file {mesh}.mesh
mesh
end

In the above both units will be in per mesh counting group. "mesh" unit will be per mesh, because it has field of per vertex group defined (parent of per vertex is per mesh). file unit will be per mesh, because it is referencing a per mesh unit in a preamble.

Ultimately file unit's counting group will dictate how many output files will it produce. (eg. if counting group is of per mesh there will be as many files as there are meshes in processed input file.

Unit references of different counting groups cannot be present in the same buffer or the same preamble definition.
Unit reference defined in preamble that has a different counting group than one or more fields' parent counting groups cannot be present in the same unit.

Examples of collisions:

begin mesh

fieldb ; vertex
end

begin file {mesh}.mesh
mesh
fieldb ; mesh
end

In the above there is a collision in file unit. counting group (per mesh) of mesh unit referenced in preamble collides with parent counting group (per scene) of mesh unit referenced as a field

Entries

An entry is one repetition of all fields specified in one buffer in .format file. In the followig:

; vertex.x vertex.y vertex.z

vertex.x vertex.y vertex.z make up one entry.

Example

; vertex.x vertex.y vertex.z

Suppose mesh has 100 vertices. The above will output 100 entries 3 fields each. Meaning the output file will have 100×3=300 floating point values (4 bytes each). File will have total size of 300×4=1200 bytes.