arosg

Includes:

Introduction

C-interface to OpenSceneGraph for augmented reality applications.

Discussion

arosg is intended to provide access to the modern plugin-based scene graph OpenSceneGraph, and its attendant model formats and graphical capabilities.

arosg provides a C-based interface to a limited subset of the functionality of OpenSceneGraph. As of version 1.0 of arosg, the supported functionality is primarily 3D model loading and drawing.

Availability: Available ARToolKit v4.4.2 and later.

Functions

arOSGDraw: Process scenegraph-related events, including drawing all visible models.
arOSGFinal: Dispose of an AROSG settings structure.
arOSGGetFrontFace: Get the polygon winding for front-facing polygons.
arOSGGetModelAnimationTime: For a model with animation, discover the animation time.
arOSGGetModelIntersection: Determine if a model is intersected by a line segment.
arOSGGetModelLighting: Find out if lighting for model is on or off.
arOSGGetModelLocalPose: Get the local pose (position and orientation) of an OSG-based model.
arOSGGetModelPose: Get the pose (position and orientation) of an OSG-based model.
arOSGGetModelVisibility: Find out if an OSG-based model is shown or hidden.
arOSGGetProjection: Get the projection matrix used in OSG drawing.
arOSGGetVersion: Get the version of ARToolKit with which the arOSG library was built.
arOSGHandleKeyboard: Pass key press events to OpenSceneGraph.
arOSGHandleMouseDownUp: Pass mouse clicks to OpenSceneGraph.
arOSGHandleMouseMove: Pass mouse motion events to OpenSceneGraph
arOSGHandleReshape: Inform OpenSceneGraph that a window reshape has occured (i.e. changes to window size have occured).
arOSGHandleReshape2: Inform OpenSceneGraph that a window reshape has occured (i.e. changes to window size have occured).
arOSGInit: Create a settings structure for use with all other arOSG functions.
arOSGLoadModel: Load an OSG model using a "model description file".
arOSGLoadModel2: Load an OSG model.
arOSGSetDrawTime: Process scenegraph-related events, including drawing all visible models.
arOSGSetFrontFace: Set the polygon winding for front-facing polygons.
arOSGSetModelAnimationLoopModeOverride: For a model with animation, override the animation loop mode.
arOSGSetModelAnimationPause: For a model with animation, pause or resume the animation.
arOSGSetModelAnimationReset: For a model with animation, reset the animation.
arOSGSetModelLighting: Set lighting for a model on or off.
arOSGSetModelLocalPose: Set the local pose (position and orientation) of an OSG-based model.
arOSGSetModelOutline: Turn on or off 2D outlining of a model's boundary.
arOSGSetModelPose: Set the pose (position and orientation) of an OSG-based model.
arOSGSetModelTransparency: Set transparency for a model on or off.
arOSGSetModelVisibility: Show or hide an OSG-based model.
arOSGSetProjection: Set the projection matrix used in OSG drawing.
arOSGUnloadModel: Unload an OSG model.

arOSGDraw

Process scenegraph-related events, including drawing all visible models.

AR_DLL_API int arOSGDraw(
    AROSG *arOsg);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)

Return Value

0, or in case of error, a value less than 0.

Discussion

This function leaves the values of the OpenGL machine in an indeterminate state, including clobbering the OpenGL viewport, projection and modelview matrices. The user should save any sensitive state prior to calling this function, and restore that state upon return.

arOSGFinal

Dispose of an AROSG settings structure.

AR_DLL_API void arOSGFinal(
    AROSG *arOsg);

Parameters

arOsg: Pointer to the AROSG settings structure to be disposed of. (See arOSGInit().)

Discussion

If you have finished with an AROSG settings structure in your running program, you can unload its internal data by calling arOSGFinal.

arOSGGetFrontFace

Get the polygon winding for front-facing polygons.

AR_DLL_API int arOSGGetFrontFace(
    AROSG *arOsg,
    int *winding);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
winding: Pointer to a location, which on return will be 0 if counter-clockwise (the default), or 1 if clockwise.

Return Value

0, or in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v5.0 and later.

arOSGGetModelAnimationTime

For a model with animation, discover the animation time.

AR_DLL_API int arOSGGetModelAnimationTime(
    AROSG *arOsg,
    const int index,
    double *animationTime);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model of which the animation time should be queried. See arOSGLoadModel().
animationTime: A pointer to a double, which will be filled with the animation time (should one be available), or 0 if no animation time is defined.

