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


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