UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

Mesh File Formats

Unigine supports the following mesh file formats for common and skinned meshes:

  • *.mesh, which is used for static geometry and animated characters.
  • *.anim, which contains animation for a skinned mesh (*.mesh file).

It is also possible to convert meshes of external formats to Unigine-supported mesh formats by using the MeshImport tool.

Here are some general notes that are valid for any mesh format.

  • All data is in the little-endian notation.
  • float is a 32-bit IEEE754 floating-point type. It has a range of 3.4 e-38 to 3.4 e+38.
  • int here is a compact signed integer.
    Notice
    To read / write compact integer values use readInt2() / writeInt2() methods respectively.
  • int32 is a signed 32-bit two's complement integer. It has a range of –2,147,483,648 to 2,147,483,647.
  • unsigned short is an unsigned 16-bit integer. It has a range of 0 to 65,535.
  • char is a signed 8-bit two's complement integer. It has a range of -128 to 127.
  • unsigned char is a 8-bit unsigned integer. It has a range of 0 to 255.
  • string must be null terminated. The string size should include this terminating null character.
  • All formats allow multiple surfaces.

Compression of Normals#

Compression of normalized floating-point normals into unsigned short format is performed in the following way:

Source code (UnigineScript)
x = (unsigned short)(clamp((int)((normal.x * 0.5f + 0.5f) * 65535.0f),0,65535));
y = (unsigned short)(clamp((int)((normal.y * 0.5f + 0.5f) * 65535.0f),0,65535));
z = (unsigned short)(clamp((int)((normal.z * 0.5f + 0.5f) * 65535.0f),0,65535));
Here:
  • normal is a normalized float normal.
  • x, y and z are unsigned short compressed normals.

Decompression of Animation Frames#

Frames' translations and scales that are compressed into the unsigned short format, can be decompressed as follows:

  • Decompression of the frame translations:
    Source code (UnigineScript)
    x = xyz_min.x + xyz_size.x * (compressed_position.x / 65535.0f);
    y = xyz_min.y + xyz_size.y * (compressed_position.y / 65535.0f);
    z = xyz_min.z + xyz_size.z * (compressed_position.z / 65535.0f);
    Here:
    • xyz_min is a bounding box minimum along X, Y and Z axes.
    • xyz_size is a bounding box size.
    • x, y and z are unsigned short compressed translations of the frame.
  • Decompression of the frame scales:
    Source code (UnigineScript)
    x = scale_min.x + scale_size.x * (compressed_scale.x / 65535.0f);
    y = scale_min.y + scale_size.y * (compressed_scale.y / 65535.0f);
    z = scale_min.z + scale_size.z * (compressed_scale.z / 65535.0f);
    Here:
    • scale_min is a bounding box minimum along X, Y and Z axes.
    • scale_size is a bounding box size.
    • x, y and z are unsigned short compressed scales of the frame.

Storing Meshes#

MESH is a universal file format for static and skinned geometry.

The skinned meshes can be stored as follows:

  • Containing both mesh data (vertices and their weights) and animation (bones and their transformations). This variant of storing mesh together with animation data in one file is less flexible and more memory consuming. Use it only for small animation sequences.
  • Containing only mesh data, i.e. the bind pose. This approach is useful, if you prefer to put additional animation out to separate files.
Notice
The first animation frame shouldn't contain the bind pose.

