Horde3D API

Summary
Horde3D API
ConventionsSome conventions for the API.
Typedefs and constants
Typedefs
Predefined constants
Enumerations
H3DOptionsThe available engine option parameters.
H3DStatsThe available engine statistic parameters.
H3DResTypesThe available resource types.
H3DResFlagsThe available flags used when adding a resource.
H3DFormatsThe available resource stream formats.
H3DGeoResThe available Geometry resource accessors.
H3DAnimResThe available Animation resource accessors.
H3DMatResThe available Material resource accessors.
H3DShaderResThe available Shader resource accessors.
H3DTexResThe available Texture resource accessors.
H3DPartEffResThe available ParticleEffect resource accessors.
H3DPipeResThe available Pipeline resource accessors.
H3DNodeTypesThe available scene node types.
H3DNodeFlagsThe available scene node flags.
H3DNodeParamsThe available scene node parameters.
H3DModelThe available Model node parameters
H3DMeshThe available Mesh node parameters.
H3DJointThe available Joint node parameters.
H3DLightThe available Light node parameters.
H3DCameraThe available Camera node parameters.
H3DEmitterThe available Emitter node parameters.
Basic functions
h3dGetVersionStringReturns the engine version string.
h3dCheckExtensionChecks if an extension is part of the engine library.
h3dGetErrorChecks if an error occured.
h3dInitInitializes the engine.
h3dReleaseReleases the engine.
h3dRenderMain rendering function.
h3dFinalizeFrameMarker for end of frame.
h3dClearRemoves all resources and scene nodes.
h3dGetMessageGets the next message from the message queue.
h3dGetOptionGets an option parameter of the engine.
h3dSetOptionSets an option parameter for the engine.
h3dGetStatGets a statistic value of the engine.
h3dShowOverlaysDisplays overlays on the screen.
h3dClearOverlaysRemoves all overlays.
General resource management functions
h3dGetResTypeReturns the type of a resource.
h3dGetResNameReturns the name of a resource.
h3dGetNextResourceReturns the next resource of the specified type.
h3dFindResourceFinds a resource and returns its handle.
h3dAddResourceAdds a resource.
h3dCloneResourceDuplicates a resource.
h3dRemoveResourceRemoves a resource.
h3dIsResLoadedChecks if a resource is loaded.
h3dLoadResourceLoads a resource.
h3dUnloadResourceUnloads a resource.
h3dGetResElemCountGets the number of elements in a resource.
h3dFindResElemFinds a resource element with the specified property value.
h3dGetResParamIGets an integer property of a resource element.
h3dSetResParamISets an integer property of a resource element.
h3dGetResParamFGets a float property of a resource element.
h3dSetResParamFSets a float property of a resource element.
h3dGetResParamStrGets a string property of a resource element.
h3dSetResParamStrSets a string property of a resource element.
h3dMapResStreamMaps the stream of a resource element.
h3dUnmapResStreamUnmaps a previously mapped resource stream.
h3dQueryUnloadedResourceReturns handle to an unloaded resource.
h3dReleaseUnusedResourcesFrees resources that are no longer used.
Specific resource management functions
h3dCreateTextureCreates a Texture resource.
h3dSetShaderPreamblesSets preambles of all Shader resources.
h3dSetMaterialUniformSets a shader uniform of a Material resource.
h3dResizePipelineBuffersChanges the size of the render targets of a pipeline.
h3dGetRenderTargetDataReads back the pixel data of a render target buffer.
General scene graph functions
h3dGetNodeTypeReturns the type of a scene node.
h3dGetNodeParentReturns the parent of a scene node.
h3dSetNodeParentRelocates a node in the scene graph.
h3dGetNodeChildReturns the handle to a child node.
h3dAddNodesAdds nodes from a SceneGraph resource to the scene.
h3dRemoveNodeRemoves a node from the scene.
h3dCheckNodeTransFlagChecks if a scene node has been transformed by the engine.
h3dGetNodeTransformGets the relative transformation of a node.
h3dSetNodeTransformSets the relative transformation of a node.
h3dGetNodeTransMatsReturns the transformation matrices of a node.
h3dSetNodeTransMatSets the relative transformation matrix of a node.
h3dGetNodeParamIGets a property of a scene node.
h3dSetNodeParamISets a property of a scene node.
h3dGetNodeParamFGets a property of a scene node.
h3dSetNodeParamFSets a property of a scene node.
h3dGetNodeParamStrGets a property of a scene node.
h3dSetNodeParamStrSets a property of a scene node.
h3dGetNodeFlagsGets the scene node flags.
h3dSetNodeFlagsSets the scene node flags.
h3dGetNodeAABBGets the bounding box of a scene node.
h3dFindNodesFinds scene nodes with the specified properties.
h3dGetNodeFindResultGets a result from the findNodes query.
h3dCastRayPerforms a recursive ray collision query.
h3dGetCastRayResultReturns a result of a previous castRay query.
h3dCheckNodeVisibilityChecks if a node is visible.
Group-specific scene graph functions
h3dAddGroupNodeAdds a Group node to the scene.
Model-specific scene graph functions
h3dAddModelNodeAdds a Model node to the scene.
h3dSetupModelAnimStageConfigures an animation stage of a Model node.
h3dSetModelAnimParamsSets the animation stage parameters of a Model node.
h3dSetModelMorpherSets the weight of a morph target.
Mesh-specific scene graph functions
h3dAddMeshNodeAdds a Mesh node to the scene.
Joint-specific scene graph functions
h3dAddJointNodeAdds a Joint node to the scene.
Light-specific scene graph functions
h3dAddLightNodeAdds a Light node to the scene.
Camera-specific scene graph functions
h3dAddCameraNodeAdds a Camera node to the scene.
h3dSetupCameraViewSets the planes of a camera viewing frustum.
h3dGetCameraProjMatGets the camera projection matrix.
Emitter-specific scene graph functions
h3dAddEmitterNodeAdds a Emitter node to the scene.
h3dAdvanceEmitterTimeAdvances the time value of an Emitter node.
h3dHasEmitterFinishedChecks if an Emitter node is still alive.

Conventions

Some conventions for the API.

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

Typedefs and constants

Typedefs

H3DReshandle to resource (type: int32)
H3DNodehandle to scene node (type: int32)

