Horde3D Utility Library

Summary
Horde3D Utility Library
IntroductionSome words about the Utility Library.
Typedefs and constants
Predefined constants
General functions
h3dutFreeMemFrees memory allocated by the Utility Library.
h3dutDumpMessagesWrites all messages in the queue to a log file.
OpenGL-related functions
h3dutInitOpenGLInitializes OpenGL.
h3dutReleaseOpenGLReleases OpenGL.
h3dutSwapBuffersDisplays the rendered image on the screen.
Resource management
h3dutGetResourcePathDeprecated Returns the search path of a resource type.
h3dutSetResourcePathDeprecated Sets the search path for a resource type.
h3dutLoadResourcesFromDiskLoads previously added resources from a data drive.
h3dutCreateGeometryResCreates a Geometry resource from specified vertex data.
h3dutCreateTGAImageCreates a TGA image in memory.
Utils
h3dutScreenshotWrites the content of the backbuffer to a tga file.
Scene graph
h3dutPickRayCalculates the ray originating at the specified camera and window coordinates
h3dutPickNodeReturns the scene node which is at the specified window coordinates.
Overlays
h3dutShowTextShows text on the screen using a font texture.
h3dutShowFrameStatsShows frame statistics on the screen.

Introduction

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.

Typedefs and constants

Predefined constants

H3DUTMaxStatModeMaximum stat mode number supported in showFrameStats

General functions

h3dutFreeMem

DLL void h3dutFreeMem(char **ptr)

Frees memory allocated by the Utility Library.

Details

This utility function frees the memory that was allocated by another function of the Utility Library.

Parameters

ptraddress of a pointer that references to memory allocated by the Utility Library

Returns

nothing

h3dutDumpMessages

DLL bool h3dutDumpMessages()

Writes all messages in the queue to a log file.

Details

This utility function pops all messages from the message queue and writes them to a HTML formated log file ‘Horde3D_Log.html’.

Parameters

none

Returns

true in case of success, otherwise false

OpenGL-related functions

h3dutInitOpenGL

DLL bool h3dutInitOpenGL(int hDC)

Initializes OpenGL.

Details

This utility function initializes an OpenGL rendering context in a specified window component.

Currently this function is only available on Windows platforms.

Parameters

hDChandle to device context for which OpenGL context shall be created

Returns

true in case of success, otherwise false

h3dutReleaseOpenGL

DLL void h3dutReleaseOpenGL()

Releases OpenGL.

Details

This utility function destroys the previously created OpenGL rendering context.

Currently this function is only available on Windows platforms.

Parameters

none

Returns

nothing

h3dutSwapBuffers

DLL void h3dutSwapBuffers()

Displays the rendered image on the screen.

Details

This utility function displays the image rendered to the previously initialized OpenGL context on the screen by copying it from the backbuffer to the frontbuffer.

Currently this function is only available on Windows platforms.

Parameters

none

Returns

nothing

Resource management

h3dutGetResourcePath

DLL const char *h3dutGetResourcePath(int type)

Deprecated Returns the search path of a resource type.

Details

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.

Parameters

typetype of resource

Returns

pointer to the search path string

h3dutSetResourcePath

DLL void h3dutSetResourcePath(int type,
const char *path)

Deprecated Sets the search path for a resource type.

Details

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.

Parameters

typetype of resource
pathpath where the resources can be found ((back-)slashes at end are removed)

Returns

nothing

h3dutLoadResourcesFromDisk

DLL bool h3dutLoadResourcesFromDisk(const char *contentDir)

Loads previously added resources from a data drive.

Details

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.

Parameters

contentDirdirectories where data is located on the drive ((back-)slashes at end are removed)

Returns

false if at least one resource could not be loaded, otherwise true

h3dutCreateGeometryRes

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.

Details

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.

Parameters

