Horde3D Utility Library Extension

Summary
Horde3D Utility Library Extension
IntroductionSome words about the Utility Library.
General functions
freeMemFrees memory allocated by the Utility Library.
dumpMessagesWrites all messages in the queue to a log file.
OpenGL-related functions
initOpenGLInitializes OpenGL.
releaseOpenGLReleases OpenGL.
swapBuffersDisplays the rendered image on the screen.
Resource management
getResourcePathReturns the search path of a resource type.
setResourcePathSets the search path for a resource type.
loadResourcesFromDiskLoads previously added resources from a data drive.
createTGAImageCreates a TGA image in memory.
Scene graph
pickNodeReturns the scene node which is at the specified window coordinates.
Overlays
showTextShows text on the screen using a font texture.

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.

General functions

freeMem

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

Parameters

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

Returns

nothing

dumpMessages

DLL bool dumpMessages()

Writes all messages in the queue to a log file.

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

Parameters

none

Returns

true in case of success, otherwise false

OpenGL-related functions

initOpenGL

DLL bool initOpenGL(int hDC)

Initializes OpenGL.

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

releaseOpenGL

DLL void releaseOpenGL()

Releases OpenGL.

This utility function destroys the previously created OpenGL rendering context.  Currently this function is only available on Windows platforms.

Parameters

none

Returns

nothing

swapBuffers

DLL void swapBuffers()

Displays the rendered image on the screen.

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

getResourcePath

DLL const char *getResourcePath(int type)

Returns the search path of a resource type.

This function returns the search path of a specified resource type.

Parameters

typetype of resource

Returns

pointer to the search path string

setResourcePath

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

Sets the search path for a resource type.

This function sets the search path for a specified resource type.

Parameters

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

Returns

nothing

loadResourcesFromDisk

DLL bool loadResourcesFromDisk(const char *contentDir)

Loads previously added resources from a data drive.

This utility function loads previously added and still unloaded resources from a specified directory on a data drive.  All resource names are directly converted to filenames when being loaded.

Parameters

contentDirdirectory 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

createTGAImage

DLL bool createTGAImage(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.

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 upper 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

Scene graph

pickNode

DLL NodeHandle pickNode(NodeHandle 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.

Parameters

cameraNodecamera used for picking
nwx, nwynormalized window coordinates

Returns

handle of picked node or 0 if no node was hit

Overlays

showText

DLL void showText(const char *text,
float x,
float y,
float size,
int layer,
ResHandle 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.  The layer corresponds to the layer parameter of overlays.

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
layerlayer index of the font overlays
fontMaterialResfont material resource used for rendering

Returns

nothing

DLL void freeMem(char **ptr)
Frees memory allocated by the Utility Library.
DLL bool dumpMessages()
Writes all messages in the queue to a log file.
DLL bool initOpenGL(int hDC)
Initializes OpenGL.
DLL void releaseOpenGL()
Releases OpenGL.
DLL void swapBuffers()
Displays the rendered image on the screen.
DLL const char *getResourcePath(int type)
Returns the search path of a resource type.
DLL void setResourcePath(int type,
const char *path)
Sets the search path for a resource type.
DLL bool loadResourcesFromDisk(const char *contentDir)
Loads previously added resources from a data drive.
DLL bool createTGAImage(const unsigned char *pixels,
int width,
int height,
int bpp,
char **outData,
int *outSize)
Creates a TGA image in memory.
DLL NodeHandle pickNode(NodeHandle cameraNode,
float nwx,
float nwy)
Returns the scene node which is at the specified window coordinates.
DLL void showText(const char *text,
float x,
float y,
float size,
int layer,
ResHandle fontMaterialRes)
Shows text on the screen using a font texture.