Predefined constants

H3DRootNodeScene root node handle

Enumerations

H3DOptions

The available engine option parameters.

MaxLogLevelDefines the maximum log level; only messages which are smaller or equal to this value (hence more important) are published in the message queue.  (Default: 4)
MaxNumMessagesDefines the maximum number of messages that can be stored in the message queue (Default: 512)
TrilinearFilteringEnables or disables trilinear filtering for textures.  (Values: 0, 1; Default: 1)
MaxAnisotropySets the maximum quality for anisotropic filtering.  (Values: 1, 2, 4, 8; Default: 1)
TexCompressionEnables or disables texture compression; only affects textures that are loaded after setting the option.  (Values: 0, 1; Default: 0)
SRGBLinearizationEanbles or disables gamma-to-linear-space conversion of input textures that are tagged as sRGB (Values: 0, 1; Default: 0)
LoadTexturesEnables or disables loading of textures referenced by materials; this can be useful to reduce loading times for testing.  (Values: 0, 1; Default: 1)
FastAnimationDisables or enables inter-frame interpolation for animations.  (Values: 0, 1; Default: 1)
ShadowMapSizeSets the size of the shadow map buffer (Values: 128, 256, 512, 1024, 2048; Default: 1024)
SampleCountMaximum number of samples used for multisampled render targets; only affects pipelines that are loaded after setting the option.  (Values: 0, 2, 4, 8, 16; Default: 0)
WireframeModeEnables or disables wireframe rendering
DebugViewModeEnables or disables debug view where geometry is rendered in wireframe without shaders and lights are visualized using their screen space bounding box.  (Values: 0, 1; Default: 0)
DumpFailedShadersEnables or disables storing of shader code that failed to compile in a text file; this can be useful in combination with the line numbers given back by the shader compiler.  (Values: 0, 1; Default: 0)
GatherTimeStatsEnables or disables gathering of time stats that are useful for profiling (Values: 0, 1; Default: 1)

H3DStats

The available engine statistic parameters.

TriCountNumber of triangles that were pushed to the renderer
BatchCountNumber of batches (draw calls)
LightPassCountNumber of lighting passes
FrameTimeTime in ms between two h3dFinalizeFrame calls
AnimationTimeCPU time in ms spent for animation
GeoUpdateTimeCPU time in ms spent for software skinning and morphing
ParticleSimTimeCPU time in ms spent for particle simulation and updates
FwdLightsGPUTimeGPU time in ms spent for forward lighting passes
DefLightsGPUTimeGPU time in ms spent for drawing deferred light volumes
ShadowsGPUTimeGPU time in ms spent for generating shadow maps
ParticleGPUTimeGPU time in ms spent for drawing particles
TextureVMemEstimated amount of video memory used by textures (in Mb)
GeometryVMemEstimated amount of video memory used by geometry (in Mb)

H3DResTypes

The available resource types.

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

H3DResFlags

The available flags used when adding a resource.

NoQueryExcludes resource from being listed by queryUnloadedResource function.
NoTexCompressionDisables texture compression for Texture resource.
NoTexMipmapsDisables generation of mipmaps for Texture resource.
TexCubemapSets Texture resource to be a cubemap.
TexDynamicEnables more efficient updates of Texture resource streams.
TexRenderableMakes Texture resource usable as render target.
TexSRGBIndicates that Texture resource is in sRGB color space and should be converted to linear space when being sampled.

H3DFormats

The available resource stream formats.

UnknownUnknown format
TEX_BGRA88-bit BGRA texture
TEX_DXT1DXT1 compressed texture
TEX_DXT3DXT3 compressed texture
TEX_DXT5DXT5 compressed texture
TEX_RGBA16FHalf float RGBA texture
TEX_RGBA32FFloat RGBA texture

H3DGeoRes

The available Geometry resource accessors.

GeometryElemBase element
GeoIndexCountINumber of indices [read-only]
GeoVertexCountINumber of vertices [read-only]
GeoIndices16IFlag indicating whether index data is 16 or 32 bit [read-only]
GeoIndexStreamTriangle index data (uint16 or uint32, depending on flag)
GeoVertPosStreamVertex position data (float x, y, z)
GeoVertTanStreamVertex tangent frame data (float nx, ny, nz, tx, ty, tz, tw)
GeoVertStaticStreamVertex static attribute data (float u0, v0, float4 jointIndices, float4 jointWeights, float u1, v1)

H3DAnimRes

The available Animation resource accessors.

EntityElemStored animation entities (joints and meshes)
EntFrameCountINumber of frames stored for a specific entity [read-only]

H3DMatRes

The available Material resource accessors.

MaterialElemBase element
SamplerElemSampler element
UniformElemUniform element
MatClassStrMaterial class
MatLinkIMaterial resource that is linked to this material
MatShaderIShader resource
SampNameStrName of sampler [read-only]
SampTexResITexture resource bound to sampler
UnifNameStrName of uniform [read-only]
UnifValueF4Value of uniform (a, b, c, d)

H3DShaderRes

The available Shader resource accessors.

ContextElemContext element
SamplerElemSampler element
UniformElemUniform element
ContNameStrName of context [read-only]
SampNameStrName of sampler [read-only]
UnifNameStrName of uniform [read-only]
UnifSizeISize (number of components) of uniform [read-only]
UnifDefValueF4Default value of uniform (a, b, c, d)

H3DTexRes

The available Texture resource accessors.

TextureElemBase element
ImageElemSubresources of the texture.  A texture consists, depending on the type, of a number of equally sized slices which again can have a fixed number of mipmaps.  Each image element represents the base image of a slice or a single mipmap level of the corresponding slice.
TexFormatITexture format [read-only]
TexSliceCountINumber of slices (1 for 2D texture and 6 for cubemap) [read-only]
ImgWidthIImage width [read-only]
ImgHeightIImage height [read-only]
ImgPixelStreamPixel data of an image.  The data layout matches the layout specified by the texture format with the exception that half-float is converted to float.  The first element in the data array corresponds to the lower left corner.

H3DPartEffRes

The available ParticleEffect resource accessors.