nameunique name of the new Geometry resource
numVerticesnumber of vertices
numTriangleIndicesnumber of vertex indices
posDatavertex positions (xyz)
indexDataindices defining triangles
normalDatanormals xyz (optional, can be NULL)
tangentDatatangents xyz (optional, can be NULL)
bitangentDatabitangents xyz (required if tangents specified, otherwise NULL)
texData1first texture coordinate uv set (optional, can be NULL)
texData2second texture coordinate uv set (optional, can be NULL)

Returns

handle to new Geometry resource or 0 in case of failure

h3dutCreateTGAImage

DLL bool h3dutCreateTGAImage(const unsigned char *pixels,
int width,
int height,
int bpp,
char **outData,
int *outSize)

Creates a TGA image in memory.

Details

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.

Parameters

pixelspointer 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
widthwidth of source image
heightheight of source image
bppcolor bit depth of source data (valid values: 24, 32)
outDataaddress of a pointer to which the address of the created memory block is written
outSizevariable to which to size of the created memory block is written

Returns

false if at least one resource could not be loaded, otherwise true

Utils

h3dutScreenshot

DLL bool h3dutScreenshot(const char *filename)

Writes the content of the backbuffer to a tga file.

Details

This function reads back the content of the backbuffer and writes it to a tga file with the specified filename and path.

Parameters

filenamefilename and path of the output tga file

Returns

true if the file could be written, otherwise false

Scene graph

h3dutPickRay

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

Details

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.

Parameters

cameraNodecamera used for picking
nwx, nwynormalized window coordinates
ox, oy, ozcalculated ray origin
dx, dy, dzcalculated ray direction

Returns

nothing

h3dutPickNode

DLL H3DNode h3dutPickNode(H3DNode cameraNode,
float nwx,
float nwy)

Returns the scene node which is at the specified window coordinates.

Details

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.

Parameters

cameraNodecamera used for picking
nwx, nwynormalized window coordinates

Returns

handle of picked node or 0 if no node was hit

Overlays

h3dutShowText

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.

Details

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.

Parameters

texttext string to be displayed
x, yposition of the lower left corner of the first character; for more details on coordinate system see overlay documentation
sizesize (scale) factor of the font
colR, colG, colBfont color
fontMaterialResfont material resource used for rendering

Returns

nothing

h3dutShowFrameStats

DLL void h3dutShowFrameStats(H3DRes fontMaterialRes,
H3DRes panelMaterialRes,
int mode)

Shows frame statistics on the screen.

Details

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.

Parameters

fontMaterialResfont material resource used for drawing text
panelMaterialResmaterial resource used for drawing info box
modedisplay mode, specifying which data is shown (<= MaxStatMode)

Returns

nothing

DLL void h3dutFreeMem(char **ptr)
Frees memory allocated by the Utility Library.
DLL bool h3dutDumpMessages()
Writes all messages in the queue to a log file.
DLL bool h3dutInitOpenGL(int hDC)
Initializes OpenGL.
DLL void h3dutReleaseOpenGL()
Releases OpenGL.
DLL void h3dutSwapBuffers()
Displays the rendered image on the screen.
DLL const char *h3dutGetResourcePath(int type)
Deprecated Returns the search path of a resource type.
DLL void h3dutSetResourcePath(int type,
const char *path)
Deprecated Sets the search path for a resource type.
DLL bool h3dutLoadResourcesFromDisk(const char *contentDir)
Loads previously added resources from a data drive.
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.
DLL bool h3dutCreateTGAImage(const unsigned char *pixels,
int width,
int height,
int bpp,
char **outData,
int *outSize)
Creates a TGA image in memory.
DLL bool h3dutScreenshot(const char *filename)
Writes the content of the backbuffer to a tga file.
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
DLL H3DNode h3dutPickNode(H3DNode cameraNode,
float nwx,
float nwy)
Returns the scene node which is at the specified window coordinates.
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.
DLL void h3dutShowFrameStats(H3DRes fontMaterialRes,
H3DRes panelMaterialRes,
int mode)
Shows frame statistics on the screen.