NAME

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

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

GLwMDrawingArea Classes

New Resources

      ___________________________________________________________________________
      |                    |                    |         |                      |
      | 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 |
      |____________________|____________________|_________|______________________|

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

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_EXPOS&/I;. 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 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 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_RESIZ&/I;.

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.

      typedef struct
      {
        int      reason;
        XEvent   * event;
        Dimensionwidth, height;
      } GLwDrawingAreaCallbackStruct;

      <KeyDown>:     glwInput()
      <KeyUp>:       glwInput()
      <BtnDown>:     glwInput()
      <BtnUp>:       glwInput()
      <BtnMotion>:   glwInput()

      <Key>osfHelp:  PrimitiveHelp()

       #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 */
           . . .
       }

       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, 0, GL_FALSE);
           GLwDrawingAreaMakeCurrent (w, glx_context);
           /* Perform any necessary graphics initialization.*/
       }