ParticleElemGeneral particle configuration
ChanMoveVelElemVelocity channel
ChanRotVelElemAngular velocity channel
ChanSizeElemSize channel
ChanColRElemRed color component channel
ChanColGElemGreen color component channel
ChanColBElemBlue color component channel
ChanColAElemAlpha channel
PartLifeMinFMinimum value of random life time (in seconds)
PartLifeMaxFMaximum value of random life time (in seconds)
ChanStartMinFMinimum for selecting initial random value of channel
ChanStartMaxFMaximum for selecting initial random value of channel
ChanEndRateFRemaining percentage of initial value when particle is dying

H3DPipeRes

The available Pipeline resource accessors.

StageElemPipeline stage
StageNameStrName of stage [read-only]
StageActivationIFlag indicating whether stage is active

H3DNodeTypes

The available scene node types.

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

H3DNodeFlags

The available scene node flags.

NoDrawExcludes scene node from all rendering
NoCastShadowExcludes scene node from list of shadow casters
NoRayQueryExcludes scene node from ray intersection queries
InactiveDeactivates scene node so that it is completely ignored (combination of all flags above)

H3DNodeParams

The available scene node parameters.

NameStrName of the scene node
AttachmentStrOptional application-specific meta data for a node encapsulated in an ‘Attachment’ XML string

H3DModel

The available Model node parameters

GeoResIGeometry resource used for the model
SWSkinningIEnables or disables software skinning (default: 0)
LodDist1FDistance to camera from which on LOD1 is used (default: infinite) (must be a positive value larger than 0.0)
LodDist2FDistance to camera from which on LOD2 is used (may not be smaller than LodDist1) (default: infinite)
LodDist3FDistance to camera from which on LOD3 is used (may not be smaller than LodDist2) (default: infinite)
LodDist4FDistance to camera from which on LOD4 is used (may not be smaller than LodDist3) (default: infinite)

H3DMesh

The available Mesh node parameters.

MatResIMaterial resource used for the mesh
BatchStartIFirst triangle index of mesh in Geometry resource of parent Model node [read-only]
BatchCountINumber of triangle indices used for drawing mesh [read-only]
VertRStartIFirst vertex in Geometry resource of parent Model node [read-only]
VertREndILast vertex in Geometry resource of parent Model node [read-only]
LodLevelILOD level of Mesh; the mesh is only rendered if its LOD level corresponds to the model’s current LOD level which is calculated based on the LOD distances (default: 0)

H3DJoint

The available Joint node parameters.

JointIndexIIndex of joint in Geometry resource of parent Model node [read-only]

H3DLight

The available Light node parameters.

MatResIMaterial resource used for the light
RadiusFRadius of influence (default: 100.0)
FovFField of view (FOV) angle (default: 90.0)
ColorF3Diffuse color RGB (default: 1.0, 1.0, 1.0)
ColorMultiplierFDiffuse color multiplier for altering intensity, mainly useful for HDR (default: 1.0)
ShadowMapCountINumber of shadow maps used for light source (values: 0, 1, 2, 3, 4; default: 0)]
ShadowSplitLambdaFConstant determining segmentation of view frustum for Parallel Split Shadow Maps (default: 0.5)
ShadowMapBiasFBias value for shadow mapping to reduce shadow acne (default: 0.005)
LightingContextStrName of shader context used for computing lighting
ShadowContextStrName of shader context used for generating shadow map

H3DCamera

The available Camera node parameters.

PipeResIPipeline resource used for rendering
OutTexResI2D Texture resource used as output buffer (can be 0 to use main framebuffer) (default: 0)
OutBufIndexIIndex of the output buffer for stereo rendering (values: 0 for left eye, 1 for right eye) (default: 0)
LeftPlaneFCoordinate of left plane relative to near plane center (default: -0.055228457)
RightPlaneFCoordinate of right plane relative to near plane center (default: 0.055228457)
BottomPlaneFCoordinate of bottom plane relative to near plane center (default: -0.041421354f)
TopPlaneFCoordinate of top plane relative to near plane center (default: 0.041421354f)
NearPlaneFDistance of near clipping plane (default: 0.1)
FarPlaneFDistance of far clipping plane (default: 1000)
ViewportXIPosition x-coordinate of the lower left corner of the viewport rectangle (default: 0)
ViewportYIPosition y-coordinate of the lower left corner of the viewport rectangle (default: 0)
ViewportWidthIWidth of the viewport rectangle (default: 320)
ViewportHeightIHeight of the viewport rectangle (default: 240)
OrthoIFlag for setting up an orthographic frustum instead of a perspective one (default: 0)
OccCullingIFlag for enabling occlusion culling (default: 0)

H3DEmitter

The available Emitter node parameters.

MatResIMaterial resource used for rendering
PartEffResIParticleEffect resource which configures particle properties
MaxCountIMaximal number of particles living at the same time
RespawnCountINumber of times a single particle is recreated after dying (-1 for infinite)
DelayFTime in seconds before emitter begins creating particles (default: 0.0)
EmissionRateFMaximal number of particles to be created per second (default: 0.0)
SpreadAngleFAngle of cone for random emission direction (default: 0.0)
ForceF3Force vector XYZ applied to particles (default: 0.0, 0.0, 0.0)

Basic functions

h3dGetVersionString

DLL const char *h3dGetVersionString()

Returns the engine version string.

Details

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

Parameters

none

Returns

pointer to the version string

h3dCheckExtension

DLL bool h3dCheckExtension(const char *extensionName)

Checks if an extension is part of the engine library.

Details

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

Parameters

extensionNamename of the extension

Returns

true if extension is implemented, otherwise false

h3dGetError

DLL bool h3dGetError()

Checks if an error occured.

Details

This function checks if an error occured in a previous API function call.  If an error flag is set, the function resets the flag and returns true.  The function will solely report errors that originate from a violated precondition, like an invalid parameter that is passed to an API function.  Errors that happen during the execution of a function, for example failure of initializing the engine due to a missing hardware feature, can be catched by checking the return value of the corresponding API function.  More information about the error can be retrieved by checking the message queue, provided that the message level is set accordingly.

Parameters

none

Returns

true in there was an error, otherwise false

h3dInit

DLL bool h3dInit()

Initializes the engine.

Details

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.

Parameters

none

Returns

true in case of success, otherwise false

h3dRelease

DLL void h3dRelease()

Releases the engine.

Details

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

Parameters

none

Returns

nothing

h3dRender

