OpenRM - RMAUX Library (rmflyui.c)

## Index of OpenRM - RMAUX Library

     void rmauxFlyUI (RMnode *cameraNode,
                      RMnode *sgRoot,
    	          float orientationScale,
    		  float stepScale)

     RMnode *cameraRoot - (input) the RMnode containing the RMcamera3D that
        will be manipulated with a flight model.

     RMnode *sgRoot - (input) the root of the scene graph that will be
        drawn on each frame. cameraRoot and sgRoot may be the same node.

     float orientationScale - (input) a floating point value between 0.0
        and 1.0 used to attenuate rotations. A good range of value for
        this parameter is 1/30...1/60.

     float stepScale - (input) a floating point value between 0.0 and 1.0
        used to attenuate translational camera motion. A good range of
        values for this parameter is 1/30..1/60.

rmauxFlyUI builds a set of button to event mappings that are useful for terrain flyovers. The fundamental assumption of rmauxFlyUI is that the input RMnode contains an RMcamera3D scene parameter. This 3D camera will be modified - thus, rmauxFlyUI changes the position of the viewer in the scene, but does not change the orientation matrices of any objects.

Pressing the left mouse button commences activity (motion), and pressing the left mouse button again stops the viewer (abruptly).

Changes in the horizontal location of the pointer cause camera roll to change, while changes to the vertical location of the pointer affect camera pitch. Heading changes as a function of roll & pitch (like flying an aircraft).

The input float parameter orientationScale is used to regulate how quickly changes occur. The value of orientationScale is inversely proportional to the number of frames required for a given change to occur. For example, on each fly frame, we compute the displacement between the pointer current position and the center of the window. Then, we adjust the camera to a new heading. The adjustment is computed such that the new heading will be achieved in 1/orientationScale frames. Therefore, orientationScale is most often a value between 0.0 and 1.0. The closer to 1.0, the more rapid will the changes occur. The closer to 0.0, the more slowly they will occur. We may some day incorporate a temporal filter on changes, but for now, we don't.

The input float parameter stepScale regulates the amount of camera translation per frame. The amount the camera moves during each frame is a function of stepScale multiplied by the cameraFocalDistance parameter (by default, the camera focal distance parameter is 1.0, which measures units of the distance from the eye point to the view reference, or look at point). Increasing the cameraFocalDistance parameter has no substantive effect on the view matrix except when viewing in stereo.

Upon entry, rmauxFlyUI checks to see if the input RMnode "cameraNode" has a 3d camera as a scene parameter. If none is present, an error message isissued and we return. If one is present, we grab a copy of the camera and use the copy for the duration of the UI run. Our copy is modified, then we set the camera3D scene parameter of the target as we fly around. Should the application want to modify the camera, it will be necessary to call rmauxFlyUI again to re-register the new camera with the FlyUI machinery.

During operation, the scene graph rooted at the input RMnode "sgRoot" is drawn on each frame from a viewpoint that "flies" through the scene.

We use a crude, static-velocity model (zero acceleration). It's like a 3 year old child: either it's completely stopped, or going at full speed, with no speed inbetween.

librmaux library source file: rmflyui.c

     int rmauxFlyResetCamera RMAUX_BUTTON_FUNC_PARMS()

     the macro RMAUX_BUTTON_FUNC_PARMS() expands to:

     RMpipe *p - a handle to the current RMpipe.

     int xbutton, ybutton - the current (x, y) positions of the mouse
        pointer.

This routine restores the 3D camera parameters to what they were when rmauxFlyUI was originally called. It is intended to be called from event loop code.

Returns 1 to the caller, presumably an event loop handler, so that processing will continue.

librmaux library source file: rmflyui.c

     int rmauxFlyToggleMotion RMAUX_BUTTON_FUNC_PARMS()

     the macro RMAUX_BUTTON_FUNC_PARMS() expands to:

     RMpipe *p - a handle to the current RMpipe.

     int xbutton, ybutton - the current (x, y) positions of the mouse
        pointer.

This routine turns on and off motion by manipulating the "idle function." When turning motion off, the idle function is removed (nothing happens). When turned on, we set the idle function to rmauxFlyMotionFunc so that we begin to fly. A 1 is returned to the caller.

librmaux library source file: rmflyui.c

     int rmauxFlyMotionFunc RMAUX_BUTTON_FUNC_PARMS()

     the macro RMAUX_BUTTON_FUNC_PARMS() expands to:

     RMpipe *p - a handle to the current RMpipe.

     int xbutton, ybutton - the current (x, y) positions of the mouse
       pointer.

Given a new cursor location, update the camera to take into account the rotational and translational effects of the change from the current values and those dictated by the new cursor position.

A static structure is used to hold state, so this routine (in fact, all of rmauxFlyUI) is not thread safe at this time.

Always returns 1 so that rmauxEventLoop will not terminate.

librmaux library source file: rmflyui.c