pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)NAME
pfuInitGUI, pfuExitGUI, pfuEnableGUI, pfuUpdateGUI, pfuRedrawGUI,
pfuGUIViewport, pfuGetGUIViewport, pfuInGUI, pfuInitGUICursors,
pfuGetGUIChan, pfuGUICursor, pfuGetGUICursor, pfuGUIHlight,
pfuGetGUIHlight, pfuGUICursorSel, pfuGetGUICursorSel, pfuUpdateGUICursor,
pfuFitWidgets, pfuGetGUIScale, pfuGetGUITranslation, pfuNewPanel,
pfuEnablePanel, pfuDisablePanel, pfuGetPanelOriginSize, pfuNewWidget,
pfuDisableWidget, pfuEnableWidget, pfuIsWidgetOn, pfuHideWidget,
pfuGetWidgetType, pfuGetWidgetId, pfuWidgetDim, pfuGetWidgetDim,
pfuWidgetLabel, pfuGetWidgetLabelWidth, pfuGetWidgetLabel,
pfuWidgetRange, pfuWidgetValue, pfuGetWidgetValue, pfuWidgetDefaultValue,
pfuWidgetActionFunc, pfuGetWidgetActionFunc, pfuWidgetSelectFunc,
pfuGetWidgetSelectFunc, pfuWidgetDrawFunc, pfuGetWidgetDrawFunc,
pfuWidgetSelections, pfuWidgetSelection, pfuGetWidgetSelection,
pfuWidgetDefaultSelection, pfuWidgetDefaultOnOff, pfuWidgetOnOff,
pfuWidgetMode, pfuGetWidgetMode, pfuUnhideWidget, pfuResetGUI,
pfuResetPanel, pfuResetWidget, pfuDrawMessage, pfuDrawMessageCI,
pfuDrawMessageRGB, pfuDrawTree - High-performance graphical user
interface routines.
FUNCTION SPECIFICATION
#include <Performer/pfutil.h>
void pfuInitGUI(pfPipeWindow *pipe);
void pfuExitGUI(void);
void pfuEnableGUI(int en);
void pfuUpdateGUI(pfuMouse *mouse);
void pfuRedrawGUI(void);
void pfuGUIViewport(float l, float r, float b, float t);
void pfuGetGUIViewport(float *l, float *r, float *b, float *t);
int pfuInGUI(int x, int y);
void pfuInitGUICursors(void);
pfChannel * pfuGetGUIChan(void);
void pfuGUICursor(int target, int c);
int pfuGetGUICursor(int target);
void pfuGUIHlight(pfHighlight *hlight);
pfHighlight * pfuGetGUIHlight(void);
Page 1
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
void pfuGUICursorSel(int c);
int pfuGetGUICursorSel(void);
void pfuUpdateGUICursor(void);
void pfuFitWidgets(int val);
void pfuGetGUIScale(float *x, float *y);
void pfuGetGUITranslation(float *x, float *y);
pfuPanel * pfuNewPanel(void);
void pfuEnablePanel(pfuPanel *p);
void pfuDisablePanel(pfuPanel *p);
void pfuGetPanelOriginSize(pfuPanel *p, float *xo, float *yo,
float *xs, float *ys);
pfuWidget * pfuNewWidget(pfuPanel *p, int type, int id);
void pfuDisableWidget(pfuWidget *w);
void pfuEnableWidget(pfuWidget *w);
int pfuIsWidgetOn(pfuWidget *w);
void pfuHideWidget(pfuWidget *w);
int pfuGetWidgetType(pfuWidget *w);
int pfuGetWidgetId(pfuWidget *w);
void pfuWidgetDim(pfuWidget *w, int xo, int yo, int xs,
int ys);
void pfuGetWidgetDim(pfuWidget *w, int *xo, int *yo, int *xs,
int *ys);
void pfuWidgetLabel(pfuWidget *w, const char *label);
int pfuGetWidgetLabelWidth(pfuWidget *w);
const char * pfuGetWidgetLabel(pfuWidget *w);
void pfuWidgetRange(pfuWidget *w, int printMode, float min,
float max, float val);
Page 2
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
void pfuWidgetValue(pfuWidget *w, float newval);
float pfuGetWidgetValue(pfuWidget *w);
void pfuWidgetDefaultValue(pfuWidget *w, float val);
void pfuWidgetActionFunc(pfuWidget *w,
pfuWidgetActionFuncType func);
pfuWidgetActionFuncType
pfuGetWidgetActionFunc(pfuWidget *w);
void pfuWidgetSelectFunc(pfuWidget *w,
pfuWidgetSelectFuncType func);
pfuWidgetSelectFuncType
pfuGetWidgetSelectFunc(pfuWidget *w);
void pfuWidgetDrawFunc(pfuWidget *w,
pfuWidgetDrawFuncType func);
pfuWidgetDrawFuncType
pfuGetWidgetDrawFunc(pfuWidget *w);
void pfuWidgetSelections(pfuWidget *w,
pfuGUIString *selectionList, int *valList,
void (**funcList)(pfuWidget *w), int numSelections);
void pfuWidgetSelection(pfuWidget *w, int index);
int pfuGetWidgetSelection(pfuWidget *w);
void pfuWidgetDefaultSelection(pfuWidget *w, int index);
void pfuWidgetDefaultOnOff(pfuWidget * w, int on);
void pfuWidgetOnOff(pfuWidget *w, int on);
void pfuWidgetMode(pfuWidget *w, int mode, int val);
int pfuGetWidgetMode(pfuWidget *w, int mode);
void pfuUnhideWidget(pfuWidget *w);
void pfuResetGUI(void);
void pfuResetPanel(pfuPanel *p);
void pfuResetWidget(pfuWidget *w);
Page 3
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
void pfuDrawMessage(pfChannel *chan, const char *msg, int rel,
int just, float x, float y, int size, int cimode);
void pfuDrawMessageCI(pfChannel *chan, const char *msg,
int rel, int just, float x, float y, int size,
int textClr, int shadowClr);
void pfuDrawMessageRGB(pfChannel *chan, const char *msg,
int rel, int just, float x, float y, int size,
pfVec4 textClr, pfVec4 shadowClr);
void pfuDrawTree(pfChannel *chan, pfNode *tree,
pfVec3 panScale);
typedef void (*pfuWidgetDrawFuncType)(pfuWidget *widget, pfuPanel *panel);
typedef pfuWidget* (*pfuWidgetSelectFuncType)(pfuWidget *widget, pfuPanel *panel);
typedef void (*pfuWidgetActionFuncType)(pfuWidget *widget);
DESCRIPTION
These functions define a simple graphical user interface library for the
OpenGL Performer sample application perfly.
Call pfuInitGUI to initialize the GUI module. Call pfuExitGUI on exit to
deallocate GUI data structures and print brief frame statistics through
pfNotify at notification level PFNFY_INFO.
pfuGetGUIChan returns the pfChannel used by the GUI.
pfuEnableGUI disables or enables GUI processing and GUI panel updates
depending on the value of en. pfuUpdateGUI uses the current mouse data
in mouse to draw the GUI according to its current configuration. The
mouse data can be collected by your own input handling routines and
stored in a pfuMouse structure to give to the GUI or retrieved from the
libpfutil input collector using pfuGetMouse. pfuRedrawGUI redraws the
GUI.
pfuGUIViewport sets the GUI coordinates relative to the GUI window.
pfuGetGUIViewport retrieves the current coordinates.
pfuInGUI returns true if the point (x, y) lies within the GUI. x and y
should be given relative to the window, not the screen.
Your application should call pfuFitWidgets if you change your panel
layout after initialization so that the widgets in the window are
accurately scaled and translated to fit inside the window. This function
is called automatically from pfuUpdateGUI if a change in window size is
detected. val is currently ignored.
pfuGetGUIScale can be called to retrieve the relative scale of the GUI to
Page 4
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
the display window. Similarly, pfuGetGUITranslation will retrieve the
current translation.
pfuNewPanel allocates and initializes a new GUI panel, pfuEnablePanel is
used to enable a panel, and pfuDisablePanel disables a panel. GUI panels
are essentially a region containing widgets, rectangular regions which
can be customized as buttons, menus, and other interface items.
pfuResetPanel restores the widgets in panel to their default values.
pfuGetPanelOriginSize retrieves the origin and size for panel.
pfuNewWidget allocates and initializes a new widget of type type. id is
the handle by which the new widget is identified. pfuGetWidgetType
returns w's type while pfuGetWidgetId returns w's id. Use
pfuEnableWidget and pfuDisableWidget to enable or disable the action of a
widget w.
pfuWidgetDim sets w's lower left corner at (xo, yo) and its top right
corner at (xo+xs, yo+ys). pfuGetWidgetDim returns w in xo and yo and its
size in xs and ys.
pfuWidgetLabel sets label to be the label by which w will be identified.
pfuGetWidgetLabelWidth returns the length of w's label while
pfuGetWidgetLabel returns the label itself.
pfuWidgetRange sets the range of legal values for the widget (min and
max), and initial value of w in val. The printMode arg takes the values 1
or 0 and is used to indicate if the value should be printed as an int
PFUGUI_INT or float PFUGUI_FLOAT.
pfuWidgetValue essentially sets w's value to newval. The actions are
different depending on w's type.
PFUGUI_SLIDER
w's value is set to newval.
PFUGUI_SLIDER_LOG
w's value is set to the base-10 logarithm of newval.
PFUGUI_SWITCH,
w's value is set to its minimum possible provided newval is
close to the minimum. Otherwise, w's value is set to its
maximum possible.
PFGUI_BUTTON
w is highlighted if newval is non-zero, otherwise it is
unhighlighted.
PFUGUI_MENU_BUTTON
w's value is set to the index of the selection whose value is
close to newval.
Page 5
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
PFUGUI_RADIO_BUTTON or PFUGUI_RADIO_BUTTON_TOGGLE
w's value is set to the index of the selection whose value is
close to newval.
pfuGetWidgetValue returns w's value. pfuWidgetDefaultValue works just
like pfuWidgetValue but sets w's default value to newval instead.
pfuWidgetActionFunc is used to set the callback function when the mouse
button is clicked on the widget. pfuGetWidgetActionFunc will return the
widget's action callback function. pfuWidgetSelectFunc and
pfuWidgetDrawFunc are used to set up custom widgets. pfuWidgetSelectFunc
is called with a custom selection function in func. func is called when
the mouse button is clicked on the widget; func returns a pointer to
another widget, whose action function is called instead of the custom
widget's action function. If pfuWidgetDrawFunc is called to set a custom
draw function, that function will be called instead of the built-in draw
function when that widget needs to be redrawn. pfuGetWidgetDrawFunc and
pfuGetWidgetSelectFunc will return the custom draw and selection callback
functions, respectively.
pfuWidgetSelections sets the selection choices for the widget w, which
must be of type PFUGUI_RADIO_BUTTON or PFUGUI_MENU_BUTTON. val contains
a list of the values assigned to each of the selections; if val is NULL,
then the selection value will be set to the ordinal index of the
selection. funcList contains a list of action functions corresponding to
each selection; if funcList is NULL, then the widget's default action
function will be used for all of the selections. Use pfuWidgetSelection
to set the current selection. Use pfuGetWidgetSelection to retrieve the
selection last chosen or set. Use pfuWidgetDefaultSelection to set the
selection which will be set when the widget (or the panel that contains
it) is reset.
pfuWidgetOnOff changes various fields of w depending on whether on is 0
or 1. These changes essentially correspond to setting the widget off or
on. Exactly how w is changed depends on its type as follows.
PFUGUI_SWITCH
If on is 0, w's value is set to its minimum. Otherwise, it is
set to the maximum possible value.
PFUGUI_BUTTON
If on is 1, w's value is set to 1 and w is highlighted. If on
is 0, w's value is set to 0 and w is restored to its normal,
unhighlighted state.
PFUGUI_RADIO_BUTTON
If on is 1, w is set on; otherwise it is set off.
pfuWidgetDefaultOnOff works essentially like pfuWidgetOnOff. If w is of
type PFUGUI_SWITCH, w's default value is modified. If w is of type
PFUGUI_RADIO_BUTTON, w's default on value is modified.
Page 6
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
pfuIsWidgetOn returns the status of w - whether it is on or off.
pfuHideWidget marks widget w to not be displayed in the GUI.
pfuUnhideWidget restores widget w for display.
pfuWidgetMode sets the specified mode to the given val. Currently only
the boolean mode PFUGUI_STICKY_DEFAULT is supported for sliders.
pfuGetWidgetMode returns the value for the specified mode.
pfuResetWidget resets w to its default values and calls w's action
function if that function has been set.
pfuDrawMessage draws the message msg justified with respect to (x, y) in
a font of size size. x and y must range between 0 and 1 and size should
take the value PFU_FONT_SMALL, PFU_FONT_MED, or PFU_FONT_BIG. just
specifies the justification and can take the value PFU_CENTER_JUSTIFIED,
PFU_LEFT_JUSTIFIED or PFU_RIGHT_JUSTIFIED. Set cimode to PFU_CI to use
color-indexing mode or PFU_RGB to use direct color mode. rel controls
whether x and y are specified as absolute values or relative to chan's
origin.
pfuDrawMessageCI works just like pfuDrawMessage except that cimode is set
to PFU_CI. The color indices are specified in textClr and shadowClr.
pfuDrawMessageRGB also works just like pfuDrawMessage except that cimode
is set to PFU_RGB. The RGB color values are specified in textClr and
shadowClr.
pfuDrawTree draws each node of the subtree of the scene graph rooted at
tree inside the view frustum defined by chan.
The following functions are not normally called by user applications but
are used by the GUI module to manipulate its internal state and are
provided here for completeness.
pfuInitGUICursors initializes the cursors used by the GUI module.
pfuGetGUICursor and pfuGUICursor are used to get and set cursor
definitions, respectively. pfuGetGUICursorSel and pfuGUICursorSel are
used to get and set the current cursor, respectively. pfuUpdateGUICursor
is called to load the current cursor bitmap into the display window.
pfuGUIHlight and pfuGetGUIHlight are used to get and set the pfHighlight
definition used to highlight selected geometry.
NOTES
pfuInit should be called before pfConfig to initialize the libpfutil
library and C++ classes for multiprocessed access.
Additionally, the GUI relies on receiving mouse information via
pfuGetMouse. This input can be collected automatically via input
Page 7
pfuGUI(3pf) OpenGL Performer 3.2.2 libpfutil Reference Pages pfuGUI(3pf)
handling utilities in libpfutil. See the pfuInitInput man pages.
These functions use pfDataPools to store multiply accessed data so as to
work well in multiprocessing applications. See
"/usr/share/Performer/src/lib/libpfutil/gui.c" for further details.
Sample source code programs using the GUI utilities include
"/usr/share/Performer/src/pguide/libpf/C/detail.c" and the perfly sample
application.
The libpfutil source code, object code and documentation are provided as
unsupported software. Routines are subject to change in future releases.
SEE ALSO
pfDataPool, pfuXFont, pfuCursor, pfuInitInput, pfuInit, pfuGetMouse
Page 8