Return Value

0, or in case of error, a value less than 0.

Discussion

You may query the animation time of models with animations.

Availability: Available in ARToolKit v4.6.7 and later.

arOSGGetModelIntersection

Determine if a model is intersected by a line segment.

AR_DLL_API int arOSGGetModelIntersection(
    AROSG *arOsg,
    const int index,
    const ARdouble p1[3],
    const ARdouble p2[3]);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to calculate the intersection of. See arOSGLoadModel().
p1: Required; a vector specifying the location of one end of the line segment, in world coordinates.
p2: Required; a vector specifying the location of the other end of the line segment, in world coordinates.

Return Value

1 if an intersection was found, 0 if no intersection was found, or in case of error, a value less than 0.

Discussion

This calculates the intersection between a line segment (defined by two points in world coordinates) and a model (actually an OSG node and subnodes). If an intersection is found, different data types can be returned by providing pointers in parameters nodeType, nodeName, and intersectionCoords.

Availability: Available in ARToolKit v4.5.1 and later.

arOSGGetModelLighting

Find out if lighting for model is on or off.

AR_DLL_API int arOSGGetModelLighting(
    AROSG *arOsg,
    const int index,
    int *lit);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to request the lighting state of. See arOSGLoadModel().
lit: Pointer to a location, which on return will contain 0 if lighting disable, or 1 if enabled.

Return Value

0, or in case of error, a value less than 0.

Discussion

By default, lighting is enabled for models.

Availability: Available in ARToolKit v4.5.1 and later.

arOSGGetModelLocalPose

Get the local pose (position and orientation) of an OSG-based model.

AR_DLL_API int arOSGGetModelLocalPose(
    AROSG *arOsg,
    const int index,
    ARdouble *model);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to retrieve the pose of. See arOSGLoadModel().
model: A 4x4 OpenGL transform matrix (column-major order) representing the local transform of the model.

Return Value

0, or in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v4.5.5 and later.

arOSGGetModelPose

Get the pose (position and orientation) of an OSG-based model.

AR_DLL_API int arOSGGetModelPose(
    AROSG *arOsg,
    const int index,
    ARdouble *modelview);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to retrieve the pose of. See arOSGLoadModel().
modelview: A 4x4 OpenGL transform matrix (column-major order) representing the modelview transform of the model.

Return Value

0, or in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v4.5.1 and later.

arOSGGetModelVisibility

Find out if an OSG-based model is shown or hidden.

AR_DLL_API int arOSGGetModelVisibility(
    AROSG *arOsg,
    const int index,
    int *visible);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to request the visibility of. See arOSGLoadModel().
visible: Pointer to a location, which on return will contain 0 if hidden, or 1 if shown.

Return Value

0, or in case of error, a value less than 0.

Discussion

Models are visible by default.

Availability: Available in ARToolKit v4.5.1 and later.

arOSGGetProjection

Get the projection matrix used in OSG drawing.

AR_DLL_API int arOSGGetProjection(
    AROSG *arOsg,
    ARdouble *p);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
p: A 4x4 OpenGL transform matrix (column-major order) representing the projection transform.

Return Value

0, or in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v4.5.1 and later.

arOSGGetVersion

Get the version of ARToolKit with which the arOSG library was built.

AR_DLL_API unsigned int arOSGGetVersion();

Return Value

Returns the full version number of the ARToolKit version corresponding to this OSG library, in binary coded decimal (BCD) format.

BCD format allows simple tests of version number in the caller e.g. if ((arGetVersion() >> 16) > 0x0272) printf("This release is later than 2.72\n");

The major version number is encoded in the most-significant byte (bits 31-24), the minor version number in the second-most-significant byte (bits 23-16), the tiny version number in the third-most-significant byte (bits 15-8), and the build version number in the least-significant byte (bits 7-0).

Discussion

It is highly recommended that any calling program that depends on features in a certain ARToolKit version, check at runtime that it is linked to a version of ARToolKit that can supply those features. It is NOT sufficient to check the ARToolKit SDK header versions, since with ARToolKit implemented in dynamically-loaded libraries, there is no guarantee that the version of ARToolKit installed on the machine at run-time will be as recent as the version of the ARToolKit SDK which the host program was compiled against.

Availability: Available in ARToolKit v4.4.2 and later.

arOSGHandleKeyboard

Pass key press events to OpenSceneGraph.

AR_DLL_API void arOSGHandleKeyboard(
    AROSG *arOsg,
    int key,
    int x,
    int y);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
