Horde3D API

Summary
Horde3D API
ConventionsSome conventions for the API.
Typedefs and constants
Typedefs
Predefined constants
Enumerations
EngineOptionsThe available engine option parameters.
ResourceTypesThe available resource types.
ResourceFlagsThe available flags used when adding a resource.
GeometryResParamsThe available Geometry resource parameters.
AnimationResParamsThe available Animation resource parameters.
TextureResParamsThe available Texture2D resource parameters.
SceneNodeTypesThe available scene node types.
GroupNodeParamsThe available Group node parameters.
ModelNodeParamsThe available Model node parameters
MeshNodeParamsThe available Mesh node parameters.
JointNodeParamsThe available Joint node parameters.
LightNodeParamsThe available Light node parameters.
CameraNodeParamsThe available Camera node parameters.
EmitterNodeParamsThe available Emitter node parameters.
Basic functions
getVersionStringReturns the engine version string.
checkExtensionChecks if an extension is part of the engine library.
initInitializes the engine.
releaseReleases the engine.
resizeResizes the viewport.
renderMain rendering function.
clearRemoves all resources and scene nodes.
getMessageGets the next message from the message queue.
getOptionGets an option parameter of the engine.
setOptionSets an option parameter for the engine.
showOverlayShows an overlay on the screen.
General resource management functions
getResourceTypeReturns the type of a resource.
getResourceNameReturns the name of a resource.
findResourceFinds a resource and returns its handle.
addResourceAdds a resource.
cloneResourceDuplicates a resource.
removeResourceRemoves a resource.
loadResourceLoads a resource.
unloadResourceUnloads a resource.
getResourceParamiGets a property of a resource.
getResourceParamfGets a property of a resource.
getResourceDataGives access to resource data.
updateResourceDataUpdates the data of a resource.
queryUnloadedResourceReturns handle to an unloaded resource.
releaseUnusedResourcesFrees resources that are no longer used.
Specific resource management functions
setShaderPreamblesSets preambles of all Shader resources.
setMaterialUniformSets a shader uniform of a Material resource.
setPipelineStageActivationSets the activation state of a pipeline stage.
getPipelineRenderTargetDataReads the pixel data of a pipeline render target buffer.
General scene graph functions
getNodeTypeReturns the type of a scene node.
getNodeNameReturns the name of a scene node.
setNodeNameSets the name of a scene node.
getNodeParentReturns the parent of a scene node.
setNodeParentRelocates a node in the scene graph.
getNodeChildReturns the handle to a child node.
getNodeAttachmentStringReturns the attachment string of a scene node.
addNodesAdds nodes from a SceneGraph resource to the scene.
removeNodeRemoves a node from the scene.
setNodeActivationSets the activation state of a node.
checkNodeTransformFlagChecks if a scene node has been transformed by the engine.
getNodeTransformGets the relative transformation of a node.
setNodeTransformSets the relative transformation of a node.
getNodeTransformMatricesReturns the transformation matrices of a node.
setNodeTransformMatrixSets the relative transformation matrix of a node.
getNodeParamfGets a property of a scene node.
setNodeParamfSets a property of a scene node.
getNodeParamiGets a property of a scene node.
setNodeParamfSets a property of a scene node.
getNodeAABBGets the bounding box of a scene node.
findNodesFinds scene nodes with the specified properties.
getNodeFindResultGets a result from the findNodes query.
castRayPerforms a recursive ray collision query.
Group-specific scene graph functions
addGroupNodeAdds a Group node to the scene.
Model-specific scene graph functions
addModelNodeAdds a Model node to the scene.
setupModelAnimStageConfigures an animation stage of a Model node.
setModelAnimParamsSets the parameters of an animation stage in a Model node.
setModelMorpherSets the weight of a morph target.
Mesh-specific scene graph functions
addMeshNodeAdds a Mesh node to the scene.
setMeshUniformSets a shader uniform of a Mesh node.
Joint-specific scene graph functions
addJointNodeAdds a Joint node to the scene.
Light-specific scene graph functions
addLightNodeAdds a Light node to the scene.
setLightContextsSets the shader contexts used by a light source.
Camera-specific scene graph functions
addCameraNodeAdds a Camera node to the scene.
setupCameraViewSets the planes of a camera viewing frustum.
calcCameraProjectionMatrixCalculates the camera projection matrix.
Emitter-specific scene graph functions
addEmitterNodeAdds a Emitter node to the scene.
advanceEmitterTimeAdvances the time value of an Emitter node.

Conventions

Some conventions for the API.

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.

Typedefs and constants

Typedefs

ResHandlehandle to resource (int)
NodeHandlehandle to scene node (int)

Predefined constants

RootNodeScene root node handle

Enumerations

EngineOptions

The available engine option parameters.

TrilinearFilteringEnables or disables trilinear filtering for textures; only affects textures that are loaded after setting the option.  (Values: 0, 1; Default: 1)
AnisotropyFactorSets the quality for anisotropic filtering; only affects textures that are loaded after setting the option.  (Values: 1, 2, 4, 8; Default: 1)
TexCompressionEnables or disables texture compression; only affects textures that are loaded after setting the option.  (Values: 0, 1; Default: 0)
LoadTexturesEnables or disables loading of texture images; option can be used to minimize loading times for testing.  (Values: 0, 1; Default: 1)
FastAnimationDisables or enables inter-frame interpolation for animations.  (Values: 0, 1; Default: 1)
OcclusionCullingEnables or disables occlusion culling; occlusion culling gives a good performance increase but can result in slight popping especially at lower framerates (Values: 0, 1; Default: 1)
ShadowMapSizeSets the size of the shadow map buffer (Values: 128, 256, 512, 1024, 2048; Default: 1024)
SampleCountMaximum number of samples used for multisampled render targets; only affects pipelines that are loaded after setting the option.  (Values: 0, 2, 4, 8, 16; Default: 0)
WireframeModeEnables or disables wireframe rendering
DebugViewModeEnables or disables debug view where geometry is rendered in wireframe without shaders and lights are visualized using their screen space bounding box.  (Values: 0, 1; Default: 0)

ResourceTypes

The available resource types.

