format file syntax

Format file syntax

You are reading format file syntax page for versions 2.0.0+. There have been some changes compared to versions 1.0.0 - 1.1.1 that make this page no longer compatible with older version. For older versions see: format file syntax v1.0.0 or format file syntax v1.1.x

File structure

Format file consists of unit definitions.
Each unit consists of name, preamble and buffers surrounded with begin and end keywords.

begin name
preamble
buffer
buffer
buffer
end

Right after begin key-word, in the same line, name is specified. Next line always describes the preamble rest describe buffers 1 line - 1 buffer. End signifies the end of unit definition, it must be in a separate line right after last buffer definition.

Each buffer has it's own preamble and field definitions. Buffer preamble must be entirely described before any of the field definitions. They cannot be mixed up.

Example format file structure is as follows:

begin unit1
preamble
buffer_preamble field field field
buffer_preamble field field
buffer_preamble field field field field
end

begin unit2
preamble
buffer_preamble field 
buffer_preamble field field field
buffer_preamble field field field
end

File units and helper units

There are two types of units:

• file units
• helper units

Helper units are exactly as described in previous paragraph. They can be referenced by other helper and file units multiple times, allowing to avoid repeating definitions in .format file.

File units determine the structure of the output file(s). File units must be named file and require output file name specification after the name ("file").

Example file unit structure is as follows:

begin file file_name.out
preamble
buffer_preamble field field field
buffer_preamble field field
buffer_preamble field field field field
end

There can be more than one file units in the .format file. Useful for defining multiple differently structured output files to be extracted from single input file.

Pattern file naming

Single file unit can produce numerous output files hence the need for pattern file naming.

Pattern parameters are given in { }.
Available parameters:

• {file} - gets replaced by [file to compile] file name without the extension
• {scene} - gets replaced by scene name defined internally inside file to compile
• {mesh} - gets replaced by mesh name defined internally inside file to compile
• {skeleton} - gets replaced by skeleton name defined internally inside file to compile
• {animation} - gets replaced by animation name defined internally inside file to compile
• {channel} - gets replaced by bone name, defined internally inside file to compile, that is affected by this animation channel defined internally inside file to compile

Just use one or more of the pattern file naming parameters in output file name specification in file unit definition.

Examples:

• begin file {scene}_{mesh}.mesh
• begin file projekt-{mesh}.mesh
• begin file {file}.mesh

Using pattern file naming parameters is highly advised unless you are sure that input file contains only one mesh / skeleton / animation or whatever else you are trying to extract the from input file.

Print mode specifier _{^{since v2.2.0}}

You can specify weather output file should be plain test or binary with following key-words:

• plainText, plain_text, plain-text - outputs plain text file _{^{since v2.2.0}}
• binary - outputs binary file with system native endianness (default) _{^{since v2.2.0}}
• bigEndian / big-endian / big_endian - outputs binary file in big endian _{^{since v2.4.0}}
• littleEndian / little-endian / little_endian - outputs binary file in little endian _{^{since v2.4.0}}

Put the key-word right after output file name.

If unspecified binary option will be selected.

Examples

• begin file out.mesh plainText
• begin file {animation}.anim binary
• begin file {animation}.anim little-endian

Preambles

Preambles can be constructed form a set of key-words, constants and unit names.
Each key-word determines one (or more) value that will be written to the output file in a binary form.
Functionality of key-words depends on weather they describe buffer_preamble or main preamble.
Available key-words:

• buffu - buffers per unit
• buffs - buffer(s) size(s)
• entryu - entries per unit
• entryb - entries per buffer
• entrys - entry size(s)
• fieldu - fields per unit
• fieldb - fields per buffer
• fielde - fields per entry
• fields - field(s) sizes(s)

Values will be written to the output file in the same order as their corresponding key-words are written in .format file.

For information on what values exactly each of the key-words will write to the output file visit dedicated pages.

Types

Every key-word, constant, field might be preceded by a type specifier and a :. For example uint8:fieldb.

Available type specifiers:

• char - 1 byte character
• short, int2 - 2 byte integer
• int, int4 - 4 byte integer
• long, int8 - 8 byte integer
• ushort, unsigned_short, uint2, unsigned_int2 - 2 byte unsigned integer
• uint, unsigned_int, uint4, unsigned_int4 - 4 byte unsigned integer
• ulong, unsigned_long, uint8, unsigned_int8 - 8 byte unsigned integer
• float, float4 - 4 byte floating point
• double, float8 - 8 byte floating point
• long_double, float16 - 8 or 16 byte (depending on compiler) floating point

For default type specifiers for each key-word and field visit dedicated pages.

Constants

Constants might be declared anywhere (either in main preamble, buffer preamble or as a field) in the .format file. They allow for writing arbitrary values to the output file. As of v2.0.0 they must be preceded by type specifier, but there are plans to change that.

