gsub_es

Version:
1.0.0
Includes:

Introduction

A collection of useful OpenGL ES routines for ARToolKit.

Discussion

Sample code for example usage of gsub_es is included with ARToolKit, in the directory <AR/examples/simpleLiteES>.

gsub_es is the preferred means for drawing camera video images acquired from ARToolKit's video libraries. It includes optimized texture handling, and a variety of flexible drawing options.

gsub_es also provides utility functions for setting the OpenGL viewing frustum and camera position based on ARToolKit- camera parameters and marker positions.

gsub_es does not depend on GLUT, or indeed, any particular window or event handling system. It is therefore well suited to use in applications which have their own window and event handling code.



Functions

arglCameraFrustumf

Create an OpenGL perspective projection matrix.

arglCameraFrustumRHf

Create an OpenGL perspective projection matrix.

arglCameraViewf

Create an OpenGL viewing transformation matrix.

arglCameraViewRHf

Create an OpenGL viewing transformation matrix.

arglCleanup

Free memory used by gsub_lite associated with the specified context.

arglDispImage

Display an ARVideo image, by drawing it using OpenGL.

arglDispImageStateful

Display an ARVideo image, by drawing it using OpenGL, using and modifying current OpenGL state.

arglDistortionCompensationGet

Enquire as to the enable state of camera lens distortion compensation in arglDispImage.

arglDistortionCompensationSet

Set compensation for camera lens distortion in arglDispImage to off or on.

arglGetPixelZoom

Retrieve the current video image drawing scalefactor.

arglGetRotate90

Find out whether ARGL is rotating all OpenGL drawing by 90 degrees.

arglGLCapabilityCheck

Checks for the presence of an OpenGL capability by version or extension.

arglGluCheckExtension

Check for the availability of an OpenGL extension.

arglPixelBufferDataUpload

Upload a buffer of pixel data to an OpenGL texture for later use by arglDispImage().

arglPixelBufferSizeGet

Query the size of pixel data buffers expected by arglPixelBufferDataUpload().

arglPixelBufferSizeSet

Specify a desired pixel buffer size larger than the camera image size.

arglPixelFormatGet

Get the format of pixel data in which arglDispImage*() is expecting data to be passed.

arglPixelFormatSet

Set the format of pixel data which will be passed to arglDispImage*()

arglSetPixelZoom

Set the current video image drawing scalefactor.

arglSetRotate90

Set or unset a 90 degree rotation in all OpenGL drawing performed by ARGL.

arglSetupForCurrentContext

Initialise the gsub_lite library for the current OpenGL context.


arglCameraFrustumf


Create an OpenGL perspective projection matrix.

void arglCameraFrustumf(
    const ARParam *cparam,
    const float focalmin,
    const float focalmax,
    GLfloat m_projection[16]);  
Parameters
cparam

Pointer to a set of ARToolKit camera parameters for the current video source.

focalmax

The maximum distance at which geometry will be rendered. Any geometry further away from the camera than this distance will be clipped and will not be appear in a rendered frame. Thus, this value should be set high enough to avoid clipping of any geometry you care about. However, the precision of the depth buffer is correlated with the ratio of focalmin to focalmax, thus you should not set focalmax any higher than it needs to be. This value should be specified in the same units as your OpenGL drawing.

focalmin

The minimum distance at which geometry will be rendered. Any geometry closer to the camera than this distance will be clipped and will not be appear in a rendered frame. Thus, this value should be set low enough to avoid clipping of any geometry you care about. However, the precision of the depth buffer is correlated with the ratio of focalmin to focalmax, thus you should not set focalmin any lower than it needs to be. Additionally, geometry viewed in a stereo projections that is too close to camera is difficult and tiring to view, so if you are rendering stereo perspectives you should set this value no lower than the near-point of the eyes. The near point in humans varies, but usually lies between 0.1 m 0.3 m. This value should be specified in the same units as your OpenGL drawing.

m_projection

Pointer to a array of 16 GLdoubles, which will be filled out with a projection matrix suitable for passing to OpenGL. The matrix is specified in column major order.