UndefinedAn undefined resource, returned by getResourceType in case of error
SceneGraphScene graph subtree stored in XML format
GeometryGeometrical data containing bones, vertices and triangles
AnimationAnimation data
MaterialMaterial script
CodeText block containing shader source code
ShaderShader program
Texture2DTwo-dimensional texture map
TextureCubeCube map texture
EffectParticle configuration
PipelineRendering pipeline

ResourceFlags

The available flags used when adding a resource.

NoQueryExcludes resource from being listed by queryUnloadedResource function.
NoTexPOTConversionDisables texture conversion to power-of-two dimensions on hardware without NPOT-support.
NoTexCompressionDisables texture compression for Texture2D or TextureCube resource.
NoTexMipmapsDisables generation of mipmaps for textures.
NoTexFilteringDisables bilinear filtering for textures.
NoTexRepeatDisables tiling (repeat mode) for textures and enables clamping instead.

GeometryResParams

The available Geometry resource parameters.

VertexCountNumber of vertices; valid for getResourceParami
IndexCountNumber of vertices; valid for getResourceParami
VertexDataVertex positon data (pointer to float); valid for getResourceData
IndexDataTriangle indices (pointer to uint); valid for getResourceData

AnimationResParams

The available Animation resource parameters.

FrameCountNumber of animation frames; valid for getResourceParami

TextureResParams

The available Texture2D resource parameters.

PixelDataImage pixel data (pointer to unsigned char); valid for updateResourceData

SceneNodeTypes

The available scene node types.

UndefinedAn undefined node type, returned by getNodeType in case of error
GroupGroup of different scene nodes
Model3D model with optional skeleton
MeshSubgroup of a model with triangles of one material
JointJoint for skeletal animation
LightLight source
CameraCamera giving view on scene
EmitterParticle system emitter

GroupNodeParams

The available Group node parameters.

MinDistMinimal distance from the viewer for the node to be visible (default: 0.0); used for level of detail [type: float]
MaxDistMaximal distance from the viewer for the node to be visible (default: infinite); used for level of detail [type: float]

ModelNodeParams

The available Model node parameters

GeometryResGeometry resource used for the model [type: ResHandle, read-only]

MeshNodeParams

The available Mesh node parameters.

MaterialResMaterial resource used for the mesh [type: ResHandle]
BatchStartFirst triangle index of mesh in Geometry resource of parent Model node [type: int, read-only]
BatchCountNumber of triangle indices used for drawing mesh [type: int, read-only]
VertRStartFirst vertex in Geometry resource of parent Model node [type: int, read-only]
VertREndLast vertex in Geometry resource of parent Model node [type: int, read-only]

JointNodeParams

The available Joint node parameters.

JointIndexIndex of joint in Geometry resource of parent Model node [type: int, read-only]

LightNodeParams

The available Light node parameters.

MaterialResMaterial resource used for the light [type: ResHandle]
RadiusRadius of influence (default: 0.0) [type: float]
FOVField of view (FOV) angle (default: 90.0) [type: float]
Col_RRed component of light diffuse color (default: 1.0) [type: float]
Col_GGreen component of light diffuse color (default: 1.0) [type: float]
Col_BBlue component of light diffuse color (default: 1.0) [type: float]
ShadowMapCountNumber of shadow maps used for light source (values: 0, 1, 2, 3, 4; default: 0) [type: int]
ShadowSplitLambdaConstant determining segmentation of view frustum for Parallel Split Shadow Maps (default: 0.5) [type: float]
ShadowMapBiasBias value for shadow mapping to reduce shadow acne (default: 0.005) [type: float]

CameraNodeParams

The available Camera node parameters.

PipelineResPipeline resource used for rendering
LeftPlaneCoordinate of left plane relative to near plane center (default: -0.055228457) [type: float]
RightPlaneCoordinate of right plane relative to near plane center (default: 0.055228457) [type: float]
BottomPlaneCoordinate of bottom plane relative to near plane center (default: -0.041421354f) [type: float]
TopPlaneCoordinate of top plane relative to near plane center (default: 0.041421354f) [type: float]
NearPlaneDistance of near clipping plane (default: 0.1) [type: float]
FarPlaneDistance of far clipping plane (default: 1000) [type: float]

EmitterNodeParams

The available Emitter node parameters.

MaterialResMaterial resource used for rendering [type: ResHandle]
EffectResEffect resource which configures particle properties [type: ResHandle]
MaxCountMaximal number of particles living at the same time [type: int]
RespawnCountNumber of times a single particle is recreated after dying (-1 for infinite) [type: int]
DelayTime in seconds before emitter begins creating particles (default: 0.0) [type: float]
EmissionRateMaximal number of particles to be created per second (default: 0.0) [type: float]
SpreadAngleAngle of cone for random emission direction (default: 0.0) [type: float]
ForceXX-component of force vector applied to particles (default: 0.0) [type: float]
ForceYY-component of force vector applied to particles (default: 0.0) [type: float]
ForceZZ-component of force vector applied to particles (default: 0.0) [type: float]

Basic functions

getVersionString

DLL const char *getVersionString()

Returns the engine version string.

This function returns a pointer to a string containing the current version of Horde3D.

Parameters

none

Returns

pointer to the version string

checkExtension

DLL bool checkExtension(const char *extensionName)

Checks if an extension is part of the engine library.

This function checks if a specified extension is contained in the DLL/shared object of the engine.

Parameters

extensionNamename of the extension

Returns

true if extension is implemented, otherwise false

init

DLL bool init()

Initializes the engine.

This function initializes the graphics engine and makes it ready for use.  It has to be the first call to the engine except for getVersionString.  In order to successfully initialize the engine the calling application must provide a valid OpenGL context.

Parameters

none

Returns

true in case of success, otherwise false

release

DLL void release()

Releases the engine.

This function releases the engine and frees all objects and associated memory.  It should be called when the application is destroyed.

Parameters

none

Returns

nothing

resize

DLL void resize(int x,
int y,
int width,
int height)

Resizes the viewport.

This function sets the dimensions of the rendering viewport.  It has to be called after initialization and whenever the viewport size changes.

Parameters