Examples: uint:213 - constant value of 213, float:0.125 - constant value of 0.125, or char:a - character 'a'.

constants will be written to the output file exactly as defined and in same order as defined. If defined in preamble they will be written only once. If defined as field they will be repeated according to field counting rules (depending on other fields declared as field values)

Fields

Field can be either a constant, unit reference or field value. In case of field value: field definition consists of a field type specifier and suffix(es).

Available field types:

• i, indice - indice

• 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

• bone_id - identifier of a bone that has an influence over the vertex _{^{since v2.1.0}}

• bone_weight - weight of an influence of the bone over the vertex _{^{since v2.1.0}}

• off_matr, off_matrix, offset_matr, offset_matrix - bone offset matrix _{^{since v2.0.0}}

• bone_parent - index of parent bone _{^{since v2.3.0}}

• bone_child - index of child bone _{^{since v2.3.0}}

• m_off_matr, m_off_matrix, m_offset_matr, m_offset_matrix - mesh bone offset matrix _{^{since v2.2.0}}

• m_bone_parent - index of parent bone _{^{since v2.3.0}}

• m_bone_child - index of child bone _{^{since v2.3.0}}

• position_key - position animation channel key-frame value _{^{since v2.0.0}}

• rotation_key - rotation animation channel key-frame value _{^{since v2.0.0}}

• scale_key - scaling animation channel key-frame value _{^{since v2.0.0}}

• position_time, position_timestamp, position_key_time, position_key_timestamp - position animation channel key-frame timestamp _{^{since v2.0.0}}

• rotation_time, rotation_timestamp, rotation_key_time, rotation_key_timestamp - rotation animation channel key-frame timestamp _{^{since v2.0.0}}

• scale_time, scale_timestamp, scale_key_time, scale_key_timestamp - scaling animation channel key-frame timestamp _{^{since v2.0.0}}

• duration - duration of the animation _{^{since v2.0.0}}

• ticks_per_second - ticks per second of the animation _{^{since v2.0.0}}

Available suffixes:

• 0, r, x, u - 1st component
• 1, g, y, v - 2nd component
• 2, b, z, w - 3rd component
• 3, a - 4th component
• 4 - 5th component
• 5 - 6th component
• 6 - 7th component
• 7 - 8th component

Field type can be followed by a dot (.) and paired with a suffix (eg. v.x - x component of a vertex position). Suffixes don't have types you can pair any suffix with any variable type (n.y, n.g, n.1 are equivalent - each defines 2nd or y component of normal vector).

Some field types allow for more than one suffix in such case each suffix must be preceded by a dot (.). (eg. uv.0.x - x component of texture coordinate set 0).

If field type was not followed by maximum supported amount of suffixes it will be repeated with every suffix. For example v is equivalent to v.x v.y v.z, and uv and is equivalent to uv.0.x uv.0.y uv.0.z uv.1.x uv.1.y uv.1.z uv.2.x .... Suffixes will be always in order 0, 1, 2...

For maximum amounts of suffixes supported by each of the field types visit their dedicated pages.

field type might be preceded by type specifier (eg. float4:vertex.x). For default types for each field type visit dedicated pages.

Field declaration will write many values to output file. How many depends on the mesh that is being processed as well as on declared field types. Read field counting rules for more info.

There must be at least one field in a buffer. Buffer with only constants or an empty one will return a buffer of only constants error.

Unit references _{^{since v2.0.0}}

helper units mentioned before can be referenced by other units. To reference a unit type it's name either in main preamble, buffer preamble or as a field definition in other unit.

Example

begin mesh

fieldb vertex
fieldb normal
end

begin extended_mesh

mesh fieldb ; tangent bitangent
end

begin file {mesh}.out
extended_mesh
end

I the above unit "mesh" is referenced by unit "extended_mesh" and unit "extended_mesh" is referenced by a file unit.

Unit must be defined before it is referenced.

In version 2.0.0 units can by named any way you want, but unit name, that collides with field type or a key-word causes an undefined behaviour (either unit will be referenced or a value of a field or key-word will be outputted). Since v2.1.0 .format interpreter throws error if such scenario happens.

one unit reference will write the entirety of the unit to the output file exactly as defined and in same order as defined. If defined in preamble they will be written only once per file. If defined as field they will be repeated according to field counting rules.

Buffer preamble end specifier _{^{since v1.1.0}}

Because constants, and unit references can be declared everywhere, it's not always obvious if they count as defined in preamble or as a field. For example consider the following:

buffs float:0.5 vertex.x

Where does the float:0.5 belong? In situations like these constants and unit references are by default assigned to preamble definition.
If you would like to incorporate them into fields definitions use buffer preamble end specifier: ;.

buffs ; float:0.5 vertex.x

In example above float:0.5 is a field definition. Buffer preamble end specifier must by separated by white-space characters.