GLwDrawingArea, GLwMDrawingArea - Open GL drawing widgets.
SYNOPSIS
#include <GL/GLwDrawA.h>
widget = XtCreateWidget(widget, glwDrawingAreaWidgetClass, ...);
ld ... -lGLw -l<anywidgetlibrary> -lXt -lGL -lX11 ...
#include <GL/GLwMDrawA.h>
widget = XtCreateWidget(widget, glwMDrawingAreaWidgetClass, ...);
ld ... -lGLw -lXm -lXt -lGL -lX11 ...
DESCRIPTION
GLwDrawingArea and GLwMDrawingArea are widgets suitable
for Open GL drawing. They provide a window with the
appropriate visual and colormaps needed for open GL, based
on supplied parameters. GLwDrawingArea and
GLwMDrawingArea also provide callbacks for redraw, resize,
input, and initialization.
GLwDrawingArea is not a part of any widget set, but
depends only on Xt. GLwDrawingArea can be used with any
widget set. GLwMDrawingArea is identical to
GLwDrawingArea except that it is a subclass of the Motif
widget class XmPrimitive and has resources and defaults
suitable for use with Motif. For example, GLwMDrawingArea
provides the default Motif background and foreground
colors for resources, and deals better with keyboard
traversal. Although the GLwDrawingArea widget can be used
in a Motif program, it is recommended that GLwMDrawingArea
be used instead.
Since both GLwDrawingArea and GLwMDrawingArea widgets
behave almost identically, the remainder of this manual
page will refer only to GLwDrawingArea, except when the
behaviors differ. Unless explicitly stated, all
statements about GLwDrawingArea also apply to
GLwMDrawingArea.
Among the information provided when creating a
GLwDrawingArea is information necessary to determine the
visual. This may be provided in three ways, all of them
through resources. A specific visualInfo structure may be
passed in. (This visualInfo must have been obtained
elsewhere; it is the application designer's responsibility
to make sure that it is compatible with the open GL
rendering done by the application). Alternatively, an
attribute list may be provided. This attribute list is
formatted identically to that used for direct open GL
programming. Finally, each attribute can be specified as
an individual resource. The latter method is the simplest,
and is the only method that works from resource files.
will also allocate the colormap unless one is provided by
the application. (If one is provided it is the
application writer's responsibility to guarantee
compatibility between the colormap and the visual). If an
application creates multiple GLwDrawingAreas are created
in the same visual, the same colormap will be used.
(However the colormap will not be shared among separate
applications).
Creating the widget does not actually create the window
until it is realized, and consequently, the application
should not perform any open GL operations 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 open GL
initialization for the window, and can subsequently
perform other operations on it. The initialization is
discussed in more detail below.
Applications select which GLwDrawingArea they are
accessing using either glXMakeCurrent or the convenience
function GLwDrawingAreaMakeCurrent which uses a widget
instead of a display and window. If there is only one
GLwDrawingArea this need only be called once, however if
there is more than one GLwDrawingArea it should be called
at the start of 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.
If an application is using double buffering, it may call
GLwDrawingAreaSwapBuffers instead of glXSwapBuffers. This
allows the use of the widget instead of the display and
window.
GLwDrawingArea Classes
GLwDrawingArea inherits behavior and resources from the
Core class. The class pointer is GLwDrawingAreaClass.
The class name is GLwDrawingArea.
GLwMDrawingArea Classes
GLwMDrawingArea inherits behavior and resources from the
XmPrimitive and Core classes. The class pointer is
GLwMDrawingAreaClass. The class name is GLwMDrawingArea.
New Resources
The following tables define a set of widget resources used
by the programmer to specify data. The programmer can
set attributes for this widget. To reference a resource
by name or by class in a .Xdefaults file, remove the GLwN
or GLwC prefix and use the remaining letters. There are
two tables included. The first table includes resources
that correspond directly to the attributes used by
glXChooseVisual. As with glXChooseVisual, all Boolean
resources default to FALSE and all integer resources
default to 0. These resources can all be set only at
creation time, and are used to determine the visual. If
either the GLwNattribList or GLwNvisualInfo resource is
set, these resources are ignored. The specific meaning of
these resources is discussed in the glXChooseVisual manual
page and will not be discussed here.
| | | | |
| Name | Class | Type | OpenGL attribute |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNbufferSize | GLwCBufferSize | int | GLX_BUFFER_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNlevel | GLwCLevel | int | GLX_LEVEL |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNrgba | GLwCRgba | Boolean | GLX_RGBA |
|____________________|____________________|_________|______________________|
| | | | |
| GLwdoublebuffer | GLwCDoublebuffer | Boolean | GLX_DOUBLEBUFFER |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNstereo | GLwCStereo | Boolean | GLX_STEREO |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNauxBuffers | GLwCAuxBuffers | Boolean | GLX_AUX_BUFFERS |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNredSize | GLwCColorSize | int | GLX_RED_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNgreenSize | GLwCColorSize | int | GLX_GREEN_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNblueSize | GLwCColorSize | int | GLX_BLUE_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNalphaSize | GLwCAlphaSize | int | GLX_ALPHA_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNDepthSize | GLwCDepthSize | int | GLX_DEPTH_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNStencilSize | GLwCStencilSize | int | GLX_STENCIL_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNaccumRedSize | GLwCAccumColorSize | int | GLX_ACCUM_RED_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNaccumGreenSize | GLwCAccumColorSize | int | GLX_ACCUM_GREEN_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNaccumBlueSize | GLwCAccumColorSize | int | GLX_ACCUM_BLUE_SIZE |
|____________________|____________________|_________|______________________|
| | | | |
| GLwNaccumAlphaSize | GLwCAccumAlphaSize | int | GLX_ACCUM_ALPHA_SIZE |
|____________________|____________________|_________|______________________|
The following table lists other resources of the
subsequently 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 |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNallocateBackground | GLwCAllocateColors | Boolean | FALSE | CG |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNallocateOtherColors | GLwCAllocateColors | Boolean | FALSE | CG |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNattribList | GLwCAttribList | int * | NULL | CG |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNexposeCallback | GLwCCallback | XtCallbackList | NULL | C |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNginitCallback | GLwCCallback | XtCallbackList | NULL | C |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNinputCallback | GLwCCallback | XtCallbackList | NULL | C |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNinstallBackground | GLwCInstallBackground | Boolean | TRUE | CG |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNinstallColormap | GLwCInstallColormap | Boolean | TRUE | CG |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNresizeCallback | GLwCCallback | XtCallbackList | NULL | C |
|_________________________|_______________________|________________|_________|________|
| | | | | |
| GLwNvisualInfo | GLwCVisualInfo | XVisualInfo* | NULL | CG |
|_________________________|_______________________|________________|_________|________|
GLwNallocateBackground
[Caveat: This resource is not honored yet.]
If TRUE, the background pixel and pixmap will be
allocated if appropriate using the newly calculated
colormap and visual. If FALSE, they will retain
values calculated using the parent's colormap and
visual. Applications which wish to have X clear their
background for them will usually set this to TRUE.
Applications clearing their own background will often
set this to FALSE, although they may set this to TRUE
if they query the background for their own use. One
index mode is in use this avoid using up a pixel from
the newly allocated colormap. Also, on hardware that
supports only one colormap, the application may need
to do more careful color allocation to avoid flashing
between the openGL colormap and the default X
colormap. (Note that because of the way Xt works, the
background colors are originally calculated using the
default colormap; if this resource is set they can be
recalculated correctly. If a colormap was explicitly
supplied to the widget rather than being dynamically
calculated, these resources are always calculated
using that colormap.)
GLwNallocateOtherColors
[Caveat: This resource is not honored yet.]
This is similar to GLwNallocateBackground, but
allocates other colors normally allocated by widgets.
Although the GLwDrawingArea and GLwMDrawingArea widget
do not make use of these colors the application may
choose to query them. For the non-Motif
GLwDrawingArea widget there are no other colors
allocated, so this resource is a no-op. For the Motif
GLwMDrawingArea are widget, the XmPrimitive resources
XmNforeground, XmNhighlightColor, and
XmNhighlightPixmap are calculated.
GLwNattribList
Contains the list of attributes suitable for a call to
glXChooseVisual. If this resource is NULL, it is
calculated based on the attribute resources. If it is
not NULL, the attribute resources are ignored.
GLwNexposeCallback
Specifies the list of callbacks that is called when
the widget receives an exposure event. The callback
reason is GLwCR_EXPOSE. The callback structure also
includes the exposure event. The application will
generally want to redraw the scene.
GLwNginitCallback
Specifies the list of callbacks that is called when
the widget is first realized. Since no open GL
operations can be done before the widget is realized,
this callback can be used to perform any appropriate
open GL initialization such as creating a context.
The callback reason is GLwCR_GINIT.
GLwNinputCallback
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
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 GLwCR_INPUT.
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.
GLwNinstallBackground
[Caveat: This resource is not honored yet.]
If set to TRUE, the background is installed on the
window. If set to FALSE, the window has no background.
This resource has no effect unless
GLwNallocateBackground is also TRUE.
GLwNinstallColormap
If set to TRUE, the widget will call
XSetWMColormapWindows to tell the window manager to
install the colormap when the window's shell has
focus. If set to FALSE, this will not be called. For
applications with multiple GLwDrawingAreas sharing a
single colormap, it is most efficient to set this
resource to TRUE for exactly one GLwDrawingArea with
each colormap. If an application needs additional
control over the order of colormaps, this resource can
be set to FALSE, with the application calling
XSetWMColormapWindows explicitly.
GLwNresizeCallback
Specifies the list of callbacks that is called when
the GLwDrawingArea is resized. The callback reason is
GLwCR_RESIZE.
GLwNvisualInfo
Contains a pointer to the window's visual info
structure. If NULL, the visualInfo is calculated at
widget creation time based on the GLwNattributeList
resource (which is itself calculated from the various
resources). If GLwNvisualInfo is not NULL the
GLwNattributList and the attribute resources are
ignored.
Inherited Resources
[Caveat: The colormap and background resources do not
receive special treatment yet.]
and resources from the core superclass. Other than the
behavior of the colormap and background resources
described previously, all defaults are the same as for
core.
In addition, the Motif version GLwMDrawingArea also
inherits from XmPrimitive. The behavior of the color
resources has been described previously. The TraversalOn
resource is disabled for this widget, but if keyboard
input is required it should be enabled. (Also, the
application should call XmProcessTraversal(widget,
XmTRAVERSE_CURRENT) whenever mouse button 1 is clicked in
the widget. This is similar to the requirements of the
Motif Drawing area.) Because Motif gets confused by having
multiple visuals in one top level shell,
XmNhighlightOnEnter has been disabled, and
XmNhighlightThickness has been set to 0.
Callback Information
A pointer to the following structure is passed to each
callback:
typedef struct
{
int reason;
XEvent * event;
Dimensionwidth, height;
} GLwDrawingAreaCallbackStruct;
reason
Indicates why the callback was invoked. Appropriate
values are stated in the above resource descriptions.
For Motif programmers, the values GLwCR_EXPOSE,
GLwCR_RESIZE, and GLwCR_INPUT are equal to
XmCR_EXPOSE, XmCR_RESIZE, and XmCR_INPUT respectively.
GLwCR_GINIT does not have a Motif equivalent.
event
Points to the XEvent that triggered the callback.
This is NULL for GLwNginitCallback and
GLwNresizeCallback.
width
height
Are set to the width and height of the window.
Translations
GLwDrawingArea has the translations listed below.
<KeyUp>: glwInput()
<BtnDown>: glwInput()
<BtnUp>: glwInput()
<BtnMotion>: glwInput()
GLwMDrawingArea 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 GLwDrawingArea has the following action routine:
glwInput()
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, glXchooseVisual 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 open GL operations can be done to the window
No resize callbacks are generated.
The normal window is available (XtWindow returns
NULL).
GLwDrawingAreaMakeCurrent (and glXMakeCurrent) should
not be called.
When the widget is realized, the following actions take
place:
The window is created.
The ginit callback is called. The user may use this
callback to perform any needed open GL initialization
to the window.
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.
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 GLwMDrawingArea widget
with the Motif style GLwCreateMDrawingArea.
EXAMPLE
Here are some code fragments that create a
GLwDrawingArea widget, and manage the appropriate
callbacks.
#include <X11/GLW/GLwDrawingArea.h>
static GLXContext glx_context; /* assume only one context */
. . .
main()
{
Arg args[10];
int n;
Widget parent;/* The parent of the gl widget */
Widget glw;/* The GLwDrawingArea widget */
. . .
/* Create the widget using RGB mode. This can also be set
* in an X Defaults file
*/
n = 0;
XtSetArg(args[n], GLwNrgba, TRUE); n++;
glw = XtCreateManagedWidget("glw", GLwDrawingAreaWidgetClass,
parent, args, n);
XtAddCallback(glw, GLwNexposeCallback, exposeCB, 0);
XtAddCallback(glw, GLwNresizeCallback, resizeCB, 0);
XtAddCallback(glw, GLwNginitCallback, ginitCB, 0);
/* Also add input callback if needed */
. . .
}
exposeCB(Widget w, XtPointer client_data,
GLwDrawingAreaCallbackStruct call_data)
{
GLwDrawingAreaMakeCurrent (w, glx_context);
/* redraw the display */
}
static void
resizeCB(Widget w, XtPointer client_data,
GLwDrawingAreaCallbackStruct call_data)
{
GLwDrawingAreaMakeCurrent (w, glx_context);
/* perform any resize actions */
}
static void
ginitCB(Widget w, XtPointer client_data,
GLwDrawingAreaCallbackStruct call_data)
{
Arg args[1];
XVisualInfo *vi;
XtSetArg(args[0], GLwNvisualInfo, &vi);
XtGetValues(w, args, 1);
/* create a visual context */
glx_context = glXCreateContext(XtDisplay(w), vi, 0, GL_FALSE);
GLwDrawingAreaMakeCurrent (w, glx_context);
/* Perform any necessary graphics initialization.*/
}
The Motif program need only differ by including
GLwMDrawingArea.h instead of GLwDrawingArea.h and by
creating a widget of type GLwMDrawingAreaWidgetClass
instead of GLwDrawingAreaWidgetClass. As an alternative,
the Motif program could use GLwCreateMDraw(3X) instead.
WARNINGS
If a GLwDrawingArea widget is created as a child of an
already realized widget, the GLwDrawingArea 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 GLwDrawingArea widget is used in a Motif
program and keyboard traversal is attempted, the behavior
is undefined if the user traverses into the GLwDrawingArea
widget.
RELATED INFORMATION
the glXChooseVisual manpage, the GLwDrawingAreaMakeCurrent
manpage, the glXMakeCurrent manpage, the
manpage, the Core manpage, the XmPrimitive manpage, the
VirtualBindings manpage, the Gflush manpage), the
XSetWMColormapWindows manpage and the Open GL spec.
DATE
$Id: GLwDrawingArea.3x,v 1.1.1.1 1999/08/19 00:55:42 jtg
Exp $
Man(1) output converted with
man2html