xthe x-position of the viewport in the rendering context
ythe y-position of the viewport in the rendering context
widththe width of the viewport
heightthe height of the viewport

Returns

nothing

render

DLL bool render(NodeHandle cameraNode)

Main rendering function.

This is the main function of the engine.  It executes all the rendering, animation and other tasks.  This function is usually called once per frame.

Parameters

cameraNodecamera node used for rendering scene

Returns

true in case of success, otherwise false

clear

DLL void clear()

Removes all resources and scene nodes.

This function removes all nodes from the scene graph except the root node and releases all resources.

Warning: All resource and node IDs are invalid after calling this function

Parameters

none

Returns

nothing

getMessage

DLL const char *getMessage(int *level,
float *time)

Gets the next message from the message queue.

This function returns the next message string from the message queue and writes additional information to the specified variables.  If no message is left over in the queue an empty string is returned.

Parameters

levelpointer to variable for storing message level indicating importance (can be NULL)
timepointer to variable for storing time when message was added (can be NULL)

Returns

message string or empty string if no message is in queue

getOption

DLL float getOption(EngineOptions::List param)

Gets an option parameter of the engine.

This function gets a specified option parameter and returns its value.

Parameters

paramoption parameter

Returns

current value of the specified option parameter

setOption

DLL bool setOption(EngineOptions::List param,
float value)

Sets an option parameter for the engine.

This function sets a specified option parameter to a specified value.

Parameters

paramoption parameter
valuevalue of the option parameter

Returns

true if the option could be set to the specified value, otherwise false

showOverlay

DLL void showOverlay(float x_ll,
float y_ll,
float u_ll,
float v_ll,
float x_lr,
float y_lr,
float u_lr,
float v_lr,
float x_ur,
float y_ur,
float u_ur,
float v_ur,
float x_ul,
float y_ul,
float u_ul,
float v_ul,
int layer,
ResHandle materialRes)

Shows an overlay on the screen.

This function displays an overlay with a specified material at a specified position on the screen.  An overlay is a 2D image that can be used to render 2D GUI elements.  The coordinate system used has its origin (0, 0) at the lower left corner of the screen and its maximum (1, 1) at the upper right corner.  Texture coordinates are using the same system, where the coordinates (0, 0) correspond to the lower left corner of the image.  Overlays can have different layers which describe the order in which they are drawn.  Overlays with smaller layer numbers are drawn before overlays with higher layer numbers.

Parameters

x_ll, y_ll, u_ll, v_llposition and texture coordinates of the lower left corner
x_lr, y_lr, u_lr, v_lrposition and texture coordinates of the lower right corner
x_ur, y_ur, u_ur, v_urposition and texture coordinates of the upper right corner
x_ul, y_ul, u_ul, v_ulposition and texture coordinates of the upper left corner
layerlayer index of the overlay (Values: from 0 to 7)
materialResmaterial resource used for rendering

Returns

nothing

General resource management functions

getResourceType

DLL ResourceTypes::List getResourceType(ResHandle res)

Returns the type of a resource.

This function returns the type of a specified resource.  If the resource handle is invalid, the function returns the resource type ‘Unknown’.

Parameters

reshandle to the resource

Returns

type of the resource

getResourceName

DLL const char *getResourceName(ResHandle res)

Returns the name of a resource.

This function returns a pointer to the name of a specified resource.  If the resource handle is invalid, the function returns an empty string.

Important Note: The pointer is const and allows only read access to the data.  Do never try to modify the data of the pointer since that can corrupt the engine’s internal states!

Parameters

reshandle to the resource

Returns

name of the resource or empty string in case of failure

findResource

DLL ResHandle findResource(ResourceTypes::List type,
const char *name)

Finds a resource and returns its handle.

This function searches the resource of the specified type and name and returns its handle.  If the resource is not available in the resource manager a zero handle is returned.

Parameters

typetype of the resource
namename of the resource

Returns

handle to the resource or 0 if not found

addResource

DLL ResHandle addResource(ResourceTypes::List type,
const char *name,
int flags)

Adds a resource.

This function tries to add a resource of a specified type and name to the resource manager.  If a resource of the same type and name is already existing, the handle to the existing resource is returned instead of creating a new one and the user reference count of the resource is increased.

Parameters

typetype of the resource
namename of the resource
flagsflags used for creating the resource

Returns

handle to the resource to be added or 0 in case of failure

cloneResource

DLL ResHandle cloneResource(ResHandle sourceRes,
const char *name)

Duplicates a resource.

This function duplicates a specified resource.  In the cloning process a new resource with the specified name is added to the resource manager and filled with the data of the specified source resource.  If the specified name for the new resource is already in use, the function fails and returns 0.

Parameters

sourceReshandle to resource to be cloned
namename of new resource

Returns

handle to the cloned resource or 0 in case of failure

removeResource

DLL int removeResource(ResHandle res)

Removes a resource.

This function decreases the user reference count of a specified resource.  When the user reference count is zero and there are no internal references, the resource can be released and removed using the API fuction releaseUnusedResources.

Parameters

reshandle to the resource to be removed

Returns

the number of references that the application is still holding after removal or -1 in case of an error

loadResource

DLL bool loadResource(ResHandle res,
const char *data,
int size)

Loads a resource.

This function loads data for a resource that was previously added to the resource manager.  If data is a NULL-pointer the resource manager is told that the resource doesn’t have any data.  This function can only be called once for every resource.

Important Note: XML-data must be NULL-terminated

Parameters

reshandle to the resource for which data is loaded
datapointer to the data to be loaded
sizesize of the data block

Returns

true in case of success, otherwise false

unloadResource

DLL bool unloadResource(ResHandle res)

Unloads a resource.

This function unloads a previously loaded resource and restores the default values it had before loading.  The state is set back to unloaded which makes it possible to load the resource again.

Parameters

reshandle to resource to be unloaded

Returns

true in case of success, otherwise false

getResourceParami

DLL int getResourceParami(ResHandle res,
int param)

Gets a property of a resource.

This function returns a specified property of the specified resource.  The property must be of the type int.

Parameters

reshandle to the resource to be accessed
paramparameter to be accessed

Returns

value of the parameter

getResourceParamf