DLL void h3dRender(H3DNode cameraNode)

Main rendering function.

Details

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.

Parameters

cameraNodecamera node used for rendering scene

Returns

nothing

h3dFinalizeFrame

DLL void h3dFinalizeFrame()

Marker for end of frame.

Details

This function tells the engine that the current frame is finished and that all subsequent rendering operations will be for the next frame.

Parameters

none

Returns

nothing

h3dClear

DLL void h3dClear()

Removes all resources and scene nodes.

Details

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

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

Parameters

none

Returns

nothing

h3dGetMessage

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

Gets the next message from the message queue.

Details

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

Parameters

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

Returns

message string or empty string if no message is in queue

h3dGetOption

DLL float h3dGetOption(H3DOptions::List param)

Gets an option parameter of the engine.

Details

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

Parameters

paramoption parameter

Returns

current value of the specified option parameter

h3dSetOption

DLL bool h3dSetOption(H3DOptions::List param,
float value)

Sets an option parameter for the engine.

Details

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

Parameters

paramoption parameter
valuevalue of the option parameter

Returns

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

h3dGetStat

DLL float h3dGetStat(H3DStats::List param,
bool reset)

Gets a statistic value of the engine.

Details

This function returns the value of the specified statistic.  The reset flag makes it possible to reset the statistic value after reading.

Parameters

paramstatistic parameter
resetflag specifying whether statistic value should be reset

Returns

current value of the specified statistic parameter

h3dShowOverlays

DLL void h3dShowOverlays(const float *verts,
int vertCount,
float colR,
float colG,
float colB,
float colA,
H3DRes materialRes,
int flags)

Displays overlays on the screen.

Details

This function displays one or more overlays with a specified material and color.  An overlay is a screen-space quad that can be used to render 2D GUI elements.  The overlay coordinate system has its origin (0, 0) at the top-left corner of the screen and its maximum (aspect, 1) at the bottom-right corner.  As the x coordinate of the maximum corresponds to the aspect ratio of the viewport, the size of overlays can always be the same, even when different screen formats (standard 4:3, widescreen 16:9, etc.) are used.  Texture coordinates are using a system where the coordinates (0, 0) correspond to the lower left corner of the image.  Overlays are drawn in the order in which they are pushed using this function.  Overlays with the same state will be batched together, so it can make sense to group overlays that have the same material, color and flags in order to achieve best performance.  Note that the overlays have to be removed manually using the function h3dClearOverlays.

Parameters

vertsvertex data (x, y, u, v), interpreted as quads
vertCountnumber of vertices (must be multiple of 4)
colR, colG, colB, colAcolor (and transparency) of overlays
materialResmaterial resource used for rendering
flagsoverlay flags (reserved for future use)

Returns

nothing

h3dClearOverlays

DLL void h3dClearOverlays()

Removes all overlays.

Details

This function removes all overlays that were added with h3dShowOverlays.

Parameters

none

Returns

nothing

General resource management functions

h3dGetResType

DLL int h3dGetResType(H3DRes res)

Returns the type of a resource.

Details

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

Parameters

reshandle to the resource

Returns

type of the resource

h3dGetResName

DLL const char *h3dGetResName(H3DRes res)

Returns the name of a resource.

Details

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

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

Parameters

reshandle to the resource

Returns

name of the resource or empty string in case of failure

h3dGetNextResource

DLL H3DRes h3dGetNextResource(int type,
H3DRes start)

Returns the next resource of the specified type.

Details

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.

Parameters

typetype of resource to be searched (H3DResTypes::Undefined for all types)
startresource handle after which the search begins (can be 0 for beginning of resource list)

Returns

handle to the found resource or 0 if it does not exist

h3dFindResource

DLL H3DRes h3dFindResource(int type,
const char *name)

Finds a resource and returns its handle.

Details

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

Parameters

typetype of the resource
namename of the resource

Returns

handle to the resource or 0 if not found

h3dAddResource

DLL H3DRes h3dAddResource(int type,
const char *name,
int flags)

Adds a resource.

Details

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

Parameters

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

Returns

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

h3dCloneResource

DLL H3DRes h3dCloneResource(H3DRes sourceRes,
const char *name)

Duplicates a resource.

Details

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.

Parameters

sourceReshandle to resource to be cloned
namename of new resource (can be empty for auto-naming)

Returns

handle to the cloned resource or 0 in case of failure

h3dRemoveResource

DLL int h3dRemoveResource(H3DRes res)

Removes a resource.

Details

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

Parameters

reshandle to the resource to be removed

Returns

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

h3dIsResLoaded

DLL bool h3dIsResLoaded(H3DRes res)

Checks if a resource is loaded.

Details

This function checks if the specified resource has been successfully loaded.

Parameters

reshandle to the resource to be checked

Returns

true if resource is loaded, otherwise or in case of failure false

h3dLoadResource

DLL bool h3dLoadResource(H3DRes res,
const char *data,
int size)

Loads a resource.

Details

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.

Parameters

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

Returns

true in case of success, otherwise false

h3dUnloadResource

DLL void h3dUnloadResource(H3DRes res)

Unloads a resource.

Details

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

Parameters

reshandle to resource to be unloaded

Returns

nothing

h3dGetResElemCount

DLL int h3dGetResElemCount(H3DRes res,
int elem)

Gets the number of elements in a resource.

Details

This function returns how many elements of the specified element type a specified resource has.

Parameters

reshandle to the resource to be accessed
elemelement type

Returns

number of elements

h3dFindResElem

DLL int h3dFindResElem(H3DRes res,
int elem,
int param,
const char *value)

Finds a resource element with the specified property value.

Details

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.

Parameters

reshandle to the resource to be accessed
elemelement type
paramparameter name
valueparameter value to be searched for

Returns

index of element or -1 if element not found

h3dGetResParamI

DLL int h3dGetResParamI(H3DRes res,
int elem,
int elemIdx,
int param)

Gets an integer property of a resource element.

Details

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

Parameters

reshandle to the resource to be accessed
elemelement type
elemIdxindex of element
paramparameter to be accessed

Returns

value of the parameter

h3dSetResParamI

DLL void h3dSetResParamI(H3DRes res,
int elem,
int elemIdx,
int param,
int value)

Sets an integer property of a resource element.

Details

