pfuInitInput(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
NAME
pfuInitInput, pfuInitMultiChanInput, pfuExitInput, pfuGetMouse,
pfuGetEvents, pfuInputHandler, pfuCollectInput, pfuCollectGLEventStream,
pfuCollectXEventStream, pfuMapMouseToChan, pfuMouseInChan,
pfuMouseButtonClick, pfuMouseButtonRelease, pfuMapXTime - Initialize,
process and reset input devices.
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
void pfuInitInput(pfPipeWindow *pipeWin, int mode);
void pfuInitMultiChanInput(pfChannel **chanArray, int numChans,
int mode);
void pfuExitInput(void);
void pfuGetMouse(pfuMouse *mouse);
void pfuGetEvents(pfuEventStream *events);
void pfuInputHandler(pfuEventHandlerFuncType userFunc, uint mask);
void pfuCollectInput(void);
void pfuCollectGLEventStream(pfuEventStream *events, pfuMouse *mouse,
int handlerMask, pfuEventHandlerFuncType handlerFunc);
void pfuCollectXEventStream(pfWSConnection dsp,
pfuEventStream *events, pfuMouse *mouse, int handlerMask,
pfuEventHandlerFuncType handlerFunc);
int pfuMapMouseToChan(pfuMouse *mouse, pfChannel *chan);
int pfuMouseInChan(pfuMouse *mouse, pfChannel *chan);
void pfuMouseButtonClick(pfuMouse *mouse, int button, int x, int y,
double time);
void pfuMouseButtonRelease(pfuMouse *mouse, int button, int x, int y,
double time);
double pfuMapXTime(double xtime);
typedef struct _pfuMouse
{
int flags; /* for PDEV_MOUSE_*_DOWN and PFUDEV_MOD_* bitmasks */
int modifiers; /* modifier keys only */
int xpos, ypos; /* Screen coordinates of mouse */
float xchan, ychan; /* Normalized coordinates of mouse */
Page 1
pfuInitInput(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
double posTime; /* msec timestamp on current mouse position */
/* These are used by the GUI and pfiXformer
* GUI needs Last click positional info
* Xformers need last and middle click and release info
*/
/* Mask of clicks seen last frame */
int click;
/* Last click position for each mouse button */
int clickPos[PFUDEV_MOUSE_DOWN_MASK][2];
/* Screen coordinates where a mouse button was last clicked */
int clickPosLast[2];
/* mask of mouse releases seen last frame */
int release;
/* last release position for each mouse button */
int releasePos[PFUDEV_MOUSE_DOWN_MASK][2];
/* Screen coordinates where a mouse button was last released*/
int releasePosLast[2];
/* Last click time for each mouse button */
double clickTime[PFUDEV_MOUSE_DOWN_MASK];
/* Time of last button click */
double clickTimeLast;
/* Last release time for each mouse button */
double releaseTime[PFUDEV_MOUSE_DOWN_MASK];
/* Time of last button release */
double releaseTimeLast;
int winSizeX; /* Window Size */
int winSizeY;
int inWin; /* Window focus flag */
} pfuMouse;
typedef void (*pfuEventHandlerFuncType)(int dev, void* val,
pfuCustomEvent *pfuevent);
DESCRIPTION
There are a variety of automatic and explicit event collection utilities
in libpfutil. Automatic X or GL input event collection is started with
pfuInitInput and the resulting events can be queried with pfuInputHandler
and pfuGetEvents.
pfuInitInput initializes mouse and keyboard input to be read from the
specified pfPipeWindow pipeWin. mode is one of:
Page 2
pfuInitInput(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
PFUINPUT_X
Read mouse and keyboard from a forked process using X device
commands. pipe must have a GLX window. See the pfuGLXWinopen
reference page for more information.
PFUINPUT_GL
Read mouse and keyboard from the draw process using GL device
commands. pipe must have a GL window. This option is no
longer supported.
pfuInitMultiChanInput is a companion function to pfuInit but for forked X
input will create a separate forked input process for each channel in the
chanArray. This is useful for multipipe programs.
pfuCollectInput should be called from the draw process if the mode is
PFUINPUT_GL and will poll the mouse and collect all queued devices. The
first time it is called, pfuCollectInput will queue the following GL
devices:
WINQUIT
REDRAW
KEYBD
LEFTMOUSE
MIDDLEMOUSE
RIGHTMOUSE
INPUTCHANGE
Any other required GL devices, such as function keys, should be queued
explicitly by the application. pfuCollectInput is no longer supported.
If the mode is PFUINPUT_X then pfuCollectInput does not need to be called
since the device input is automatically collected by the forked process.
pfuInputHandler installs the custom handler userFunc, which will then be
called to process each input event included in mask. If the mode is
PFUINPUT_X, then mask can be set to the bitwise-or of an X input mask
with PFUINPUT_CATCH_UNKNOWN, PFUINPUT_CATCH_SIM, or PFU_CATCH_ALL. The
PFUINPUT_GL mode is no longer supported.
pfuGetMouse copies the current mouse values from the libpfutil event
collector (initially triggered with pfuInitInput) into mouse and
pfuGetEvents copies the events of the current frame into events.
pfuGetEvents also resets the internal event queue.
pfuMapMouseToChan maps the mouse screen coordinates (mouse->xpos, mouse-
>ypos) into coordinates in the range [-1, 1] (mouse->xchan, mouse->ychan)
based on chan's viewport. Either TRUE or FALSE is returned to indicate
that the mouse is in or out of the chan's viewport.
pfuMouseInChan does the pfuMapMouseToChan mapping. In addition, its
return value considers mouse focus if a mouse button is recorded as being
Page 3
pfuInitInput(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
down in mouse. In this case, the recorded position of where the mouse
button was clicked will determine if the current channel has focus. The
mouse will be considered to be "in" the channel of focus.
pfuCollectGLEventStream will do immediate IRIS GL input collection into
the provided pfuEventStream and pfuMouse structures. If the provided
event stream or mouse pointer is NULL, it will be ignored. This routine
must be called in the draw process. This function is no longer
supported.
pfuCollectXEventStream will do immediate X input collection from the
provided pfWSConnection into the provided pfuEventStream and pfuMouse
structures. If the provided event stream or mouse pointer is NULL, it
will be ignored.
pfuExitInput must be called to terminate the forked X input process.
Call pfuMouseButtonClick to insert a mouse button click event into the
designated pfuMouse structure. The arguments button, x, y, and time allow
the button-click event to be localized in screen-based space-time
coordinates.
pfuMouseButtonRelease provides a similar capability for button-up
(release) events. As before, button specifies which button, x and y
identify the location of the virtual event, and time denotes when the
even is to be considered to have occurred.
pfuMapXTime performs the mapping from an X-event time xtime to the OpenGL
Performer time system.
NOTES
pfuInit should be called immediately after pfConfig when using these
routines to initialize shared memory used by the utility library. OpenGL
Performer recommends that you use X device input. The OpenGL Performer
sample application, perfly, is shipped with PFUINPUT_X as the default. X
device input is recommended for the following reasons:
OpenGL does not contain device input routines and all input must be
managed through X.
Collecting X device input in an asynchronous process can improve
real-time characteristics.
See the pfuEventQueue man page for a description of the pfuEventStream
structure.
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
Page 4
pfuInitInput(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages
SEE ALSO
pfuGLXWinopen, pfuInit, pfuEventQueue, pfuGUI
Page 5
