| Horde3D Utility Library | |
| Introduction | Some words about the Utility Library. |
| Typedefs and constants | |
| Predefined constants | |
| General functions | |
| h3dutFreeMem | Frees memory allocated by the Utility Library. |
| h3dutDumpMessages | Writes all messages in the queue to a log file. |
| Resource management | |
| h3dutGetResourcePath | Deprecated Returns the search path of a resource type. |
| h3dutSetResourcePath | Deprecated Sets the search path for a resource type. |
| h3dutLoadResourcesFromDisk | Loads previously added resources from a data drive. |
| h3dutCreateGeometryRes | Creates a Geometry resource from specified vertex data. |
| h3dutCreateTGAImage | Creates a TGA image in memory. |
| Utils | |
| h3dutScreenshot | Writes the content of the backbuffer to a tga file. |
| Scene graph | |
| h3dutPickRay | Calculates the ray originating at the specified camera and window coordinates |
| h3dutPickNode | Returns the scene node which is at the specified window coordinates. |
| h3dutGetScreenshotParam | Return width and height for current screenshot. |
| h3dutScreenshotRaw | Take screenshot and copy it to user provided `rgb` buffer. |
| Overlays | |
| h3dutShowText | Shows text on the screen using a font texture. |
| h3dutShowInfoBox | Shows a customizable info box on the screen. |
| h3dutShowFrameStats | Shows frame statistics on the screen. |
Some words about the Utility Library.
Horde3D has a simple core API which offers all the functionality needed to control the engine. The engine core is intended to be as generic as possible to make the complete system lightweight and clean. Nevertheless, it is sometimes useful to have more specific functions in order to increase productivity. For this reason the Utility Library is offered. It has some very handy functions that can help to make your life easier.
DLL void h3dutFreeMem( char ** ptr )
Frees memory allocated by the Utility Library.
This utility function frees the memory that was allocated by another function of the Utility Library.
| ptr | address of a pointer that references to memory allocated by the Utility Library |
nothing
DLL const char *h3dutGetResourcePath( int type )
Deprecated Returns the search path of a resource type.
This function returns the search path of a specified resource type.
The function is now marked as deprecated since it is better practice to make all paths relative to the content directory.
| type | type of resource |
pointer to the search path string
DLL void h3dutSetResourcePath( int type, const char * path )
Deprecated Sets the search path for a resource type.
This function sets the search path for a specified resource type.
The function is now marked as deprecated since it is better practice to make all paths relative to the content directory.
| type | type of resource |
| path | path where the resources can be found ((back-)slashes at end are removed) |
nothing
DLL bool h3dutLoadResourcesFromDisk( const char * contentDir )
Loads previously added resources from a data drive.
This utility function loads previously added and still unloaded resources from the specified directories on a data drive. Several search paths can be specified using the pipe character (|) as separator. All resource names are directly converted to filenames and the function tries to find them in the specified directories using the given order of the search paths.
| contentDir | directories where data is located on the drive ((back-)slashes at end are removed) |
false if at least one resource could not be loaded, otherwise true
DLL H3DRes h3dutCreateGeometryRes( const char * name, int numVertices, int numTriangleIndices, float * posData, unsigned int * indexData, short * normalData, short * tangentData, short * bitangentData, float * texData1, float * texData2 )
Creates a Geometry resource from specified vertex data.
This utility function allocates and initializes a Geometry resource with the specified vertex attributes and indices. The optional tangent space data (normal, tangent, bitangent) is encoded as int16, where -1.0 maps to -32’767 and 1.0f to +32’767.
| name | unique name of the new Geometry resource |
| numVertices | number of vertices |
| numTriangleIndices | number of vertex indices |
| posData | vertex positions (xyz) |
| indexData | indices defining triangles |
| normalData | normals xyz (optional, can be NULL) |
| tangentData | tangents xyz (optional, can be NULL) |
| bitangentData | bitangents xyz (required if tangents specified, otherwise NULL) |
| texData1 | first texture coordinate uv set (optional, can be NULL) |
| texData2 | second texture coordinate uv set (optional, can be NULL) |
handle to new Geometry resource or 0 in case of failure
DLL bool h3dutCreateTGAImage( const unsigned char * pixels, int width, int height, int bpp, char ** outData, int * outSize )
Creates a TGA image in memory.
This utility function allocates memory at the pointer outData and creates a TGA image from the specified pixel data. The dimensions of the image have to be specified as well as the bit depth. The created TGA-image-data can be used as Texture2D or TexureCube resource in the engine.
Note: The memory allocated by this routine has to freed manually using the freeMem function.
| pixels | pointer to pixel source data in BGR(A) format from which TGA-image is constructed; memory layout: pixel with position (x, y) in image (origin of image is lower left corner) has memory location (y * width + x) * (bpp / 8) in pixels array |
| width | width of source image |
| height | height of source image |
| bpp | color bit depth of source data (valid values: 24, 32) |
| outData | address of a pointer to which the address of the created memory block is written |
| outSize | variable to which to size of the created memory block is written |
false if at least one resource could not be loaded, otherwise true
DLL bool h3dutScreenshot( const char * filename )
Writes the content of the backbuffer to a tga file.
This function reads back the content of the backbuffer and writes it to a tga file with the specified filename and path.
| filename | filename and path of the output tga file |
true if the file could be written, otherwise false
DLL void h3dutPickRay( H3DNode cameraNode, float nwx, float nwy, float * ox, float * oy, float * oz, float * dx, float * dy, float * dz )
Calculates the ray originating at the specified camera and window coordinates
This utility function takes normalized window coordinates (ranging from 0 to 1 with the origin being the bottom left corner of the window) and returns ray origin and direction for the given camera. The function is especially useful for selecting objects by clicking on them.
| cameraNode | camera used for picking |
| nwx, nwy | normalized window coordinates |
| ox, oy, oz | calculated ray origin |
| dx, dy, dz | calculated ray direction |
nothing
DLL H3DNode h3dutPickNode( H3DNode cameraNode, float nwx, float nwy )
Returns the scene node which is at the specified window coordinates.
This utility function takes normalized window coordinates (ranging from 0 to 1 with the origin being the bottom left corner of the window) and returns the scene node which is visible at that location. The function is especially useful for selecting objects by clicking on them. Currently picking is only working for Meshes.
| cameraNode | camera used for picking |
| nwx, nwy | normalized window coordinates |
handle of picked node or 0 if no node was hit
DLL void h3dutGetScreenshotParam( int * width, int * height )
Return width and height for current screenshot.
This function is useful in conjunction with h3dutScreenshotRaw to allocate arrays with the correct size.
width: will contain the screenshot width height: will contain the screenshot height
None
DLL bool h3dutScreenshotRaw( unsigned char * rgb, int rgb_len )
Take screenshot and copy it to user provided `rgb` buffer.
The user must provide an RGB array and its size in bytes. The buffer must be at least width * height * 3 bytes large. Use `h3dutGetScreenshotParam` to determine the width and height.
rgb: buffer to hold the image (must be at least width * height * 3 bytes large) rgb_len: length of `rgb` buffer in bytes.
true if screenshot could be copied.
DLL void h3dutShowText( const char * text, float x, float y, float size, float colR, float colG, float colB, H3DRes fontMaterialRes )
Shows text on the screen using a font texture.
This utility function uses overlays to display a text string at a specified position on the screen. The font texture of the specified font material has to be a regular 16x16 grid containing all ASCII characters in row-major order.
| text | text string to be displayed |
| x, y | position of the lower left corner of the first character; for more details on coordinate system see overlay documentation |
| size | size (scale) factor of the font |
| colR, colG, colB | font color |
| fontMaterialRes | font material resource used for rendering |
nothing
DLL void h3dutShowInfoBox( float x, float y, float width, const char * title, int numRows, const char ** column1, const char ** column2, H3DRes fontMaterialRes, H3DRes panelMaterialRes )
Shows a customizable info box on the screen.
This utility function displays an info box with custom text for the current frame on the screen.
| x, y | position of the top left corner of the box; for more details on coordinate system see overlay documentation |
| width | maximum width of info box |
| title | title string of info box |
| numRows | Number of info rows |
| column1 | list of strings to print in first column (=numRows) |
| column2 | list of strings to print in second column (=numRows) |
| panelMaterialRes | material resource used for drawing info box |
nothing
DLL void h3dutShowFrameStats( H3DRes fontMaterialRes, H3DRes panelMaterialRes, int mode )
Shows frame statistics on the screen.
This utility function displays an info box with statistics for the current frame on the screen. Since the statistic counters are reset after the call, the function should be called exactly once per frame to obtain correct values.
| fontMaterialRes | font material resource used for drawing text |
| panelMaterialRes | material resource used for drawing info box |
| mode | display mode, specifying which data is shown (<= MaxStatMode) |
nothing
Frees memory allocated by the Utility Library.
DLL void h3dutFreeMem( char ** ptr )
Writes all messages in the queue to a log file.
DLL bool h3dutDumpMessages()
Deprecated Returns the search path of a resource type.
DLL const char *h3dutGetResourcePath( int type )
Deprecated Sets the search path for a resource type.
DLL void h3dutSetResourcePath( int type, const char * path )
Loads previously added resources from a data drive.
DLL bool h3dutLoadResourcesFromDisk( const char * contentDir )
Creates a Geometry resource from specified vertex data.
DLL H3DRes h3dutCreateGeometryRes( const char * name, int numVertices, int numTriangleIndices, float * posData, unsigned int * indexData, short * normalData, short * tangentData, short * bitangentData, float * texData1, float * texData2 )
Creates a TGA image in memory.
DLL bool h3dutCreateTGAImage( const unsigned char * pixels, int width, int height, int bpp, char ** outData, int * outSize )
Writes the content of the backbuffer to a tga file.
DLL bool h3dutScreenshot( const char * filename )
Calculates the ray originating at the specified camera and window coordinates
DLL void h3dutPickRay( H3DNode cameraNode, float nwx, float nwy, float * ox, float * oy, float * oz, float * dx, float * dy, float * dz )
Returns the scene node which is at the specified window coordinates.
DLL H3DNode h3dutPickNode( H3DNode cameraNode, float nwx, float nwy )
Return width and height for current screenshot.
DLL void h3dutGetScreenshotParam( int * width, int * height )
Take screenshot and copy it to user provided `rgb` buffer.
DLL bool h3dutScreenshotRaw( unsigned char * rgb, int rgb_len )
Shows text on the screen using a font texture.
DLL void h3dutShowText( const char * text, float x, float y, float size, float colR, float colG, float colB, H3DRes fontMaterialRes )
Shows a customizable info box on the screen.
DLL void h3dutShowInfoBox( float x, float y, float width, const char * title, int numRows, const char ** column1, const char ** column2, H3DRes fontMaterialRes, H3DRes panelMaterialRes )
Shows frame statistics on the screen.
DLL void h3dutShowFrameStats( H3DRes fontMaterialRes, H3DRes panelMaterialRes, int mode )