Horde3D Usage Guide

Introduction

Horde3D isn't intended to be an enormous class library as many other graphics engines. While being heavily object-oriented internally, it offers a simple and intuitive C-style DLL interface for applications. This makes it easy to use the engine from almost any programming and scripting language without much conversion effort. So the focus of Horde3D is rather on good usability than on easy extensibility, although the latter is basically also possible. The engine core offers functions in a rather abstract way for maximizing flexibility and keeping the API small and clean. To make some of the abstract functions easier to use, there is the Horde3D utility library which is a layer above the engine.

API functions
Utility functions



Conventions

Horde3D uses a right-handed coordinate system, where y is the up-axis and the positive z-axis is pointing out of the screen. The rotations are specified in degrees and rotation direction is counter-clockwise when looking down the axis from the the positive end towards the origin. View vectors like the camera or light direction are always pointing along the negative z-axis when no transformation is applied. Matrices in Horde are stored in a column-major memory layout.



Basic concepts

The Horde3D API uses two types of objects, namely resources and scene graph nodes. These objects are constructed with special creation functions which return a handle to the object (basically just an ID). This handle can later be used to access the object in appropriate functions for setting its properties or destroying it. The scene is always rendered from the perspective of a virtual camera. There are functions with which you can set the camera frustum and transformation.

Basic engine functions



Resource management

The engine distinguishes between resource data and concrete instances of that data in the scene. Resources are data blocks which are loaded from a file, an archive or any similar source. They can be referenced by scene nodes. The advantage of this separation is obvious: Resources only have to be loaded once and can afterwards be instanced an arbitrary number of times in the scene without the costly need of reloading redundant data. The following resource types are available:

SceneGraph, Geometry, Animation, Material, Code, Shader, Texture2D, TextureCube

The resources are managed by a resource manager. Some resource types like materials can depend on other resources. To make the manager robust it is using some sort of garbage collection with reference counting. Resources can only be removed if they are not referenced by other resources or a scene node. Horde3D offers a special function that can be called to free all resources that are no longer referenced.

When a resource is added, it is always initialized with some default data. After adding the data for the resource can be loaded. This can only be done once for a resource and in this process the data structures and values are intialized. After the resource is loaded, it is generally possible to alter the data values, but not the data structure. That means for example that you can change the pixel colors of a texture image but not the dimensions or color depth of the image.

Resource management functions



Scene Graph

The scene graph represents the objects in the virtual world in a hierarchical tree structure. Every node except the root node has a parent and a local transformation relative to that parent. When a node is transformed, all of its children are also transformed accordingly. So as an example, if you want to move the whole scene a bit, you just have to set the transformation for the root node and the rest happens automatically. There are different types of scene nodes all of which represent concrete objects in the world. The root node is a Group node and has a predefined constant handle.
There are some rules that define which node types can be attached to what parent node. What follows is a list of the available node types with valid parent types:

Group: Can be attached to Group and Joint
Model: Can be attached to Group and Joint
Mesh: Can be attached to Model
Joint: Can be attached to Model
Light: Can be attached to Group and Joint
Camera: Can be attached to any node type

Every node type has a special creation function that takes a set of specific parameters. Some of them can only be specified at creation time and are immutable, others can be changed again later. For accessing nodes there are some general functions which operate on all nodes and some specific to a type of node. The latter require as a parameter usually a valid handle to a node of the corresponding type. To make life easier, it is also possible to pass to these functions a Group node in which case all of the children of the specified group are affected by the function call.

Scene graph functions



Data formats

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. Materials can reference a shader and setup texture units with images. Furthermore they can be used to define shader uniforms which are one- to four-dimensional float vectors with arbitrary user defined data. Materials can e.g. be used to define the appearance of a surface. 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}
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>
    <Shader name="myshader.shader.xml" />
    <TexUnit unit="0" map="mytex.jpg" />
    <Uniform name="myColor" size="3" 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}
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 {*}
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 {required}
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}
shadowMapEnabled see LightNodeParams (Values: "true", "false") {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}

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



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 59.



Tools

Collada Converter

The Collada Converter is a command line tool for converting COLLADA 1.4 assets exported from a modeling package to formats compatible with Horde3D. For each asset the converter will create a scene graph file containing the model structure, a geometry resource with the raw vertex data, an animation resource with information on the node transformations over time and usually several material files.

Important Note: At the moment there are some restrictions for COLLADA files to be compatible with the converter. All geometry has to stored as triangle data. Furthermore transformations have to be stored as matrices which is usually achieved by enabling the 'bake matrices' option in your COLLADA exporter. Finally animations should be exported as sampled keyframe data.

The tool has the following command line syntax:

ColladaConv inputFile [-o outputName] [-s shaderName] [-opt]


inputFile filename of the collada document
-o outputName name of the output files, without file extension (optional)
-s shaderName filename of the default shader that is used for the created material files (optional)
-opt geometry optimization for better performance; this can cause problems with some models (optional)


Copyright © 2006-2007 Nicolas Schulz