OMA XML File Format Specification 0.1.11
-
Basic Information
- Root element tag: <oma> and </oma>
- The root node may contain any chunk elements.
-
Element Types
- Chunk:
- At the root of the document, a chunk's type is determined by the tag name. The presently available tag names are: text, int, short, byte, float, set, quat, matrix, mesh, object, bone, animation, tag, extension.
- A chunk referenced as a child of another will use the attribute type to instead define the chunk type. The tag name will instead be used to define how the chunk relates to the parent chunk.
- Attributes:
- id
- Type: Unsigned Integer
- Optional
- id
- Chunk of type text:
Each character will become an element of the string. The length of the string is the element count.
For example:<text>String Contents</text>
Will result in the C-style string "String Contents" (null terminated). - Chunk of type int, short, byte:
- Elements
Each element tag name will become an index in the resulting chunk element data. The number of different element tag names will define the width of the chunk element data. The first value given for any tag name will become the default value for any missing definitions later in the sequence. The contents of each element will be parsed as integer values.
For example, given int as the chunk type:<x>1</x><y>2</y>
<x>3</x><y>4</y>
<y>5</y>
Will result in a C-style int[3][2] array with the values { { 1, 2 }, { 3, 4 }, { 1, 5 } }.
- Elements
- Chunk of type float:
- Elements
Each element tag name will become an index in the resulting chunk element data. The number of different element tag names will define the width of the chunk element data. The first value given for any tag name will become the default value for any missing definitions later in the sequence. The contents of each element will be parsed as floating point values.
For example:<x>1.0</x><y>2.0</y>
<x>3.0</x><y>4.0</y>
<y>5.0</y>
Will result in a C-style float[3][2] array with the values { { 1.0f, 2.0f }, { 3.0f, 4.0f }, { 1.0f, 5.0f } }.
- Elements
- Chunk of type set:
- Elements
- item
- Attributes
- id
- Type: Unsigned Integer (ID of another chunk)
- Optional if type is specified
- type
- Type: String giving a chunk type
- Optional if id is specified
- id
<item id="5" /> <item type="text">Text<item>
Will result in a C-style OmapiId[2] array with the values { 5U, generated-id-for-child-chunk }. - Attributes
- item
- Elements
- Chunk of type quat:
- Elements
- item
- Attributes
- x
- Type: Floating Point
- Default Value: 0.0
- y
- Type: Floating Point
- Default Value: 0.0
- z
- Type: Floating Point
- Default Value: 0.0
- w
- Type: Floating Point
- Default Value: 1.0
- x
For example:
- Attributes
<item x="1" y="2" z="3" w="4" /> <item />
This will result in the following C-style definition:OmapiQuat quat[2] = { /* x y z w */ { 1.0f, 2.0f, 3.0f, 4.0f }, { 0.0f, 0.0f, 0.0f, 1.0f } }; - item
- Elements
- Chunk:
- Chunk of type matrix:
- Elements
- item
- Attributes
- Each attribute is given the form "m", followed by its column, followed by its row.
- m00
- Type: Floating Point
- Default Value: 1.0
- m10
- Type: Floating Point
- Default Value: 0.0
- m20
- Type: Floating Point
- Default Value: 0.0
- m30
- Type: Floating Point
- Default Value: 0.0
- m01
- Type: Floating Point
- Default Value: 0.0
- m11
- Type: Floating Point
- Default Value: 1.0
- m21
- Type: Floating Point
- Default Value: 0.0
- m31
- Type: Floating Point
- Default Value: 0.0
- m02
- Type: Floating Point
- Default Value: 0.0
- m12
- Type: Floating Point
- Default Value: 0.0
- m22
- Type: Floating Point
- Default Value: 1.0
- m32
- Type: Floating Point
- Default Value: 0.0
- m03
- Type: Floating Point
- Default Value: 0.0
- m13
- Type: Floating Point
- Default Value: 0.0
- m23
- Type: Floating Point
- Default Value: 0.0
- m33
- Type: Floating Point
- Default Value: 1.0
For example:
- Attributes
<item m00="2" m11="3" m22="4" m33="5" m30="6" />
This will result in the following C-style definition:OmapiMatrix matrix[1] = { { 2.0f, 0.0f, 0.0f, 0.0f }, { 0.0f, 3.0f, 0.0f, 0.0f }, { 6.0f, 0.0f, 4.0f, 0.0f }, { 0.0f, 0.0f, 0.0f, 5.0f } };Notice how the column-major storage results in the positioning of value m30. - item
- Elements
- Elements
- item
- Attributes
- type
- Type: String
- Possible Values: undefined, triangles, triangle stip, triangle fan, quads, quad strip, lines, line loop, polygon, points
- Default Value: undefined
- type
- Elements
- indices, vertices, attribs, texcoords, normals, colors, weights, weight_indices
- Quantity: one or fewer of each tag per item
- Attributes
- id
- Type: Unsigned Integer (ID of another chunk)
- Optional if type is specified
- type
- Type: String giving a chunk type
- Optional if id is specified
- id
- indices, vertices, attribs, texcoords, normals, colors, weights, weight_indices
For example:
- Attributes
<item type="triangles">
<vertices id="7" /></item>
<texcoords type="float">
<x>1.0</x></texcoords>
This will result in the following C-style definition:OmapiMesh mesh[1] = { { /* type: */ OMAPI_MESH_TYPE_TRIANGLES, /* index: */ 0U, /* vertex: */ 7U, /* attrib: */ 0U, /* texcoord: */ generated-id-for-child-chunk, /* normal: */ 0U, /* color: */ 0U, /* weight: */ 0U, /* weight_index: */ 0U } } - item
- Elements
- item
- Elements
- mesh, bone, material
- Quantity: one or fewer of each tag per item
- Attributes
- id
- Type: Unsigned Integer (ID of another chunk)
- Optional if type is specified
- type
- Type: String giving a chunk type
- Optional if id is specified
- id
- mesh, bone, material
- Elements
- item
- Elements
- item
- Elements
- The orientation matrix and position can be combined to describe a single 4x3 matrix.
- To get the orientation matrix relative to the parent bone, multiply the inverse of the parent bone's matrix by this bone's matrix.
- orientation
- Each orientation matrix is defined relative to the same space regardless of the number of parent bones.
- Quantity: one or fewer per item
- Attributes
- Each attribute is given the form "m", followed by its column, followed by its row.
- m00
- Type: Floating Point
- Default Value: 1.0
- m10
- Type: Floating Point
- Default Value: 0.0
- m20
- Type: Floating Point
- Default Value: 0.0
- m01
- Type: Floating Point
- Default Value: 0.0
- m11
- Type: Floating Point
- Default Value: 1.0
- m21
- Type: Floating Point
- Default Value: 0.0
- m02
- Type: Floating Point
- Default Value: 0.0
- m12
- Type: Floating Point
- Default Value: 0.0
- m22
- Type: Floating Point
- Default Value: 1.0
- position
- Each position is defined relative to the same space regardless of the number of parent bones.
- Quantity: one or fewer per item
- Attributes
- x
- Type: Floating Point
- Default Value: 0.0
- y
- Type: Floating Point
- Default Value: 0.0
- z
- Type: Floating Point
- Default Value: 0.0
- x
- item
- Quantity: zero or more per item
- A bone to be a descendant of this bone
- See chunk type bone's item.
For example, to define a bone with two children and one grandchild:
- Elements
<item>
<orientation m00="1.0" /></item>
<item>
<orientation m00="2.0" /></item>
<position x="1.0" />
<item>
<orientation m00="3.0" /></item>
<position x="1.0" y="1.0" />
<item>
<orientation m00="4.0" /></item>
<position x="-1.0" />
This will result in the following C-style definition:OmapiBone bones[4] = { { /* orientation: */ { { 1.0f, 0.0f, 0.0f }, { 0.0f, 1.0f, 0.0f }, { 0.0f, 0.0f, 1.0f } }, /* position: */ { 0.0f, 0.0f, 0.0f }, /* children: */ 2U }, { /* orientation: */ { { 2.0f, 0.0f, 0.0f }, { 0.0f, 1.0f, 0.0f }, { 0.0f, 0.0f, 1.0f } }, /* position: */ { 1.0f, 0.0f, 0.0f }, /* children: */ 1U }, { /* orientation: */ { { 3.0f, 0.0f, 0.0f }, { 0.0f, 1.0f, 0.0f }, { 0.0f, 0.0f, 1.0f } }, /* position: */ { 1.0f, 1.0f, 0.0f }, /* children: */ 0U }, { /* orientation: */ { { 4.0f, 0.0f, 0.0f }, { 0.0f, 1.0f, 0.0f }, { 0.0f, 0.0f, 1.0f } }, /* position: */ { -1.0f, 0.0f, 0.0f }, /* children: */ 0U } }; - item
- Elements
- item
- Attributes
- value_type
- Type: String
- Possible Values: undefined, translate, translate x, translate y, translate z, rotate, rotate x, rotate y, rotate z, scale, scale x, scale y, scale z, index
- Default Value: undefined
- object_type
- Type: String
- Possible Values: undefined, bone, object, mesh
- Default Value: undefined
- object_index
- Type: Integer
- Default Value: 0
- transition
- Type: String
- Possible Values: undefined, round down, round up, round nearest, linear, cubic
- Default Value: undefined
- value_type
- Elements
- times
- Quantity: one or fewer per item
- id
- Type: Unsigned Integer (ID of another chunk)
- Optional if type is specified
- type
- Type: String giving a chunk type
- Optional if id is specified
- values
- Quantity: one or fewer per item
- id
- Type: Unsigned Integer (ID of another chunk)
- Optional if type is specified
- type
- Type: String giving a chunk type
- Optional if id is specified
- times
For example, to define a simple animation that rotates the first bone fully around the Z-axis once in 1,000 time units:
- Attributes
<item value_type="rotate z" object_type="bone" object_index="0" >
<times type="int"></item>
<t>0</t></times>
<t>1000</t>
<values type="float">
<radians>0.0</radians></values>
<radians>6.283185307</radians>
- item
- Elements
- item
- Required: Yes
- Attributes
- label
- Type: String
- Required: Yes
- id
- Type: Unsigned Integer (ID of another chunk)
- Optional if type is specified
- type
- Type: String giving a chunk type
- Optional if id is specified
- label
For example:
<item label="one" id="1" />
<item label="two" type="float" />
<x>1.0</x></item>
Will result in a C-style OmapiTag[2] array with the values { { 1, "one" }, { generated-id-for-child-chunk, "two" } }. - item
- Elements
- item
- Elements
- fallback
- Type: Unsigned Integer
- Required: Yes
- type
- Type: Unsigned Integer
- Required: Yes
- version
- Type: Unsigned Integer
- Required: Yes
- name
- Type: String (maximum of 23 bytes when stored as UTF-8)
- Required: Yes
- fallback
- Elements
- item
Miscellaneous Notes
- Vertex order: counter-clockwise (anti-clockwise) is recommended.
- Any alpha color data is stored with 0% as transparent and 100% for opaque. For floats that would be 0.0f and 1.0f.
- Texture Coordinates
- X: 0.0f is the left, 1.0f is the right.
- Y: 0.0f is the bottom, 1.0f is the top.
- Z: 0.0f is the front, 1.0f is the back.
- Filename Extension: On filesystems where filename extensions are used to specify file type, an OMA XML file will be appended with ".omx" or perhaps ".xml".
