MirBSD manpage: GLwDrawingArea(3), GLwMDrawingArea(3)

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)


     GLwDrawingArea, GLwMDrawingArea - OpenGL drawing widgets.


     #include <X11/GLw/GLwDrawA.h>
     ld ... -lGLw -lGL -l<anywidgetlibrary> -lXext -lXt -lX11 -lm

     #include <X11/GLw/GLwMDrawA.h>
     ld ... -lGLw -lGL -lXm -lXext -lXt -lX11 -lm


     GLwDrawingArea and GLwMDrawingArea 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.

     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 back-
     ground 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 else-
     where; 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 identi-
     cally 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.

     In addition to allocating the visual, the GLwDrawingArea
     will also allocate the colormap unless one is provided by

MirBSD #10-current     Printed 2021-12-07                       1

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

     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).

     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 ginit callback may be used to indicate when the window
     has been created.  Upon receiving this callback, the appli-
     cation can perform all OpenGL 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 win-

     GLwDrawingArea Classes
     GLwDrawingArea inherits behavior and resources from the Core
     The class pointer is glwDrawingAreaWidgetClass.
     The class name is GLwDrawingArea.

     GLwMDrawingArea Classes
     GLwMDrawingArea inherits behavior and resources from the
     XmPrimitive and Core classes.
     The class pointer is glwMDrawingAreaWidgetClass.
     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 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 GLwN or GLwC

MirBSD #10-current     Printed 2021-12-07                       2

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

     prefix and use the remaining letters. There are two tables
     included.  The first table includes resources that
     correspond directly to the attributes used by glXChooseV-
     isual. As with glXChooseVisual, 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 GLwNattri-
     bList or GLwNvisualInfo resource is set, these resources are
     ignored.  The specific meaning of these resources is dis-
     cussed 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            |
|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|

     The following table lists other resources of the
     GLwDrawingArea widget.  each of these will be described

MirBSD #10-current     Printed 2021-12-07                       3

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

     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 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

          If TRUE, the background pixel and pixmap will be allo-
          cated if appropriate using the newly calculated color-
          map and visual.  If FALSE, they will retain values cal-
          culated using the parent's colormap and visual.  Appli-
          cations 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 allo-
          cated colormap.  Also, on hardware that supports only
          one colormap, the application may need to do more care-
          ful 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 color-

          This is similar to GLwNallocateBackground, but allo-
          cates 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,

MirBSD #10-current     Printed 2021-12-07                       4

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

          XmNhighlightColor, and XmNhighlightPixmap are calcu-

          Contains the list of attributes suitable for a call to
          glXChooseVisual.  If this resource is NULL, it is cal-
          culated based on the attribute resources.  If it is not
          NULL, the attribute resources are ignored.

          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.

          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 call-
          back can be used to perform any appropriate OpenGL ini-
          tialization such as creating a context. The callback
          reason is GLwCR_GINIT.

          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 GLwCR_INPUT.

          The input callback is provided as a programming con-
          venience, 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 transla-
          tions can also provide for more customization.

          If set to TRUE, the background is installed on the win-
          dow.  If set to FALSE, the window has no background.
          This resource has no effect unless GLwNallocateBack-
          ground is also TRUE.

          If set to TRUE, the widget will call XSetWMColormapWin-
          dows to tell the window manager to install the colormap
          when the window's shell has focus.  If set to FALSE,

MirBSD #10-current     Printed 2021-12-07                       5

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

          this will not be called.  For applications with multi-
          ple GLwDrawingAreas sharing a single colormap, it is
          most efficient to set this resource to TRUE for exactly
          one GLwDrawingArea with each colormap.  If an applica-
          tion needs additional control over the order of color-
          maps, this resource can be set to FALSE, with the
          application calling XSetWMColormapWindows explicitly.

          Specifies the list of callbacks that is called when the
          GLwDrawingArea is resized. The callback reason is

          Contains a pointer to the window's visual info struc-
          ture.  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 GLwNat-
          tributList and the attribute resources are ignored.

     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 previ-
     ously, 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 dis-
     abled 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 call-

     typedef struct
       int         reason;
       XEvent     *event;
       Dimension   width, height;
     } GLwDrawingAreaCallbackStruct;

MirBSD #10-current     Printed 2021-12-07                       6

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

     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 respec-
            tively.  GLwCR_GINIT does not have a Motif

     event  Points to the XEvent that triggered the callback.
            This is NULL for GLwNginitCallback and GLwNresize-

     width and height
            Are set to the width and height of the window.

     GLwDrawingArea has the translations listed below.

     <KeyDown>:     glwInput()
     <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

     Action Routines
     The GLwDrawingArea has the following action routine:

          Called whenever one of the above translations specifies
          that input has occurred.  Its sole purpose is to call
          the input callback.


     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 avail-

MirBSD #10-current     Printed 2021-12-07                       7

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

     Between the time the widget is created and it is realized,
     the following apply:

     +    No OpenGL 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

     +    The window is created.

     +    The ginit callback is called.  The user may use this
          callback to perform any needed OpenGL 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.


     Here are some code fragments that create a GLwDrawingArea
     widget, and manage the appropriate callbacks.

        #include <stdlib.h>
        #include <X11/GLw/GLwDrawA.h>
        static GLXContext glx_context;
        . . .

            Arg args[10];

MirBSD #10-current     Printed 2021-12-07                       8

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

            int n;

            Widget parent;
            Widget glw;
            . . .

            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);

            . . .

        static void
        exposeCB(Widget w, XtPointer client_data,
                 GLwDrawingAreaCallbackStruct *call_data)
            GLwDrawingAreaMakeCurrent(w, glx_context);


        static void
        resizeCB(Widget w, XtPointer client_data,
                 GLwDrawingAreaCallbackStruct *call_data)
            GLwDrawingAreaMakeCurrent(w, glx_context);


        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);

            glx_context = glXCreateContext(XtDisplay(w), vi,
                                           NULL, GL_FALSE);
            GLwDrawingAreaMakeCurrent(w, glx_context);


MirBSD #10-current     Printed 2021-12-07                       9

GLwDrawingArea(3X)  UNIX Programmer's Manual   GLwDrawingArea(3X)

     The Motif program need only differ by including
     GLwMDrawingArea.h instead of GLwDrawingArea.h and by creat-
     ing a widget of type GLwMDrawingAreaWidgetClass instead of
     GLwDrawingAreaWidgetClass.  As an alternative, the Motif
     program could use GLwCreateMDraw(3X) instead.


     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


     glXChooseVisual(3G), GLwDrawingAreaMakeCurrent(3X),
     glXMakeCurrent(3G), GLwDrawingAreaSwapBuffers(3X)
     GLwCreateMDraw(3X), Core(3X), XmPrimitive(3X),
     VirtualBindings(3X), XSetWMColormapWindows(3X11) and the
     OpenGL spec.

MirBSD #10-current     Printed 2021-12-07                      10

Generated on 2021-12-07 11:07:08 by $MirOS: src/scripts/roff2htm,v 1.103 2021/01/23 20:24:35 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2021 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.