| Horde3D API | |
| Conventions | Some conventions for the API. |
| Typedefs and constants | |
| Typedefs | |
| Predefined constants | |
| Enumerations | |
| H3DOptions | The available engine option parameters. |
| H3DStats | The available engine statistic parameters. |
| H3DResTypes | The available resource types. |
| H3DResFlags | The available flags used when adding a resource. |
| H3DFormats | The available resource stream formats. |
| H3DGeoRes | The available Geometry resource accessors. |
| H3DAnimRes | The available Animation resource accessors. |
| H3DMatRes | The available Material resource accessors. |
| H3DShaderRes | The available Shader resource accessors. |
| H3DTexRes | The available Texture resource accessors. |
| H3DPartEffRes | The available ParticleEffect resource accessors. |
| H3DPipeRes | The available Pipeline resource accessors. |
| H3DNodeTypes | The available scene node types. |
| H3DNodeParams | The available scene node parameters. |
| H3DModel | The available Model node parameters |
| H3DMesh | The available Mesh node parameters. |
| H3DJoint | The available Joint node parameters. |
| H3DLight | The available Light node parameters. |
| H3DCamera | The available Camera node parameters. |
| H3DEmitter | The available Emitter node parameters. |
| Basic functions | |
| h3dGetVersionString | Returns the engine version string. |
| h3dCheckExtension | Checks if an extension is part of the engine library. |
| h3dInit | Initializes the engine. |
| h3dRelease | Releases the engine. |
| h3dSetupViewport | Sets the location and size of the viewport. |
| h3dRender | Main rendering function. |
| h3dFinalizeFrame | Marker for end of frame. |
| h3dClear | Removes all resources and scene nodes. |
| h3dGetMessage | Gets the next message from the message queue. |
| h3dGetOption | Gets an option parameter of the engine. |
| h3dSetOption | Sets an option parameter for the engine. |
| h3dGetStat | Gets a statistic value of the engine. |
| h3dShowOverlay | Shows an overlay on the screen. |
| h3dClearOverlays | Removes all overlays. |
| General resource management functions | |
| h3dGetResType | Returns the type of a resource. |
| h3dGetResName | Returns the name of a resource. |
| h3dGetNextResource | Returns the next resource of the specified type. |
| h3dFindResource | Finds a resource and returns its handle. |
| h3dAddResource | Adds a resource. |
| h3dCloneResource | Duplicates a resource. |
| h3dRemoveResource | Removes a resource. |
| h3dIsResLoaded | Checks if a resource is loaded. |
| h3dLoadResource | Loads a resource. |
| h3dUnloadResource | Unloads a resource. |
| h3dGetResElemCount | Gets the number of elements in a resource. |
| h3dFindResElem | Finds a resource element with the specified property value. |
| h3dGetResParamI | Gets an integer property of a resource element. |
| h3dSetResParamI | Sets an integer property of a resource element. |
| h3dGetResParamF | Gets a float property of a resource element. |
| h3dSetResParamF | Sets a float property of a resource element. |
| h3dGetResParamStr | Gets a string property of a resource element. |
| h3dSetResParamStr | Sets a string property of a resource element. |
| h3dMapResStream | Maps the stream of a resource element. |
| h3dUnmapResStream | Unmaps a previously mapped resource stream. |
| h3dQueryUnloadedResource | Returns handle to an unloaded resource. |
| h3dReleaseUnusedResources | Frees resources that are no longer used. |
| Specific resource management functions | |
| h3dCreateTexture | Creates a Texture resource. |
| h3dSetShaderPreambles | Sets preambles of all Shader resources. |
| h3dSetMaterialUniform | Sets a shader uniform of a Material resource. |
| h3dGetPipelineRenderTargetData | Reads the pixel data of a pipeline render target buffer. |
| General scene graph functions | |
| h3dGetNodeType | Returns the type of a scene node. |
| h3dGetNodeParent | Returns the parent of a scene node. |
| h3dSetNodeParent | Relocates a node in the scene graph. |
| h3dGetNodeChild | Returns the handle to a child node. |
| h3dAddNodes | Adds nodes from a SceneGraph resource to the scene. |
| h3dRemoveNode | Removes a node from the scene. |
| h3dSetNodeActivation | Sets the activation (visibility) state of a node. |
| h3dCheckNodeTransFlag | Checks if a scene node has been transformed by the engine. |
| h3dGetNodeTransform | Gets the relative transformation of a node. |
| h3dSetNodeTransform | Sets the relative transformation of a node. |
| h3dGetNodeTransMats | Returns the transformation matrices of a node. |
| h3dSetNodeTransMat | Sets the relative transformation matrix of a node. |
| h3dGetNodeParamI | Gets a property of a scene node. |
| h3dSetNodeParamI | Sets a property of a scene node. |
| h3dGetNodeParamF | Gets a property of a scene node. |
| h3dSetNodeParamF | Sets a property of a scene node. |
| h3dGetNodeParamStr | Gets a property of a scene node. |
| h3dSetNodeParamStr | Sets a property of a scene node. |
| h3dGetNodeAABB | Gets the bounding box of a scene node. |
| h3dFindNodes | Finds scene nodes with the specified properties. |
| h3dGetNodeFindResult | Gets a result from the findNodes query. |
| h3dCastRay | Performs a recursive ray collision query. |
| h3dGetCastRayResult | Returns a result of a previous castRay query. |
| h3dCheckNodeVisibility | Checks if a node is visible. |
| Group-specific scene graph functions | |
| h3dAddGroupNode | Adds a Group node to the scene. |
| Model-specific scene graph functions | |
| h3dAddModelNode | Adds a Model node to the scene. |
| h3dSetupModelAnimStage | Configures an animation stage of a Model node. |
| h3dSetModelAnimParams | Sets the parameters of an animation stage in a Model node. |
| h3dSetModelMorpher | Sets the weight of a morph target. |
| Mesh-specific scene graph functions | |
| h3dAddMeshNode | Adds a Mesh node to the scene. |
| Joint-specific scene graph functions | |
| h3dAddJointNode | Adds a Joint node to the scene. |
| Light-specific scene graph functions | |
| h3dAddLightNode | Adds a Light node to the scene. |
| Camera-specific scene graph functions | |
| h3dAddCameraNode | Adds a Camera node to the scene. |
| h3dSetupCameraView | Sets the planes of a camera viewing frustum. |
| h3dGetCameraProjMat | Gets the camera projection matrix. |
| Emitter-specific scene graph functions | |
| h3dAddEmitterNode | Adds a Emitter node to the scene. |
| h3dAdvanceEmitterTime | Advances the time value of an Emitter node. |
| h3dHasEmitterFinished | Checks if an Emitter node is still alive. |
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. When Euler angles are used, the rotation order is YXZ [*vec], so the z-rotation is applied first.
The available engine option parameters.
The available engine statistic parameters.
The available resource types.
The available flags used when adding a resource.
The available Geometry resource accessors.
The available Material resource accessors.
The available Texture resource accessors.
The available ParticleEffect resource accessors.
The available scene node types.
The available Model node parameters
The available Mesh node parameters.
The available Light node parameters.
The available Camera node parameters.
The available Emitter node parameters.
DLL bool h3dCheckExtension( 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 h3dInit()
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. The function can be called several times on different rendering contexts in order to initialize them.
none
true in case of success, otherwise false
DLL void h3dSetupViewport( int x, int y, int width, int height, bool resizeBuffers )
Sets the location and size of the viewport.
This function sets the location and size of the viewport. It has to be called after engine initialization and whenever the size of the rendering context/window changes. The resizeBuffers parameter specifies whether render targets with a size relative to the viewport dimensions should be resized. This is usually desired after engine initialization and when the window is resized but not for just rendering to a part of the framebuffer.
| x | the x-position of the lower left corner of the viewport rectangle |
| y | the y-position of the lower left corner of the viewport rectangle |
| width | the width of the viewport |
| height | the height of the viewport |
| resizeBuffers | specifies whether render targets should be adapted to new size |
nothing
DLL bool h3dRender( H3DNode cameraNode )
Main rendering function.
This is the main function of the engine. It executes all the rendering, animation and other tasks. The function can be called several times per frame, for example in order to write to different output buffers.
| cameraNode | camera node used for rendering scene |
true in case of success, otherwise false
DLL const char *h3dGetMessage( 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 h3dSetOption( H3DOptions:: 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 float h3dGetStat( H3DStats:: List param, bool reset )
Gets a statistic value of the engine.
This function returns the value of the specified statistic. The reset flag makes it possible to reset the statistic value after reading.
| param | statistic parameter |
| reset | flag specifying whether statistic value should be reset |
current value of the specified statistic parameter
DLL void h3dShowOverlay( float x_tl, float y_tl, float u_tl, float v_tl, float x_bl, float y_bl, float u_bl, float v_bl, float x_br, float y_br, float u_br, float v_br, float x_tr, float y_tr, float u_tr, float v_tr, float colR, float colG, float colB, float colA, H3DRes materialRes, int layer )
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 top-left corner of the screen and its maximum (1, 1) at the bottom-right corner. Texture coordinates are using a 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. Note that the overlays have to be removed manually using the function clearOverlays.
| x_tl, y_tl, u_tl, v_tl | position and texture coordinates of the top-left corner |
| x_bl, y_bl, u_bl, v_bl | position and texture coordinates of the bottom-left corner |
| x_br, y_br, u_br, v_br | position and texture coordinates of the bottom-right corner |
| x_tr, y_tr, u_tr, v_tr | position and texture coordinates of the top-right corner |
| colR, colG, colB, colA | color of the overlay that is set for the material’s shader |
| materialRes | material resource used for rendering |
| layer | layer index of the overlay (Values: from 0 to 7) |
nothing
DLL const char *h3dGetResName( H3DRes 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 H3DRes h3dGetNextResource( int type, H3DRes start )
Returns the next resource of the specified type.
This function searches the next resource of the specified type and returns its handle. The search begins after the specified start handle. If a further resource of the queried type does not exist, a zero handle is returned. The function can be used to iterate over all resources of a given type by using as start the return value of the previous iteration step. The first iteration step should start at 0 and iteration can be ended when the function returns 0.
| type | type of resource to be searched (ResourceTypes::Undefined for all types) |
| start | resource handle after which the search begins (can be 0 for beginning of resource list) |
handle to the found resource or 0 if it does not exist
DLL H3DRes h3dFindResource( int 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 H3DRes h3dAddResource( int 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.
Note: The name string may not contain a colon character (:)
| 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 H3DRes h3dCloneResource( H3DRes 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. If the name string is empty, a unique name for the resource is generated automatically.
Note: The name string may not contain a colon character (:)
| sourceRes | handle to resource to be cloned |
| name | name of new resource (can be empty for auto-naming) |
handle to the cloned resource or 0 in case of failure
DLL int h3dRemoveResource( H3DRes 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 h3dLoadResource( H3DRes 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 (e.g. the corresponding file was not found). In this case, the resource remains in the unloaded state but is no more returned when querying unloaded resources. When the specified resource is already loaded, the function returns false.
Important Note: XML-data must be NULL-terminated
| res | handle to the resource for which data will be loaded |
| data | pointer to the data to be loaded |
| size | size of the data block |
true in case of success, otherwise false
DLL bool h3dUnloadResource( H3DRes 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 h3dGetResElemCount( H3DRes res, int elem )
Gets the number of elements in a resource.
This function returns how many elements of the specified element type a specified resource has.
| res | handle to the resource to be accessed |
| elem | element type |
number of elements
DLL int h3dFindResElem( H3DRes res, int elem, int param, const char * value )
Finds a resource element with the specified property value.
This function searches in a specified resource for the first element of the specified type that has the property with the specified name set to the specified search value. If such element is found, its index is returned, otherwise the function returns -1. All string comparisons done for the search are case-sensitive.
| res | handle to the resource to be accessed |
| elem | element type |
| param | parameter name |
| value | parameter value to be searched for |
index of element or -1 if element not found
DLL int h3dGetResParamI( H3DRes res, int elem, int elemIdx, int param )
Gets an integer property of a resource element.
This function returns a specified property of the specified resource element. The property must be of the type int.
| res | handle to the resource to be accessed |
| elem | element type |
| elemIdx | index of element |
| param | parameter to be accessed |
value of the parameter
DLL bool h3dSetResParamI( H3DRes res, int elem, int elemIdx, int param, int value )
Sets an integer property of a resource element.
This function sets a specified property of the specified resource element to the specified value. The property must be of the type int.
| res | handle to the resource to be modified |
| elem | element type |
| elemIdx | index of element |
| param | parameter to be modified |
| value | new value for the specified parameter |
true in case of success otherwise false
DLL float h3dGetResParamF( H3DRes res, int elem, int elemIdx, int param, int compIdx )
Gets a float property of a resource element.
This function returns the specified component of the specified resource element property. The property must be of the type float. Float properties can have several indexed components, for example the x, y and z components of a vector.
| res | handle to the resource to be accessed |
| elem | element type |
| elemIdx | index of element |
| param | parameter to be accessed |
| compIdx | component of the parameter to be accessed |
value of the parameter
DLL bool h3dSetResParamF( H3DRes res, int elem, int elemIdx, int param, int compIdx, float value )
Sets a float property of a resource element.
This function sets the specified component of the specified resource element property to the specified value. The property must be of the type float.
| res | handle to the resource to be modified |
| elem | element type |
| elemIdx | index of element |
| param | parameter to be modified |
| compIdx | component of the parameter to be modified |
| value | new value for the specified parameter |
true in case of success otherwise false
DLL const char *h3dGetResParamStr( H3DRes res, int elem, int elemIdx, int param )
Gets a string property of a resource element.
This function returns a specified property of the specified resource element. The property must be of the type string (const char *).
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 |
| elem | element type |
| elemIdx | index of element |
| param | parameter to be accessed |
value of the property or empty string if no such property exists
DLL bool h3dSetResParamStr( H3DRes res, int elem, int elemIdx, int param, const char * value )
Sets a string property of a resource element.
This function sets a specified property of the specified resource element to the specified value. The property must be of the type string (const char *).
| res | handle to the resource to be modified |
| elem | element type |
| elemIdx | index of element |
| param | parameter to be modified |
| value | new value for the specified parameter |
true in case of success otherwise false
DLL void *h3dMapResStream( H3DRes res, int elem, int elemIdx, int stream, bool read, bool write )
Maps the stream of a resource element.
This function maps the specified stream of a specified resource element and returns a pointer to the stream data. The required access to the data can be specified with the read write parameters. If read is false, the pointer will usually not contain meaningful data. Not all resource streams can be mapped with both read and write access. If it is not possible to map the stream, the function will return a NULL pointer. A mapped stream should be unmapped again as soon as possible but always before subsequent API calls are made. It is only possible to map one stream per resource at a time.
| res | handle to the resource to be mapped |
| elem | element type |
| elemIdx | index of element |
| stream | stream to be mapped |
| read | flag indicating whether read access is required |
| write | flag indicating whether write access is required |
pointer to stream data or NULL if stream cannot be mapped
DLL H3DRes h3dQueryUnloadedResource( int index )
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 or the zero based index specified is greater than the number of the currently unloaded resources, 0 is returned.
| index | index of unloaded resource within the internal list of unloaded resources (starting with 0) |
handle to an unloaded resource or 0
DLL void h3dReleaseUnusedResources()
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 removeResource or are no more referenced by any other engine objects.
none
nothing
DLL H3DRes h3dCreateTexture( const char * name, int width, int height, int fmt, int flags )
Creates a Texture resource.
This function tries to create and add a Texture resource with the specified name to the resource manager. If a Texture resource with the same name is already existing, the function fails. The texture is initialized with the specified dimensions and the resource is declared as loaded. This function is especially useful to create dynamic textures (e.g. for displaying videos) or output buffers for render-to-texture.
Note: The name string may not contain a colon character (:)
| name | name of the resource |
| width | width of the texture image |
| height | height of the texture image |
| fmt | texture format (see stream formats) |
| flags | flags used for creating the resource |
handle to the created resource or 0 in case of failure
DLL void h3dSetShaderPreambles( 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 h3dSetMaterialUniform( H3DRes 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 h3dGetPipelineRenderTargetData( H3DRes 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 H3DNode h3dGetNodeParent( H3DNode 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 h3dSetNodeParent( H3DNode node, H3DNode 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 H3DNode h3dGetNodeChild( H3DNode 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 H3DNode h3dAddNodes( H3DNode parent, H3DRes 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. If an invalid scenegraph resource is specified or the scenegraph resource is unloaded, the function returns 0.
| parent | handle to parent node to which the root of the new nodes will be attached |
| sceneGraphRes | handle to loaded SceneGraph resource |
handle to the root of the created nodes or 0 in case of failure
DLL bool h3dSetNodeActivation( H3DNode node, bool active )
Sets the activation (visibility) state of a node.
This function sets the activation state of the specified node to active or inactive. Inactive nodes with all their children 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 h3dCheckNodeTransFlag( H3DNode 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 h3dGetNodeTransform( H3DNode 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 h3dSetNodeTransform( H3DNode 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 h3dGetNodeTransMats( H3DNode 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 h3dSetNodeTransMat( H3DNode 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 int h3dGetNodeParamI( H3DNode 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 H3DRes.
| node | handle to the node to be accessed |
| param | parameter to be accessed |
value of the parameter
DLL bool h3dSetNodeParamI( H3DNode node, int param, int 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 int or H3DRes.
| 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 float h3dGetNodeParamF( H3DNode node, int param, int compIdx )
Gets a property of a scene node.
This function returns a specified property of the specified node. Float properties can have several indexed components, for example the x, y and z components of a vector. The property must be of the type float.
| node | handle to the node to be accessed |
| param | parameter to be accessed |
| compIdx | component of the parameter to be accessed |
value of the parameter
DLL bool h3dSetNodeParamF( H3DNode node, int param, int compIdx, 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 |
| compIdx | component of the parameter to be modified |
| value | new value for the specified parameter |
true in case of success otherwise false
DLL const char *h3dGetNodeParamStr( H3DNode 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 string (const char *).
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 |
| param | parameter to be accessed |
value of the property or empty string if no such property exists
DLL bool h3dSetNodeParamStr( H3DNode node, int param, const char * 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 string (const char *).
| 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 h3dGetNodeAABB( H3DNode 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 h3dFindNodes( H3DNode 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 H3DNode h3dGetNodeFindResult( 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 int h3dCastRay( H3DNode node, float ox, float oy, float oz, float dx, float dy, float dz, int numNearest )
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 intersections relative to the ray origin and returns the number of intersecting scene nodes. 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. For Meshes, the base LOD (LOD0) is always used for performing the ray-triangle intersection tests.
| node | node at which intersection check is beginning |
| ox, oy, oz | ray origin |
| dx, dy, dz | ray direction vector also specifying ray length |
| numNearest | maximum number of intersection points to be stored (0 for all) |
number of intersections
DLL bool h3dGetCastRayResult( int index, H3DNode * node, float * distance, float * intersection )
Returns a result of a previous castRay query.
This functions is used to access the results of a previous castRay query. The index is used to access a specific result. The intersection data is copied to the specified variables.
| index | index of result to be accessed (range: 0 to number of results returned by castRay) |
| node | handle of intersected node |
| distance | distance from ray origin to intersection point |
| intersection | coordinates of intersection point (float[3] array) |
true if index was valid and data could be copied, otherwise false
DLL int h3dCheckNodeVisibility( H3DNode node, H3DNode cameraNode, bool checkOcclusion, bool calcLod )
Checks if a node is visible.
This function checks if a specified node is visible from the perspective of a specified camera. The function always checks if the node is in the camera’s frustum. If checkOcclusion is true, the function will take into account the occlusion culling information from the previous frame (if occlusion culling is disabled the flag is ignored). The flag calcLod determines whether the detail level for the node should be returned in case it is visible. The function returns -1 if the node is not visible, otherwise 0 (base LOD level) or the computed LOD level.
| node | node to be checked for visibility |
| cameraNode | camera node from which the visibility test is done |
| checkOcclusion | specifies if occlusion info from previous frame should be taken into account |
| calcLod | specifies if LOD level should be computed |
computed LOD level or -1 if node is not visible
DLL H3DNode h3dAddGroupNode( H3DNode 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 H3DNode h3dAddModelNode( H3DNode parent, const char * name, H3DRes 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 h3dSetupModelAnimStage( H3DNode modelNode, int stage, H3DRes 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. If a NULL-handle is used for animationRes, the stage is cleared and the previous animation is removed.
A simple 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.
| modelNode | handle to the Model node to be modified |
| stage | index of the animation stage to be configured |
| animationRes | handle to Animation resource (can be 0) |
| 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 h3dSetModelAnimParams( H3DNode modelNode, 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.
| modelNode | handle to the Model 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 h3dSetModelMorpher( H3DNode modelNode, 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.
| modelNode | handle to the Model node to be modified |
| target | name of morph target |
| weight | new weight for morph target |
true in case of success, otherwise false
DLL H3DNode h3dAddMeshNode( H3DNode parent, const char * name, H3DRes 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 H3DNode h3dAddJointNode( H3DNode 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 H3DNode h3dAddLightNode( H3DNode parent, const char * name, H3DRes 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 H3DNode h3dAddCameraNode( H3DNode parent, const char * name, H3DRes 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 h3dSetupCameraView( H3DNode cameraNode, 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.
| cameraNode | 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 h3dGetCameraProjMat( H3DNode cameraNode, float * projMat )
Gets the camera projection matrix.
This function gets the camera projection matrix used for bringing the geometry to screen space and copies it to the specified array.
| cameraNode | handle to Camera node |
| projMat | pointer to float array with 16 elements |
true in case of success otherwise false
DLL H3DNode h3dAddEmitterNode( H3DNode parent, const char * name, H3DRes materialRes, H3DRes particleEffectRes, 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 |
| particleEffectRes | handle to ParticleEffect 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 h3dAdvanceEmitterTime( H3DNode emitterNode, 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.
| emitterNode | handle to the Emitter node which will be modified |
| timeDelta | time delta in seconds |
true in case of success otherwise false
DLL bool h3dHasEmitterFinished( H3DNode emitterNode )
Checks if an Emitter node is still alive.
This function checks if a particle system is still active and has living particles or will spawn new particles. The specified node must be an Emitter node. The function can be used to check when a not infinitely running emitter for an effect like an explosion can be removed from the scene.
| emitterNode | handle to the Emitter node which is checked |
true if Emitter will no more emit any particles, otherwise or in case of failure false
Returns the engine version string.
DLL const char *h3dGetVersionString()
Checks if an extension is part of the engine library.
DLL bool h3dCheckExtension( const char * extensionName )
Initializes the engine.
DLL bool h3dInit()
Releases the engine.
DLL void h3dRelease()
Sets the location and size of the viewport.
DLL void h3dSetupViewport( int x, int y, int width, int height, bool resizeBuffers )
Main rendering function.
DLL bool h3dRender( H3DNode cameraNode )
Marker for end of frame.
DLL bool h3dFinalizeFrame()
Removes all resources and scene nodes.
DLL void h3dClear()
Gets the next message from the message queue.
DLL const char *h3dGetMessage( int * level, float * time )
Gets an option parameter of the engine.
DLL float h3dGetOption( H3DOptions:: List param )
Sets an option parameter for the engine.
DLL bool h3dSetOption( H3DOptions:: List param, float value )
Gets a statistic value of the engine.
DLL float h3dGetStat( H3DStats:: List param, bool reset )
Shows an overlay on the screen.
DLL void h3dShowOverlay( float x_tl, float y_tl, float u_tl, float v_tl, float x_bl, float y_bl, float u_bl, float v_bl, float x_br, float y_br, float u_br, float v_br, float x_tr, float y_tr, float u_tr, float v_tr, float colR, float colG, float colB, float colA, H3DRes materialRes, int layer )
Removes all overlays.
DLL void h3dClearOverlays()
Returns the type of a resource.
DLL int h3dGetResType( H3DRes res )
Returns the name of a resource.
DLL const char *h3dGetResName( H3DRes res )
Returns the next resource of the specified type.
DLL H3DRes h3dGetNextResource( int type, H3DRes start )
Finds a resource and returns its handle.
DLL H3DRes h3dFindResource( int type, const char * name )
Adds a resource.
DLL H3DRes h3dAddResource( int type, const char * name, int flags )
Duplicates a resource.
DLL H3DRes h3dCloneResource( H3DRes sourceRes, const char * name )
Removes a resource.
DLL int h3dRemoveResource( H3DRes res )
Checks if a resource is loaded.
DLL bool h3dIsResLoaded( H3DRes res )
Loads a resource.
DLL bool h3dLoadResource( H3DRes res, const char * data, int size )
Unloads a resource.
DLL bool h3dUnloadResource( H3DRes res )
Gets the number of elements in a resource.
DLL int h3dGetResElemCount( H3DRes res, int elem )
Finds a resource element with the specified property value.
DLL int h3dFindResElem( H3DRes res, int elem, int param, const char * value )
Gets an integer property of a resource element.
DLL int h3dGetResParamI( H3DRes res, int elem, int elemIdx, int param )
Sets an integer property of a resource element.
DLL bool h3dSetResParamI( H3DRes res, int elem, int elemIdx, int param, int value )
Gets a float property of a resource element.
DLL float h3dGetResParamF( H3DRes res, int elem, int elemIdx, int param, int compIdx )
Sets a float property of a resource element.
DLL bool h3dSetResParamF( H3DRes res, int elem, int elemIdx, int param, int compIdx, float value )
Gets a string property of a resource element.
DLL const char *h3dGetResParamStr( H3DRes res, int elem, int elemIdx, int param )
Sets a string property of a resource element.
DLL bool h3dSetResParamStr( H3DRes res, int elem, int elemIdx, int param, const char * value )
Maps the stream of a resource element.
DLL void *h3dMapResStream( H3DRes res, int elem, int elemIdx, int stream, bool read, bool write )
Unmaps a previously mapped resource stream.
DLL bool h3dUnmapResStream( H3DRes res )
Returns handle to an unloaded resource.
DLL H3DRes h3dQueryUnloadedResource( int index )
Frees resources that are no longer used.
DLL void h3dReleaseUnusedResources()
Creates a Texture resource.
DLL H3DRes h3dCreateTexture( const char * name, int width, int height, int fmt, int flags )
Sets preambles of all Shader resources.
DLL void h3dSetShaderPreambles( const char * vertPreamble, const char * fragPreamble )
Sets a shader uniform of a Material resource.
DLL bool h3dSetMaterialUniform( H3DRes materialRes, const char * name, float a, float b, float c, float d )
Reads the pixel data of a pipeline render target buffer.
DLL bool h3dGetPipelineRenderTargetData( H3DRes 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 h3dGetNodeType( H3DNode node )
Returns the parent of a scene node.
DLL H3DNode h3dGetNodeParent( H3DNode node )
Relocates a node in the scene graph.
DLL bool h3dSetNodeParent( H3DNode node, H3DNode parent )
Returns the handle to a child node.
DLL H3DNode h3dGetNodeChild( H3DNode node, int index )
Adds nodes from a SceneGraph resource to the scene.
DLL H3DNode h3dAddNodes( H3DNode parent, H3DRes sceneGraphRes )
Removes a node from the scene.
DLL bool h3dRemoveNode( H3DNode node )
Sets the activation (visibility) state of a node.
DLL bool h3dSetNodeActivation( H3DNode node, bool active )
Checks if a scene node has been transformed by the engine.
DLL bool h3dCheckNodeTransFlag( H3DNode node, bool reset )
Gets the relative transformation of a node.
DLL bool h3dGetNodeTransform( H3DNode 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 h3dSetNodeTransform( H3DNode 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 h3dGetNodeTransMats( H3DNode node, const float ** relMat, const float ** absMat )
Sets the relative transformation matrix of a node.
DLL bool h3dSetNodeTransMat( H3DNode node, const float * mat4x4 )
Gets a property of a scene node.
DLL int h3dGetNodeParamI( H3DNode node, int param )
Sets a property of a scene node.
DLL bool h3dSetNodeParamI( H3DNode node, int param, int value )
Gets a property of a scene node.
DLL float h3dGetNodeParamF( H3DNode node, int param, int compIdx )
Sets a property of a scene node.
DLL bool h3dSetNodeParamF( H3DNode node, int param, int compIdx, float value )
Gets a property of a scene node.
DLL const char *h3dGetNodeParamStr( H3DNode node, int param )
Sets a property of a scene node.
DLL bool h3dSetNodeParamStr( H3DNode node, int param, const char * value )
Gets the bounding box of a scene node.
DLL bool h3dGetNodeAABB( H3DNode node, float * minX, float * minY, float * minZ, float * maxX, float * maxY, float * maxZ )
Finds scene nodes with the specified properties.
DLL int h3dFindNodes( H3DNode startNode, const char * name, int type )
Gets a result from the findNodes query.
DLL H3DNode h3dGetNodeFindResult( int index )
Performs a recursive ray collision query.
DLL int h3dCastRay( H3DNode node, float ox, float oy, float oz, float dx, float dy, float dz, int numNearest )
Returns a result of a previous castRay query.
DLL bool h3dGetCastRayResult( int index, H3DNode * node, float * distance, float * intersection )
Checks if a node is visible.
DLL int h3dCheckNodeVisibility( H3DNode node, H3DNode cameraNode, bool checkOcclusion, bool calcLod )
Adds a Group node to the scene.
DLL H3DNode h3dAddGroupNode( H3DNode parent, const char * name )
Adds a Model node to the scene.
DLL H3DNode h3dAddModelNode( H3DNode parent, const char * name, H3DRes geometryRes )
Configures an animation stage of a Model node.
DLL bool h3dSetupModelAnimStage( H3DNode modelNode, int stage, H3DRes animationRes, const char * startNode, bool additive )
Sets the parameters of an animation stage in a Model node.
DLL bool h3dSetModelAnimParams( H3DNode modelNode, int stage, float time, float weight )
Sets the weight of a morph target.
DLL bool h3dSetModelMorpher( H3DNode modelNode, const char * target, float weight )
Adds a Mesh node to the scene.
DLL H3DNode h3dAddMeshNode( H3DNode parent, const char * name, H3DRes materialRes, int batchStart, int batchCount, int vertRStart, int vertREnd )
Adds a Joint node to the scene.
DLL H3DNode h3dAddJointNode( H3DNode parent, const char * name, int jointIndex )
Adds a Light node to the scene.
DLL H3DNode h3dAddLightNode( H3DNode parent, const char * name, H3DRes materialRes, const char * lightingContext, const char * shadowContext )
Adds a Camera node to the scene.
DLL H3DNode h3dAddCameraNode( H3DNode parent, const char * name, H3DRes pipelineRes )
Sets the planes of a camera viewing frustum.
DLL bool h3dSetupCameraView( H3DNode cameraNode, float fov, float aspect, float nearDist, float farDist )
Gets the camera projection matrix.
DLL bool h3dGetCameraProjMat( H3DNode cameraNode, float * projMat )
Adds a Emitter node to the scene.
DLL H3DNode h3dAddEmitterNode( H3DNode parent, const char * name, H3DRes materialRes, H3DRes particleEffectRes, int maxParticleCount, int respawnCount )
Advances the time value of an Emitter node.
DLL bool h3dAdvanceEmitterTime( H3DNode emitterNode, float timeDelta )
Checks if an Emitter node is still alive.
DLL bool h3dHasEmitterFinished( H3DNode emitterNode )