Discussion

Use this function to create a matrix suitable for passing to OpenGL to set the viewing projection.

Availability
First appeared in ARToolKit 2.68.

arglCameraFrustumRHf


Create an OpenGL perspective projection matrix.

void arglCameraFrustumRHf(
    const ARParam *cparam,
    const float focalmin,
    const float focalmax,
    GLfloat m_projection[16]);  
Parameters
cparam

Pointer to a set of ARToolKit camera parameters for the current video source.

focalmax

The maximum distance at which geometry will be rendered. Any geometry further away from the camera than this distance will be clipped and will not be appear in a rendered frame. Thus, this value should be set high enough to avoid clipping of any geometry you care about. However, the precision of the depth buffer is correlated with the ratio of focalmin to focalmax, thus you should not set focalmax any higher than it needs to be. This value should be specified in the same units as your OpenGL drawing.

focalmin

The minimum distance at which geometry will be rendered. Any geometry closer to the camera than this distance will be clipped and will not be appear in a rendered frame. Thus, this value should be set low enough to avoid clipping of any geometry you care about. However, the precision of the depth buffer is correlated with the ratio of focalmin to focalmax, thus you should not set focalmin any lower than it needs to be. Additionally, geometry viewed in a stereo projections that is too close to camera is difficult and tiring to view, so if you are rendering stereo perspectives you should set this value no lower than the near-point of he eyes. The near point in humans varies, but usually lies between 0.1 m 0.3 m. This value should be specified in the same units as your OpenGL drawing.

m_projection

(description)

Discussion

Use this function to create a matrix suitable for passing to OpenGL to set the viewing projection.


arglCameraViewf


Create an OpenGL viewing transformation matrix.

void arglCameraViewf(
    float para[3][4],
    GLfloat m_modelview[16],
    const float scale);  
Parameters
para

Pointer to 3x4 matrix array of doubles which specify the position of an ARToolKit marker, as returned by arGetTransMat().

m_modelview

Pointer to a array of 16 GLdoubles, which will be filled out with a modelview matrix suitable for passing to OpenGL. The matrix is specified in column major order.

scale