DLL float getResourceParamf(ResHandle res,
int param)

Gets a property of a resource.

This function returns a specified property of the specified resource.  The property must be of the type float.

Parameters

reshandle to the resource to be accessed
paramparameter to be accessed

Returns

value of the parameter

getResourceData

DLL const void *getResourceData(ResHandle res,
int param)

Gives access to resource data.

This function returns a pointer to the specified data of a specified resource.  For information on the format (uint, float, ..) of the pointer see the ResourceData description.

Important Note: The pointer is const and allows only read access to the data.  Do never try to modify the data of the pointer since that can corrupt the engine’s internal states!

Parameters

reshandle to the resource to be accessed
paramparameter indicating data of the resource that will be accessed

Returns

pointer to the specified resource data if it is available, otherwise NULL-pointer

updateResourceData

DLL bool updateResourceData(ResHandle res,
int param,
const void *data,
int size)

Updates the data of a resource.

This function updates the content of a resource that was successfully loaded before.  The new data must have exactly the same data layout as the data that was loaded.

Notes on available ResourceData parameters

  • Texture2DResData::PixelData Sets the image data of a Texture2D resource.  The data pointer must point to a memory block that contains the pixels of the image.  Each pixel needs to have 32 bit color data in BGRA format and the dimensions of the image (width, height) must be exactly the same as the dimensions of the image that was originally loaded for the resource.  The first element in the data array corresponds to the lower left corner of the image and subsequent elements progress from left to right in the image.

Parameters

reshandle to the resource for which the data is modified
paramdata structure which will be updated
datapointer to the new data
sizesize of the new data block

Returns

true in case of success, otherwise false

queryUnloadedResource

DLL ResHandle queryUnloadedResource()

Returns handle to an unloaded resource.

This function looks for a resource that is not yet loaded and returns its handle.  If there are no unloaded resources, 0 is returned.

Parameters

none

Returns

handle to an unloaded resource or 0

releaseUnusedResources

DLL void releaseUnusedResources()

Frees resources that are no longer used.

This function releases resources that are no longer used.  Unused resources were either told to be released by the user calling egReleaseResource or are no more referenced by any other engine objects.

Parameters

none

Returns

nothing

Specific resource management functions

setShaderPreambles

DLL void setShaderPreambles(const char *vertPreamble,
const char *fragPreamble)

Sets preambles of all Shader resources.

This function defines a header that is inserted at the beginning of all shaders.  The preamble is used when a shader is compiled, so changing it will not affect any shaders that are already compiled.  The preamble is useful for setting platform-specific defines that can be employed for creating several shader code paths, e.g. for supporting different hardware capabilities.

Parameters

vertPreamblepreamble text of vertex shaders (default: empty string)
fragPreamblepreamble text of fragment shaders (default: empty string)

Returns

nothing

setMaterialUniform

DLL bool setMaterialUniform(ResHandle materialRes,
const char *name,
float a,
float b,
float c,
float d)

Sets a shader uniform of a Material resource.

This function sets the specified shader uniform of the specified material to the specified values.

Parameters

materialReshandle to the Material resource to be accessed
namename of the uniform as defined in Material resource
a, b, c, dvalues of the four components

Returns

true in case of success, otherwise false

setPipelineStageActivation

DLL bool setPipelineStageActivation(ResHandle pipelineRes,
const char *stageName,
bool enabled)

Sets the activation state of a pipeline stage.

This function enables or disables a specified stage of the specified pipeline resource.

Parameters

pipelineReshandle to the Pipeline resource to be accessed
stageNamename of the stage to be modified
enabledflag indicating whether the stage shall be enabled or disabled

Returns

true in case of success, otherwise false

getPipelineRenderTargetData

DLL bool getPipelineRenderTargetData(ResHandle pipelineRes,
const char *targetName,
int bufIndex,
int *width,
int *height,
int *compCount,
float *dataBuffer,
int bufferSize)

Reads the pixel data of a pipeline render target buffer.

This function reads the pixels of the specified buffer of the specified render target from the specified pipeline resource and stores it in the specified float array.  To calculate the size required for the array this function can be called with a NULL pointer for dataBuffer and pointers to variables where the width, height and number of (color) components (e.g.  4 for RGBA or 1 for depth) will be stored.  The function is not intended to be used for real-time scene rendering but rather as a tool for debugging.  For more information about the render buffers please refer to the Pipeline documentation.

Parameters

pipelineReshandle to pipeline resource
targetNameunique name of render target to access
bufIndexindex of buffer to be accessed
widthpointer to variable where the width of the buffer will be stored (can be NULL)
heightpointer to variable where the height of the buffer will be stored (can be NULL)
compCountpointer to variable where the number of components will be stored (can be NULL)
dataBufferpointer to float array where the pixel data will be stored (can be NULL)
bufferSizesize of dataBuffer array in bytes

Returns

true in case of success, otherwise false

General scene graph functions

getNodeType

DLL int getNodeType(NodeHandle node)

Returns the type of a scene node.

This function returns the type of a specified scene node.  If the node handle is invalid, the function returns the node type ‘Unknown’.

Parameters

nodehandle to the scene node

Returns

type of the scene node

getNodeName

DLL const char *getNodeName(NodeHandle node)

Returns the name of a scene node.

This function returns a pointer to the name of a specified scene node.  If the node handle is invalid, the function returns an empty string.

Important Note: The pointer is const and allows only read access to the data.  Do never try to modify the data of the pointer since that can corrupt the engine’s internal states!

Parameters

nodehandle to the scene node

Returns

name of the scene node or empty string in case of failure

setNodeName

DLL bool setNodeName(NodeHandle node,
const char *name)

Sets the name of a scene node.

This function sets the name of the specified scene node to the specified value.

Parameters

nodehandle to the scene node
namenew name of the scene node

Returns

true in case of success, otherwise false

getNodeParent

DLL NodeHandle getNodeParent(NodeHandle node)

Returns the parent of a scene node.

This function returns the handle to the parent node of a specified scene node.  If the specified node handle is invalid or the root node, 0 is returned.

Parameters

nodehandle to the scene node

Returns

handle to parent node or 0 in case of failure