This function sets a specified property of the specified resource element to the specified value.  The property must be of the type int.

Parameters

reshandle to the resource to be modified
elemelement type
elemIdxindex of element
paramparameter to be modified
valuenew value for the specified parameter

Returns

nothing

h3dGetResParamF

DLL float h3dGetResParamF(H3DRes res,
int elem,
int elemIdx,
int param,
int compIdx)

Gets a float property of a resource element.

Details

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.

Parameters

reshandle to the resource to be accessed
elemelement type
elemIdxindex of element
paramparameter to be accessed
compIdxcomponent of the parameter to be accessed

Returns

value of the parameter

h3dSetResParamF

DLL void h3dSetResParamF(H3DRes res,
int elem,
int elemIdx,
int param,
int compIdx,
float value)

Sets a float property of a resource element.

Details

This function sets the specified component of the specified resource element property to the specified value.  The property must be of the type float.

Parameters

reshandle to the resource to be modified
elemelement type
elemIdxindex of element
paramparameter to be modified
compIdxcomponent of the parameter to be modified
valuenew value for the specified parameter

Returns

nothing

h3dGetResParamStr

DLL const char *h3dGetResParamStr(H3DRes res,
int elem,
int elemIdx,
int param)

Gets a string property of a resource element.

Details

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!

Parameters

reshandle to the resource to be accessed
elemelement type
elemIdxindex of element
paramparameter to be accessed

Returns

value of the property or empty string if no such property exists

h3dSetResParamStr

DLL void h3dSetResParamStr(H3DRes res,
int elem,
int elemIdx,
int param,
const char *value)

Sets a string property of a resource element.

Details

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 *).

Parameters

reshandle to the resource to be modified
elemelement type
elemIdxindex of element
paramparameter to be modified
valuenew value for the specified parameter

Returns

nothing

h3dMapResStream

DLL void *h3dMapResStream(H3DRes res,
int elem,
int elemIdx,
int stream,
bool read,
bool write)

Maps the stream of a resource element.

Details

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.

Parameters

reshandle to the resource to be mapped
elemelement type
elemIdxindex of element
streamstream to be mapped
readflag indicating whether read access is required
writeflag indicating whether write access is required

Returns

pointer to stream data or NULL if stream cannot be mapped

h3dUnmapResStream

DLL void h3dUnmapResStream(H3DRes res)

Unmaps a previously mapped resource stream.

Details

This function unmaps a resource stream that has been mapped before.

Parameters

reshandle to the resource to be unmapped

Returns

nothing

h3dQueryUnloadedResource

DLL H3DRes h3dQueryUnloadedResource(int index)

Returns handle to an unloaded resource.

Details

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.

Parameters

indexindex of unloaded resource within the internal list of unloaded resources (starting with 0)

Returns

handle to an unloaded resource or 0

h3dReleaseUnusedResources

DLL void h3dReleaseUnusedResources()

Frees resources that are no longer used.

Details

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.

Parameters

none

Returns

nothing

Specific resource management functions

h3dCreateTexture

DLL H3DRes h3dCreateTexture(const char *name,
int width,
int height,
int fmt,
int flags)

Creates a Texture resource.

Details

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.

Parameters

namename of the resource
widthwidth of the texture image
heightheight of the texture image
fmttexture format (see stream formats)
flagsflags used for creating the resource

Returns

handle to the created resource or 0 in case of failure

h3dSetShaderPreambles

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

Sets preambles of all Shader resources.

Details

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

Parameters

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

Returns

nothing

h3dSetMaterialUniform

DLL bool h3dSetMaterialUniform(H3DRes materialRes,
const char *name,
float a,
float b,
float c,
float d)

Sets a shader uniform of a Material resource.

Details

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

Parameters

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

Returns

true if uniform was found, otherwise false

h3dResizePipelineBuffers

DLL void h3dResizePipelineBuffers(H3DRes pipeRes,
int width,
int height)

Changes the size of the render targets of a pipeline.

Details

This function sets the base width and height which affects render targets with relative (in percent) size specification.  Changing the base size is usually desired after engine initialization and when the window is being resized.  Note that in case several cameras use the same pipeline resource instance, the change will affect all cameras.

Parameters

pipeResthe pipeline resource instance to be changed
widthbase width in pixels used for render targets with relative size
heightbase height in pixels used for render targets with relative size

Returns

nothing

h3dGetRenderTargetData

DLL bool h3dGetRenderTargetData(H3DRes pipelineRes,
const char *targetName,
int bufIndex,
int *width,
int *height,
int *compCount,
void *dataBuffer,
int bufferSize)

Reads back the pixel data of a render target buffer.

Details

This function reads back the pixels of a specified render target.  If no pipeline resource is specified, the color data of the backbuffer is read back as RGBA float.  Otherwise, the specified buffer of the specified render target is read back and stored in dataBuffer as RGBA float values.  To compute the required size of the output buffer to which the data is written, the function can be called with a NULL pointer for dataBuffer and pointers to variables where the buffer width, height and the number of components will be stored.  As this function has a considerable performance overhead, it is only intended for debugging purposes and screenshots.  For more information about the render buffers, refer to the Pipeline documentation.

Parameters

pipelineReshandle to pipeline resource (0 for backbuffer)
targetNamename of render target to be accessed (ignored for backbuffer)
bufIndexindex of buffer to be accessed (32 for depth buffer)
widthpointer to variable where the width of the buffer will be stored (can be NULL)
heightpointer to variable where the height of the buffer will be stored (can be NULL)
compCountpointer to variable where the number of components will be stored (can be NULL)
dataBufferpointer to array where the pixel data will be stored (can be NULL)
bufferSizesize of dataBuffer array in bytes

Returns

true if specified render target could be found, otherwise false

General scene graph functions

h3dGetNodeType

DLL int h3dGetNodeType(H3DNode node)

Returns the type of a scene node.

Details

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

Parameters

nodehandle to the scene node

Returns

type of the scene node

h3dGetNodeParent

DLL H3DNode h3dGetNodeParent(H3DNode node)

Returns the parent of a scene node.

Details

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

Parameters

nodehandle to the scene node

Returns

handle to parent node or 0 in case of failure

h3dSetNodeParent

DLL bool h3dSetNodeParent(H3DNode node,
H3DNode parent)

