Horde3D API Reference

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.



Function and enumeration overview

This is a list of the functions and enumerations that Horde3D is exporting via its DLL interface.

Engine types and constants

Engine enumerations

Basic engine functions

Resource management functions

General

Material specific

Scene graph functions

General

Group specific

Model specific

Mesh specific

Joint specific

Light specific

Camera specific

Emitter specific



Type and constant details

Types:
ResHandle   unsigned int
NodeHandle   unsigned int
Constants:
RootNode = 1   Scene root node handle
PrimeTimeCam = 2   Default camera node handle




Enumeration details

enum ResourceFlags

The available flags used when adding a resource.

Enumerator:
NoQuery = 1   Excludes resource from being listed by queryUnloadedResource function.
NoCompression = 2   Disables texture compression for new Texture2D or TextureCube resource.


enum EngineOptions

The available engine option parameters.

Enumerator:
TrilinearFiltering   Enables or disables trilinear filtering for textures; only affects textures that are loaded after setting the option. (Values: 0, 1; Default: 1)
AnisotropyFactor   Sets the quality for anisotropic filtering; only affects textures that are loaded after setting the option. (Values: 1, 2, 4, 8; Default: 1)
TexCompression   Enables or disables texture compression; only affects textures that are loaded after setting the option. (Values: 0, 1; Default: 0)
LoadTextures   Enables or disables loading of texture images; option can be used to minimize loading times for testing. (Values: 0, 1; Default: 1)
FastAnimation   Disables or enables inter-frame interpolation for animations. (Values: 0, 1; Default: 1)
OcclusionCulling   Enables 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)
ShadowMapSize   Sets the size of the shadow map buffer (Values: 128, 256, 512, 1024, 2048; Default: 512)
DebugViewMode   Enables 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)


enum ResourceTypes

The available resource types.

Enumerator:
SceneGraph   scene graph subtree
Geometry   geometrical data containing bones, vertices and triangles
Animation   animation data
Material   material script
Code   shader source code
Shader   shader program
Texture2D   two-dimensional texture map
TextureCube   cube map texture
Effect   particle configuration
Undefined = 9999   undefined resource, returned by getResourceType in case of error


enum ResourceData

The available parameters for accessing resource data.

Enumerator:
AnimFrameCount   number of animation frames (pointer to uint); valid for Animation resource for reading data
Tex2DPixelData   image pixel data (pointer to unsigned char); valid for Texture2D resource for writing data


enum SceneNodeTypes

The available scene node types.

Enumerator:
Group   group of different scene nodes
Model   3d model with optional skeleton
Mesh   subgroup of a model with triangles of one material
Joint   joint for skeletal animation
Light   light source
Camera   camera giving view on scene
Emitter   particle system emitter
Undefined = 9999   undefined node type, returned by getNodeType in case of error


enum GroupNodeParams

The available group node parameters.

Enumerator:
MinDist   minimal distance from the viewer for the node to be visible (default: 0.0); used for level of detail [type: float]
MaxDist   maximal distance from the viewer for the node to be visible (default: infinite); used for level of detail [type: float]


enum MeshNodeParams

The available mesh node parameters.

Enumerator:
MaterialRes   material resource used for the mesh [type: ResHandle]


enum LightNodeParams

The available model node parameters.

Enumerator:
MaterialRes   material resource used for the light [type: ResHandle]
Radius   radius of influence (default: 0.0) [type: float]
FOV   field of view (FOV) in degrees (default: 90.0) [type: float]
Col_R   red component of light diffuse color (default: 1.0) [type: float]
Col_G   green component of light diffuse color (default: 1.0) [type: float]
Col_B   blue component of light diffuse color (default: 1.0) [type: float]
ShadowMapCount   number of shadow maps used for light source (values: 0, 1, 2, 3, 4; default: 0) [type: int]
ShadowSplitLambda   constant determining segmentation of view frustum for Parallel Split Shadow Maps (default: 0.5) [type: float]
ShadowMapBias   bias value for shadow mapping to reduce shadow acne (default: 0.005) [type: float]


enum CameraNodeParams

The available camera node parameters.

Enumerator:
LeftPlane   coordinate of left plane relative to near plane center (default: -0.055228457) [type: float]
RightPlane   coordinate of right plane relative to near plane center (default: 0.055228457) [type: float]
BottomPlane   coordinate of bottom plane relative to near plane center (default: -0.041421354f) [type: float]
TopPlane   coordinate of top plane relative to near plane center (default: 0.041421354f) [type: float]
NearPlane   distance of near clipping plane (default: 0.1) [type: float]
FarPlane   distance of far clipping plane (default: 1000) [type: float]


