xenocara/doc/gl-docs/GLw/glwdrawingarea.gl

.\" **
.\" **  (c) Copyright 1993, 1994, 1995, 1996 Silicon Graphics, Inc.
.\" **
.\" **  (c) Copyright 1989, 1990, 1991 Open Software Foundation, Inc.
.\" **      All Rights Reserved.
.\" **
.\" **  (c) Copyright 1987, 1988, 1989, by Hewlett-Packard Company
.\" **
.\" **  (c) Copyright 1987, 1988 by Digital Equipment Corporation,
.\" **      Maynard, MA.  All Rights Reserved.
.\" **
.\" **
.TH GLwDrawingArea 3X "" "" "" ""
.SH NAME
\fBGLwDrawingArea, GLwMDrawingArea \(em OpenGL drawing widgets.\fP
.iX "GLwDrawingArea" "GLwMDrawingArea"
.iX "widget class" "OpenGL" "Draw"
.sp 1
.SH SYNOPSIS
\fB#include <GL/GLwDrawA.h>
.br
\fBld ... -lGLw -lGL -l<anywidgetlibrary> -lXext -lXt -lX11 -lm
.sp
\fB#include <GL/GLwMDrawA.h>
.br
\fBld ... -lGLw -lGL -lXm -lXext -lXt -lX11 -lm
.sp 1
.SH DESCRIPTION
\fBGLwDrawingArea\fP and \fBGLwMDrawingArea\fP are widgets suitable
for OpenGL drawing.  They
provide a window with the appropriate visual and colormaps needed for
OpenGL, based on supplied parameters.  GLwDrawingArea and
GLwMDrawingArea also provide
callbacks for redraw, resize, input, and initialization.
.PP
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\(Tm 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.
.PP
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.
.PP
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 OpenGL 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.
.PP
In addition to allocating the visual, the GLwDrawingArea 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 with the same visual, 
the same colormap will be used.  (However the colormap
will not be shared among separate applications).
.PP
Creating the widget does not actually create the window until it is
realized, and consequently, the application should not perform any
OpenGL operations
to the window immediately after creation.  Instead the application
must wait until after it has realized the window.  Alternatively, the
\fBginit\fP callback may be used to indicate when the window has been
created.  Upon receiving this callback, the application can perform
all OpenGL initialization for the window, and can subsequently perform
other operations on it.  The initialization is discussed in more
detail below.
.PP
Applications select which GLwDrawingArea they are accessing using either
\fBglXMakeCurrent\fP or the convenience function
\fBGLwDrawingAreaMakeCurrent\fP 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.
.PP
If an application is using double buffering, it may call
\fBGLwDrawingAreaSwapBuffers\fP instead of \fBglXSwapBuffers\fP.  This
allows the use of the widget instead of the display and window.
.ne 5
.SS "GLwDrawingArea Classes"
GLwDrawingArea inherits behavior and resources from the \fBCore\fP class.
.br
The class pointer is \fBglwDrawingAreaWidgetClass\fP.
.br
The class name is \fBGLwDrawingArea\fP.
.PP
.ne 5
.SS "GLwMDrawingArea Classes"
GLwMDrawingArea inherits behavior and resources from the
\fBXmPrimitive\fP and \fBCore\fP classes.
.br
The class pointer is \fBglwMDrawingAreaWidgetClass\fP.
.br
The class name is \fBGLwMDrawingArea\fP.
.sp 1
.SS "New Resources"
The following tables define 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 \fBGLwN\fP or
\fBGLwC\fP prefix and use the remaining letters.
There are two tables included.  The first table includes resources
that correspond directly to the attributes used by \fBglXChooseVisual\fP.
As with \fBglXChooseVisual\fP, all Boolean resources default to FALSE
and all integer resources default to 0, except redSize, greenSize and
blueSize which default to 1.  These resources can all be
set only at creation time, and are used to determine the visual.  If
either the \fIGLwNattribList\fP or \fIGLwNvisualInfo\fP resource is
set, these resources are ignored.  The specific meaning of these
resources is discussed in the \fBglXChooseVisual\fP manual page and
will not be discussed here.
.sp 1
.ne 18
.TS
center allbox;
lBp8 lBp8 lBp8 lBp8
lp8 lp8 lp8 lp8.
Name	Class	Type	OpenGL attribute
GLwNbufferSize	GLwCBufferSize	int	GLX_BUFFER_SIZE
GLwNlevel	GLwCLevel	int	GLX_LEVEL
GLwNrgba	GLwCRgba	Boolean	GLX_RGBA
GLwNdoublebuffer	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
.TE
.sp 1
.PP
The following table lists other resources of the GLwDrawingArea
widget.  each of these will be described subsequently.
The codes in the access column indicate if the given resource can be
set at creation time (\fBC\fP),
set by using \fBXtSetValues\fP (\fBS\fP), 
retrieved by using \fBXtGetValues\fP (\fBG\fP), or is not applicable
(\fBN/A\fP).
.sp 1
.ne 12
.TS
center;
lp8B lp8B lp8B lp8B lp8B
lp8 lp8 lp8 lp8 lp8.
Name	Class	Type	Def	Acc
_
GLwNallocateBackground	GLwCAllocateColors	Boolean	F	CG
GLwNallocateOtherColors	GLwCAllocateColors	Boolean	F	CG
GLwNattribList	GLwCAttribList	int *	NULL	CG
GLwNexposeCallback	GLwCCallback	XtCallbackList	NULL	C
GLwNginitCallback	GLwCCallback	XtCallbackList	NULL	C
GLwNinputCallback	GLwCCallback	XtCallbackList	NULL	C
GLwNinstallBackground	GLwCInstallBackground	Boolean	T	CG
GLwNinstallColormap	GLwCInstallColormap	Boolean	T	CG
GLwNresizeCallback	GLwCCallback	XtCallbackList	NULL	C
GLwNvisualInfo	GLwCVisualInfo	XVisualInfo*	NULL	CG
.TE
.sp 1
.IP "\fBGLwNallocateBackground\fP"
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 reason to
leave this resource FALSE is that if color 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.)
.IP "\fBGLwNallocateOtherColors\fP"
This is similar to \fBGLwNallocateBackground\fP, 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 \fBXmNforeground\fP, \fBXmNhighlightColor\fP,
and \fBXmNhighlightPixmap\fP are calculated.
.IP "\fBGLwNattribList\fP"
Contains the list of attributes suitable for a call to
\fBglXChooseVisual\fP.  If this resource is NULL, it is calculated
based on the attribute resources.  If it is not NULL, the attribute
resources are ignored.
.IP "\fBGLwNexposeCallback\fP"
Specifies the list of callbacks that is
called when the widget receives an exposure event.
The callback reason is \fBGLwCR_EXPOSE\fP.
The callback structure also includes the exposure event.  The
application will generally want to redraw the scene.
.IP "\fBGLwNginitCallback\fP"
Specifies the list of callbacks that is
called when the widget is first realized.  Since no OpenGL operations can
be done before the widget is realized, this callback can be used to
perform any appropriate OpenGL initialization such as creating a context.
The callback reason is \fBGLwCR_GINIT\fP.
.IP "\fBGLwNinputCallback\fP"
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 \fBGLwCR_INPUT\fP.
.IP ""
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
customization. 
.IP "\fBGLwNinstallBackground\fP"
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 \fBGLwNallocateBackground\fP is also TRUE.
.IP "\fBGLwNinstallColormap\fP"
If set to TRUE, the widget will call \fIXSetWMColormapWindows\fP 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 \fIXSetWMColormapWindows\fP
explicitly.
.IP "\fBGLwNresizeCallback\fP"
Specifies the list of callbacks that is
called when the GLwDrawingArea is resized.
The callback reason is \fBGLwCR_RESIZE\fP.
.IP "\fBGLwNvisualInfo\fP"
Contains a pointer to the window's visual info structure.  If NULL,
the visualInfo is calculated at widget creation time based on the
\fIGLwNattributeList\fP resource (which is itself calculated from the
various resources).  If \fBGLwNvisualInfo\fP is not NULL the
\fIGLwNattributList\fP and the attribute resources are ignored.
.sp 1
.SS "Inherited Resources"
Both GLwDrawingArea and GLwMDrawingArea inherit behavior 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.
.PP
In addition, the Motif version GLwMDrawingArea also inherits from XmPrimitive.
The behavior of the color resources has been described previously.
The \fITraversalOn\fP resource is disabled for this widget, but if
keyboard input is required it should be enabled.  (Also, the
application should call \fBXmProcessTraversal(widget, XmTRAVERSE_CURRENT)\fP
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,
\fBXmNhighlightOnEnter\fP has been disabled, and
\fBXmNhighlightThickness\fP has been set to 0.
.SS "Callback Information"
A pointer to the following structure is passed to each callback:
.sp 1
.ne 6
.nf
.ta .25i 1.3i
\fBtypedef struct\fP
{
	\fBint\fP	 \fIreason\fP;
	\fBXEvent\fP	\fI*event\fP;
	\fBDimension\fP	 \fIwidth, height\fP;
} \fBGLwDrawingAreaCallbackStruct\fP;
.fi
.sp 1
.IP "\fIreason\fP" .75i
Indicates why the callback was invoked.  Appropriate values are
stated in the above resource descriptions.  For Motif programmers, the
values \fBGLwCR_EXPOSE\fP, \fBGLwCR_RESIZE\fP, and \fBGLwCR_INPUT\fP
are equal to \fBXmCR_EXPOSE\fP, \fBXmCR_RESIZE\fP, and
\fBXmCR_INPUT\fP respectively.  \fBGLwCR_GINIT\fP does not have a
Motif equivalent.
.IP "\fIevent\fP" .75i
Points to the \fBXEvent\fP that triggered the callback.
This is NULL for \fBGLwNginitCallback and \fBGLwNresizeCallback\fP.
.IP "\fIwidth\fP and \fIheight\fP" .75i
Are set to the width and height of the window.
.br
.ne 10
.sp 1 \"Adds space before the SS
.SS "Translations"
GLwDrawingArea has the translations listed below.
\fB
.nf
.ta 1.5i
.ne 5
<KeyDown>:	glwInput()
<KeyUp>:	glwInput()
<BtnDown>:	glwInput()
<BtnUp>:	glwInput()
<BtnMotion>:	glwInput()
.fi
.PP
GLwMDrawingArea has the following additional translation:
\fB
.nf
.ta 1.5i
<Key>osfHelp:	PrimitiveHelp()
.fi
.PP
An application wishing to catch other events than these defaults can
do so by installing a different translation table.
\fP
.sp 1 \"Adds space before the SS
.SS "Action Routines"
The GLwDrawingArea has the following action routine:
.IP "\fBglwInput()\fP:"
Called whenever one of the above translations specifies that input has
occurred.  Its sole purpose is to call the input callback.
.sp 1
.SH INITIALIZATION 	
.PP
When the widget is initially created (e.g. through
\fBXtCreateWidget(3X)\fP) the associated window is not actually
created.  Instead, window creation is delayed until the widget is
realized.  However, \fBglXchooseVisual\fP is called immediately, so
information based on its results is available.
.PP
Between the time the widget is created and it is realized,
the following apply:
.TP
\(bu
No OpenGL operations can be done to the window
.TP
\(bu
No resize callbacks are generated.
.TP
\(bu
The normal window is available (XtWindow returns NULL).
.TP
\(bu
\fBGLwDrawingAreaMakeCurrent\fP (and \fBglXMakeCurrent\fP) should not
be called.
.PP
When the widget is realized, the following actions take place:
.PP
.TP
\(bu
The window is created.
.TP
\(bu
The \fBginit\fP callback is called.  The user may use this callback to
perform any needed OpenGL initialization to the window.
.sp 1
.SH NOTES
.PP
When using the input callback to receive keyboard input, the keycode
in the event must be converted to a KeySym.  Use
\fBXLookupKeysym(3X)\fP or \fBXLookupString(3X)\fP to do the
conversion.  Keyboard input can also be dealt using translations, in
which case no such conversion is required.
.PP
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.
.PP
Motif programmers may also create a GLwMDrawingArea widget with the Motif
style \fBGLwCreateMDrawingArea\fP.
.sp 1
.ne 10
.SH EXAMPLE
Here are some code fragments that create a GLwDrawingArea widget, and manage
the appropriate callbacks.
.sp
.nf
\f(CW
   #include <stdlib.h>
   #include <GL/GLwDrawA.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, NULL);
       XtAddCallback(glw, GLwNresizeCallback, resizeCB, NULL);
       XtAddCallback(glw, GLwNginitCallback, ginitCB, NULL);
       /* Also add input callback if needed */
       . . .
   }

   static void
   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,
                                      NULL, GL_FALSE);
       GLwDrawingAreaMakeCurrent(w, glx_context);
       /* Perform any necessary graphics initialization.*/
   }
\fP
.fi
.P
The Motif program need only differ by including
\fBGLwMDrawingArea.h\fP instead of \fBGLwDrawingArea.h\fP and by creating a widget of type
\fBGLwMDrawingAreaWidgetClass\fP instead of \fBGLwDrawingAreaWidgetClass\fP.  As an
alternative, the Motif program could use \fBGLwCreateMDraw(3X)\fP instead.
.sp 1
.SH WARNINGS
.PP
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 \fBginit\fP callback.  In such a
case, initialization should be done immediately after creating the
widget rather than by using the callback.
.PP
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.
.SH SEE ALSO
\fBglXChooseVisual(3G)\fP, \fBGLwDrawingAreaMakeCurrent(3X)\fP,
\fBglXMakeCurrent(3G)\fP, \fBGLwDrawingAreaSwapBuffers(3X)\fP
\fBGLwCreateMDraw(3X)\fP, \fBCore(3X)\fP, \fBXmPrimitive(3X)\fP,
\fBVirtualBindings(3X)\fP, \fBXSetWMColormapWindows(3X11)\fP
and the OpenGL spec.