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.

DDS (pixel formats: RGB8, RGBA8, RGBA16F, DXT1, DXT3, DXT5 and a few other)
JPEG (baseline & progressive)
PNG
TGA
GIF
BMP (non-RLE)
PSD (RGB format only)
HDR

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}

DataBuffer

buffer used for compute purposes {*}

name	name of the buffer that will be used by the shader {required}
source	(file-)name of the compute buffer that contains the data {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" />
    <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}
tessellatable	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}
col_mult	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}

Compute

Compute scene node. Used for visualization of compute buffer data {*}

material	(file-)name of material resource {required}
computeBuffer	(file-)name of compute buffer resource {required}
elementsCount	number of vertices to draw {required}
drawType	specifies how to treat data in compute buffer. Possible values: triangles, lines, points {required}
aabbMinX	X position of the first point used for AABB creation {required}
aabbMinY	Y position of the first point used for AABB creation {required}
aabbMinZ	Z position of the first point used for AABB creation {required}
aabbMaxX	X position of the second point used for AABB creation {required}
aabbMaxY	Y position of the second point used for AABB creation {required}
aabbMaxZ	Z position of the second point used for AABB creation {required}

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>

ComputeBuffer Files

Filename-extension: .compute.xml

ComputeBuffer files are used to configure buffers that are processed on the GPU. The results of computing can also be visualized via Compute node. Currently only float data can be stored in compute buffer.

The following XML node elements with the described attributes are supported for a ComputeBuffer file:

ComputeBuffer

root element of the document {1}

dataSize	size of data to be processed (in bytes) {required}
drawable	specifies whether buffer contents can be renderer via Compute node {required}

Bindings

configuration of a vertex bindings (used for drawing)

name	id of the binding {required}
offset	number of bytes from the start of the buffer or previous vertex attribute {required}
size	number of components that are handled by this binding (for example, 4 means four floats) {required}
attribNumber	position of attributes in the buffer. Starts from 1 {required}

Data

data that will be stored in compute buffer. Only float type data is supported. Values are separated with semicolon (;) symbol. Last value should also be appended with ; symbol. New line, space and tabulation symbols are ignored.

Sample

<ComputeBuffer dataSize="800000" drawable="True">
    <Bindings name="partPosition" offset="0" size="4" attribNumber="1" />
    <Bindings name="partVelocity" offset="16" size="4" attribNumber="2" />
    <Data>
	-51.5535;-12.7655;70.6242;1;0.807698;0;2.94798;0;
	-24.599;-5.81407;-11.7187;1;-0.430079;0;4.51396;0;
	6.09182;-5.38925;-24.9027;1;-0.971359;0;-1.18809;0;
	19.7755;5.50008;58.1599;1;0.946767;0;-1.6096;0;
	9.45681;0.459008;-34.2102;1;-0.963852;0;-1.3322;0;
    </Data>
</ComputeBuffer>

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 for OpenGL 2 and 330 for OpenGL 4.

Version 5

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

header
joints (number of joints: #J)
vertices (number of vertices: #V)
triangle indices (number of triangle indices: #TI)
morph targets

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