pfiTDFXformer(3pf) OpenGL Performer 3.2.2 libpfui Reference Pages
NAME
pfiNewTDFXformer, pfiGetTDFXformerClassType, pfiCreateTDFXformer,
pfiTDFXformerStartMotion, pfiGetTDFXformerStartMotion,
pfiTDFXformerFastClickTime, pfiGetTDFXformerFastClickTime,
pfiTDFXformerTrackball, pfiTDFXformerDrive, pfiTDFXformerFly,
pfiGetTDFXformerTrackball, pfiGetTDFXformerDrive, pfiGetTDFXformerFly,
pfiProcessTDFXformerMouseEvents, pfiProcessTDFXformerMouse,
pfiProcessTDFTrackballMouse, pfiProcessTDFTravelMouse - Performer utility
module used by perfly for managing a collection of motion models with a
default user interface.
FUNCTION SPECIFICATION
#include <Performer/pfui.h>
pfiTDFXformer * pfiNewTDFXformer(void* arena);
pfType* pfiGetTDFXformerClassType(void);
pfiXformer * -
pfiCreateTDFXformer( pfiInputXformTrackball *tb,
pfiInputXformDrive *drive,
pfiInputXformFly *fly, void *arena);
void pfiTDFXformerStartMotion(pfiTDFXformer* xf,
float startSpeed, float startAccel,
float accelMult);
void pfiGetTDFXformerStartMotion(pfiTDFXformer* xf,
float *startSpeed, float *startAccel,
float *accelMult);
void pfiTDFXformerFastClickTime(pfiTDFXformer* xf,
float msecs);
float pfiGetTDFXformerFastClickTime(pfiXformer* xf);
void pfiTDFXformerTrackball(pfiTDFXformer *xf,
pfiInputXformTrackball *tb);
void pfiTDFXformerDrive(pfiTDFXformer *xf,
pfiInputXformDrive *tb);
void pfiTDFXformerFly(pfiTDFXformer *xf,
pfiInputXformFly *tb);
pfiInputXformTrackball * pfiGetTDFXformerTrackball(pfiTDFXformer *xf);
pfiInputXformDrive * pfiGetTDFXformerDrive(pfiTDFXformer *xf);
pfiInputXformFly * pfiGetTDFXformerFly(pfiTDFXformer *xf);
Page 1
pfiTDFXformer(3pf) OpenGL Performer 3.2.2 libpfui Reference Pages
int pfiProcessTDFXformerMouseEvents(pfiInput *,
pfuEventStream *, void *data);
void pfiProcessTDFXformerMouse(pfiTDFXformer *xf,
pfuMouse *mouse, pfChannel *inputChan);
void pfiProcessTDFTrackballMouse(pfiTDFXformer *xf,
pfiInputXformTrackball *trackball,
pfuMouse *mouse);
void pfiProcessTDFTravelMouse(pfiTDFXformer *xf,
pfiInputXformTravel *tr, pfuMouse *mouse);
DESCRIPTION
pfiTDFXformer is a facility developed using the pfiXformer to provide a
convenient utility for managing motion models derived from
pfiInputXformTrackball, pfiInputXformDrive, and pfiInputXformFly and
providing a default user interface for such motion models based on input
received through a pfuMouse structure. This utility is used by OpenGL
Performer sample programs, such as perfly, in conjunction with the
libpfutil input collection utilities (see the pfuInitInput reference page
for more information).
A pfiTDFXformer is a child of the pfiXformer class and so pfiXformer
routines may be called with a pfiTDFXformer. See the pfiXformer and
pfiInputXform reference pages for information on other general
functionality. Functionality specific to the pfiXformer are discussed
here The pfiTDFXformer has a complete C++ API following the conventions
of general OpenGL Performer C++ API; C++ methods are declared in
/usr/include/Performer/pfui/pfiXformer.h. This reference page only
discusses the C API.
pfiInit should be called once before any pfiTDFXformer routines and
before the forked creation of any additional processes that will be
calling pfiXformer routines.
pfiGetTDFXformerClassType returns the pfType* for the class pfiXformer.
Because OpenGL Performer allows subclassing of built-in types, when
decisions are made based on the type of an object, it is usually better
to use pfIsOfType to test if an object is of a type derived from a
Performer type rather than to test for strict equality of the pfType*'s.
pfiNewTDFXformer creates a new pfiTDFXformer data structure as described
above and returns a pointer to that structure. arena should specify the
shared arena handle returned by pfGetSharedArena or from the process
dynamic memory area.
pfiProcessTDFXformerMouse is the default update function used by the
pfiTDFXformer and implements a interface based on input from pfuMouse and
pfChannel specified with pfiXformerAutoInput. The type of the currently
selected motion model (selected with pfiSelectXformerModel) is to see if
it is derived from one of pfiInputXformTrackball, or pfiInputXformTravel,
Page 2
pfiTDFXformer(3pf) OpenGL Performer 3.2.2 libpfui Reference Pages
causes the pfiTDFXformer to invoke the mouse handling routine
pfiProcessTDFTrackballMouse or pfiProcessTDFTravelMouse for the
corresponding motion model type. The trackball, drive, and fly motion
models have the following interpretations of mouse events:
TRACKBALL
Motion models derived from pfiInputXformTrackball will get the
TRACKBALL mouse mapping. This mode causes the transformation matrix
to be transformed as if the user was using the mouse pointer to spin
a virtual trackball that surrounds the scene. The center of the
scene is the computed center of the database supplied by
pfiXformerNode, or the center of the supplied database bounding box
via pfiXformerLimits or pfiIXformDBLimits in world-space
coordinates. Trackball motion is intended to applied to the matrix
of a pfDCS transforming the database.. This can be done
automatically if the pfDCS was supplied with pfiXformerAutoPosition.
The trackball transformation matrix can be requested from the
pfiTDFXformer with pfiGetXformerModelMat. Collision detection is
disabled in trackball mode. Two kinds of motion are possible in
this mode.
ROTATION
The user can "spin" the virtual trackball by holding down the
middle mouse button and moving the cursor relative to where it
was at the time the middle button was pressed. Thus, when the
middle mouse button is down, moving the cursor horizontally on
the screen will cause rotation around Performer's world-space
Z-axis, while moving the cursor vertically will cause rotation
around Performer's world-space X-axis. Releasing the middle
mouse button while moving the cursor will cause the pfiXformer
to continue to rotate the transformation matrix at the current
rate. Holding down both the middle and right mouse buttons will
cause rotation around Performer's world-space Y-axis.
TRANSLATION
The user can "move" or translate the virtual trackball in the
XZ plane in Performer's world-space (the plane of the screen
when the view into the pfChannel is directed down the Y-axis -
the default in perfly) by holding down the left mouse button
and moving the cursor relative to its position at the time the
left mouse button was pressed. The user can "zoom" or
translate the virtual trackball on the Y axis in Performer's
world-space by holding down the right (or both left and right)
mouse buttons while moving the cursor vertically on the screen.
Mouse Action Motion Effect
______________________________________________________________________________________Left mouse down Translation in X and Z
Middle mouse down Rotation around the X and Z axis
Middle+Right mouse down Rotation about Y axis
|
Page 3
pfiTDFXformer(3pf) OpenGL Performer 3.2.2 libpfui Reference Pages
Right mouse down: Translation along Y axis (zoom)Middle+Right mouse down Translation in along Y axis (zoom)
No mouse down mouse position is ignored.
|
If the motion model is changed from the trackball model to a moving
viewpoint model, pfiInputXformDrive or pfiInputXformFly, the
corresponding final transformations on the scene pfDCS are then
transformed to the viewpoint.
DRIVE
Motion models derived from pfiInputXformDrive will get the DRIVE
mouse mapping. This mode causes the transformation matrix to be
transformed as if the user were using the mouse to control a car or
other land-based vehicle. In this mode the cursor's position
relative to the center of the screen will continue to cause relative
turning of the transformation matrix. Moving the cursor to the
right causes a right turn. Moving the cursor to the left causes a
left turn. Keeping the cursor in the middle keeps the
transformation "facing" the same direction. The left and right
mouse buttons control acceleration and deceleration, respectively.
If moving forward, the right mouse button will decelerate until
eventually you start moving backward. The left and right buttons
together will set your current speed to zero but allow you to
control viewing direction. So, if you are moving forwards and you
desire to be going in reverse immediately, hit the right and left
mouse buttons together, then release the left mouse button. The
middle mouse button allows control of viewing direction while
maintaining a constant speed, or will maintain the current position
if the viewer was stopped when the middle mouse button was pushed.
Additionally, when the middle mouse button is pressed, the driving
height may be altered by holding down a ctrl-key and moving the
mouse up and down. A single fast middle-mouse click anywhere on the
screen will cause motion to stop. Additionally, if all three mouse
buttons are down, motion will stop. When no mouse buttons are down,
the mouse position is ignored; motion in progress when mouse buttons
were pressed will continue at a constant speed.
The mouse buttons are the same as are interpreted as follows:
Mouse Action Motion Effect
___________________________________________________________
Left mouse down Accelerate forward motion and steer
Right mouse down Decelerate motion direction and steer
Middle mouse down Maintain current motion and and steer
Left and Right down Halt current motion and steer
Fast middle click Halt all motion
No mouse down mouse position is ignored.
|
FLY Motion models derived from pfiInputXformFly will get the FLY mouse
mapping. This mode causes the transformation matrix to be
transformed as if the user were using the mouse to direct flight in
Page 4
pfiTDFXformer(3pf) OpenGL Performer 3.2.2 libpfui Reference Pages
3D space. The viewer position will follow the mouse: vertical
motion of the mouse will direct motion up and down. The behavior in
this mode is different from that of classic flight models where
moving the mouse up pushes the nose of the aircraft up and moving
the mouse down pushes the nose down. Here the pitch of the aircraft
follows the mouse. Motion controls are analogous to the
pfiInputXformDrive model. The left and right buttons do
acceleration and deceleration, middle mouse directs heading and
maintains current motion at a constant speed. Keeping the cursor in
the middle of the screen will maintain current direction. The mouse
buttons are interpreted this way.
Mouse Action Motion Effect
___________________________________________________________
Left mouse down Accelerate forward motion and steer
Right mouse down Decelerate motion direction and steer
Middle mouse down Maintain current motion and and steer
Left and Right down Halt current motion and steer
Fast middle click Halt all motion
No mouse down mouse position is ignored.
|
pfiTDFXformerFastClickTime will set the maximum time for a mouse button
to be down and still to qualify as a "fast click" for xf to be msecs. If
msecs is less than 0, fast click checking will be disabled and no such
clicks will be recognized. The default fast click time is 300msecs.
pfiGetTDFXformerFastClickTime returns the fast click time for xf.
NOTES
The libpfui source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
Page 5