setNodeParent

DLL bool setNodeParent(NodeHandle node,
NodeHandle parent)

Relocates a node in the scene graph.

This function relocates a scene node.  It detaches the node from its current parent and attaches it to the specified new parent node.  If the attachment to the new parent is not possible, the function returns false.  Relocation is not possible for the RootNode.

Parameters

nodehandle to the scene node to be relocated
parenthandle to the new parent node

Returns

true in case of success, otherwise false

getNodeChild

DLL NodeHandle getNodeChild(NodeHandle node,
int index)

Returns the handle to a child node.

This function looks for the n-th (index) child node of a specified node and returns its handle.  If the child doesn’t exist, the function returns 0.

Parameters

nodehandle to the parent node
indexindex of the child node

Returns

handle to the child node or 0 if child doesn’t exist

getNodeAttachmentString

DLL const char *getNodeAttachmentString(NodeHandle node)

Returns the attachment string of a scene node.

This function returns a pointer to the attachment string of a specified scene node.  If the node handle is invalid or if the node does not have an attachment, the function returns an empty string.

Important Note: The pointer is const and allows only read access to the data.  Do never try to modify the data of the pointer since that can corrupt the engine’s internal states!

Parameters

nodehandle to the node to be accessed

Returns

attachment string (can be empty) or empty string in case of failure

addNodes

DLL NodeHandle addNodes(NodeHandle parent,
ResHandle sceneGraphRes)

Adds nodes from a SceneGraph resource to the scene.

This function creates several new nodes as described in a SceneGraph resource and attaches them to a specified parent node.

Important Note: The SceneGraph resource needs to be loaded!

Parameters

parenthandle to parent node to which the root of the new nodes will be attached
sceneGraphReshandle to SceneGraph resource

Returns

handle to the root of the created nodes or 0 in case of failure

removeNode

DLL bool removeNode(NodeHandle node)

Removes a node from the scene.

This function removes the specified node and all of it’s children from the scene.

Parameters

nodehandle to the node to be removed

Returns

true in case of success otherwise false

setNodeActivation

DLL bool setNodeActivation(NodeHandle node,
bool active)

Sets the activation state of a node.

This function sets the activation state of the specified node to active or inactive.  Inactive nodes are excluded from rendering.

Parameters

nodehandle to the node to be modified
activeboolean value indicating whether node shall be active or inactive

Returns

true in case of success otherwise false

checkNodeTransformFlag

DLL bool checkNodeTransformFlag(NodeHandle node,
bool reset)

Checks if a scene node has been transformed by the engine.

This function checks if a scene node has been transformed by the engine since the last time the transformation flag was reset.  Therefore, it stores a flag that is set to true when a setTransformation function is called explicitely by the application or when the node transformation has been updated by the animation system.  The function also makes it possible to reset the transformation flag.

Parameters

nodehandle to the node to be accessed
resetflag indicating whether transformation flag shall be reset

Returns

true if node has been transformed, otherwise false

getNodeTransform

DLL bool getNodeTransform(NodeHandle node,
float *tx,
float *ty,
float *tz,
float *rx,
float *ry,
float *rz,
float *sx,
float *sy,
float *sz)

Gets the relative transformation of a node.

This function gets the translation, rotation and scale of a specified scene node object.  The coordinates are in local space and contain the transformation of the node relative to its parent.

Parameters

nodehandle to the node which will be accessed
tx, ty, tzpointers to variables where translation of the node will be stored (can be NULL)
rx, ry, rzpointers to variables where rotation of the node in Euler angles will be stored (can be NULL)
sx, sy, szpointers to variables where scale of the node will be stored (can be NULL)

Returns

true in case of success otherwise false

setNodeTransform

DLL bool setNodeTransform(NodeHandle node,
float tx,
float ty,
float tz,
float rx,
float ry,
float rz,
float sx,
float sy,
float sz)

Sets the relative transformation of a node.

This function sets the relative translation, rotation and scale of a specified scene node object.  The coordinates are in local space and contain the transformation of the node relative to its parent.

Parameters

nodehandle to the node which will be modified
tx, ty, tztranslation of the node
rx, ry, rzrotation of the node in Euler angles
sx, sy, szscale of the node

Returns

true in case of success otherwise false

getNodeTransformMatrices

DLL bool getNodeTransformMatrices(NodeHandle node,
const float **relMat,
const float **absMat)

Returns the transformation matrices of a node.

This function stores a pointer to the relative and absolute transformation matrices of the specified node in the specified pointer varaibles.

Parameters

nodehandle to the scene node to be accessed
relMatpointer to a variable where the address of the relative transformation matrix will be stored (can be NULL if matrix is not required)
absMatpointer to a variable where the address of the absolute transformation matrix will be stored (can be NULL if matrix is not required)

Returns

true in case of success otherwise false

setNodeTransformMatrix

DLL bool setNodeTransformMatrix(NodeHandle node,
const float *mat4x4)

Sets the relative transformation matrix of a node.

This function sets the relative transformation matrix of the specified scene node.  It is basically the same as setNodeTransform but takes directly a matrix instead of individual transformation parameters.

Parameters

nodehandle to the node which will be modified
mat4x4pointer to a 4x4 matrix in column major order

Returns

true in case of success otherwise false

getNodeParamf

DLL float getNodeParamf(NodeHandle node,
int param)

Gets a property of a scene node.

This function returns a specified property of the specified node.  The property must be of the type float.

Parameters

nodehandle to the node to be accessed
paramparameter to be accessed

Returns

value of the parameter

setNodeParamf

DLL bool setNodeParamf(NodeHandle node,
int param,
float value)

Sets a property of a scene node.

This function sets a specified property of the specified node to a specified value.  The property must be of the type float.

Parameters

nodehandle to the node to be modified
paramparameter to be modified
valuenew value for the specified parameter

Returns

true in case of success otherwise false

getNodeParami

DLL int getNodeParami(NodeHandle node,
int param)

Gets a property of a scene node.

This function returns a specified property of the specified node.  The property must be of the type int or ResHandle.

Parameters

nodehandle to the node to be accessed
paramparameter to be accessed

Returns

value of the parameter

setNodeParamf