key: Key code. The handling of this is OSG-depdendent, but ASCII key codes (0x00 to 0x7f) at least can be passed in directly. For the appropriate key code to use for other keys, see the values defined in OpenSceneGraph. The values are listed in the OSG header file <osgGA/GUIEventAdapter> under the enum "KeyCode".
x: The mouse x location in window relative coordinates when the key was pressed -- presently ignored.
y: The mouse y location in window relative coordinates when the key was pressed -- presently ignored.

Discussion

arOSGHandleMouseDownUp

Pass mouse clicks to OpenSceneGraph.

AR_DLL_API void arOSGHandleMouseDownUp(
    AROSG *arOsg,
    const int button,
    const int state,
    const int x,
    const int y);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
button: The values 0, 1 or 2 for the left, middle and right mouse buttons, respectively. (For the convenience of users using GLUT, these values match the values of GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON and GLUT_RIGHT_BUTTON.)
state: 0 for a mouse-button-down event, and 1 for a mouse-button-up (button released) event.
x: The mouse x location in window relative coordinates when the mouse button was pressed.
y: The mouse y location in window relative coordinates.

Discussion

arOSGHandleMouseMove

Pass mouse motion events to OpenSceneGraph

AR_DLL_API void arOSGHandleMouseMove(
    AROSG *arOsg,
    int x,
    int y);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
x: The mouse x location in window relative coordinates.
y: The mouse y location in window relative coordinates.

Discussion

arOSGHandleReshape

Inform OpenSceneGraph that a window reshape has occured (i.e. changes to window size have occured).

AR_DLL_API void arOSGHandleReshape(
    AROSG *arOsg,
    const int w,
    const int h);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
w: The new window width, in pixels.
h: The new window height, in pixels.

Discussion

This function should be called when the window is first created, and then whenever the operating system generates a notification that the user has changed the window size.

arOSGHandleReshape2

Inform OpenSceneGraph that a window reshape has occured (i.e. changes to window size have occured).

AR_DLL_API void arOSGHandleReshape2(
    AROSG *arOsg,
    const int left,
    const int bottom,
    const int width,
    const int height);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
left: The new viewport origin left coordinate, in pixels.
bottom: The new viewport origin bottom coordinate, in pixels.
width: The new viewport width, in pixels.
height: The new viewport height, in pixels.

Discussion

This function should be called when the window is first created, and then whenever the operating system generates a notification that the user has changed the window size.

arOSGInit

Create a settings structure for use with all other arOSG functions.

AR_DLL_API AROSG *arOSGInit();

Return Value

Pointer to the new AROSG settings structure.

Discussion

All other arOSG functions require a reference to settings and global data. Use this function to create and initialise such a structure.

arOSGLoadModel

Load an OSG model using a "model description file".

AR_DLL_API int arOSGLoadModel(
    AROSG *arOsg,
    const char *modelDescriptionFilePath);

Parameters

arOsg: Pointer to the AROSG settings structure into which the model should be loaded. (See arOSGInit().)
modelDescriptionFilePath: A string holding the path to a "model description file". This file must contain a structured list of the following data: the relative path to the actual OSG model to be loaded, the translation (in x,y,z axes) to be applied to the model, the rotation (in angle/axis form, as degrees, angle of rotation x,y,z), and the scale factor to be applied to the model (in the x,y,z axes). See the sample files included in the ARToolKit distribution in the directory bin/OSG for examples.

Return Value

An index value with which the loaded model can be referred to, in the range [0, AR_OSG_MODELS_MAX - 1], or, in case of error, a value less than 0.

Discussion

- The format of this file is a simple text file. Comments may be included by prefixing the line with a "#" character. The object definition consists of the following:

A line with the path to the object's data file, relative to the objects file. (This path may include spaces.)
A line with the position of the object's origin, relative to the parent coordinate system's origin, expressed as 3 floating point numbers separated by spaces, representing the offset in x, y, and z. This is the same format used by the glTranslate() function.
A line with the orientation of the object's coordinate system, relative to the parent coordinate system, expressed as 4 floating point numbers separated by spaces, representing an angle and an axis of a rotation from the parent. This is the same format used by the glRotate() function.
A line with the scale factor to apply to the object, expressed as 3 floating point numbers separated by spaces, representing the scale factor to apply in x, y, and z. This is the same format used by the glScale() function.
Zero or more lines with optional tokens representing additional information about the object. The following tokens are defined:
- LIGHTING f: Enables or disables lighting calculations for this object. Note that disabling lighting will result in the object being drawn fully lit but without shading. f = 0 to disable, f = 1 to enable. Default is enabled.
- TRANSPARENT: Provides a hint that this object includes transparent portions, and should be drawn alpha-blended. Default is that no transparency hint is provided.

