Horde3D Data Format Reference

Texture Maps

Horde3D supports two-dimensional textures and cube maps. 2D textures can be loaded from the Direct3D DDS format or from any other image format listed below. Cube maps need to be stored in the DDS format. In contrast to other image formats, DDS files can store mipmaps and DXT compressed data. Therefore, the texture-related resource flags for mipmap generation and compression are ignored for DDS textures.
In order to guarantee optimal loading performance for DDS textures, Horde3D uses the D3D texture coordinate system convention where the origin is at the top left corner of the image. This is different from the OpenGL coordinate system which defines the image origin as the lower left corner. For that reason, texture coordinates for 2D texture maps need to be flipped manually in the shaders.

The engine can load the following image formats. Since Horde3D uses a pretty lightweight image loading library, there are some limitations concerning exotic formats like 1 bpp textures.

Materials

Filename-extension: .material.xml

Materials are used to bind data to shaders. They can reference a shader and setup texture samplers with images. They can also define shader uniforms which are four-dimensional float vectors with arbitrary user defined data. Materials are also responsible for setting shader flags which are used to select a shader combination from an übershader.
A material can for example be used to define the appearance of a surface. Every material can have a class string which is useful for accessing geometry with specific properties, e.g. translucency. Since the material class system is hierarchical, names can contain subclasses which are separated from the parent class using a dot character. A further feature of the material system is that a single material can link to another material to use its texture samplers and uniforms. This is useful to define global data (e.g. ambient lighting settings) at a single location.
In Horde3D materials are specified with an XML syntax.

The following XML node elements with the described attributes are supported:

Material root element of the document {1}
class hierarchical class name (Default: empty string) {optional}
link link to other material (Default: empty string) {optional}
Shader shader used for rendering {0, 1}
source name of the shader resource {required}
ShaderFlag definition of a shader flag {*}
name name of the shader flag to be set {required}
Sampler configuration of a texture sampler {*}
name name of the sampler as used in the hardware shader code {required}
map name of the texture resource for the specified unit {required}
allowCompression true if texture may be compressed, otherwise false; (Default: true) {optional}
Note: This flag is only respected if the texture isn't already loaded with an opposed flag setting
mipmaps true if texture shall use mipmaps, otherwise false; (Default: true) {optional}
Note: This flag is only respected if the texture isn't already loaded with an opposed flag setting
sRGB true if texture is in sRGB space and should be converted to linear space when sampled, otherwise false; (Default: false) {optional}
Note: This flag is only respected if the texture isn't already loaded with an opposed flag setting
Uniform definition of a four-dimensional vector shader uniform {*}
name name of the uniform {required}
a value of first component (Default: 0.0) {optional}
b value of second component (Default: 0.0) {optional}
c value of third component (Default: 0.0) {optional}
d value of fourth component (Default: 0.0) {optional}

Sample

<Material class="Translucent.MyClass">
    <Shader source="myshader.shader.xml" />
    <Sampler name="albedoMap" map="mytex.jpg" />
    <Uniform name="myColor" a="1.0" b="1.0" c="0.5" />
</Material>

Pipeline Files

Filename-extension: .pipeline.xml

Pipeline files are used to configure the rendering pipeline. A detailed description can bed found in the pipeline documentation.

Shader Files

Filename-extension: .shader

Shader files define render states and hardware shader code. A detailed description can bed found in the pipeline documentation.

Code Files

Filename-extension: arbitrary, usually .glsl

Code files are pure text files that can be used to define shader code. These files can be referenced by shader resources.

Scene Graph Files

Filename-extension: .scene.xml

Scene graph files are XML documents that define a subtree of the scene graph.

Each scene node defined as XML element can have the following XML attributes:

name name of the node {optional}
tx, ty, tz translation of the node {optional}
rx, ry, rz rotation of the node in Euler angles (degrees) {optional}
sx, sy, sz scale of the node {optional}

The following XML elements and attributes are supported for defining the scene nodes.