Sets a property of a scene node.

This function sets a specified property of the specified node to a specified value.  The property must be of the type int or ResHandle.

Parameters

nodehandle to the node to be modified
paramparameter to be modified
valuenew value for the specified parameter

Returns

true in case of success otherwise false

getNodeAABB

DLL bool getNodeAABB(NodeHandle node,
float *minX,
float *minY,
float *minZ,
float *maxX,
float *maxY,
float *maxZ)

Gets the bounding box of a scene node.

This function stores the world coordinates of the axis aligned bounding box of a specified node in the specified variables.  The bounding box is represented using the minimum and maximum coordinates on all three axes.

Parameters

nodehandle to the node which will be accessed
minX, minY, minZpointers to variables where minimum coordinates will be stored
maxX, maxY, maxZpointers to variables where maximum coordinates will be stored

Returns

true in case of success otherwise false

findNodes

DLL int findNodes(NodeHandle startNode,
const char *name,
int type)

Finds scene nodes with the specified properties.

This function loops recursively over all children of startNode and adds them to an internal list of results if they match the specified name and type.  The result list is cleared each time this function is called.  The function returns the number of nodes which were found and added to the list.

Parameters

startNodehandle to the node where the search begins
namename of nodes to be searched (empty string for all nodes)
typetype of nodes to be searched (SceneNodeTypes::Undefined for all types)

Returns

number of search results

getNodeFindResult

DLL NodeHandle getNodeFindResult(int index)

Gets a result from the findNodes query.

This function returns the n-th (index) result of a previous findNodes query.  The result is the handle to a scene node with the poperties specified at the findNodes query.  If the index doesn’t exist in the result list the function returns 0.

Parameters

indexindex of search result

Returns

handle to scene node from findNodes query or 0 if result doesn’t exist

castRay

DLL NodeHandle castRay(NodeHandle node,
float ox,
float oy,
float oz,
float dx,
float dy,
float dz)

Performs a recursive ray collision query.

This function checks recursively if the specified ray intersects the specified node or one of its children.  The function finds the nearest intersection relative to the ray origin and returns the handle to the corresponding scene node.  The ray is a line segment and is specified by a starting point (the origin) and a finite direction vector which also defines its length.  Currently this function is limited to returning intersections with Meshes.

Parameters

nodenode at which intersection check is beginning
ox, oy, ozray origin
dx, dy, dzray direction vector also specifying ray length

Returns

handle to nearest intersected node or 0 if no node was hit

Group-specific scene graph functions

addGroupNode

DLL NodeHandle addGroupNode(NodeHandle parent,
const char *name)

Adds a Group node to the scene.

This function creates a new Group node and attaches it to the specified parent node.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node

Returns

handle to the created node or 0 in case of failure

Model-specific scene graph functions

addModelNode

DLL NodeHandle addModelNode(NodeHandle parent,
const char *name,
ResHandle geometryRes)

Adds a Model node to the scene.

This function creates a new Model node and attaches it to the specified parent node.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node
geometryResGeometry resource used by Model node

Returns

handle to the created node or 0 in case of failure

setupModelAnimStage

DLL bool setupModelAnimStage(NodeHandle node,
int stage,
ResHandle animationRes,
const char *startNode,
bool additive)

Configures an animation stage of a Model node.

This function is used to setup the specified animation stage (channel) of the specified Model node.

The function is used for animation blending.  There is a fixed number of stages (by default 16) on which different animations can be played.  The start node determines the first node (Joint or Mesh) to which the animation is recursively applied.  If the start node is an empty string, the animation affects all animatable nodes (Joints and Meshes) of the model.

A simpler way to do animation mixing is using additive animations.  If a stage is configured to be additive the engine calculates the difference between the current frame and the first frame in the animation and adds this delta to the current transformation of the joints or meshes.

Parameters

nodehandle to the node to be modified
stageindex of the animation stage to be configured
animationReshandle to Animation resource
startNodename of first node to which animation shall be applied (or empty string)
additiveflag indicating whether stage is additive

Returns

true in case of success, otherwise false

setModelAnimParams

DLL bool setModelAnimParams(NodeHandle node,
int stage,
float time,
float weight)

Sets the parameters of an animation stage in a Model node.

This function sets the current animation time and weight for a specified stage of the specified model.  The time corresponds to the frames of the animation and the animation is looped if the time is higher than the maximum number of frames in the Animation resource.  The weight is used for animation blending and determines how much influence the stage has compared to the other active stages.  When the sum of the weights of all stages is more than one, the animations on the lower stages get priority.

Parameters

nodehandle to the node to be modified
stageindex of the animation stage to be modified
timenew animation time/frame
weightnew blend weight

Returns

true in case of success, otherwise false

setModelMorpher

DLL bool setModelMorpher(NodeHandle node,
const char *target,
float weight)

Sets the weight of a morph target.

This function sets the weight of a specified morph target.  If the target parameter is an empty string the weight of all morph targets in the specified Model node is modified.  If the specified morph target is not found the function returns false.

Parameters

nodehandle to the node to be modified
targetname of morph target
weightnew weight for morph target

Returns

true in case of success, otherwise false

Mesh-specific scene graph functions

addMeshNode

DLL NodeHandle addMeshNode(NodeHandle parent,
const char *name,
ResHandle materialRes,
int batchStart,
int batchCount,
int vertRStart,
int vertREnd)

Adds a Mesh node to the scene.

This function creates a new Mesh node and attaches it to the specified parent node.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node
materialResmaterial resource used by Mesh node
batchStartfirst triangle index of mesh in Geometry resource of parent Model node
batchCountnumber of triangle indices used for drawing mesh
vertRStartfirst vertex in Geometry resource of parent Model node
vertREndlast vertex in Geometry resource of parent Model node

Returns

handle to the created node or 0 in case of failure

setMeshUniform

DLL bool setMeshUniform(NodeHandle node,
const char *name,
float a,
float b,
float c,
float d,
bool recursive)

Sets a shader uniform of a Mesh node.

This function sets the specified shader uniform of the specified mesh to the specified values.  Each mesh has its own copy of the uniforms defined in the associated Material resource and if the uniform has not explicitely been set using this function, the default values from the Material resource are applied for rendering.