enum EmitterNodeParams

The available emitter node parameters.

Enumerator:
Delay   time in seconds before emitter begins creating particles (default: 0.0) [type: float]
EmissionRate   maximal number of particles to be created per second (default: 0.0) [type: float]
SpreadAngle   angle (in degrees) of cone for random emission direction (default: 0.0) [type: float]
ForceX   x-component of force vector applied to particles (default: 0.0) [type: float]
ForceY   y-component of force vector applied to particles (default: 0.0) [type: float]
ForceZ   z-component of force vector applied to particles (default: 0.0) [type: float]




Function details (in alphabetical order)

The following functions are all in the namespace Horde3D


NodeHandle addCameraNode( NodeHandle parent, const char *name )

Adds a Camera node to the scene.

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

Parameters:
parent   handle to parent node to which the new node will be attached
name   name of the node
Returns:
handle to the created node or 0 in case of failure


NodeHandle addEmitterNode( NodeHandle parent, const char *name, ResHandle matRes, ResHandle effectRes, uint 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:
parent   handle to parent node to which the new node will be attached
name   name of the node
matRes   handle to material resource used for rendering
effectRes   handle to effect resource used for configuring particle properties
maxParticleCount   maximal number of particles living at the same time
respawnCount   number of times a single particle is recreated after dying (-1 for infinite)
Returns:
handle to the created node or 0 in case of failure


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:
parent   handle to parent node to which the new node will be attached
name   name of the node
Returns:
handle to the created node or 0 in case of failure


NodeHandle addJointNode( NodeHandle parent, const char *name, uint jointIndex )

Adds a Joint node to the scene.

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

Parameters:
parent   handle to parent node to which the new node will be attached
name   name of the node
jointIndex   index of joint in Geometry resource of parent Model node
Returns:
handle to the created node or 0 in case of failure


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:
parent   handle to parent node to which the new node will be attached
name   name of the node
materialRes   material resource for light configuration or 0 if not used
lightingContext   name of the shader context used for doing light calculations
shadowContext   name of the shader context used for doing shadow map rendering
Returns:
handle to the created node or 0 in case of failure


NodeHandle addMeshNode( NodeHandle parent, const char *name, ResHandle matRes, uint batchStart, uint batchCount, uint vertRStart, uint vertREnd )

Adds a Mesh node to the scene.

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

Parameters:
parent   handle to parent node to which the new node will be attached
name   name of the node
matRes   Material resource used by Mesh node
batchStart   first vertex index in Geometry resource of parent Model node
batchCount   number of vertex indices in Geometry resource of parent Model node
vertRStart   minimum vertex array index contained in Geometry resource indices of parent Model node
vertREnd   maximum vertex array index contained in Geometry resource indices of parent Model node
Returns:
handle to the created node or 0 in case of failure


NodeHandle addModelNode( NodeHandle parent, const char *name, ResHandle geoRes )

Adds a Model node to the scene.

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

Parameters:
parent   handle to parent node to which the new node will be attached
name   name of the node
geoRes   Geometry resource used by Model node
Returns:
handle to the created node or 0 in case of failure


NodeHandle addNodes( NodeHandle parent, ResHandle res )

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.

Parameters:
parent   handle to parent node to which the root of the new nodes will be attached
res   handle to the SceneGraph resource
Returns:
handle to the root of the created nodes or 0 in case of failure


ResHandle addResource( ResourceType type, const char *name, uint 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 found, the handle to the existing resource is returned instead of creating a new one.

Parameters:
type   type of the resource
name   name of the resource
flags   flags used for creating the resource
Returns:
handle to the resource to be added or 0 in case of failure


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.

Parameters:
node   handle to the Emitter node which will be modified
timeDelta   time delta in seconds
Returns:
true in case of success, otherwise false


void clear( )

Frees 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


ResHandle findResource( ResourceType 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:
type   type of the resource
name   name of the resource
Returns:
handle to the resource or 0 if not found


NodeHandle getActiveCamera( )

Returns the active camera.

This function returns the handle to the currently actice camera node from which the scene is rendered.

Parameters:
none
Returns:
handle to the active camera node


float getCameraParam( NodeHandle node, CameraNodeParam param )

Gets a property of a Camera node.

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

Parameters:
node   handle to the node to be accessed
param   parameter to be accessed
Returns:
value of the parameter


float getEmitterParam( NodeHandle node, EmitterNodeParam param )

Gets a property of an Emitter node.

This function returns a specified property of the specified node. The specified node must be an Emitter node.

Parameters:
node   handle to the node to be accessed
param   parameter to be accessed
Returns:
value of the parameter


float getGroupParam( NodeHandle node, GroupNodeParam param )

Gets a property of a Group node.

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

Parameters:
node   handle to the node to be accessed
param   parameter to be accessed
Returns:
value of the parameter


float getLightParam( NodeHandle node, LightNodeParam param )

Gets a property of a Light node.

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

Parameters:
node   handle to the node to be accessed
param   parameter to be accessed
Returns:
value of the parameter


bool getMeshData( NodeHandle node, uint *vertPosArrayCount, const float **vertPosArrayData, uint *indexArrayCount, const uint **indexArayData, uint *indexOffset )

Gives access to Mesh node geometry data.

This function gives access to the vertex position data and triangle vertex indices of the meshes geometry. The vertex positions are untransformed and are stored as float coordinates in X, Y, Z order.

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:
node   handle to the node to be accessed
vertPosArrayCount   pointer to variable where number of vertices in position array will be stored (can be NULL if data is not required)
vertPosArrayData   pointer to variable where address of vertex position array will be stored (can be NULL if data is not required)
indexArrayCount   pointer to variable where number of indices will be stored (can be NULL if data is not required)
indexArayData   pointer to variable where address of index array will be stored (can be NULL if data is not required)
indexOffset   pointer to variable where offset of the first index value relative to zero will be stored; required to access vertPosArrayData array with indexArayData indices
Returns:
true in case of success, otherwise false


float getMeshParam( NodeHandle node, MeshNodeParam param )

Gets a property of a Mesh node.

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

Parameters:
node   handle to the node to be accessed
param   parameter to be accessed
Returns:
value of the parameter


const char *getMessage( unsigned 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:
level   pointer to variable for storing message level indicating importance (can be NULL)
time   pointer to variable for stroing time when message was added (can be NULL)
Returns:
message string or empty string if no message is in queue


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:
node   handle to the node which will be accessed
minX, minY, minZ   pointers to variables where minimum coordinates will be stored
maxX, maxY, maxZ   pointers to variables where maximum coordinates will be stored
Returns:
true in case of success, otherwise false


NodeHandle getNodeChild( NodeHandle parent, const char *name, uint index, bool recursive )

Returns the handle to a child node.

This function looks for the n-th child node with a specified name and returns its handle. If no matching child node was found, the function returns 0.

Parameters:
parent   handle to the parent node
name   name of the child node; if name is empty string, all children are considered
index   index of the child node (useful if there are several matching children)
recursive   specifies whether the node is scanned recursively, meaning that children of a child are also examined
Returns:
the handle to the child node or 0 if no matching child was found


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:
node   handle to the scene node whose name will be returned
Returns:
name of the scene node or empty string in case of failure


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:
node   handle to the scene node whose parent will be returned
Returns:
handle to parent node or 0 in case of failure


bool getNodeTransform( NodeHandle node, float *px, float *py, float *pz, 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:
node   handle to the node which will be accessed
px, py, pz   pointers to variables where position of the node will be stored
rx, ry, rz   pointers to variables where rotation of the node in Euler angles (degrees) will be stored
sx, sy, sz   pointers to variables where scale of the node will be stored
Returns:
true in case of success, otherwise false


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:
node   handle to the scene node whose matrices will be accessed
relMat   pointer to a variable where the address of the relative transformation matrix will be stored (can be NULL if matrix is not required)
absMat   pointer 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


SceneNodeType 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:
node   handle to the scene node whose type will be returned
Returns:
type of the scene node


float getOption( EngineOption param )

Gets an option parameter of the engine.

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

Parameters:
param   option parameter
Returns:
current value of the specified option parameter


const void *getResourceData( ResHandle res, ResourceData 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:
res   handle to the resource to be accessed
param   parameter indicating data of the resource that will be accessed
Returns:
pointer to the specified resource data if it is available, otherwise NULL-pointer


const char *getResourcePath( ResourceType type )

Gets the search path of a resource type.

This function returns the search path of a specified resource type.

Parameters:
type   type of resource
Returns:
pointer to the search path string


ResourceType 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:
res   handle to the resource whose type will be returned
Returns:
type of the scene node


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


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.

Parameters:
none
Returns:
true in case of success, otherwise false


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:
res   handle to resource to be unloaded
Returns:
true in case of success, otherwise false


bool loadPipelineConfig( const char *configFilename )

Loads the pipeline configuration.

This function loads the pipeline configuration from a specified file. If another configuration has already been loaded the pipeline is reset and initialized with the new configuration.

Parameters:
configFilename   name of the pipeline configuration file to be loaded
Returns:
true in case of success, otherwise false


bool loadResource( const char *name, const char *data, uint 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. The function can only be called once for every resource.

Important Note: The data block must be null terminated!

Parameters:
name   name of the resource for which the data is loaded
data   pointer to the data to be loaded (null terminated block)
size   size of the data block
Returns:
true in case of success, otherwise false


const char *queryUnloadedResource( )

Returns the name of an unloaded resource.

This function searches a resource that is not yet loaded and returns a pointer to its name string. If there are no unloaded resources, an empty string is returned.

Parameters:
none
Returns:
pointer to the name of an unloaded resource or empty string


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


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


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:
node   handle to the node to be removed
Returns:
true in case of success otherwise false


bool removeResource( ResHandle res )

Removes a resource.

This function removes a specified resource from the resource manager. If the resource is still in use, this operation is delayed.

Note: The memory is not freed until you call releaseUnusedResources.

Parameters:
res   handle to the resource to be removed
Returns:
true in case of success, otherwise false


void render( )

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:
none
Returns:
nothing


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:
x   the x-position of the viewport in the rendering context
y   the y-position of the viewport in the rendering context
width   the width of the viewport
height   the height of the viewport
Returns:
nothing


bool setActiveCamera( NodeHandle camNode )

Sets the active camera.

This function sets the specified camera node as active camera from which the scene is rendered.

Parameters:
camNode   handle to camera node
Returns:
true in case of success, otherwise false


bool setCameraParam( NodeHandle node, CameraNodeParams param, float value )

Sets a property of a Camera node.

This function sets a specified property of the specified node to a specified value. The specified node must be a Camera node, or alternatively a Group node. Calls on the latter node type are recursively passed to all Camera child nodes.

Parameters:
node   handle to the node to be modified
param   parameter to be modified
value   new value for the specified parameter
Returns:
true in case of success otherwise false


bool setEmitterParam( NodeHandle node, EmitterNodeParams param, float value )

Sets a property of an Emitter node.

This function sets a specified property of the specified node to a specified value. The specified node must be an Emitter node, or alternatively a Group node. Calls on the latter node type are recursively passed to all Emitter child nodes.

Parameters:
node   handle to the node to be modified
param   parameter to be modified
value   new value for the specified parameter
Returns:
true in case of success otherwise false


bool setGroupParam( NodeHandle node, GroupNodeParam param, float value )

Sets a property of a Group node.

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

Parameters:
node   handle to the node to be modified
param   parameter to be modified
value   new value for the specified parameter
Returns:
true in case of success otherwise false


bool setLightParam( NodeHandle node, LightNodeParam param, float value )

Sets a property of a Light node.

This function sets a specified property of the specified node to a specified value. The specified node must be a Light node, or alternatively a Group node. Calls on the latter node type are recursively passed to all Light child nodes.

Parameters:
node   handle to the node to be modified
param   parameter to be modified
value   new value for the specified parameter
Returns:
true in case of success otherwise false


bool setMaterialUniform( ResHandle matRes, 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:
matRes   handle to the Material resource to be accessed
name   name of the uniform as defined in Material resource
a   value of first component
b   value of second component
c   value of third component
d   value of fourth component
Returns:
true in case of success, otherwise false


bool setMeshParam( NodeHandle node, MeshNodeParam param, float value )

Sets a property of a Mesh node.

This function sets a specified property of the specified node to a specified value. The specified node must be a Mesh node, or alternatively a Model or Group node. Calls on the latter two node types are recursively passed to all Mesh child nodes.

Parameters:
node   handle to the node to be modified
param   parameter to be modified
value   new value for the specified parameter
Returns:
true in case of success otherwise false


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:
node   handle to the Mesh node to be accessed
name   name of the uniform as defined in mesh material resource
a   value of first component
b   value of second component
c   value of third component
d   value of fourth component
recursive   parameter specifying whether uniform is set recursively for all Mesh children of Mesh node
Returns:
true in case of success, otherwise false


bool setModelAnimParams( NodeHandle node, uint 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. The function operates on Model nodes but accepts also Group nodes in which case the call is passed recursively to the Model child nodes.

Parameters:
node   handle to the node to be modified
stage   index of the animation stage to be modified
time   new animation time
weight   new animation weight
Returns:
true in case of success, otherwise false


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. The function operates on Model nodes but accepts also Group nodes in which case the call is passed recursively to the Model child nodes. If the specified morph target is not found the function returns false.

Parameters:
node   handle to the node to be modified
target   name of morph target
weight   new weight for morph target
Returns:
true in case of success, otherwise false


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:
node   handle to the node to be modified
active   boolean value indicating whether node is active or inactive
Returns:
true in case of success, otherwise false


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:
node   handle to the scene node whose name will be changed
name   new name of the scene node
Returns:
true in case of success, otherwise false


bool setNodeTransform( NodeHandle node, float px, float py, float pz, 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:
node   handle to the node which will be modified
px, py, pz   position of the node
rx, ry, rz   rotation of the node in Euler angles (degrees)
sx, sy, sz   scale of the node
Returns:
true in case of success, otherwise false


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:
node   handle to the scene node whose matrix will be updated
mat4x4   pointer to a 4x4 matrix in column major order
Returns:
true in case of success, otherwise false


bool setOption( EngineOption param, float value )

Sets an option parameter for the engine.

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

Parameters:
param   option parameter
value   value of the option parameter
Returns:
true if the option could be set to the specified value, otherwise false


void setResourcePath( ResourceType type, const char *path )

Sets the search path for a resource type.

This function sets the search path for a specified resource type. Whenever a new resource is added, the specified path is concatenated to the name of the created resource.

Parameters:
type   type of resource
path   path where the resources can be found (without slash or backslash at the end)
Returns:
nothing


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:
node   handle to the Camera node which will be modified
fov   field of view (FOV) in degrees
aspect   aspect ratio
nearDist   distance of near clipping plane
farDist   distance of far clipping plane
Returns:
true in case of success, otherwise false


bool setupModelAnimStage( NodeHandle node, uint stage, ResHandle res, const char *animMask, 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 operates on Model nodes but accepts also Group nodes in which case the call is passed recursively to the Model child nodes.
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 animation mask determines which child-nodes of the model (joints or meshes) are affected by the specified animation on the stage to be configured. If the mask is an empty string, the animation affects all nodes. Otherwise the mask can contain several node names separated by the two character sequence '<>'. When a mask is specified, the initial state of all nodes is 'not affected by animation'. For every node in the mask the function recurses down the (skeleton-) hierarchy starting at the currently processed node in the mask and inverts the state of the considered nodes. This makes it possible to do complex animation mixing.
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:
node   handle to the node to be modified
stage   index of the animation stage to be configured
res   handle to Animation resource
animMask   mask defining which nodes will be affected by animation
additive   flag indicating whether stage is additive
Returns:
true in case of success, otherwise false


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, uint layer, ResHandle material )

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_ll   position and texture coordinates of the lower left corner
x_lr, y_lr, u_lr, v_lr   position and texture coordinates of the lower right corner
x_ur, y_ur, u_ur, v_ur   position and texture coordinates of the upper right corner
x_ul, y_ul, u_ul, v_ul   position and texture coordinates of the upper left corner
layer   layer index of the overlay (Values: from 0 to 7)
material   material resource used for rendering
Returns:
nothing


bool updateResourceData( ResHandle res, ResourceData param, const void *data, uint 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:
Tex2DPixelData   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. 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.

Parameters:
res   handle to the resource for which the data is modified
param   data structure which will be updated
data   pointer to the new data
size   size of the new data block
Returns:
true in case of success, otherwise false




Integration Library

For more information on the Integration Library see the Usage Guide.


Prototypes:
typedef void (*NodeAttFactoryFunc)( unsigned int node, const char *attachmentString )
Callback function evoked when a scene node with attachment is created, passing node handle and attachment string
typedef void (*NodeAttCollectorFunc)( unsigned int node )
Callback function evoked when a scene node with attachment is removed, passing node handle


class NodeAttachment

Attachments can be assigned to scene nodes in order to be notified on updates of the scene graph and to store not graphics related data within the scene graph.

Public Static:
static NodeAttFactoryFunc getFactory( )
Returns user specified attachment construction callback function
static void setFactory( NodeAttFactoryFunc func )
Sets attachment construction callback function
static NodeAttCollectorFunc getCollector( )
Returns user specified attachment destruction callback function
static void setCollector( NodeAttCollectorFunc func )
Sets attachment destruction callback function
static NodeAttachment *getFromNode( NodeHandle node )
Returns the attachment of a specified scene node or NULL if it doesn't exist

Protected:
uint _node
Node to which attachment class is assigned

Public:
NodeAttachment( NodeHandle node )
Constructor assigning attachment to specified scene node
virtual ~NodeAttachment( )
Destructor
virtual void onUpdate( )
Update event called when scene node transformation changes
void updateSceneGraph( )
Function used for telling the engine to update the scene graph in case of changes


Copyright © 2006-2007 Nicolas Schulz