arOSGLoadModel2

Load an OSG model.

AR_DLL_API int arOSGLoadModel2(
    AROSG *arOsg,
    const char *modelFilePath,
    const ARdouble translation[3],
    const ARdouble rotation[4],
    const ARdouble scale[3]);

Parameters

arOsg: Pointer to the AROSG settings structure into which the model should be loaded. (See arOSGInit().)
modelFilePath: A string holding the path to a file readable by OSG (as a node, e.g. an .ive or .osg file).
translation: The translation (in x,y,z axes) to be applied to the model, or NULL to apply no translation.
rotation: The rotation (in angle/axis form, as degrees, angle of rotation x,y,z) to be applied to the model, or NULL to apply no rotation.
scale: The scale factor to be applied to the model (in the x,y,z axes) or NULL to retain the scale at 1.0.

Return Value

An index value with which the loaded model can be referred to, in the range [0, AR_OSG_MODELS_MAX - 1], or, in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v4.5.1 and later.

arOSGSetDrawTime

Process scenegraph-related events, including drawing all visible models.

AR_DLL_API int arOSGSetDrawTime(
    AROSG *arOsg,
    double time);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
time: Decimal seconds value at which to render the next arOSGDraw call.

Return Value

0, or in case of error, a value less than 0.

Discussion

OSG maintains its own internal reference time for animation and simulation rendering. If you wish to render at particular time instants or at non-unit timescales, you can manipulate the timeline for following arOSGDraw calls by calling this function with the time (in decimal seconds) supplied in the parameter. To revert to OSG's internal reference time, pass the value AR_OSG_TIME_USE_REFERENCE_TIME.

See Also

AR_OSG_TIME_USE_REFERENCE_TIME
arOSGDraw

arOSGSetFrontFace

Set the polygon winding for front-facing polygons.

AR_DLL_API int arOSGSetFrontFace(
    AROSG *arOsg,
    int winding);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
winding: 0 to set counter-clockwise (the default), or 1 to set clockwise.

Return Value

0, or in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v5.0 and later.

arOSGSetModelAnimationLoopModeOverride

For a model with animation, override the animation loop mode.

AR_DLL_API int arOSGSetModelAnimationLoopModeOverride(
    AROSG *arOsg,
    const int index,
    const int mode);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model of which the animation loop mode should be overridden. See arOSGLoadModel().
