Horde3D Data Format Reference

Texture Maps

Horde3D supports two dimensional texture maps and cube maps with up to four 8-bit color components, thus including an Alpha channel. It is recommended that texture maps have power of two dimensions (1, 2, 4, 8, 16, ..., 512, 1024, 2048) but this is no strict requirement. Newer graphics cards support textures with arbitrary sizes. If a graphics card doesn't have support for these so called NPOT textures Horde3D will convert the texture to a compatible size, although this can result in some visible stretching artifacts. Horde3D has also support for the Radiance RGBE format which makes it possible to use 16 bit floating point textures.
The engine can load the following image formats. Since Horde uses a pretty lightweight image loading library there are some limitations concerning exotic formats like 1 bpp textures.

JPEG (non-progressive)
PNG (non-interlaced)
TGA
BMP (non-RLE)
PSD (RGB format only)
HDR

Cube maps are stored with a special texture layout, a so called vertical cross, as can be seen in the following figure. The label PZ stands for positive z coordinate and is the front face of the cube map.

cubemap

Materials

Filename-extension: .material.xml

Materials are used to bind data to shaders. They can reference a shader and setup texture units with images. Furthermore materials can define shader uniforms which are four-dimensional float vectors with arbitrary user defined data. Materials can e.g. be used to define the appearance of a surface. Every material can have a class which is useful for accessing geometry with specific properties, e.g. translucency. Since the material 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 units 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}

TexUnit

configuration for a texture unit {*}

unit	index of the texture unit (Values: 0-11) {required}
map	name of the texture resource for the specified unit {required}
type	type of the texture map (Default: 2D) {optional} Values: 2D for standard texture maps and CUBE for cube maps
allowPOTConversion	true if texture may be converted to power-of-two dimensions on hardware without NPOT-support, otherwise false; (Default: true) {optional} Note: This flag is only respected if the texture isn't already loaded with an opposed flag setting
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
bilinear	true if texture shall use bilinear filtering, otherwise false; (Default: true) {optional} Note: This flag is only respected if the texture isn't already loaded with an opposed flag setting
repeatMode	true if texture shall be repeated for texture coordinates larger than one, otherwise false (clamping); (Default: true) {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" />
    <TexUnit unit="0" map="mytex.jpg" />
    <Uniform name="myColor" a="1.0" b="1.0" c="0.5" />
</Material>

Code Files

Filename-extension: arbitrary, usually .txt

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

Shaders

Filename-extension: .shader.xml

Shaders are used to create a plenty of different effects. A shader can generally be executed in different stages of the rendering pipeline. For that reason it is possible to define shader contexts. Horde3D uses an XML format to define shaders in the OpenGL Shading Language (GLSL). To make it easier to locate errors returned by the GLSL compiler, Horde3D uses a special system for encoding line numbers. Each DefCode and InsCode is considered as a block and gets a consecutive number starting at 1. The number of the block where an error occured is encoded as thousand and the actual line number inside this block as the rest. So if you get the message that there is an error in line 2023, you know that the problem is in the second block in line 23.

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

Shader

root element of the document {1}

Context

definition of a shader context

id	name of the context {required}

RenderConfig

configuration of rendering parameters; child of Context element {1}

writeDepth	enable writing to depth buffer (Values: false, true) (Default: true) {optional}
blendMode	blend function (Values: REPLACE, BLEND, ADD, ADD_BLENDED, MULT) (Default: REPLACE) {optional}

VertexShader

vertex shader created by concatenating code blocks; child of Context element {1}

FragmentShader

fragment shader created by concatenating code blocks; child of Context element {1}

DefCode

directly defines GLSL code block in CDATA section; child of VertexShader or FragmentShader element {*}

InsCode

inserts code block from a Code resource; child of VertexShader or FragmentShader element {*}

code

name of the Code resource {required}

Sample

<Shader>
    <Context id="OVERLAY">
        <VertexShader>
            <DefCode>
            <![CDATA[
                void main( void )
                {
                    gl_TexCoord[0] = gl_MultiTexCoord0;
                    gl_Position = gl_ModelViewProjectionMatrix * gl_Vertex;    
                }
            ]]>
            </DefCode>
        </VertexShader>
        
        <FragmentShader>
            <InsCode code="texUtils.txt" />
            <DefCode>
            <![CDATA[
                uniform sampler2D tex0;
            
                void main( void )
                {
                    vec4 albedo = getColor( tex0, gl_TexCoord[0].st );
                    gl_FragColor = albedo;
                }
            ]]>
            </DefCode>
        </FragmentShader>
    </Context>
</Shader>

For more information on available shader attributes see the pipeline documentation.

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 {*}

minDist	see GroupNodeParams {optional}
maxDist	see GroupNodeParams {optional}

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}

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}

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 {*}

pipelineRes	(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}
effect	(file-)name of 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.

Effect Files

Filename-extension: .effect.xml

Effect 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
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 an effect file:

ParticleConfig

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
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 + 1: With 4 joints you have to write 5 here
defaultTransformationMatrix	16 floats	default transformation matrix, most of the time this is a identity matrix. A matrix is written row by row
jointInverseBindMatrices	#J * 16 floats	inverse bind matrices for every joint, iff #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