format file syntax v1.1.x

Format file syntax v1.1.0 - v1.1.1

You are reading format file syntax page for versions 1.1.x. There have been some changes compared to version 1.0.0 that make this page no longer compatible with older version. For older version 1.0.0 refer to format file syntax v1.0.0

File structure

Format file consists of preamble and buffers.
1st line always describes the preamble rest describe buffers 1 line - 1 buffer.

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.

File structure is as follows:

preamble
buffer_preamble field field field
buffer_preamble field field
buffer_preamble field field field field

Preambles

Preambles can be constructed form a set of key-words and constants.
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:

• buffc
• buffs
• entrya
• entryc
• entrys
• fielda
• fielde
• fieldc
• fields

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.

Size and counting base

Additionally key-words might have attached size and counting base specification: eg. buffc2 or buffs4_4.
size determines on how many bytes should the value be written. counting base allows to reduce the value - value will be divided by counting base. counting base is only applicable to size values ( the ones ending with s eg. buffs )

Available sizes and counting bases are: 1, 2, 4 and 8.

By default (if not explicitly specified) size and counting base are set to 4.
You cannot specify counting base without specifying size. For example buffs_4 will return unknown statement error.

Constants _{^{since v1.1.0}}

Constants might be declared anywhere in the .format file. They allow for writing arbitrary values to the output file.
Available constant value types:

• 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
• f, float - 4 byte floating point
• double - 8 byte floating point
• float8 - 8 byte floating point _{^{since v1.1.1}}
• long_double - 8 or 16 byte (depending on compiler) floating point
• float16 - 8 or 16 byte (depending on compiler) floating point _{^{since v1.1.1}}

constant value type must be followed by : and a value (eg. 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 variable types)

Fields

Field definition consists of a type indicator and value or suffix. type can be either a variable type or a constant type (only 4 byte constants are supported)
Available types:

• variable types:
  • i, indice - indice
  • v, vertex - vertex
  • n, normal - normal
  • t, tangent - tangent
  • b, bitangent - bitangent
  • tex_coord - texture coordinate / uv set 0
  • uv0 - uv set 0
  • uv1 - uv set 1
  • uv2 - uv set 2
  • uv3 - uv set 3
  • uv4 - uv set 3
  • uv5 - uv set 5
  • uv6 - uv set 6
  • uv7 - uv set 7
  • vertex_color0 - vertex color 0 _{^{since v1.1.0}}
  • vertex_color1 - vertex color 1 _{^{since v1.1.0}}
  • vertex_color2 - vertex color 2 _{^{since v1.1.0}}
  • vertex_color3 - vertex color 3 _{^{since v1.1.0}}
  • vertex_color4 - vertex color 4 _{^{since v1.1.0}}
  • vertex_color5 - vertex color 5 _{^{since v1.1.0}}
  • vertex_color6 - vertex color 6 _{^{since v1.1.0}}
  • vertex_color7 - vertex color 7 _{^{since v1.1.0}}
• constant value types:
  • int, int4 - 4 byte integer _{^{since v1.1.0}}
  • uint, unsigned_int, uint4, unsigned_int4 - 4 byte unsigned integer _{^{since v1.1.0}}
  • f, float - 4 byte floating point

Available suffixes:

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

variable type field must 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).

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

At least one of the fields in a buffer must be of a variable type. Buffer with fields of only constants will return a buffer of only constants error. Buffer must also not be empty. It ust contain at least one field declaration.

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

Because constants 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:

buffs4_4 float:0.5 vertex.x

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

buffs4_4 ; float:0.5 vertex.x

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

Examples

#1

fielde i.0 i.1 i.2
fielde v.x v.y v.z float:1.0
fielde n.x n.y n.z float:0.0
fielde uv0.u uv0.v
fielde t.x b.x n.x t.y b.y n.y t.z b.z n.z

File above will produce:

• index list
• list of vertices in homogeneous coordinates
• list of normals in homogeneous coordinates
• list of texture coordinates form texture set 0
• list of inverted TBN matrices in column major storage format

Before each list the amount of values to read will be appended