Parameters

nodehandle to the node to be accessed
namename of the uniform as defined in mesh material resource
a, b, c, dvalues of the four components
recursiveparameter specifying whether uniform is set recursively for all Mesh children of Mesh node

Returns

true in case of success otherwise false

Joint-specific scene graph functions

addJointNode

DLL NodeHandle addJointNode(NodeHandle parent,
const char *name,
int jointIndex)

Adds a Joint node to the scene.

This function creates a new Joint node and attaches it to the specified parent node.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node
jointIndexindex of joint in Geometry resource of parent Model node

Returns

handle to the created node or 0 in case of failure

Light-specific scene graph functions

addLightNode

DLL NodeHandle addLightNode(NodeHandle parent,
const char *name,
ResHandle materialRes,
const char *lightingContext,
const char *shadowContext)

Adds a Light node to the scene.

This function creates a new Light node and attaches it to the specified parent node.  The direction vector of the untransformed light node is pointing along the the negative z-axis.  The specified material resource can define uniforms and projective textures.  Furthermore it can contain a shader for doing lighting calculations if deferred shading is used.  If no material is required the parameter can be zero.  The context names define which shader contexts are used when rendering shadow maps or doing light calculations for forward rendering configurations.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node
materialResmaterial resource for light configuration or 0 if not used
lightingContextname of the shader context used for doing light calculations
shadowContextname of the shader context used for doing shadow map rendering

Returns

handle to the created node or 0 in case of failure

setLightContexts

DLL bool setLightContexts(NodeHandle node,
const char *lightingContext,
const char *shadowContext)

Sets the shader contexts used by a light source.

This function sets the lighting and shadow shader contexts of the specified light source.  The contexts define which shader code is used when doing lighting calculations or rendering the shadow map.

Parameters

nodehandle to the node to be modified
lightingContextname of the shader context used for performing lighting calculations
shadowContextname of the shader context used for rendering shadow maps

Returns

true in case of success otherwise false

Camera-specific scene graph functions

addCameraNode

DLL NodeHandle addCameraNode(NodeHandle parent,
const char *name,
ResHandle pipelineRes)

Adds a Camera node to the scene.

This function creates a new Camera node and attaches it to the specified parent node.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node
pipelineRespipeline resource used for rendering

Returns

handle to the created node or 0 in case of failure

setupCameraView

DLL bool setupCameraView(NodeHandle node,
float fov,
float aspect,
float nearDist,
float farDist)

Sets the planes of a camera viewing frustum.

This function calculates the view frustum planes of the specified camera node using the specified view parameters.

Parameters

nodehandle to the Camera node which will be modified
fovfield of view (FOV) angle
aspectaspect ratio
nearDistdistance of near clipping plane
farDistdistance of far clipping plane

Returns

true in case of success otherwise false

calcCameraProjectionMatrix

DLL bool calcCameraProjectionMatrix(NodeHandle node,
float *projMat)

Calculates the camera projection matrix.

This function calculates the camera projection matrix used for bringing the geometry to screen space and copies it to the specified array.

Parameters

nodehandle to Camera node
projMatpointer to float array with 16 elements

Returns

true in case of success otherwise false

Emitter-specific scene graph functions

addEmitterNode

DLL NodeHandle addEmitterNode(NodeHandle parent,
const char *name,
ResHandle materialRes,
ResHandle effectRes,
int maxParticleCount,
int respawnCount)

Adds a Emitter node to the scene.

This function creates a new Emitter node and attaches it to the specified parent node.

Parameters

parenthandle to parent node to which the new node will be attached
namename of the node
materialReshandle to Material resource used for rendering
effectReshandle to Effect resource used for configuring particle properties
maxParticleCountmaximal number of particles living at the same time
respawnCountnumber of times a single particle is recreated after dying (-1 for infinite)

Returns

handle to the created node or 0 in case of failure

advanceEmitterTime

DLL bool advanceEmitterTime(NodeHandle node,
float timeDelta)

Advances the time value of an Emitter node.

This function advances the simulation time of a particle system and continues the particle simulation with timeDelta being the time elapsed since the last call of this function.  The specified node must be an Emitter node.

Parameters

nodehandle to the Emitter node which will be modified
timeDeltatime delta in seconds

Returns

true in case of success otherwise false

