Functions


arglSetupForCurrentContext
Initialise the gsub_lite library for the current OpenGL context.
arglCleanup
Free memory used by gsub_lite associated with the specified context.
arglCameraFrustum
Create an OpenGL perspective projection matrix.
arglCameraView
Create an OpenGL viewing transformation matrix.
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.

arglCameraFrustum


Create an OpenGL perspective projection matrix.
void arglCameraFrustum(
    const ARParam *cparam,
    const double focalmin,
    const double focalmax,
    GLdouble m_projection [ 16 ]);

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

Parameter Descriptions
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.
availability
First appeared in ARToolKit 2.68.

arglCameraView


Create an OpenGL viewing transformation matrix.
void arglCameraView(
    double para [ 3 ][ 4 ],
    GLdouble m_modelview [ 16 ],
    double scale );

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

Parameter Descriptions
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.
availability
First appeared in ARToolKit 2.68.

arglCleanup


Free memory used by gsub_lite associated with the specified context.
void arglCleanup(
    ARGL_CONTEXT_SETTINGS_REF contextSettings );

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.

Parameter Descriptions
contextSettings
A reference to ARGL's settings for an OpenGL context, as returned by arglSetupForCurrentContext().
availability
First appeared in ARToolKit 2.68.

arglDispImage


Display an ARVideo image, by drawing it using OpenGL.
void arglDispImage(
    ARUint8 *image,
    const ARParam *cparam,
    const double zoom,
    ARGL_CONTEXT_SETTINGS_REF contextSettings );

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.

Parameter Descriptions
image
Pointer to the tightly-packed image data (as returned by arVideoGetImage()). The horizontal and vertical dimensions of the image data must exactly match the values specified in the fields cparam->xsize and cparam->ysize (see below).

The first byte of image data corresponds to the first component of the top-left-most pixel in the image. The data continues with the remaining pixels of the first row, followed immediately by the pixels of the second row, and so on to the last byte of the image data, which corresponds to the last component of the bottom-right-most pixel.

In the current version of gsub_lite, the format of the pixels (i.e. the arrangement of components within each pixel) is fixed at the time the library is built, and cannot be changed at runtime. (It is determined by which of the possible AR_PIXEL_FORMAT_xxxx symbols was defined 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.
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.
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.
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.
availability
First appeared in ARToolKit 2.68.

arglDispImageStateful


Display an ARVideo image, by drawing it using OpenGL, using and modifying current OpenGL state.
void arglDispImageStateful(
    ARUint8 *image,
    const ARParam *cparam,
    const double zoom,
    ARGL_CONTEXT_SETTINGS_REF contextSettings );

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.

arglSetupForCurrentContext


Initialise the gsub_lite library for the current OpenGL context.
ARGL_CONTEXT_SETTINGS_REF arglSetupForCurrentContext(
    void );

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.

function result
An ARGL_CONTEXT_SETTINGS_REF. See the documentation for this type for more info.
availability
First appeared in ARToolKit 2.68.

© 2003-2004 Philip Lamb (Last Updated 07/02/2004)