Relocates a node in the scene graph.

Details

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

Parameters

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

Returns

true if node could be relocated, otherwise false

h3dGetNodeChild

DLL H3DNode h3dGetNodeChild(H3DNode node,
int index)

Returns the handle to a child node.

Details

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

Parameters

nodehandle to the parent node
indexindex of the child node

Returns

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

h3dAddNodes

DLL H3DNode h3dAddNodes(H3DNode parent,
H3DRes sceneGraphRes)

Adds nodes from a SceneGraph resource to the scene.

Details

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.

Parameters

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

Returns

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

h3dRemoveNode

DLL void h3dRemoveNode(H3DNode node)

Removes a node from the scene.

Details

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

Parameters

nodehandle to the node to be removed

Returns

nothing

h3dCheckNodeTransFlag

DLL bool h3dCheckNodeTransFlag(H3DNode node,
bool reset)

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

Details

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

Parameters

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

Returns

true if node has been transformed, otherwise false

h3dGetNodeTransform

DLL void 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.

Details

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

Parameters

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

Returns

nothing

h3dSetNodeTransform

DLL void 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.

Details

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

Parameters

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

Returns

nothing

h3dGetNodeTransMats

DLL void h3dGetNodeTransMats(H3DNode node,
const float **relMat,
const float **absMat)

Returns the transformation matrices of a node.

Details

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

Parameters

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

Returns

nothing

h3dSetNodeTransMat

DLL void h3dSetNodeTransMat(H3DNode node,
const float *mat4x4)

Sets the relative transformation matrix of a node.

Details

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

Parameters

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

Returns

nothing

h3dGetNodeParamI

DLL int h3dGetNodeParamI(H3DNode node,
int param)

Gets a property of a scene node.

Details

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

Parameters

nodehandle to the node to be accessed
paramparameter to be accessed

Returns

value of the parameter

h3dSetNodeParamI

DLL void h3dSetNodeParamI(H3DNode node,
int param,
int value)

Sets a property of a scene node.

Details

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

Parameters

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

Returns

nothing

h3dGetNodeParamF

DLL float h3dGetNodeParamF(H3DNode node,
int param,
int compIdx)

Gets a property of a scene node.

Details

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.

Parameters

nodehandle to the node to be accessed
paramparameter to be accessed
compIdxcomponent of the parameter to be accessed

Returns

value of the parameter

h3dSetNodeParamF

DLL void h3dSetNodeParamF(H3DNode node,
int param,
int compIdx,
float value)

Sets a property of a scene node.

Details

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

Parameters

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

Returns

nothing

h3dGetNodeParamStr

DLL const char *h3dGetNodeParamStr(H3DNode node,
int param)

Gets a property of a scene node.

Details

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!

Parameters

nodehandle to the node to be accessed
paramparameter to be accessed

Returns

value of the property or empty string if no such property exists

h3dSetNodeParamStr

DLL void h3dSetNodeParamStr(H3DNode node,
int param,
const char *value)

Sets a property of a scene node.

Details

This function sets a specified property of the specified node to a specified value.  The property must be of the type string (const char *).

Parameters

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

Returns

nothing

h3dGetNodeFlags

DLL int h3dGetNodeFlags(H3DNode node)

Gets the scene node flags.

Details

This function returns a bit mask containing the set scene node flags.

Parameters

nodehandle to the node to be accessed

Returns

flag bitmask

h3dSetNodeFlags

DLL void h3dSetNodeFlags(H3DNode node,
int flags,
bool recursive)

Sets the scene node flags.

Details

This function sets the flags of the specified scene node.

Parameters

nodehandle to the node to be modified
flagsnew flag bitmask
recursivespecifies whether flags should be applied recursively to all child nodes

Returns

nothing

h3dGetNodeAABB

DLL void h3dGetNodeAABB(H3DNode node,
float *minX,
float *minY,
float *minZ,
float *maxX,
float *maxY,
float *maxZ)

Gets the bounding box of a scene node.

Details

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

Parameters

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

Returns

nothing

h3dFindNodes

DLL int h3dFindNodes(H3DNode startNode,
const char *name,
int type)

Finds scene nodes with the specified properties.

Details

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

Parameters

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

Returns

number of search results

h3dGetNodeFindResult

DLL H3DNode h3dGetNodeFindResult(int index)

Gets a result from the findNodes query.

Details

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

Parameters

indexindex of search result

Returns

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

h3dCastRay

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.

Details

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.

Parameters

nodenode at which intersection check is beginning
ox, oy, ozray origin
dx, dy, dzray direction vector also specifying ray length
numNearestmaximum number of intersection points to be stored (0 for all)

Returns

number of intersections

h3dGetCastRayResult

DLL bool h3dGetCastRayResult(int index,
H3DNode *node,
float *distance,
float *intersection)

Returns a result of a previous castRay query.

Details

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.

Parameters

indexindex of result to be accessed (range: 0 to number of results returned by castRay)
nodehandle of intersected node
distancedistance from ray origin to intersection point
intersectioncoordinates of intersection point (float[3] array)

Returns

true if index was valid and data could be copied, otherwise false

h3dCheckNodeVisibility

DLL int h3dCheckNodeVisibility(H3DNode node,
H3DNode cameraNode,
bool checkOcclusion,
bool calcLod)

Checks if a node is visible.

Details

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.

Parameters

nodenode to be checked for visibility
cameraNodecamera node from which the visibility test is done
checkOcclusionspecifies if occlusion info from previous frame should be taken into account
calcLodspecifies if LOD level should be computed

Returns

computed LOD level or -1 if node is not visible

Group-specific scene graph functions

h3dAddGroupNode

DLL H3DNode h3dAddGroupNode(H3DNode parent,
const char *name)

Adds a Group node to the scene.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

Model-specific scene graph functions

h3dAddModelNode

DLL H3DNode h3dAddModelNode(H3DNode parent,
const char *name,
H3DRes geometryRes)

Adds a Model node to the scene.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

h3dSetupModelAnimStage

DLL void h3dSetupModelAnimStage(H3DNode modelNode,
int stage,
H3DRes animationRes,
int layer,
const char *startNode,
bool additive)

Configures an animation stage of a Model node.

Details

This function is used to setup the specified animation stage/slot of the specified Model node.