DLL const char *getVersionString()
Returns the engine version string.
DLL bool checkExtension(const char *extensionName)
Checks if an extension is part of the engine library.
DLL bool init()
Initializes the engine.
DLL void release()
Releases the engine.
DLL void resize(int x,
int y,
int width,
int height)
Resizes the viewport.
DLL bool render(NodeHandle cameraNode)
Main rendering function.
DLL void clear()
Removes all resources and scene nodes.
DLL const char *getMessage(int *level,
float *time)
Gets the next message from the message queue.
DLL float getOption(EngineOptions::List param)
Gets an option parameter of the engine.
DLL bool setOption(EngineOptions::List param,
float value)
Sets an option parameter for the engine.
DLL void showOverlay(float x_ll,
float y_ll,
float u_ll,
float v_ll,
float x_lr,
float y_lr,
float u_lr,
float v_lr,
float x_ur,
float y_ur,
float u_ur,
float v_ur,
float x_ul,
float y_ul,
float u_ul,
float v_ul,
int layer,
ResHandle materialRes)
Shows an overlay on the screen.
DLL ResourceTypes::List getResourceType(ResHandle res)
Returns the type of a resource.
DLL const char *getResourceName(ResHandle res)
Returns the name of a resource.
DLL ResHandle findResource(ResourceTypes::List type,
const char *name)
Finds a resource and returns its handle.
DLL ResHandle addResource(ResourceTypes::List type,
const char *name,
int flags)
Adds a resource.
DLL ResHandle cloneResource(ResHandle sourceRes,
const char *name)
Duplicates a resource.
DLL int removeResource(ResHandle res)
Removes a resource.
DLL bool loadResource(ResHandle res,
const char *data,
int size)
Loads a resource.
DLL bool unloadResource(ResHandle res)
Unloads a resource.
DLL int getResourceParami(ResHandle res,
int param)
Gets a property of a resource.
DLL float getResourceParamf(ResHandle res,
int param)
Gets a property of a resource.
DLL const void *getResourceData(ResHandle res,
int param)
Gives access to resource data.
DLL bool updateResourceData(ResHandle res,
int param,
const void *data,
int size)
Updates the data of a resource.
DLL ResHandle queryUnloadedResource()
Returns handle to an unloaded resource.
DLL void releaseUnusedResources()
Frees resources that are no longer used.
DLL void setShaderPreambles(const char *vertPreamble,
const char *fragPreamble)
Sets preambles of all Shader resources.
DLL bool setMaterialUniform(ResHandle materialRes,
const char *name,
float a,
float b,
float c,
float d)
Sets a shader uniform of a Material resource.
DLL bool setPipelineStageActivation(ResHandle pipelineRes,
const char *stageName,
bool enabled)
Sets the activation state of a pipeline stage.
DLL bool getPipelineRenderTargetData(ResHandle pipelineRes,
const char *targetName,
int bufIndex,
int *width,
int *height,
int *compCount,
float *dataBuffer,
int bufferSize)
Reads the pixel data of a pipeline render target buffer.
DLL int getNodeType(NodeHandle node)
Returns the type of a scene node.
DLL const char *getNodeName(NodeHandle node)
Returns the name of a scene node.
DLL bool setNodeName(NodeHandle node,
const char *name)
Sets the name of a scene node.
DLL NodeHandle getNodeParent(NodeHandle node)
Returns the parent of a scene node.
DLL bool setNodeParent(NodeHandle node,
NodeHandle parent)
Relocates a node in the scene graph.
DLL NodeHandle getNodeChild(NodeHandle node,
int index)
Returns the handle to a child node.
DLL const char *getNodeAttachmentString(NodeHandle node)
Returns the attachment string of a scene node.
DLL NodeHandle addNodes(NodeHandle parent,
ResHandle sceneGraphRes)
Adds nodes from a SceneGraph resource to the scene.
DLL bool removeNode(NodeHandle node)
Removes a node from the scene.
DLL bool setNodeActivation(NodeHandle node,
bool active)
Sets the activation state of a node.
DLL bool checkNodeTransformFlag(NodeHandle node,
bool reset)
Checks if a scene node has been transformed by the engine.
DLL bool getNodeTransform(NodeHandle node,
float *tx,
float *ty,
float *tz,
float *rx,
float *ry,
float *rz,
float *sx,
float *sy,
float *sz)
Gets the relative transformation of a node.
DLL bool setNodeTransform(NodeHandle node,
float tx,
float ty,
float tz,
float rx,
float ry,
float rz,
float sx,
float sy,
float sz)
Sets the relative transformation of a node.
DLL bool getNodeTransformMatrices(NodeHandle node,
const float **relMat,
const float **absMat)
Returns the transformation matrices of a node.
DLL bool setNodeTransformMatrix(NodeHandle node,
const float *mat4x4)
Sets the relative transformation matrix of a node.
DLL float getNodeParamf(NodeHandle node,
int param)
Gets a property of a scene node.
DLL bool setNodeParamf(NodeHandle node,
int param,
float value)
Sets a property of a scene node.
DLL int getNodeParami(NodeHandle node,
int param)
Gets a property of a scene node.
DLL bool getNodeAABB(NodeHandle node,
float *minX,
float *minY,
float *minZ,
float *maxX,
float *maxY,
float *maxZ)
Gets the bounding box of a scene node.
DLL int findNodes(NodeHandle startNode,
const char *name,
int type)
Finds scene nodes with the specified properties.
DLL NodeHandle getNodeFindResult(int index)
Gets a result from the findNodes query.
DLL NodeHandle castRay(NodeHandle node,
float ox,
float oy,
float oz,
float dx,
float dy,
float dz)
Performs a recursive ray collision query.
DLL NodeHandle addGroupNode(NodeHandle parent,
const char *name)
Adds a Group node to the scene.
DLL NodeHandle addModelNode(NodeHandle parent,
const char *name,
ResHandle geometryRes)
Adds a Model node to the scene.
DLL bool setupModelAnimStage(NodeHandle node,
int stage,
ResHandle animationRes,
const char *startNode,
bool additive)
Configures an animation stage of a Model node.
DLL bool setModelAnimParams(NodeHandle node,
int stage,
float time,
float weight)
Sets the parameters of an animation stage in a Model node.
DLL bool setModelMorpher(NodeHandle node,
const char *target,
float weight)
Sets the weight of a morph target.
DLL NodeHandle addMeshNode(NodeHandle parent,
const char *name,
ResHandle materialRes,
int batchStart,
int batchCount,
int vertRStart,
int vertREnd)
Adds a Mesh node to the scene.
DLL bool setMeshUniform(NodeHandle node,
const char *name,
float a,
float b,
float c,
float d,
bool recursive)
Sets a shader uniform of a Mesh node.
DLL NodeHandle addJointNode(NodeHandle parent,
const char *name,
int jointIndex)
Adds a Joint node to the scene.
DLL NodeHandle addLightNode(NodeHandle parent,
const char *name,
ResHandle materialRes,
const char *lightingContext,
const char *shadowContext)
Adds a Light node to the scene.
DLL bool setLightContexts(NodeHandle node,
const char *lightingContext,
const char *shadowContext)
Sets the shader contexts used by a light source.
DLL NodeHandle addCameraNode(NodeHandle parent,
const char *name,
ResHandle pipelineRes)
Adds a Camera node to the scene.
DLL bool setupCameraView(NodeHandle node,
float fov,
float aspect,
float nearDist,
float farDist)
Sets the planes of a camera viewing frustum.
DLL bool calcCameraProjectionMatrix(NodeHandle node,
float *projMat)
Calculates the camera projection matrix.
DLL NodeHandle addEmitterNode(NodeHandle parent,
const char *name,
ResHandle materialRes,
ResHandle effectRes,
int maxParticleCount,
int respawnCount)
Adds a Emitter node to the scene.
DLL bool advanceEmitterTime(NodeHandle node,
float timeDelta)
Advances the time value of an Emitter node.