GlxDraw(3X) UNIX System V 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. GlxDraw 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 parameter must be
passed in as the glxConfig resource when creating the
widget. When created, the widget will automatically choose
the appropriate visual and colormap, as well as returning
the in the glxConfig resource the actual GL configuration
chosen.
Page 1 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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 initialization for the window, and can subsequently
perform other GL operations 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 provided 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 values of
GlxNoverlayWindow, GlxNunderlayWindow, or GlxNpopupWindow to
determine the proper parameter to GLXwinset when using
auxiliary windows.
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.
Page 2 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
New Resources
The following table defines a set of widget resources used
by the programmer to specify data. The programmer can also
set the resource values 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 GlxCREXPOSE. 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
Page 3 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
initialization. The callback reason is GlxCRGINIT.
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 configuration 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 callback 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 GlxCRINPUT.
The input callback is provided as a programming
convenience, as it provides a convenient way to catch
all input events. However, 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 colormap is
provided, it is the application programmer's
responsible for guaranteeing that the colormap is
compatible with the depths of the overlay planes. Note
that unlike the normal window, it is not necessary to
specify an additional resource stating 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 GlxCREXPOSE. The callback structure also
Page 4 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
includes the exposure event. The application will
generally want to redraw the overlay.
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 XtNcolormap Core resource will be
overridden when the widget is created. 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 colormap
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
GlxCRRESIZE. The application may wish to call
viewport(3G) using the supplied width and height
parameters, and then redraw the scene.
GlxNunderlayColormap
Page 5 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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.
Page 6 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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 widget. XtNdepth is calculated when the visual is
created; the depth cannot be specified explicitly except
indirectly through the GlxNglxConfig resource. If
GlxNoverrideColormap is TRUE, than the default for
GlxNcolormap 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 unsupported and may not be changed.
Page 7 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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 programmers, the values GlxCREXPOSE,
GlxCRRESIZE, and GlxCRINPUT are equal to
XmCREXPOSE, XmCRRESIZE, and XmCRINPUT
respectively. GlxCRGINIT 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 GLXNORMAL,
GLXOVERLAY, GLXUNDERLAY, and GLXPOPUP.
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
Page 8 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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 callback.
INITIALIZATION
When the widget is initially created (e.g. through
XtCreateWidget(3X)) the associated window is not actually
created. Instead, window creation is delayed until the
widget is realized. However, GLXgetconfig(3G) is called
immediately, so information based on its results is
available.
Between the time the widget is created and it is realized,
the following apply:
⊕ No GL operations can be done to the window
⊕ No resize callbacks are generated.
⊕ Neither the normal window nor the auxiliary windows are
available.
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 widget 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
Page 9 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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 auxiliary 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 specify 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
Page 10 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
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 routine 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 standard Core resource for which a default
already exists. Consequently, the default colormap will be
overridden by the result of GLXgetconfig(3G) unless
GlxNoverrideColormap resource is set to FALSE. For
auxiliary 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 },
Page 11 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
{ 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);
Page 12 (printed 1/22/99)
GlxDraw(3X) UNIX System V GlxDraw(3X)
/* 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 background 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 widget, the GlxDraw widget will be created
immediately, without giving the user an opportunity to add
the ginit callback. In such a case, initialization 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 INFORMATION
GLXgetconfig(3G), GLXwinset(3G), GlxCreateMDraw(3X),
Core(3X), XmPrimitive(3X), VirtualBindings(3X), Gflush(3G),
XSetWMColormapWindows(3X11) and the "IRIS NeWS to X
Transition Guide"
Page 13 (printed 1/22/99)