Specifies a scaling between ARToolKit's units (usually millimeters) and OpenGL's coordinate system units. What you pass for the scalefactor parameter depends on what units you want to do your OpenGL drawing in. If you use a scalefactor of 1.0, then 1.0 OpenGL unit will equal 1.0 millimetre (ARToolKit's default units). To use different OpenGL units, e.g. metres, then you would pass 0.001.

Discussion

Use this function to create a matrix suitable for passing to OpenGL to set the viewing transformation of the virtual camera.

The matrix is formed so that the world coordinate system is placed at the centre of the marker, with the marker lying in the x-y plane. The positive x axis points to the right of the marker, the positive y axis to the bottom of the marker, and the positive z axis into the marker. Note that this orientation, while still a right-hand coordinate system, is oriented differentky from the usual sense for OpenGL graphics, and if drawing with OpenGL, you might wish to use arglCameraFrustumRHf() instead.

Availability
First appeared in ARToolKit 2.68.

arglCameraViewRHf


Create an OpenGL viewing transformation matrix.

void arglCameraViewRHf(
    float para[3][4],
    GLfloat m_modelview[16],
    const float scale);  
Parameters
para

Pointer to 3x4 matrix array of doubles which specify the position of an ARToolKit marker, as returned by arGetTransMat().

m_modelview

Pointer to a array of 16 GLdoubles, which will be filled out with a modelview matrix suitable for passing to OpenGL. The matrix is specified in column major order.

scale

Specifies a scaling between ARToolKit's units (usually millimeters) and OpenGL's coordinate system units. What you pass for the scalefactor parameter depends on what units you want to do your OpenGL drawing in. If you use a scalefactor of 1.0, then 1.0 OpenGL unit will equal 1.0 millimetre (ARToolKit's default units). To use different OpenGL units, e.g. metres, then you would pass 0.001.

Discussion

Use this function to create a matrix suitable for passing to OpenGL to set the viewing transformation of the virtual camera.

The matrix is formed so that the world coordinate system is placed at the centre of the marker, with the marker lying in the x-y plane. The positive x axis points to the right of the marker, the positive y axis to the top of the marker, and the positive z axis out of the marker. This is a right-hand coordinate system with the usual sense for OpenGL graphics.


arglCleanup


Free memory used by gsub_lite associated with the specified context.

void arglCleanup(
    ARGL_CONTEXT_SETTINGS_REF contextSettings);  
Parameters
contextSettings

A reference to ARGL's settings for an OpenGL context, as returned by arglSetupForCurrentContext().

Discussion

Should be called after no more argl* functions are needed, in order to prevent memory leaks etc.

The library can be setup again for the context at a later time by calling arglSetupForCurrentContext() again.

Availability
First appeared in ARToolKit 2.68.

arglDispImage


Display an ARVideo image, by drawing it using OpenGL.

void arglDispImage(
    ARGL_CONTEXT_SETTINGS_REF contextSettings);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context. It is the callers responsibility to make sure that the current context at the time arglDisplayImage() is called matches that under which contextSettings was created.

Discussion

This function draws an image from an ARVideo source to the current OpenGL context. This operation is most useful in video see-through augmented reality applications for drawing the camera view as a background image, but can also be used in other ways.

An undistorted image is drawn with the lower-left corner of the bottom-left-most pixel at OpenGL screen coordinates (0,0), and the upper-right corner of the top-right-most pixel at OpenGL screen coodinates (x * zoom, y * zoom), where x and y are the values of the fields cparam->xsize and cparam->ysize (see below) and zoom is the value of the parameter zoom (also see below). If cparam->dist_factor indicates that an un-warping correction should be applied, the actual coordinates will differ from the values specified here.

OpenGL state: Drawing is performed with depth testing and lighting disabled, and thus leaves the the depth buffer (if any) unmodified. If pixel transfer is by texturing (see documentation for arglDrawMode), the drawing is done in replacement texture environment mode. The depth test enable and lighting enable state and the texture environment mode are restored before the function returns.

Availability
First appeared in ARToolKit 2.68.

arglDispImageStateful


Display an ARVideo image, by drawing it using OpenGL, using and modifying current OpenGL state.

Discussion

This function is identical to arglDispImage except that whereas arglDispImage sets an orthographic 2D projection and the OpenGL state prior to drawing, this function does not. It also does not restore any changes made to OpenGL state.

This allows you to do effects with your image, other than just drawing it 2D and with the lower-left corner of the bottom-left-most pixel attached to the bottom-left (0,0) of the window. For example, you might use a perspective projection instead of an orthographic projection with a glLoadIdentity() / glTranslate() on the modelview matrix to place the lower-left corner of the bottom-left-most pixel somewhere other than 0,0 and leave depth-testing enabled.

See the documentation for arglDispImage() for more information.

Availability
First appeared in ARToolKit 2.68.2.

arglDistortionCompensationGet


Enquire as to the enable state of camera lens distortion compensation in arglDispImage.

char arglDistortionCompensationGet(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    char *enable);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

enable

Pointer to an integer value which will be set to TRUE if distortion compensation is enabled in the specified context, or FALSE if it is disabled.

Return Value

TRUE if the distortion value was retreived, FALSE if an error occurred.

Discussion

By default, arglDispImage compensates for the distortion of the camera's acquired image caused by the lens when it draws. This function enquires as to whether arglDispImage is currently doing compensation or not.

Availability
First appeared in ARToolKit 2.71.

arglDistortionCompensationSet


Set compensation for camera lens distortion in arglDispImage to off or on.

char arglDistortionCompensationSet(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    char enable);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

enable

TRUE to enabled distortion compensation, FALSE to disable it. The default state for new contexts is enable = TRUE.

Return Value

TRUE if the distortion value was set, FALSE if an error occurred.

Discussion

By default, arglDispImage compensates for the distortion of the camera's acquired image caused by the lens when it draws. By calling this function with enabled = FALSE, this compensation will be disabled in the specified drawing context. It may be re-enabled at any time. This function is useful if you need to draw an image, but do not know the extent of the camera's lens distortion (such as during distortion calibration). While distortion compensation is disabled, the dist_factor[] array in a the camera cparam structure passed to arglDispImage is ignored.

Availability
First appeared in ARToolKit 2.71.

arglGetPixelZoom


Retrieve the current video image drawing scalefactor.

char arglGetPixelZoom(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    float *zoom);  
Parameters
zoom

The amount to scale the video image up or down. To draw the video image double size, use a zoom value of 2.0. To draw the video image half size use a zoom value of 0.5.


arglGetRotate90


Find out whether ARGL is rotating all OpenGL drawing by 90 degrees.

char arglGetRotate90(
    ARGL_CONTEXT_SETTINGS_REF contextSettings);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

Return Value

TRUE if a 90 degree rotation is enabled, FALSE if it is disabled.

Discussion

On some OpenGL ES devices, it may be desirable to rotate all OpenGL drawing by 90 degrees in the window coordinate system, in order to swap the horizontal and vertical axes of the device. This may be a higher performance solution than manually swapping rows and columns of submitted data.

This function queries the current state of whether such a rotation is being performed by ARGL or not.


arglGLCapabilityCheck


Checks for the presence of an OpenGL capability by version or extension.

int arglGLCapabilityCheck(
    const unsigned short minVersion,
    const unsigned char *extension);  
Parameters
minVersion

A binary-coded decimal (i.e. version 1.0 is represented as 0x0100) version number. If minVersion is zero, (i.e. there is no version of OpenGL with this extension in core) the version test will always fail, and the result will only be true if the extension string test passes.

extension

A string with an extension name to search the drivers extensions string for. E.g. "GL_EXT_texture". If NULL, the extension name test will always fail, and the result will only be true if the version number test passes.

Return Value

TRUE If either of the tests passes, or FALSE if both fail.

Discussion

Checks for the presence of an OpenGL capability by version or extension. The test returns true if EITHER the OpenGL driver's OpenGL implementation version meets or exceeds a minimum value (passed in in minVersion) OR if an OpenGL extension identifier passed in as a character string is non-NULL, and is found in the current driver's list of supported extensions.


arglGluCheckExtension


Check for the availability of an OpenGL extension.

GLboolean arglGluCheckExtension(
    const GLubyte *extName,
    const GLubyte *extString);  
Parameters
extName

Name of the extension, e.g. "GL_EXT_texture".

extString

The OpenGL extensions string, as returned by glGetString(GL_EXTENSIONS);

Return Value

TRUE, if the extension is found, FALSE otherwise.

Discussion

Provides the same functionality as the gluCheckExtension() function, since some platforms don't have GLU version 1.3 or later.


arglPixelBufferDataUpload


Upload a buffer of pixel data to an OpenGL texture for later use by arglDispImage().

char arglPixelBufferDataUpload(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    ARUint8 *bufDataPtr);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

bufDataPtr

A pointer to the pixel buffer, which is a block of memory from which texture data will be read.

The layout of pixel data in the memory pointed to by bufDataPtr is assumed to be specified by the value of pixelFormat in the ARHandle submitted to arglSetupForCurrentContext(), but can be changed by calling arglPixelFormatSet() and/or arglPixelBufferSizeSet().

By default, the pixel buffer is assumed to be tightly packed, row-major array of dimensions equal to the calibrated camera image size (as passed in the fields arParam.xsize and arParam.ysize of the ARHandle submitted to arglSetupForCurrentContext().

The pixel data buffer submitted may, under some circumstances be allowed to be larger than the values of the calibrated camera image size (i.e. padded). See the discussion section of the documentation for function arglPixelBufferSizeSet() for more information.

This may only occur when the underlying OpenGL ES impementation does not support non-power-of-two textures. For the Apple iPhone family, this applies to the iPhone, the iPhone 3G, the iPod Touch 1st and 2nd Generation. The iPhone 3GS and the iPod Touch 3rd Generation support non-power-of-two textures, and thus padding of the pixel data buffer is not supported on these devices. If padding is desired, the desired buffer size must be submitted using arglPixelBufferSizeSet(). Check that the result from this function is TRUE before attempting to upload such a padded buffer.

Return Value

TRUE if the pixel buffer was successfully uploaded to OpenGL, FALSE otherwise.

Discussion

ARGL provides the ability to perform distortion-compensated texturing of a camera video image into the OpenGL context, for the purpose of video-see through augmented reality. This function uploads the camera image data to an OpenGL texture, ready for later drawing using the function arglDispImage().


arglPixelBufferSizeGet


Query the size of pixel data buffers expected by arglPixelBufferDataUpload().

char arglPixelBufferSizeGet(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    int *bufWidth,
    int *bufHeight);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

bufWidth

A pointer to int, which will be filled out with the buffer width, in pixels, or NULL if this value is not required.

bufHeight

A pointer to int, which will be filled out with the buffer height, in pixels, or NULL if this value is not required..

Return Value

TRUE if the buffer size was successfully queried, FALSE otherwise.

Discussion

See function arglPixelBufferSizeSet() for a full discussion.


arglPixelBufferSizeSet


Specify a desired pixel buffer size larger than the camera image size.

char arglPixelBufferSizeSet(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    int bufWidth,
    int bufHeight);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

bufWidth

The desired buffer width, in pixels.

bufHeight

The desired buffer height, in pixels.

Return Value

TRUE if the desired buffer size is supported, FALSE otherwise.

Discussion

By default, the pixel buffer accepted by function arglPixelBufferDataUpload() is assumed to be tightly packed, row-major array of dimensions equal to the calibrated camera image size (as passed in the fields arParam.xsize and arParam.ysize of the ARHandle submitted to arglSetupForCurrentContext().

The pixel data buffer submitted may, under some circumstances be allowed to be larger than the values of the calibrated camera image size (i.e. padded). This may only occur when the underlying OpenGL ES impementation does not support non-power-of-two textures. For the Apple iPhone family, this applies to the iPhone, the iPhone 3G, the iPod Touch 1st and 2nd Generation. The iPhone 3GS and the iPod Touch 3rd Generation support non-power-of-two textures, and thus padding of the pixel data buffer is not supported on these devices. If padding is desired, the desired buffer size must be submitted using this function. Check that the result from this function is TRUE before attempting to upload such a padded buffer.


arglPixelFormatGet


Get the format of pixel data in which arglDispImage*() is expecting data to be passed.

char arglPixelFormatGet(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    AR_PIXEL_FORMAT *format,
    int *size);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

format

A symbolic constant for the pixel format in use. See AR_PIXEL_FORMAT in ar.h for a list of all possible formats.

size

The number of bytes of memory occupied per pixel, for the given format.

Return Value

TRUE if the pixel format and size values were retreived, FALSE if an error occurred.

Discussion

This function enquires as to the current format of pixel data being expected by the arglDispImage*() functions. The default format is determined by the value of AR_DEFAULT_PIXEL_FORMAT at the time the library was built.

Availability
First appeared in ARToolKit 2.71.

arglPixelFormatSet


Set the format of pixel data which will be passed to arglDispImage*()

Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL context, as returned by arglSetupForCurrentContext() for this context.

format

A symbolic constant for the pixel format being set. See AR_PIXEL_FORMAT in ar.h for a list of all possible formats.

Return Value

TRUE if the pixel format value was set, FALSE if an error occurred.

Discussion

(description) In gsub_lite, the format of the pixels (i.e. the arrangement of components within each pixel) can be changed at runtime. Use this function to inform gsub_lite the format the pixels being passed to arglDispImage*() functions are in. This setting applies only to the context passed in parameter contextSettings. The default format is determined by the value of AR_DEFAULT_PIXEL_FORMAT at the time the library was built. Usually, image data is passed in directly from images generated by ARVideo, and so you should ensure that ARVideo is generating pixels of the same format.

Availability
First appeared in ARToolKit 2.71.

arglSetPixelZoom


Set the current video image drawing scalefactor.

char arglSetPixelZoom(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    float zoom);  
Parameters
zoom

The amount to scale the video image up or down. To draw the video image double size, use a zoom value of 2.0. To draw the video image half size use a zoom value of 0.5.


arglSetRotate90


Set or unset a 90 degree rotation in all OpenGL drawing performed by ARGL.

void arglSetRotate90(
    ARGL_CONTEXT_SETTINGS_REF contextSettings,
    char rotate90);  
Parameters
contextSettings

A reference to ARGL's settings for the current OpenGL. context, as returned by arglSetupForCurrentContext() for this context.

rotate90

Set to TRUE or 1 to enable 90 degree rotation, FALSE to disable.

Discussion

On some OpenGL ES devices, it may be desirable to rotate all OpenGL drawing by 90 degrees in the window coordinate system, in order to swap the horizontal and vertical axes of the device. This may be a higher performance solution than manually swapping rows and columns of submitted data.

This function enables or disables such an axis swap in ARGL with very little performance cost, by introducing a 90-degree rotation into the OpenGL projection matrix.

By default, 90 degree rotation is DISABLED.


arglSetupForCurrentContext


Initialise the gsub_lite library for the current OpenGL context.

Parameters
cparam

Pointer to a set of ARToolKit camera parameters for the current video source. The size of the source image is taken from the fields xsize and ysize of the ARParam structure pointed to. Also, when the draw mode is AR_DRAW_BY_TEXTURE_MAPPING (see the documentation for the global variable arglDrawMode) the field dist_factor of the ARParam structure pointed to will be taken as the amount to un-warp the supplied image.

The ARParam structure pointed to must remain valid in memory for the duration of the ARGL_CONTEXT_SETTINGS_REF's usage.

pixelFormat

The type and format of pixels of the images to be drawn by the gsub library. This value can be changed later by using arglPixelFormatSet()

Return Value

An ARGL_CONTEXT_SETTINGS_REF. See the documentation for this type for more info.

Discussion

This function performs required setup of the gsub_lite library for the current OpenGL context and must be called before any other argl*() functions are called for this context.

An OpenGL context holds all of the state of the OpenGL machine, including textures and display lists etc. There will usually be one OpenGL context for each window displaying OpenGL content.

Other argl*() functions whose operation depends on OpenGL state will require an ARGL_CONTEXT_SETTINGS_REF. This is just so that they can keep track of per-context variables.

You should call arglCleanup() passing in the ARGL_CONTEXT_SETTINGS_REF when you have finished with the library for this context.

Availability
First appeared in ARToolKit 2.68.

Typedefs

ARGL_CONTEXT_SETTINGS_REF

Opaque type to hold ARGL settings for a given OpenGL context.


ARGL_CONTEXT_SETTINGS_REF


Opaque type to hold ARGL settings for a given OpenGL context.

typedef struct _ARGL_CONTEXT_SETTINGS *ARGL_CONTEXT_SETTINGS_REF;  
Discussion

An OpenGL context is an implementation-defined structure which keeps track of OpenGL state, including textures and display lists. Typically, individual OpenGL windows will have distinct OpenGL contexts assigned to them by the host operating system.

As gsub_lite uses textures and display lists, it must be able to track which OpenGL context a given texture or display list it is using belongs to. This is especially important when gsub_lite is being used to draw into more than one window (and therefore more than one context.)

Basically, functions which depend on OpenGL state, will require an ARGL_CONTEXT_SETTINGS_REF to be passed to them. An ARGL_CONTEXT_SETTINGS_REF is generated by setting the current OpenGL context (e.g. if using GLUT, you might call glutSetWindow()) and then calling arglSetupForCurrentContext(). When you have finished using ARGL in a given context, you should call arglCleanup(), passing in an ARGL_CONTEXT_SETTINGS_REF, to free the memory used by the settings structure.

Availability
First appeared in ARToolKit 2.68.