GlxDraw(3X)GlxDraw(3X)NAME
GlxDraw, GlxMDraw — GL drawing widgets.
SYNOPSIS
#include <Sgm/GlxDraw.h>
widget = XtCreateWidget(widget, glxDrawWidgetClass, ...);
ld ... -lSgm -l<anywidgetlibrary> -lXt -lgl -lX11 ...
#include <Sgm/GlxMDraw.h>
widget = XtCreateWidget(widget, glxMDrawWidgetClass, ...);
ld ... -lSgm -lXm -lXt -lgl -lX11 ...
VERSION
This page documents the version of Sgm that accompanies Motif 1.2.
DESCRIPTION
GlxDraw and GlxMDraw are widgets suitable for GL drawing. They provide
a window with the appropriate visual and colormaps needed for GL, based
on supplied parameters. GlxDraw and GlxMdraw also provides callbacks
for redraw, resize, input, and initialization.
GlxDraw is not a part of any widget set, but depends only on Xt. Glx‐
Draw can be used with any widget set. GlxMDraw is identical to GlxDraw
except that it is a subclass of the Motif widget class XmPrimitive and
has resources and defaults suitable for use with Motif. For example,
GlxMDraw provides the default Motif background and foreground colors
for resources, and deals better with keyboard traversal. Although the
GlxDraw widget can be used in a Motif program, it is recommended that
GlxMDraw be used instead.
Since both GlxDraw and GlxMDraw widgets behave almost identically, the
remainder of this manual page will refer only to GlxDraw, except when
the behaviors differ. Unless explicitly stated, all statements about
GlxDraw also apply to GlxMDraw.
To create a GlxDraw, the application must first set up a GLXconfig
structure as described in GLXgetconfig(3G). The GLXconfig structure
describes the desired GL configuration of the window being created,
including information such as single or double buffering, RGB vs.
color index mode, use of the overlay planes, etc. The GLXconfig param‐
eter must be passed in as the glxConfig resource when creating the wid‐
get. When created, the widget will automatically choose the appropri‐
ate visual and colormap, as well as returning the in the glxConfig
resource the actual GL configuration chosen.
Creating the widget does not actually create the window until it is
realized, and consequently, the application should not perform any GL
to the window immediately after creation. Instead the application must
wait until after it has realized the window. Alternatively, the ginit
callback may be used to indicate when the window has been created.
Upon receiving this callback, the application can perform all GL ini‐
tialization for the window, and can subsequently perform other GL oper‐
ations on it. The initialization is discussed in more detail below.
The widget will create additional windows for overlays, underlays, or
popup planes if required, and if underlying support is available. The
remainder of this manual page will use the term auxiliary windows to
refer to these additional windows. The main window in the normal
planes will be referred to as the normal window.
If an application contains more than one GL window, it must use the
GLXwinset(3G) call before doing any GL operations to a window. This
will select the appropriate window for the operation. There are two
common situations where there is more than one GL window. One is where
more than on GlxDraw widget is used in a program. The other is where
auxiliary windows are used.
Normally, the call to GLXwinset would be the first function called in
each callback. Callbacks in this case include not only callbacks pro‐
vided by the widget itself, but any other callback that leads to GL
activity such as a timeout or a workproc. The call to GLXwinset should
be of the form
GLXwinset(display, call_data->window);
Using the window passed in the call_data has two purposes over using
XtWindow(3X) to obtain the window. First, it is more efficient, since
it avoids the function call. Second, if auxiliary windows are used, it
obtains the correct window if this is an expose callback. For other
callbacks it may be necessary to use XtGetValues(3X) to obtain the val‐
ues of GlxNoverlayWindow, GlxNunderlayWindow, or GlxNpopupWindow to
determine the proper parameter to GLXwinset when using auxiliary win‐
dows.
GlxDraw Classes
GlxDraw inherits behavior and resources from the Core class.
The class pointer is glxDrawClass.
The class name is GlxDraw.
GlxMDraw Classes
GlxMDraw inherits behavior and resources from the XmPrimitive and Core
classes.
The class pointer is glxMDrawClass.
The class name is GlxMDraw.
New Resources
The following table defines a set of widget resources used by the pro‐
grammer to specify data. The programmer can also set the resource val‐
ues for the inherited classes to set attributes for this widget. To
reference a resource by name or by class in a .Xdefaults file, remove
the GlxN or GlxC prefix and use the remaining letters. The codes in
the access column indicate if the given resource can be set at creation
time (C), set by using XtSetValues (S), retrieved by using XtGetValues
(G), or is not applicable (N/A).
Name Class Type Default Access
────────────────────────────────────────────────────────────────────────────────────────
GlxNexposeCallback GlxCCallback XtCallbackList NULL C
GlxNginitCallback GlxCCallback XtCallbackList NULL C
GlxNglxConfig GlxCGlxConfig GLXconfig* {{0,0,0}} CG
GlxNinputCallback GlxCCallback XtCallbackList NULL C
GlxNoverlayColormap GlxCColormap Colormap dynamic CG
GlxNoverlayDepth GlxCDepth int dynamic G
GlxNoverlayExposeCallback GlxCCallback XtCallbackList NULL C
GlxNoverlayVisual GlxCVisual XVisualInfo* dynamic G
GlxNoverlayWindow GlxCWindow Window dynamic G
GlxNresizeCallback GlxCCallback XtCallbackList NULL C
GlxNoverrideColormap GlxCOverrideColormap Boolean TRUE CG
GlxNpopupColormap GlxCColormap Colormap dynamic CG
GlxNpopupDepth GlxCDepth int dynamic G
GlxNpopupExposeCallback GlxCCallback XtCallbackList NULL C
GlxNpopupVisual GlxCVisual XVisualInfo* dynamic G
GlxNpopupWindow GlxCWindow Window dynamic G
GlxNunderlayColormap GlxCColormap Colormap dynamic CG
GlxNunderlayExposeCallback GlxCCallback XtCallbackList NULL C
GlxNunderlayDepth GlxCDepth int dynamic G
GlxNunderlayVisual GlxCVisual XVisualInfo* dynamic G
GlxNunderlayWindow GlxCWindow Window dynamic G
GlxNuseOverlay GlxCUseOverlay Boolean FALSE CG
GlxNusePopup GlxCUsePopup Boolean FALSE CG
GlxNuseUnderlay GlxCUseUndrlay Boolean FALSE CG
GlxNvisual GlxCVisual XVisualInfo* Dynamic G
GlxNexposeCallback
Specifies the list of callbacks that is called when the widget
receives an exposure event. The callback reason is
GlxCR_EXPOSE. The callback structure also includes the exposure
event. The application will generally want to redraw the scene.
GlxNginitCallback
Specifies the list of callbacks that is called when the widget
is first realized. Since no GL operations can be done before
the widget is realized, this callback can be used to perform any
appropriate GL initialization. The callback reason is
GlxCR_GINIT.
GlxNglxConfig
On widget creation, specifies the GL configuration information
that is to be passed to GLXgetconfig(3G). The default is an
empty configuration structure, providing the same default as
GLXgetconfig After the widget is created, the actual configura‐
tion chosen can be obtained by doing an XtGetValues(3Xt) on this
resource. The passed in configuration structure may be freed
after the widget is created.
GlxNinputCallback
Specifies the list of callbacks that is called when the widget
receives a keyboard or mouse event. By default, the input call‐
back is called on each key press and key release, on each mouse
button press and release, and whenever the mouse is moved while
a button is pressed. However this can be changed by providing a
different translation table. The callback structure also
includes the input event. The callback reason is GlxCR_INPUT.
The input callback is provided as a programming convenience, as
it provides a convenient way to catch all input events. How‐
ever, a more modular program can often be obtained by providing
specific actions and translations in the application rather than
using a single catch all callback. Use of explicit translations
can also provide for more customizability.
GlxNoverlayColormap
Specifies the colormap to use in the overlay planes. It is only
meaningful if overlay planes were selected in the configuration.
If the colormap is not provided when the widget is created, the
colormap returned by GLXgetconfig(3X) will be used. If a col‐
ormap is provided, it is the application programmer's responsi‐
ble for guaranteeing that the colormap is compatible with the
depths of the overlay planes. Note that unlike the normal win‐
dow, it is not necessary to specify an additional resource stat‐
ing whether the colormap should be used; it will always be used
if provided.
GlxNoverlayDepth
Returns the depth of the overlay. It is only meaningful if the
overlays are in use.
GlxNoverlayExposeCallback
Specifies the list of callbacks that is called when the overlay
receives an exposure event. The callback reason is
GlxCR_EXPOSE. The callback structure also includes the exposure
event. The application will generally want to redraw the over‐
lay.
GlxNoverlayVisual
Returns the visual for the overlay. It is only meaningful if
the overlays are in use.
GlxNoverlayWindow
Returns the window that is used for the overlay. It is only
meaningful if the overlays are in use.
GlxNoverrideColormap
If TRUE, specifies that the colormap returned by GLXgetconfig
should be installed by the widget. In this case, the XtNcol‐
ormap Core resource will be overridden when the widget is cre‐
ated. After creating the widget, the XtNcolormap resource is
set to the new colormap. This is the default case. If
GlxNoverrideColormap is FALSE, the colormap specified in the
XtNcolormap Core resource will be used. When setting this
resource to FALSE, the programmer is responsible for making sure
that the colormap is consistent with the request parameters to
GLXgetconfig such as the depth. Specifying an inconsistent col‐
ormap will result in an X Bad Match error. This resource only
has an effect if set at widget creation time.
GlxNpopupColormap
Similar to GlxNoverlayColormap, but for the popup planes.
GlxNpopupDepth
Similar to GlxNoverlayDepth, but for the popup planes.
GlxNpopupExposeCallback
Similar to GlxNoverlayCallback, but for the popup planes.
GlxNpopupVisual
Similar to GlxNoverlayVisual, but for the popup planes.
GlxNpopupWindow
Similar to GlxNoverlayWindow, but for the popup planes.
GlxNresizeCallback
Specifies the list of callbacks that is called when the GlxDraw
is resized. The callback reason is GlxCR_RESIZE. The applica‐
tion may wish to call viewport(3G) using the supplied width and
height parameters, and then redraw the scene.
GlxNunderlayColormap
Similar to GlxNoverlayColormap, but for the underlay planes.
Note that underlay support is not currently provided in GLX.
GlxNunderlayDepth
Similar to GlxNoverlayDepth, but for the underlay planes. Note
that underlay support is not currently provided in GLX.
GlxNunderlayExposeCallback
Similar to GlxNoverlayCallback, but for the underlay planes.
Note that underlay support is not currently provided in GLX.
GlxNunderlayVisual
Similar to GlxNoverlayVisual, but for the underlay planes. Note
that underlay support is not currently provided in GLX.
GlxNunderlayWindow
Similar to GlxNoverlayWindow, but for the underlay planes. Note
that underlay support is not currently provided in GLX.
GlxNuseOverlay
To use the overlays this must be set to TRUE when creating the
widget.
GlxNusePopup
To use the popup planes this must be set to TRUE when creating
the widget.
GlxNuseUnderlay
To use the underlays this must be set to TRUE when creating the
widget. Note that underlay support is not currently provided in
GLX.
GlxNvisual
Specifies the normal window's visual. It is always computed
when the widget is created, and cannot be specified by the
application.
Inherited Resources
Both GlxDraw and GlxMDraw inherit behavior and resources from the core
superclass. For a complete description of each resource, refer to the
man page for that superclass. Motif programmers may use Xm prefixes
instead of Xt prefixes where appropriate.
Name Class Type Default Access
──────────────────────────────────────────────────────────────────────────────────────────────────────────────
XtNaccelerators XtCAccelerators XtAccelerators dynamic CSG
XtNancestorSensitive XtCSensitive Boolean dynamic G
XtNbackground XtCBackground Pixel dynamic CSG
XtNbackgroundPixmap XtCPixmap Pixmap unspecified CSG
XtNborderColor XtCBorderColor Pixel XtDefaultForeground CSG
XtNborderPixmap XtCPixmap Pixmap unspecified CSG
XtNborderWidth XtCBorderWidth Dimension 0 CSG
XtNcolormap XtCColormap Colormap dynamic CG
XtNdepth XtCDepth int dynamic G
XtNdestroyCallback XtCCallback XtCallbackList NULL C
XtNheight XtCHeight Dimension dynamic CSG
XtNinitialResourcesPersistent XtCInitialResourcesPersistent Boolean True C
XtNmappedWhenManaged XtCMappedWhenManaged Boolean True CSG
XtNscreen XtCScreen Screen * dynamic CG
XtNsensitive XtCSensitive Boolean True CSG
XtNtranslations XtCTranslations XtTranslations dynamic CSG
XtNwidth XtCWidth Dimension dynamic CSG
XtNx XtCPosition Position 0 CSG
XtNy XtCPosition Position 0 CSG
A few of the resources above behave somewhat differently in the GL wid‐
get. XtNdepth is calculated when the visual is created; the depth can‐
not be specified explicitly except indirectly through the GlxNglxConfig
resource. If GlxNoverrideColormap is TRUE, than the default for GlxN‐
colormap is to calculate it dynamically based on the GlxNglxConfig
parameter.
In addition, the Motif version GlxMDraw also inherits from XmPrimitive.
Name Class Type Default Access
─────────────────────────────────────────────────────────────────────────────────────────────────
XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG
XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
XmNforeground XmCForeground Pixel dynamic CSG
XmNhelpCallback XmCCallback XtCallbackList NULL C
XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
XmNhighlightThickness XmCHighlightThickness Dimension 0 G
XmNnavigationType XmCNavigationType XmNavigationType XmNONE G
XmNshadowThickness XmCShadowThickness Dimension 0 G
XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
XmNtraversalOn XmCTraversalOn Boolean False CSG
XmNunitType XmCUnitType unsigned char dynamic CSG
XmNuserData XmCUserData Pointer NULL CSG
The resources XmNhighlightThickness and XmNshadowThickness are unsup‐
ported and may not be changed.
Callback Information
A pointer to the following structure is passed to each callback:
typedef struct
{
int reason;
XEvent * event;
Window window;
int buffer;
Dimensionwidth, height;
} GlxDrawCallbackStruct;
reason Indicates why the callback was invoked. Appropriate values are
stated in the above resource descriptions. For Motif program‐
mers, the values GlxCR_EXPOSE, GlxCR_RESIZE, and GlxCR_INPUT are
equal to XmCR_EXPOSE, XmCR_RESIZE, and XmCR_INPUT respectively.
GlxCR_GINIT does not have a Motif equivalent.
event Points to the XEvent that triggered the callback. This is NULL
for GlxNginitCallback and GlxNresizeCallback.
window Is set to the appropriate window. Generally, this is the normal
window. However, for the auxiliary expose callbacks, this is
the appropriate auxiliary window.
buffer Is the buffer type of window (as described in GLXgetconfig(3G)).
It is one of GLX_NORMAL, GLX_OVERLAY, GLX_UNDERLAY, and
GLX_POPUP.
width and height
Are set to the width and height of the window.
Translations
GlxDraw has the translations listed below.
<KeyDown>: glxInput()
<KeyUp>: glxInput()
<BtnDown>: glxInput()
<BtnUp>: glxInput()
<BtnMotion>: glxInput()GlxMDraw has the following additional translation:
<Key>osfHelp: PrimitiveHelp()
An application wishing to catch other events than these defaults can do
so by installing a different translation table.
Action Routines
The GlxDraw has the following action routine:
glxInput():
Called whenever one of the above translations specifies that
input has occurred. Its sole purpose is to call the input call‐
back.
INITIALIZATION
When the widget is initially created (e.g. through XtCreateWidget(3X))
the associated window is not actually created. Instead, window cre‐
ation is delayed until the widget is realized. However, GLXgetcon‐
fig(3G) is called immediately, so information based on its results is
available.
Between the time the widget is created and it is realized, the follow‐
ing apply:
· No GL operations can be done to the window
· No resize callbacks are generated.
· Neither the normal window nor the auxiliary windows are avail‐
able.
When the widget is realized, the following actions take place:
· The normal window and any auxiliary windows are created.
· GLXlink(3G) is called. An application using the GlxDraw widget
should never need to call GLXlink(3G). (Similarly it should
never need to call GLXunlink(3G) as that is called when the wid‐
get is destroyed.)
· GLXwinset(3G) is called on the normal window. If an application
has only one GL window, it need never call GLXwinset(3G).
· The ginit callback is called. The user may use this callback to
perform any needed GL initialization to the window.
The GlxDraw widget will generally use a different colormap than the X
based portion of the application. The colormap may need to be
installed using XSetWMColormapWindows(3X11). (Auxiliary windows will
also need their colormaps installed, as describe in the next section.)
OVERLAYS, UNDERLAYS, and POPUP PLANES
To include auxiliary windows, the following steps must be taken:
· Verify that there is support for the appropriate type of auxil‐
iary window. Not all hardware supports overlays. Currently,
the underlying GLX does not support underlays.
· Set the GlxNuseOverlay, GlxNuseUnderlay, or GlxNusePopup
resources as appropriate to TRUE.
· Set the appropriate entries in the GlxNconfig parameter as
described in GLXgetconfig(3G).
· Create the widget as normal.
· Make sure that the auxiliary colormap is installed along with
the GlxDraw colormap using XSetWMColormapWindows(3X11). (Note
that the call to XSetWMColormapWindows(3X11) will usually spec‐
ify three windows in this case: the overlay window, the GlxDraw
window, and the top level window.)
· Provide an expose callback routine for each auxiliary used, by
setting GlxNoverlayExposeCallback, GlxNunderlayExposeCallback,
or GlxNpopupExposeCallback.
· Before drawing to an auxiliary window, do a GLXwinset(3G) to
that window. The window ID can be obtained from the callback if
the drawing is in response to an expose, or by querying the
GlxNoverlayWindow, GlxNunderlayWindow or GlxNpopupWindow
resources.
NOTES
When using the input callback to receive keyboard input, the keycode in
the event must be converted to a KeySym. Use XLookupKeysym(3X) or
XLookupString(3X) to do the conversion. Keyboard input can also be
dealt using translations, in which case no such conversion is required.
GL programs will typically draw their backgrounds by using clear(3G),
gclear(3G), or some similar routine in a specified color. Thus, the
XtNbackground resource will have no direct effect. To get a matching
background in GL, first use XtGetValues on the XtNbackground resource
to find the background color and use that color explicitly. However,
be aware that the background pixel was set relative to the parent's
colormap, not the GlxDraw widget's colormap. Motif programs may also
choose to make use of the XtNforeground resource in a similar manner.
GL functions such as getsize(3G) and getorigin(3G) require round trips
to the server and are thus slow. It is quicker to use XtGetValues to
obtain the XtNx, XtNy, XtNheight, and XtNwidth values directly from the
widget.
To work properly over the network using the Distributed Graphics
Library (DGL), applications may need to call gflush(3G) after drawing
using GL. The end of each callback and action routine is a good place
to include the call. Alternatively, if there is a common drawing rou‐
tine used by all callbacks and actions, the gflush(3G) call may be
placed at the end of that routine.
Providing a user colormap is handled slightly differently for normal
and for auxiliary windows. For normal windows, the colormap is a stan‐
dard Core resource for which a default already exists. Consequently,
the default colormap will be overridden by the result of GLXgetcon‐
fig(3G) unless GlxNoverrideColormap resource is set to FALSE. For aux‐
iliary windows, there is no preexisting default colormap, so if a user
provided colormap is provided, it will always be used.
Motif programmers should keep in mind that OSF uses virtual bindings
and replaces some of the key bindings. As a common example, if the ESC
key is to be used to exit the program (as it often is in GL programs),
the translation should specify <key>osfCancel instead of <key>Escape.
Motif programmers may also create a GlxMDraw widget with the Motif
style GlxCreateMDraw(3X).
EXAMPLE
Here are some code fragments that create a GlxDraw widget, and manage
the appropriate callbacks.
#include <Sgm/GlxDraw.h>
. . .
/* The following configuration should match your hardware needs as */
/* Described in GLXgetconfig(3X) */
GLXconfig db_rgb_desc[] = {
{ GLX_NORMAL,GLX_RGB,TRUE },
{ GLX_NORMAL,GLX_DOUBLE,TRUE },
{ 0, 0, 0 }
};
main()
{
Arg args[10];
int n;
Widget parent;/* The parent of the gl widget */
Widget glw;/* The glxDraw widget */
. . .
n = 0;
XtSetArg(args[n], GlxNglxConfig, db_rgb_desc); n++;
glw = XtCreateManagedWidget("glx", glxDrawWidgetClass,
parent, args, n);
XtAddCallback(glw, GlxNexposeCallback, exposeCB, 0);
XtAddCallback(glw, GlxNresizeCallback, resizeCB, 0);
XtAddCallback(glw, GlxNginitCallback, ginitCB, 0);
/* Also add input callback if need be */
. . .
}
static void
exposeCB(w, client_data, call_data)
Widget w;
caddr_t client_data;
GlxDrawCallbackStruct *call_data;
{
GLXwinset(display, call_data->window);
/* redraw the display */
}
static void
resizeCB(w, client_data, call_data)
Widget w;
caddr_t client_data;
GlxDrawCallbackStruct *call_data;
{
GLXwinset(display, call_data->window);
viewport(0, (Screencoord) call_data->width-1,
0, (Screencoord) call_data->height-1);
/* redraw the display */
}
static void
ginitCB(w, client_data, call_data)
Widget w;
caddr_t client_data;
GlxDrawCallbackStruct *call_data;
{
GLXwinset(display, call_data->window);
/* Perform any necessary graphics initialization.*/
}
The Motif program need only differ by including GlxMDraw.h instead of
GlxDraw.h and by creating a widget of type GlxMDrawWidgetClass instead
of GlxDrawWidgetClass. As an alternative, the Motif program could use
GlxCreateMDraw(3X) instead.
WARNINGS
The GlxDraw should be used only for GL drawing. Using X drawing to a
GlxDraw is unsupported.
All color resources (e.g XtNbackground) specify pixels in the GlxDraw's
parent's colormap. Since GL does not directly make use of these
resources, this won't normally be a problem. However, if a program
wishes to query such a color (for example, to make a matching back‐
ground in the GlxDraw widget), it should use the parent's colormap.
Colormaps should be installed using XSetWMColormapWindows(3X11). This
requests that the window manager install the appropriate colormaps
every time the pointer enters the window. Colormaps should not be
installed with XInstallColormap(3X11).
If a GlxDraw widget is created as a child of an already realized wid‐
get, the GlxDraw widget will be created immediately, without giving the
user an opportunity to add the ginit callback. In such a case, ini‐
tialization should be done immediately after creating the widget rather
than by using the callback.
If the non-Motif GlxDraw widget is used in a Motif program and keyboard
traversal is attempted, the behavior is undefined if the user traverses
into the GlxDraw widget.
RELATED INFORMATIONGLXgetconfig(3G), GLXwinset(3G), GlxCreateMDraw(3X), Core(3X), XmPrimi‐
tive(3X), VirtualBindings(3X), Gflush(3G), XSetWMColormapWindows(3X11)
and the "IRIS NeWS to X Transition Guide"
GlxDraw(3X)