The function can be used for animation blending and mixing.  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 currently set animation is removed.

The layer determines the priority of the animation and how the weights are distributed.  See h3dSetModelAnimParams for more information.

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, scaled by the weight factor, to the current transformation of the joints or meshes.  Additive animations completely ignore the layer settings.  They are only applied by the engine if a non-additive animation is assigned to the model as well.

Parameters

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

Returns

nothing

h3dSetModelAnimParams

DLL void h3dSetModelAnimParams(H3DNode modelNode,
int stage,
float time,
float weight)

Sets the animation stage parameters of a Model node.

Details

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.  All weights of stages that are on the same layer are normalized.  Stages with a higher layer id are animated before stages with lower layers.  The blend weight is distributed across the layers.  If the weight sum of a layer is smaller than 1.0, the remaining weight is propagated to the next lower layer.  So if a layer uses a weight of 100%, the lower layers will not get any weight and consequently not contribute to the overall animation.

Parameters

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

Returns

nothing

h3dSetModelMorpher

DLL bool h3dSetModelMorpher(H3DNode modelNode,
const char *target,
float weight)

Sets the weight of a morph target.

Details

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

Parameters

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

Returns

true if morph target was found, otherwise false

Mesh-specific scene graph functions

h3dAddMeshNode

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.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

Joint-specific scene graph functions

h3dAddJointNode

DLL H3DNode h3dAddJointNode(H3DNode parent,
const char *name,
int jointIndex)

Adds a Joint node to the scene.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

Light-specific scene graph functions

h3dAddLightNode

DLL H3DNode h3dAddLightNode(H3DNode parent,
const char *name,
H3DRes materialRes,
const char *lightingContext,
const char *shadowContext)

Adds a Light node to the scene.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

Camera-specific scene graph functions

h3dAddCameraNode

DLL H3DNode h3dAddCameraNode(H3DNode parent,
const char *name,
H3DRes pipelineRes)

Adds a Camera node to the scene.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

h3dSetupCameraView

DLL void h3dSetupCameraView(H3DNode cameraNode,
float fov,
float aspect,
float nearDist,
float farDist)

Sets the planes of a camera viewing frustum.

Details

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

Parameters

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

Returns

nothing

h3dGetCameraProjMat

DLL void h3dGetCameraProjMat(H3DNode cameraNode,
float *projMat)

Gets the camera projection matrix.

Details

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

Parameters

cameraNodehandle to Camera node
projMatpointer to float array with 16 elements

Returns

nothing

Emitter-specific scene graph functions

h3dAddEmitterNode

DLL H3DNode h3dAddEmitterNode(H3DNode parent,
const char *name,
H3DRes materialRes,
H3DRes particleEffectRes,
int maxParticleCount,
int respawnCount)

Adds a Emitter node to the scene.

Details

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

Parameters

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

Returns

handle to the created node or 0 in case of failure

h3dAdvanceEmitterTime

DLL void h3dAdvanceEmitterTime(H3DNode emitterNode,
float timeDelta)

Advances the time value of an Emitter node.

Details

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

Parameters

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

Returns

nothing

h3dHasEmitterFinished

DLL bool h3dHasEmitterFinished(H3DNode emitterNode)

Checks if an Emitter node is still alive.

Details

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.

Parameters

emitterNodehandle to the Emitter node which is checked

Returns

true if Emitter will no more emit any particles, otherwise or in case of failure false