MESH File Format#

  1. File format identifier (int32 "ms11" ('m' | ('s' << 8) | ('1' << 16) | ('0' << 24)))
  2. Bounding volume of the whole mesh:
    • Mesh bounding box minimum (float[3])
    • Mesh bounding box maximum (float[3])
    • Mesh bounding sphere center (float[3])
    • Mesh bounding sphere radius (float)
  3. Number of bones (int)
  4. Header information for each bone:
    • Name of the bone. It is a null-terminated string that contains:
      1. The number of characters in the string including the null character (int).
      2. Bone name of the specified length (char[length]).
    • Parent of the bone. If case of the root bone without a parent, -1 is used. (short)
  5. Number of mesh animations (int)
  6. Header information for each animation:
    • Name of the animation. It is a null-terminated string that contains:
      1. The number of characters in the string including the null character (int).
      2. Animation name of the specified length (char[length])
  7. Number of surfaces (int)
  8. Header information for each surface:
    • Name of the surface. It is a null-terminated string that contains:
      1. The number of characters in the string including the null character (int).
      2. Surface name of the specified length (char[length])
    • Surface bounding box minimum (float[3])
    • Surface bounding box maximum (float[3])
    • Surface bounding sphere center (float[3])
    • Surface bounding sphere radius (float)
    • Number of the surface morph targets (int)
    • Header information for each morph target:
      1. Name of the morph target. It is a null-terminated string that contains:
        • The number of characters in the string including the null character (int).
        • Morph target name of the specified length (char[length])
  9. File format identifier (int32 "ms11" ('m' | ('s' << 8) | ('1' << 16) | ('0' << 24)))
  10. For each bone:
    • Bone position along X, Y, Z axes (float[3])
    • Bone rotation quaternion (float[4])
    • Bone scale in all directions(float[3])
  11. For each animation:
    • Number of bones taking part in the animation (int)
    • Indices of the bones taking part in the animation (short[length])
    • Flag (unsigned char), each 8 bits of which determine if the mesh animations should store translation, scale or rotation components for bones taking part in the animations.
    • Number of animation frames (int)
    • Transformation data for each bone in each frame:
      1. Flag (unsigned char), each 8 bits of which determine if the current frame should store new translation, scale or rotation components for the bone. If these components have not changed since the previous frame, new data is not stored. Instead, data from the previous frame is used, which maximizes the efficiency of memory usage.
      2. If the data is flagged as changed, for each component of the bone:
        • Translation of the bone along X (float)
        • Translation of the bone along Y (float)
        • Translation of the bone along Z (float)
        • Rotation quaternion (short[4])
        • X component of the bone scale (float)
        • Y component of the bone scale (float)
        • Z component of the bone scale (float)
  12. Data on each surface geometry:
    • Data on each morph target of the surface:
      1. Number of vertices in the morph target (int)
      2. Vertices of the morph target (float[3*length])
      3. Number of tangents (int)
      4. For each tangent:
        • X, Y, Z, and W components are of the short type and represent a quaternion.
    • Number of surface weights (int)
    • For each surface weight:
      1. Number of bones that affect the vertex (the maximum value is 4) (unsigned char)
      2. For each bone that affects the vertex:
        • Bone index (short)
        • Bone weight (unsigned short)
    • Number of texture coordinates in the 1st UV set (int)
    • For each of texture coordinates:
      1. 1st UV texture coordinates(float[2])
    • Number of texture coordinates in the 2nd UV set (int)
    • For each of texture coordinates:
      1. 2nd UV texture coordinates (float[2])
    • Number of 8-bit vertex colors (int).
    • For each color:
      1. Color value (char[4])
    • Number of coordinate indices (int)
    • Сoordinate indices for each vertex of the surface:
      1. If the zero morph target contains less than 256 coordinate vertices, all the indices are unsigned char[length]
      2. If the zero morph target contains less than 65536 coordinate vertices, all the indices are short[length]
      3. Otherwise, all the indices are int32[length]
    • Number of triangle indices (int)
    • Triangle indices for each vertex of the surface:
      1. If the zero morph target contains less than 256 triangle vertices, all the indices are unsigned char[length]
      2. If the zero morph target contains less than 65536 triangle vertices, all the indices are short[length]
      3. Otherwise, all the indices are int32[length]
  13. File format identifier (int32 "ms11" ('m' | ('s' << 8) | ('1' << 16) | ('0' << 24)))

Storing Skinned Mesh Animation#

Skinned mesh animation format contains only animation for skinned mesh MESH files. They are useless without a "base" skinned mesh in its bind pose that contains vertices and their weights.

ANIM files store animation data more efficiently than one skinned mesh MESH file containing both a mesh and bones transformations. That is the reason why ANIM files are ideal for long animations.

If you need to load such a file in a script, treat it like a MESH animation file.

ANIM File Format#

  1. File format identifier (int32 "an10" ('a' | ('n' << 8) | ('1' << 16) | ('0' << 24)))
  2. Bounding volume of the whole animation:
    • Bounding box minimum (float[3])
    • Bounding box maximum (float[3])
    • Bounding sphere center (float[3])
    • Bounding sphere radius (float)
  3. Number of bones in skinned animation (int)
  4. Header information for each bone:
    • Name of the bone. It is a null-terminated string that contains:
      1. The number of characters in the string including the null character (int).
      2. Bone name of the specified length (char[length])
    • Parent of the bone (short)
  5. Number of animations (int)
  6. Header information for each animation:
    • Name of the animation. It is a null-terminated string that contains:
      1. The number of characters in the string including the null character (int).
      2. Animation name of the specified length (char[length])
  7. File format identifier (int32 "an10" ('a' | ('n' << 8) | ('1' << 16) | ('0' << 24)))
  8. For each bone:
    • Bone position along X, Y, Z axes (float[3])
    • Bone rotation quaternion (float[4])
    • Bone scale in all directions(float[3])
  9. For each animation:
    • Number of animation bones (int)
    • Indices of the bones taking part in the animation (short[length])
    • Bounding box within which animation takes place:
      1. Bounding box within which the translation of animation bones is performed:
        • Bounding box minimum along X, Y and Z axes (float[3])
        • Bounding box size (float[3]).
      2. Bounding box within which the scaling of animation bones is performed:
        • Bounding box minimum along X, Y and Z axes (float[3])
        • Bounding box size (float[3]).
    • Flag (unsigned char), each 8 bits of which determine if the animations should store translation, scale or rotation components for bones taking part in the animations.
    • Number of animation frames (int)
    • Transformation data for each bone in each frame:
      • Flag (unsigned char), each 8 bits of which determine if the current frame should store new translation, scale or rotation components for the bone. If these components have not changed since the previous frame, new data is not stored. Instead, data from the previous frame is used, which maximizes the efficiency of memory usage.
      • If the data is flagged as changed, for each component of the bone:
        1. Translation of the bone along X (unsigned short)
        2. Translation of the bone along Y (unsigned short)
        3. Translation of the bone along Z (unsigned short)
        4. Rotation quaternion (short[4])
        5. X component of the bone scale (unsigned short)
        6. Y component of the bone scale (unsigned short)
        7. Z component of the bone scale (unsigned short)

        These position and rotation values are specified inside of the calculated bounding box: as a coordinate between its minimum and its maximum (a value in range from 0 to 65535).

  10. File format identifier (int32 "an10" ('a' | ('n' << 8) | ('1' << 16) | ('0' << 24)))
Last update: 2019-04-30