Group Group scene node {*}
Reference reference to another scene graph resource that shall be included in the scene graph at the specified position in the tree hierarchy {*}
name (if specified) and transformation of Reference node are taken over for root node of referenced scene structure
sceneGraph (file-)name of the scene graph resource {required}
Model Model scene node {*}
geometry (file-)name of the geometry resource {required}
softwareSkinning see ModelNodeParams {optional}
lodDist1 see ModelNodeParams {optional}
lodDist2 see ModelNodeParams {optional}
lodDist3 see ModelNodeParams {optional}
lodDist4 see ModelNodeParams {optional}
Mesh Mesh scene node {*}
material (file-)name of the material resource {required}
batchStart first vertex index in geometry resource of parent model {required}
batchCount number of vertex indices in geometry resource of parent model {required}
vertRStart minimum vertex array index contained in indices of geometry resource of parent model {required}
vertREnd maximum vertex array index contained in indices of geometry resource of parent model {required}
lodLevel see MeshNodeParams {optional}
Joint Joint scene node {*}
jointIndex index of joint in geometry resource of parent model {required}
Light Light scene node {*}
material (file-)name of the light material resource {optional}
lightingContext name of the shader context used for lighting {required}
shadowContext name of the shader context used for shadow map rendering {required}
radius see LightNodeParams {optional}
fov see LightNodeParams {optional}
col_R see LightNodeParams {optional}
col_G see LightNodeParams {optional}
col_B see LightNodeParams {optional}
shadowMapCount see LightNodeParams {optional}
shadowSplitLambda see LightNodeParams {optional}
shadowMapBias see LightNodeParams {optional}
Camera Camera scene node {*}
pipeline (file-)name of pipeline resource used for rendering {required}
outputTex see CameraNodeParams {optional}
outputBufferIndex see CameraNodeParams {optional}
leftPlane see CameraNodeParams {optional}
rightPlane see CameraNodeParams {optional}
bottomPlane see CameraNodeParams {optional}
topPlane see CameraNodeParams {optional}
nearPlane see CameraNodeParams {optional}
farPlane see CameraNodeParams {optional}
orthographic see CameraNodeParams {optional}
occlusionCulling see CameraNodeParams {optional}
Emitter Emitter scene node {*}
material (file-)name of material resource {required}
particleEffect (file-)name of particle effect resource {required}
maxCount maximal number of particles {required}
respawnCount number of times a particle is reborn (-1 for inifinite) {required}
delay see EmitterNodeParams {optional}
emissionRate see EmitterNodeParams {optional}
spreadAngle see EmitterNodeParams {optional}
forceX see EmitterNodeParams {optional}
forceY see EmitterNodeParams {optional}
forceZ see EmitterNodeParams {optional}

The XML document can have an arbitrary scene node as root element.

ParticleEffect Files

Filename-extension: .particle.xml

ParticleEffect files are used to configure particles of a particle system. Each particle has a randomly selected life time which is assigned when the particle is created. This time is continually decreased and when it is equal to zero the particle has died and can possibly be reborn. The particle has several channels defining its properties over the life time. The following channels are available:

moveVel - Velocity defining how many units per second particle is moving
rotVel - Velocity defining how many degrees per second particle is rotating
drag - Amount of velocity that particles inherit from emitter; if value is positive, particles move in same direction as the emitter
size - Size of the particle in generic units
colR - Color red intensity between 0.0 and 1.0
colG - Color green intensity between 0.0 and 1.0
colB - Color blue intensity between 0.0 and 1.0
colA - Color alpha intensity between 0.0 and 1.0

The following XML node elements with the described attributes are supported for a particle-effect file:

ParticleEffect root element of the document {1}
lifeMin minimum value for selecting random life time {required}
lifeMax maximum value for selecting random life time {required}
ChannelOverLife configuration of a channel
channel id of the channel {required}
startMin minimum value for selecting random initial value {required}
startMax maximum value for selecting random initial value (Default: startMin) {optional}
endRate percentage of the initial value when particle is dying (Default: 1.0) {optional}

Sample

<ParticleConfig lifeMin="4.0" lifeMax="7.0">
    <ChannelOverLife channel="moveVel" startMin="3.0" startMax="3.0" endRate="0.0" />
    <ChannelOverLife channel="colR" startMin="0.4" startMax="0.4" endRate="0.5" />
</ParticleConfig>

Geometry

Filename-extensions: .geo

The file format for geometry is a binary format and has to be created with a suitable tool like the Collada Converter described above. A geometry resource contains the raw vertex data with optional morph targets organized as streams. Furthermore it contains the triangle data as well as information about the skeleton of a model.

Important Note: Currently the maximum number of joints for skeletal animation is limited to 75.

Version 5

The file format is based on streams. The streams are written in that order:

Header File header at beginning of the file
magic 4 chars byte sequence 'H3DG'
version int version number: 5
Joints Joint stream, just after the header
numJoints int #J: Number of joints. It can make sense to have an additional default joint as first joint that is used if a vertex has no explicit joint assignment (joint index 0 at vertex). This joint usually has the identity matrix as inverse bind matrix.
jointInverseBindMatrices #J * 16 floats inverse bind matrices for every joint, if #J is zero nothing is written here
Vertices Vertex stream, just after the joint stream
numVertexStreams int number of parts of your vertex data. If you want to write only position and normals write 2 here.
The default implementation uses 6 (no joints) or 8 (with joints) to write:
  • position
  • normals
  • tangents
  • bitangents
  • joint indices (only with joints)
  • joint weights (only with joints)
  • texture coordinates, set 0
  • texture coordinates, set 1
numVertices int Number of vertices #V
Vertices - positions May be written at any position inside the vertex stream
magic int position identifier, write 0
streamElementSize int size of one element of the stream. Here 12
positions #V * 3 floats Write position data as contiguous array of X0,Y0,Z0,X1,Y1,Z1,...
Vertices - normals May be written at any position inside the vertex stream
magic int normal identifier, write 1
streamElementSize int size of one element of the stream. Here 6
normals #V * 3 shorts Write normal data as contiguous array of X0,Y0,Z0,X1,Y1,Z1,...
To save space normals are stored as shorts. Before writing multiply your float with 32767 and convert it then to short
Vertices - tangents May be written at any position inside the vertex stream
magic int tangent identifier, write 2
streamElementSize int size of one element of the stream. Here 6
tangents #V * 3 shorts Write tangent data as contiguous array of X0,Y0,Z0,X1,Y1,Z1,...
To save space tangents are stored as shorts. Before writing multiply your float with 32767 and convert it then to short
Vertices - bitangents May be written at any position inside the vertex stream
magic int bitangents identifier, write 3
streamElementSize int size of one element of the stream. Here 6
bitangents #V * 3 shorts Write bitangent data as contiguous array of X0,Y0,Z0,X1,Y1,Z1,...
To save space bitangents are stored as shorts. Before writing multiply your float with 32767 and convert it then to short
Vertices - joint indices May be written at any position inside the vertex stream
magic int joint indices identifier, write 4
streamElementSize int size of one element of the stream. Here 4
jointIndices 4 unsigned chars joint indices of current vertex (up to 4); a 0 means unused
Vertices - joint weights May be written at any position inside the vertex stream
magic int joint weights identifier, write 5
streamElementSize int size of one element of the stream. Here 4
jointWeights 4 unsigned chars To save space joint weights are stored as unsigned chars. Before writing multiply your float with 255 and convert it then to unsigned char
Vertices - texture coordinates set 0 May be written at any position inside the vertex stream
magic int texture coordinates set 0 identifier, write 6
streamElementSize int size of one element of the stream. Here 8
textureCoordinates #V * 2 floats Write texture coordinate data as contiguous array of U0,V0,U1,V1,,...
Vertices - texture coordinates set 1 May be written at any position inside the vertex stream
magic int texture coordinates set 1 identifier, write 7
streamElementSize int size of one element of the stream. Here 8
textureCoordinates #V * 2 floats Write texture coordinate data as contiguous array of U0,V0,U1,V1,,...
Triangle indices Triangle index stream, just after the vertex stream
numTriangleIndices int number of triangle indices
triangleIndices #TI ints
Morph targets Morph target stream, just after the triangle index stream
numMorphTargets int number of morph targets. If numMorphTargets == 0 then this is the only entry of the morph target stream.
For each morph target:
morphTargetName 256 chars morph target name, must be null terminated
numMorphVertices int number of vertices which differ between base vertices and morph target
morphVertexIndices numMorphVertices ints indices of the vertices which should be morphed
numMorphStreams int number of parts in morph vertex data. The default implementation uses 4.
  • positions
  • normals
  • tangents
  • bitangents
The content of the morph streams stores difference vectors relative to the base data.

Animation

Filename-extensions: .anim

The animation resource consists of sampled animation data for the joints and meshes of a model.

Version 3

Header File header at beginning of the file
magic 4 chars byte sequence 'H3DA'
version int version number: 3
numAnimations int number of animated joints and meshes
numFrames int number of frames
Animation data Animation data, just after header repeated numAnimations times for all animated nodes. Nodes that have no animation don't need to be stored in the animation file. Animation data is sampled, meaning that all nodes must have the same number of frames, namely numFrames. The format supports a simple compression scheme for nodes that have the same transformation for all frames. If the compression flag is set to 1, only one single transformation is stored for the corresponding animated node.
nodeName 256 chars node name, must be null terminated
compressed 1 char compression flag: 0 for no compression, 1 for compression
rotation 4 floats rotation quaternion: x, y, z, w
translation 3 floats translation vector: x, y z
scale 3 floats scale vector: x, y, z