DLL const char *h3dGetVersionString()
Returns the engine version string.
DLL bool h3dCheckExtension(const char *extensionName)
Checks if an extension is part of the engine library.
DLL bool h3dGetError()
Checks if an error occured.
DLL bool h3dInit()
Initializes the engine.
DLL void h3dRelease()
Releases the engine.
DLL void h3dRender(H3DNode cameraNode)
Main rendering function.
DLL void h3dFinalizeFrame()
Marker for end of frame.
DLL void h3dClear()
Removes all resources and scene nodes.
DLL const char *h3dGetMessage(int *level,
float *time)
Gets the next message from the message queue.
DLL float h3dGetOption(H3DOptions::List param)
Gets an option parameter of the engine.
DLL bool h3dSetOption(H3DOptions::List param,
float value)
Sets an option parameter for the engine.
DLL float h3dGetStat(H3DStats::List param,
bool reset)
Gets a statistic value of the engine.
DLL void h3dShowOverlays(const float *verts,
int vertCount,
float colR,
float colG,
float colB,
float colA,
H3DRes materialRes,
int flags)
Displays overlays on the screen.
DLL void h3dClearOverlays()
Removes all overlays.
DLL int h3dGetResType(H3DRes res)
Returns the type of a resource.
DLL const char *h3dGetResName(H3DRes res)
Returns the name of a resource.
DLL H3DRes h3dGetNextResource(int type,
H3DRes start)
Returns the next resource of the specified type.
DLL H3DRes h3dFindResource(int type,
const char *name)
Finds a resource and returns its handle.
DLL H3DRes h3dAddResource(int type,
const char *name,
int flags)
Adds a resource.
DLL H3DRes h3dCloneResource(H3DRes sourceRes,
const char *name)
Duplicates a resource.
DLL int h3dRemoveResource(H3DRes res)
Removes a resource.
DLL bool h3dIsResLoaded(H3DRes res)
Checks if a resource is loaded.
DLL bool h3dLoadResource(H3DRes res,
const char *data,
int size)
Loads a resource.
DLL void h3dUnloadResource(H3DRes res)
Unloads a resource.
DLL int h3dGetResElemCount(H3DRes res,
int elem)
Gets the number of elements in a resource.
DLL int h3dFindResElem(H3DRes res,
int elem,
int param,
const char *value)
Finds a resource element with the specified property value.
DLL int h3dGetResParamI(H3DRes res,
int elem,
int elemIdx,
int param)
Gets an integer property of a resource element.
DLL void h3dSetResParamI(H3DRes res,
int elem,
int elemIdx,
int param,
int value)
Sets an integer property of a resource element.
DLL float h3dGetResParamF(H3DRes res,
int elem,
int elemIdx,
int param,
int compIdx)
Gets a float property of a resource element.
DLL void h3dSetResParamF(H3DRes res,
int elem,
int elemIdx,
int param,
int compIdx,
float value)
Sets a float property of a resource element.
DLL const char *h3dGetResParamStr(H3DRes res,
int elem,
int elemIdx,
int param)
Gets a string property of a resource element.
DLL void h3dSetResParamStr(H3DRes res,
int elem,
int elemIdx,
int param,
const char *value)
Sets a string property of a resource element.
DLL void *h3dMapResStream(H3DRes res,
int elem,
int elemIdx,
int stream,
bool read,
bool write)
Maps the stream of a resource element.
DLL void h3dUnmapResStream(H3DRes res)
Unmaps a previously mapped resource stream.
DLL H3DRes h3dQueryUnloadedResource(int index)
Returns handle to an unloaded resource.
DLL void h3dReleaseUnusedResources()
Frees resources that are no longer used.
DLL H3DRes h3dCreateTexture(const char *name,
int width,
int height,
int fmt,
int flags)
Creates a Texture resource.
DLL void h3dSetShaderPreambles(const char *vertPreamble,
const char *fragPreamble)
Sets preambles of all Shader resources.
DLL bool h3dSetMaterialUniform(H3DRes materialRes,
const char *name,
float a,
float b,
float c,
float d)
Sets a shader uniform of a Material resource.
DLL void h3dResizePipelineBuffers(H3DRes pipeRes,
int width,
int height)
Changes the size of the render targets of a pipeline.
DLL bool h3dGetRenderTargetData(H3DRes pipelineRes,
const char *targetName,
int bufIndex,
int *width,
int *height,
int *compCount,
void *dataBuffer,
int bufferSize)
Reads back the pixel data of a render target buffer.
DLL int h3dGetNodeType(H3DNode node)
Returns the type of a scene node.
DLL H3DNode h3dGetNodeParent(H3DNode node)
Returns the parent of a scene node.
DLL bool h3dSetNodeParent(H3DNode node,
H3DNode parent)
Relocates a node in the scene graph.
DLL H3DNode h3dGetNodeChild(H3DNode node,
int index)
Returns the handle to a child node.
DLL H3DNode h3dAddNodes(H3DNode parent,
H3DRes sceneGraphRes)
Adds nodes from a SceneGraph resource to the scene.
DLL void h3dRemoveNode(H3DNode node)
Removes a node from the scene.
DLL bool h3dCheckNodeTransFlag(H3DNode node,
bool reset)
Checks if a scene node has been transformed by the engine.
DLL void 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.
DLL void 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.
DLL void h3dGetNodeTransMats(H3DNode node,
const float **relMat,
const float **absMat)
Returns the transformation matrices of a node.
DLL void h3dSetNodeTransMat(H3DNode node,
const float *mat4x4)
Sets the relative transformation matrix of a node.
DLL int h3dGetNodeParamI(H3DNode node,
int param)
Gets a property of a scene node.
DLL void h3dSetNodeParamI(H3DNode node,
int param,
int value)
Sets a property of a scene node.
DLL float h3dGetNodeParamF(H3DNode node,
int param,
int compIdx)
Gets a property of a scene node.
DLL void h3dSetNodeParamF(H3DNode node,
int param,
int compIdx,
float value)
Sets a property of a scene node.
DLL const char *h3dGetNodeParamStr(H3DNode node,
int param)
Gets a property of a scene node.
DLL void h3dSetNodeParamStr(H3DNode node,
int param,
const char *value)
Sets a property of a scene node.
DLL int h3dGetNodeFlags(H3DNode node)
Gets the scene node flags.
DLL void h3dSetNodeFlags(H3DNode node,
int flags,
bool recursive)
Sets the scene node flags.
DLL void h3dGetNodeAABB(H3DNode node,
float *minX,
float *minY,
float *minZ,
float *maxX,
float *maxY,
float *maxZ)
Gets the bounding box of a scene node.
DLL int h3dFindNodes(H3DNode startNode,
const char *name,
int type)
Finds scene nodes with the specified properties.
DLL H3DNode h3dGetNodeFindResult(int index)
Gets a result from the findNodes query.
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.
DLL bool h3dGetCastRayResult(int index,
H3DNode *node,
float *distance,
float *intersection)
Returns a result of a previous castRay query.
DLL int h3dCheckNodeVisibility(H3DNode node,
H3DNode cameraNode,
bool checkOcclusion,
bool calcLod)
Checks if a node is visible.
DLL H3DNode h3dAddGroupNode(H3DNode parent,
const char *name)
Adds a Group node to the scene.
DLL H3DNode h3dAddModelNode(H3DNode parent,
const char *name,
H3DRes geometryRes)
Adds a Model node to the scene.
DLL void h3dSetupModelAnimStage(H3DNode modelNode,
int stage,
H3DRes animationRes,
int layer,
const char *startNode,
bool additive)
Configures an animation stage of a Model node.
DLL void h3dSetModelAnimParams(H3DNode modelNode,
int stage,
float time,
float weight)
Sets the animation stage parameters of a Model node.
DLL bool h3dSetModelMorpher(H3DNode modelNode,
const char *target,
float weight)
Sets the weight of a morph target.
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.
DLL H3DNode h3dAddJointNode(H3DNode parent,
const char *name,
int jointIndex)
Adds a Joint node to the scene.
DLL H3DNode h3dAddLightNode(H3DNode parent,
const char *name,
H3DRes materialRes,
const char *lightingContext,
const char *shadowContext)
Adds a Light node to the scene.
DLL H3DNode h3dAddCameraNode(H3DNode parent,
const char *name,
H3DRes pipelineRes)
Adds a Camera node to the scene.
DLL void h3dSetupCameraView(H3DNode cameraNode,
float fov,
float aspect,
float nearDist,
float farDist)
Sets the planes of a camera viewing frustum.
DLL void h3dGetCameraProjMat(H3DNode cameraNode,
float *projMat)
Gets the camera projection matrix.
DLL H3DNode h3dAddEmitterNode(H3DNode parent,
const char *name,
H3DRes materialRes,
H3DRes particleEffectRes,
int maxParticleCount,
int respawnCount)
Adds a Emitter node to the scene.
DLL void h3dAdvanceEmitterTime(H3DNode emitterNode,
float timeDelta)
Advances the time value of an Emitter node.
DLL bool h3dHasEmitterFinished(H3DNode emitterNode)
Checks if an Emitter node is still alive.