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.
For loading texture images the engine uses the Corona image library. For this reason Horde3D can load the following image formats:

Cube maps are stored with a special texture layout, a so called horizontal cross, as can be seen in the following figure:

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. In Horde3D materials are specified with a 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}
Shader shader used for rendering {0, 1}
name name of the shader resource {required}
TexUnit configuration for a texture unit {*}
unit index of the texture unit (Values: 0-7) {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
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
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 name="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).

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) (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}
px, py, pz position 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 filename of the scene graph resource {required}
Model Model scene node {*}
geometry filename of the geometry resource {required}
Mesh Mesh scene node {*}
material filename 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 filename of the light material {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 {*}
fov see CameraNodeParams {optional}
aspect see CameraNodeParams {optional}
nearDist see CameraNodeParams {optional}
farDist see CameraNodeParams {optional}
Emitter Emitter scene node {*}
material filename of material resource {required}
effect filename 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 and Animations

Filename-extensions: .geo and .anim

The file formats for geometry and animations are binary formats and have to be created with a suitable tool like the Collada Converter described below. A geometry resource contains raw vertex and triangle data as well as information on the skeleton of a model and up to four weights per vertex for skinning. The animation resource consists of sampled animation data for the joints and meshes of a model.

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



Copyright © 2006-2007 Nicolas Schulz