mode: 0 to disable looping, 1 to enable looping (where at the end of the animation sequence, animation continues from the beginning again), or 2 to enable swinging animation (where at the end of animation, animation proceeds in reverse until the beginning is reached, at which point animation proceeds forward again, ad infinitum.

Return Value

0, or in case of error, a value less than 0.

Discussion

Models with animations have a default mode set at time of creation. To override the mode at runtime, use this function.

Availability: Available in ARToolKit v4.6.7 and later.

arOSGSetModelAnimationPause

For a model with animation, pause or resume the animation.

AR_DLL_API int arOSGSetModelAnimationPause(
    AROSG *arOsg,
    const int index,
    const int pause);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model of which the animation should be paused or resumed. See arOSGLoadModel().
pause: 0 to resume the animation, 1 to pause it.

Return Value

0, or in case of error, a value less than 0.

Discussion

Models with animations may have the animation paused and later resumed.

Availability: Available in ARToolKit v4.6.7 and later.

arOSGSetModelAnimationReset

For a model with animation, reset the animation.

AR_DLL_API int arOSGSetModelAnimationReset(
    AROSG *arOsg,
    const int index);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model of which the animation should be reset. See arOSGLoadModel().

Return Value

0, or in case of error, a value less than 0.

Discussion

Models with animations may have the animation reset to the initial state.

Availability: Available in ARToolKit v4.6.7 and later.

arOSGSetModelLighting

Set lighting for a model on or off.

AR_DLL_API int arOSGSetModelLighting(
    AROSG *arOsg,
    const int index,
    const int lit);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to adjust the lighting of. See arOSGLoadModel().
lit: 0 to disable lighting, or non-zero to enable.

Return Value

0, or in case of error, a value less than 0.

Discussion

By default, lighting is enabled for models.

Availability: Available in ARToolKit v4.5.1 and later.

arOSGSetModelLocalPose

Set the local pose (position and orientation) of an OSG-based model.

AR_DLL_API int arOSGSetModelLocalPose(
    AROSG *arOsg,
    const int index,
    const ARdouble model[16]);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to adjust the pose of. See arOSGLoadModel().
model: A 4x4 OpenGL transform matrix (column-major order) representing the local transform of the model.

Return Value

0, or in case of error, a value less than 0.

Discussion

Availability: Available in ARToolKit v4.5.5 and later.

arOSGSetModelOutline

Turn on or off 2D outlining of a model's boundary.

AR_DLL_API int arOSGSetModelOutline(
    AROSG *arOsg,
    const int index,
    const int width,
    const unsigned char rgba[4]);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to retrieve the pose of. See arOSGLoadModel().
width: The width, in pixels, of the outline to place around the model. To disable outlining, pass 0. Outlining is initially disabled.
rgba: The colour of the outline, as an array of unsigned bytes in order red, green, blue, alpha. An opaque outline can be generated by passing 255 for the alpha value. Values less than 255 will result in a transparent outline.

Return Value

0, or in case of error, a value less than 0.

Discussion

Outlining allows a model to be highlighted by drawing a 2D outline of the models extreme boundary. Outlining is not currently supported by OSG on platforms using OpenGL ES, and calling this function will produce erroneous visual results if used on an OpenGL ES platform.

Availability: Available in ARToolKit v4.6.3 and later.

arOSGSetModelPose

Set the pose (position and orientation) of an OSG-based model.

AR_DLL_API int arOSGSetModelPose(
    AROSG *arOsg,
    const int index,
    const ARdouble modelview[16]);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to adjust the pose of. See arOSGLoadModel().
modelview: A 4x4 OpenGL transform matrix (column-major order) representing the modelview transform of the model.

Return Value

0, or in case of error, a value less than 0.

Discussion

arOSGSetModelTransparency

Set transparency for a model on or off.

AR_DLL_API int arOSGSetModelTransparency(
    AROSG *arOsg,
    const int index,
    const int transparent);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to adjust the transparency of. See arOSGLoadModel().
transparent: 0 to disable transparency, or non-zero to enable.

Return Value

0, or in case of error, a value less than 0.

Discussion

By default, transparency for models depends on the state with which the model was created. However, this setting allows overriding of the transparency settings. One example usage would be to force an image texture containing an alpha channel to draw with transparency, or alternately without.

Availability: Available in ARToolKit v4.6. and later.

arOSGSetModelVisibility

Show or hide an OSG-based model.

AR_DLL_API int arOSGSetModelVisibility(
    AROSG *arOsg,
    const int index,
    const int visible);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
index: The index of the model to adjust the visibility of. See arOSGLoadModel().
visible: 0 to hide, or non-zero to show.

Return Value

0, or in case of error, a value less than 0.

Discussion

Models are visible by default.

arOSGSetProjection

Set the projection matrix used in OSG drawing.

AR_DLL_API int arOSGSetProjection(
    AROSG *arOsg,
    ARdouble p[16]);

Parameters

arOsg: Pointer to the AROSG settings structure. (See arOSGInit().)
p: A 4x4 OpenGL transform matrix (column-major order) representing the projection transform.

Return Value

0, or in case of error, a value less than 0.

Discussion

arOSGUnloadModel

Unload an OSG model.

AR_DLL_API int arOSGUnloadModel(
    AROSG *arOsg,
    const int index);

Parameters

arOsg: Pointer to the AROSG settings structure from which the model should be unloaded. (See arOSGInit().)

Return Value

0, or in case of error, a value less than 0.

Discussion

Frees the memory associated with an OSG model.

Constants

AR_OSG_TIME_USE_REFERENCE_TIME: Variable to supply to arOSGSetDrawTime to direct OpenSceneGraph to use its internal reference time.

AR_OSG_TIME_USE_REFERENCE_TIME

Variable to supply to arOSGSetDrawTime to direct OpenSceneGraph to use its internal reference time.

extern const double AR_OSG_TIME_USE_REFERENCE_TIME;

Discussion

OSG maintains its own internal reference time for animation and simulation rendering. If you wish to render using OSG's reference time, supply this value to arOSGSetDrawTime.

See Also

arOSGSetDrawTime

Last Updated: Friday, April 24, 2015