Horde3D API | |
Conventions | Some conventions for the API. |
Typedefs and constants | |
Typedefs | |
Predefined constants | |
Enumerations | |
EngineOptions | The available engine option parameters. |
ResourceTypes | The available resource types. |
ResourceFlags | The available flags used when adding a resource. |
GeometryResParams | The available Geometry resource parameters. |
AnimationResParams | The available Animation resource parameters. |
TextureResParams | The available Texture2D resource parameters. |
SceneNodeTypes | The available scene node types. |
GroupNodeParams | The available Group node parameters. |
ModelNodeParams | The available Model node parameters |
MeshNodeParams | The available Mesh node parameters. |
JointNodeParams | The available Joint node parameters. |
LightNodeParams | The available Light node parameters. |
CameraNodeParams | The available Camera node parameters. |
EmitterNodeParams | The available Emitter node parameters. |
Basic functions | |
getVersionString | Returns the engine version string. |
checkExtension | Checks if an extension is part of the engine library. |
init | Initializes the engine. |
release | Releases the engine. |
resize | Resizes the viewport. |
render | Main rendering function. |
clear | Removes all resources and scene nodes. |
getMessage | Gets the next message from the message queue. |
getOption | Gets an option parameter of the engine. |
setOption | Sets an option parameter for the engine. |
showOverlay | Shows an overlay on the screen. |
General resource management functions | |
getResourceType | Returns the type of a resource. |
getResourceName | Returns the name of a resource. |
findResource | Finds a resource and returns its handle. |
addResource | Adds a resource. |
cloneResource | Duplicates a resource. |
removeResource | Removes a resource. |
loadResource | Loads a resource. |
unloadResource | Unloads a resource. |
getResourceParami | Gets a property of a resource. |
getResourceParamf | Gets a property of a resource. |
getResourceData | Gives access to resource data. |
updateResourceData | Updates the data of a resource. |
queryUnloadedResource | Returns handle to an unloaded resource. |
releaseUnusedResources | Frees resources that are no longer used. |
Specific resource management functions | |
setShaderPreambles | Sets preambles of all Shader resources. |
setMaterialUniform | Sets a shader uniform of a Material resource. |
setPipelineStageActivation | Sets the activation state of a pipeline stage. |
getPipelineRenderTargetData | Reads the pixel data of a pipeline render target buffer. |
General scene graph functions | |
getNodeType | Returns the type of a scene node. |
getNodeName | Returns the name of a scene node. |
setNodeName | Sets the name of a scene node. |
getNodeParent | Returns the parent of a scene node. |
setNodeParent | Relocates a node in the scene graph. |
getNodeChild | Returns the handle to a child node. |
getNodeAttachmentString | Returns the attachment string of a scene node. |
addNodes | Adds nodes from a SceneGraph resource to the scene. |
removeNode | Removes a node from the scene. |
setNodeActivation | Sets the activation state of a node. |
checkNodeTransformFlag | Checks if a scene node has been transformed by the engine. |
getNodeTransform | Gets the relative transformation of a node. |
setNodeTransform | Sets the relative transformation of a node. |
getNodeTransformMatrices | Returns the transformation matrices of a node. |
setNodeTransformMatrix | Sets the relative transformation matrix of a node. |
getNodeParamf | Gets a property of a scene node. |
setNodeParamf | Sets a property of a scene node. |
getNodeParami | Gets a property of a scene node. |
setNodeParamf | Sets a property of a scene node. |
getNodeAABB | Gets the bounding box of a scene node. |
findNodes | Finds scene nodes with the specified properties. |
getNodeFindResult | Gets a result from the findNodes query. |
castRay | Performs a recursive ray collision query. |
Group-specific scene graph functions | |
addGroupNode | Adds a Group node to the scene. |
Model-specific scene graph functions | |
addModelNode | Adds a Model node to the scene. |
setupModelAnimStage | Configures an animation stage of a Model node. |
setModelAnimParams | Sets the parameters of an animation stage in a Model node. |
setModelMorpher | Sets the weight of a morph target. |
Mesh-specific scene graph functions | |
addMeshNode | Adds a Mesh node to the scene. |
setMeshUniform | Sets a shader uniform of a Mesh node. |
Joint-specific scene graph functions | |
addJointNode | Adds a Joint node to the scene. |
Light-specific scene graph functions | |
addLightNode | Adds a Light node to the scene. |
setLightContexts | Sets the shader contexts used by a light source. |
Camera-specific scene graph functions | |
addCameraNode | Adds a Camera node to the scene. |
setupCameraView | Sets the planes of a camera viewing frustum. |
calcCameraProjectionMatrix | Calculates the camera projection matrix. |
Emitter-specific scene graph functions | |
addEmitterNode | Adds a Emitter node to the scene. |
advanceEmitterTime | Advances the time value of an Emitter node. |
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.
The available engine option parameters.
The available resource types.
The available flags used when adding a resource.
The available Geometry resource parameters.
The available scene node types.
The available Mesh node parameters.
The available Light node parameters.
The available Camera node parameters.
The available Emitter node parameters.
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.
extensionName | name of the extension |
true if extension is implemented, otherwise false
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.
none
true in case of success, otherwise false
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.
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 |
nothing
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.
cameraNode | camera node used for rendering scene |
true in case of success, otherwise false
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.
level | pointer to variable for storing message level indicating importance (can be NULL) |
time | pointer to variable for storing time when message was added (can be NULL) |
message string or empty string if no message is in queue
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.
param | option parameter |
value | value of the option parameter |
true if the option could be set to the specified value, otherwise false
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.
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) |
materialRes | material resource used for rendering |
nothing
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’.
res | handle to the resource |
type of the resource
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!
res | handle to the resource |
name of the resource or empty string in case of failure
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.
type | type of the resource |
name | name of the resource |
handle to the resource or 0 if not found
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.
type | type of the resource |
name | name of the resource |
flags | flags used for creating the resource |
handle to the resource to be added or 0 in case of failure
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.
sourceRes | handle to resource to be cloned |
name | name of new resource |
handle to the cloned resource or 0 in case of failure
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.
res | handle to the resource to be removed |
the number of references that the application is still holding after removal or -1 in case of an error
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
res | handle to the resource for which data is loaded |
data | pointer to the data to be loaded |
size | size of the data block |
true in case of success, otherwise false
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.
res | handle to resource to be unloaded |
true in case of success, otherwise false
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.
res | handle to the resource to be accessed |
param | parameter to be accessed |
value of the parameter
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.
res | handle to the resource to be accessed |
param | parameter to be accessed |
value of the parameter
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!
res | handle to the resource to be accessed |
param | parameter indicating data of the resource that will be accessed |
pointer to the specified resource data if it is available, otherwise NULL-pointer
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.
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 |
true in case of success, otherwise false
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.
none
nothing
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.
vertPreamble | preamble text of vertex shaders (default: empty string) |
fragPreamble | preamble text of fragment shaders (default: empty string) |
nothing
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.
materialRes | handle to the Material resource to be accessed |
name | name of the uniform as defined in Material resource |
a, b, c, d | values of the four components |
true in case of success, otherwise false
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.
pipelineRes | handle to the Pipeline resource to be accessed |
stageName | name of the stage to be modified |
enabled | flag indicating whether the stage shall be enabled or disabled |
true in case of success, otherwise false
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.
pipelineRes | handle to pipeline resource |
targetName | unique name of render target to access |
bufIndex | index of buffer to be accessed |
width | pointer to variable where the width of the buffer will be stored (can be NULL) |
height | pointer to variable where the height of the buffer will be stored (can be NULL) |
compCount | pointer to variable where the number of components will be stored (can be NULL) |
dataBuffer | pointer to float array where the pixel data will be stored (can be NULL) |
bufferSize | size of dataBuffer array in bytes |
true in case of success, otherwise false
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!
node | handle to the scene node |
name of the scene node or empty string in case of failure
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.
node | handle to the scene node |
handle to parent node or 0 in case of failure
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.
node | handle to the scene node to be relocated |
parent | handle to the new parent node |
true in case of success, otherwise false
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.
node | handle to the parent node |
index | index of the child node |
handle to the child node or 0 if child doesn’t exist
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!
node | handle to the node to be accessed |
attachment string (can be empty) or empty string in case of failure
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!
parent | handle to parent node to which the root of the new nodes will be attached |
sceneGraphRes | handle to SceneGraph resource |
handle to the root of the created nodes or 0 in case of failure
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.
node | handle to the node to be modified |
active | boolean value indicating whether node shall be active or inactive |
true in case of success otherwise false
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.
node | handle to the node to be accessed |
reset | flag indicating whether transformation flag shall be reset |
true if node has been transformed, otherwise false
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.
node | handle to the node which will be accessed |
tx, ty, tz | pointers to variables where translation of the node will be stored (can be NULL) |
rx, ry, rz | pointers to variables where rotation of the node in Euler angles will be stored (can be NULL) |
sx, sy, sz | pointers to variables where scale of the node will be stored (can be NULL) |
true in case of success otherwise false
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.
node | handle to the node which will be modified |
tx, ty, tz | translation of the node |
rx, ry, rz | rotation of the node in Euler angles |
sx, sy, sz | scale of the node |
true in case of success otherwise false
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.
node | handle to the scene node to 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) |
true in case of success otherwise false
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.
node | handle to the node which will be modified |
mat4x4 | pointer to a 4x4 matrix in column major order |
true in case of success otherwise false
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.
node | handle to the node to be accessed |
param | parameter to be accessed |
value of the parameter
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.
node | handle to the node to be modified |
param | parameter to be modified |
value | new value for the specified parameter |
true in case of success otherwise false
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.
node | handle to the node to be accessed |
param | parameter to be accessed |
value of the parameter
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.
node | handle to the node to be modified |
param | parameter to be modified |
value | new value for the specified parameter |
true in case of success otherwise false
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.
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 |
true in case of success otherwise false
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.
startNode | handle to the node where the search begins |
name | name of nodes to be searched (empty string for all nodes) |
type | type of nodes to be searched (SceneNodeTypes::Undefined for all types) |
number of search results
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.
index | index of search result |
handle to scene node from findNodes query or 0 if result doesn’t exist
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.
node | node at which intersection check is beginning |
ox, oy, oz | ray origin |
dx, dy, dz | ray direction vector also specifying ray length |
handle to nearest intersected node or 0 if no node was hit
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.
parent | handle to parent node to which the new node will be attached |
name | name of the node |
handle to the created node or 0 in case of failure
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.
parent | handle to parent node to which the new node will be attached |
name | name of the node |
geometryRes | Geometry resource used by Model node |
handle to the created node or 0 in case of failure
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.
node | handle to the node to be modified |
stage | index of the animation stage to be configured |
animationRes | handle to Animation resource |
startNode | name of first node to which animation shall be applied (or empty string) |
additive | flag indicating whether stage is additive |
true in case of success, otherwise false
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.
node | handle to the node to be modified |
stage | index of the animation stage to be modified |
time | new animation time/frame |
weight | new blend weight |
true in case of success, otherwise false
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.
node | handle to the node to be modified |
target | name of morph target |
weight | new weight for morph target |
true in case of success, otherwise false
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.
parent | handle to parent node to which the new node will be attached |
name | name of the node |
materialRes | material resource used by Mesh node |
batchStart | first triangle index of mesh in Geometry resource of parent Model node |
batchCount | number of triangle indices used for drawing mesh |
vertRStart | first vertex in Geometry resource of parent Model node |
vertREnd | last vertex in Geometry resource of parent Model node |
handle to the created node or 0 in case of failure
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.
node | handle to the node to be accessed |
name | name of the uniform as defined in mesh material resource |
a, b, c, d | values of the four components |
recursive | parameter specifying whether uniform is set recursively for all Mesh children of Mesh node |
true in case of success otherwise false
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.
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 |
handle to the created node or 0 in case of failure
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.
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 |
handle to the created node or 0 in case of failure
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.
node | handle to the node to be modified |
lightingContext | name of the shader context used for performing lighting calculations |
shadowContext | name of the shader context used for rendering shadow maps |
true in case of success otherwise false
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.
parent | handle to parent node to which the new node will be attached |
name | name of the node |
pipelineRes | pipeline resource used for rendering |
handle to the created node or 0 in case of failure
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.
node | handle to the Camera node which will be modified |
fov | field of view (FOV) angle |
aspect | aspect ratio |
nearDist | distance of near clipping plane |
farDist | distance of far clipping plane |
true in case of success otherwise false
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.
node | handle to Camera node |
projMat | pointer to float array with 16 elements |
true in case of success otherwise false
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.
parent | handle to parent node to which the new node will be attached |
name | name of the node |
materialRes | 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) |
handle to the created node or 0 in case of failure
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.
node | handle to the Emitter node which will be modified |
timeDelta | time delta in seconds |
true in case of success otherwise false
Returns the engine version string.
DLL const char *getVersionString()
Checks if an extension is part of the engine library.
DLL bool checkExtension( const char * extensionName )
Initializes the engine.
DLL bool init()
Releases the engine.
DLL void release()
Resizes the viewport.
DLL void resize( int x, int y, int width, int height )
Main rendering function.
DLL bool render( NodeHandle cameraNode )
Removes all resources and scene nodes.
DLL void clear()
Gets the next message from the message queue.
DLL const char *getMessage( int * level, float * time )
Gets an option parameter of the engine.
DLL float getOption( EngineOptions:: List param )
Sets an option parameter for the engine.
DLL bool setOption( EngineOptions:: List param, float value )
Shows an overlay on the screen.
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 )
Returns the type of a resource.
DLL ResourceTypes::List getResourceType( ResHandle res )
Returns the name of a resource.
DLL const char *getResourceName( ResHandle res )
Finds a resource and returns its handle.
DLL ResHandle findResource( ResourceTypes:: List type, const char * name )
Adds a resource.
DLL ResHandle addResource( ResourceTypes:: List type, const char * name, int flags )
Duplicates a resource.
DLL ResHandle cloneResource( ResHandle sourceRes, const char * name )
Removes a resource.
DLL int removeResource( ResHandle res )
Loads a resource.
DLL bool loadResource( ResHandle res, const char * data, int size )
Unloads a resource.
DLL bool unloadResource( ResHandle res )
Gets a property of a resource.
DLL int getResourceParami( ResHandle res, int param )
Gets a property of a resource.
DLL float getResourceParamf( ResHandle res, int param )
Gives access to resource data.
DLL const void *getResourceData( ResHandle res, int param )
Updates the data of a resource.
DLL bool updateResourceData( ResHandle res, int param, const void * data, int size )
Returns handle to an unloaded resource.
DLL ResHandle queryUnloadedResource()
Frees resources that are no longer used.
DLL void releaseUnusedResources()
Sets preambles of all Shader resources.
DLL void setShaderPreambles( const char * vertPreamble, const char * fragPreamble )
Sets a shader uniform of a Material resource.
DLL bool setMaterialUniform( ResHandle materialRes, const char * name, float a, float b, float c, float d )
Sets the activation state of a pipeline stage.
DLL bool setPipelineStageActivation( ResHandle pipelineRes, const char * stageName, bool enabled )
Reads the pixel data of a pipeline render target buffer.
DLL bool getPipelineRenderTargetData( ResHandle pipelineRes, const char * targetName, int bufIndex, int * width, int * height, int * compCount, float * dataBuffer, int bufferSize )
Returns the type of a scene node.
DLL int getNodeType( NodeHandle node )
Returns the name of a scene node.
DLL const char *getNodeName( NodeHandle node )
Sets the name of a scene node.
DLL bool setNodeName( NodeHandle node, const char * name )
Returns the parent of a scene node.
DLL NodeHandle getNodeParent( NodeHandle node )
Relocates a node in the scene graph.
DLL bool setNodeParent( NodeHandle node, NodeHandle parent )
Returns the handle to a child node.
DLL NodeHandle getNodeChild( NodeHandle node, int index )
Returns the attachment string of a scene node.
DLL const char *getNodeAttachmentString( NodeHandle node )
Adds nodes from a SceneGraph resource to the scene.
DLL NodeHandle addNodes( NodeHandle parent, ResHandle sceneGraphRes )
Removes a node from the scene.
DLL bool removeNode( NodeHandle node )
Sets the activation state of a node.
DLL bool setNodeActivation( NodeHandle node, bool active )
Checks if a scene node has been transformed by the engine.
DLL bool checkNodeTransformFlag( NodeHandle node, bool reset )
Gets the relative transformation of a node.
DLL bool getNodeTransform( 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 setNodeTransform( NodeHandle node, float tx, float ty, float tz, float rx, float ry, float rz, float sx, float sy, float sz )
Returns the transformation matrices of a node.
DLL bool getNodeTransformMatrices( NodeHandle node, const float ** relMat, const float ** absMat )
Sets the relative transformation matrix of a node.
DLL bool setNodeTransformMatrix( NodeHandle node, const float * mat4x4 )
Gets a property of a scene node.
DLL float getNodeParamf( NodeHandle node, int param )
Sets a property of a scene node.
DLL bool setNodeParamf( NodeHandle node, int param, float value )
Gets a property of a scene node.
DLL int getNodeParami( NodeHandle node, int param )
Gets the bounding box of a scene node.
DLL bool getNodeAABB( NodeHandle node, float * minX, float * minY, float * minZ, float * maxX, float * maxY, float * maxZ )
Finds scene nodes with the specified properties.
DLL int findNodes( NodeHandle startNode, const char * name, int type )
Gets a result from the findNodes query.
DLL NodeHandle getNodeFindResult( int index )
Performs a recursive ray collision query.
DLL NodeHandle castRay( NodeHandle node, float ox, float oy, float oz, float dx, float dy, float dz )
Adds a Group node to the scene.
DLL NodeHandle addGroupNode( NodeHandle parent, const char * name )
Adds a Model node to the scene.
DLL NodeHandle addModelNode( NodeHandle parent, const char * name, ResHandle geometryRes )
Configures an animation stage of a Model node.
DLL bool setupModelAnimStage( NodeHandle node, int stage, ResHandle animationRes, const char * startNode, bool additive )
Sets the parameters of an animation stage in a Model node.
DLL bool setModelAnimParams( NodeHandle node, int stage, float time, float weight )
Sets the weight of a morph target.
DLL bool setModelMorpher( NodeHandle node, const char * target, float weight )
Adds a Mesh node to the scene.
DLL NodeHandle addMeshNode( NodeHandle parent, const char * name, ResHandle materialRes, int batchStart, int batchCount, int vertRStart, int vertREnd )
Sets a shader uniform of a Mesh node.
DLL bool setMeshUniform( NodeHandle node, const char * name, float a, float b, float c, float d, bool recursive )
Adds a Joint node to the scene.
DLL NodeHandle addJointNode( NodeHandle parent, const char * name, int jointIndex )
Adds a Light node to the scene.
DLL NodeHandle addLightNode( NodeHandle parent, const char * name, ResHandle materialRes, const char * lightingContext, const char * shadowContext )
Sets the shader contexts used by a light source.
DLL bool setLightContexts( NodeHandle node, const char * lightingContext, const char * shadowContext )
Adds a Camera node to the scene.
DLL NodeHandle addCameraNode( NodeHandle parent, const char * name, ResHandle pipelineRes )
Sets the planes of a camera viewing frustum.
DLL bool setupCameraView( NodeHandle node, float fov, float aspect, float nearDist, float farDist )
Calculates the camera projection matrix.
DLL bool calcCameraProjectionMatrix( NodeHandle node, float * projMat )
Adds a Emitter node to the scene.
DLL NodeHandle addEmitterNode( NodeHandle parent, const char * name, ResHandle materialRes, ResHandle effectRes, int maxParticleCount, int respawnCount )
Advances the time value of an Emitter node.
DLL bool advanceEmitterTime( NodeHandle node, float timeDelta )