This section briefly explains how to work with resources in the context of an OpenGL program. In Xt, resources provide widget properties, allowing you to customize how your widgets will look. Note that the term “resource” used here refers to window properties stored by a resource manager in a resource database, not to the X server data structures for windows, pixmaps, and context described earlier.

F allback resources inside a program are used when a widget is created and the application cannot open the class resource file when it calls XtOpenApplication() to open the connection to the X server. (In the code fragment below, the first two resources are specific to Silicon Graphics and give the application a Silicon Graphics look and feel.)

static String  fallbackResources[] = {
    "*useSchemes: all",”*sgimode:True”,
    "*glxwidget*width: 300", 
    "*glxwidget*height: 300",
    "*frame*shadowType: SHADOW_IN",
    NULL};

---

Note: Applications ship with resource files installed in a resource directory (in /usr/lib/X11/ app-defaults). If you do install such a file automatically with your application, there is no need to duplicate the resources in your program.

---

Widgets always exist in a hierarchy with each widget contributing to what is visible on screen. There is always a top-level widget and almost always a container widget (for example, form or frame). In addition, you may decide to add buttons or scroll bars, which are also part of the IRIS IM widget set. Therefore, creating your drawing surface consists of the following two steps:

Note that unlike most other Motif user interface widgets, the OpenGL widget explicitly sets the visual. Once a visual is set and the widget is realized, the visual can no longer be changed.

When calling the widget creation function,there are three ways of configuring the GLwMDrawingArea widget (all done through resources):

Appropriate error handling is critical to a robust program. If you wish to provide error handling, call glXChooseVisual(), as all the example programs do (although for the sake of brevity, none of the examples actually provides error handling). If you provide the resources and let the widget choose the visual, the widget just prints an error message and quits. Note that a certain visual may be supported on one system but not on another.

The advantage of using a list of resources is that you can override them with the app-defaults file.

Most applications have one context per widget, though sharing is possible. If you want to use multiple widgets with the same configuration, you must use the same visual for each widget. Windows with different visuals cannot share contexts. To share contexts, do the following:

The GLwMDrawingArea widget provides callbacks for redrawing, resizing, input, and initialization, as well as the standard XmNdestroyCallback provided by all widgets.

Each callback must first be defined and then added to the widget. In some cases, this is quite simple, as, for example, the resize callback from motif/simplest.c:

static void
resize(Widget w, XtPointer client_data, XtPointer call) {
   GLwDrawingAreaCallbackStruct *call_data;
   call_data = (GLwDrawingAreaCallbackStruct *) call;
   glXWaitX();
   
   glViewport(0, 0, call_data->width, call_data->height);
}

---

Note: The X and OpenGL command streams are asynchronous, meaning that the order in which OpenGL and X commands complete is not strictly defined. In a few cases, it is important to explicitly synchronize X and OpenGL command completion. For example, if an X call is used to resize a window within a widget program, call glXWaitX() before calling glViewport() to ensure that the window resize operation is complete.

---

Other cases are slightly more complex, such as the input callback from motif/simplest.c, which exits when the user presses the Esc key:

static void
input(Widget w, XtPointer client_data, XtPointer call) {
char buffer[31];
KeySym keysym;
XEvent *event = ((GLwDrawingAreaCallbackStruct *)call) ->event;

switch(event->type) {
case KeyRelease:
XLookupString(&event->xkey, buffer, 30, &keysym, NULL);
switch(keysym) {
case XK_Escape :
exit(EXIT_SUCCESS);
break;
default: break;
}
break;
}
}

To add callbacks to a widget, use XtAddCallback(); for example:

XtAddCallback(glxwidget, GLwNexposeCallback, expose, NULL);
XtAddCallback(glxwidget, GLwNresizeCallback, resize, NULL);
XtAddCallback(glxwidget, GLwNinputCallback, input, NULL);

Each callback must ensure that the thread is made current with the correct context to the window associated with the widget generating the callback. You can do this by calling either GLwMDrawingAreaMakeCurrent() or glXMakeCurrent().

If you are using only one GLwMDrawingArea, you can call a routine to make the widget “current” just once after initializing the widget. However, if you are using more than one GLwMDrawingArea or rendering context, you need to make the correct context and the window current for each callback (see “Binding the Context to the Window” in Chapter 2).

The following callbacks are available:

Motif programs are callback-driven. They differ in that respect from IRIS GL programs, which implement their own event loops to process events. To handle input with a widget, you can either use the input callback built into the widget or use actions and translations (Xt-provided mechanisms that map keyboard input into user-provided routines). Both approaches have advantages:

By default, the input callback is called with every key press and release, with every mouse button press and release, and whenever the mouse is moved while a mouse button is pressed. You can change this by providing a different translation table, although the default setting should be suitable for most applications.  

For example, to have the input callback called on all pointer motions, not just on mouse button presses, add the following to the app-defaults file:

*widgetname.translations : \
    <KeyDown>:      glwInput() \n\
    <KeyUp>:        glwInput() \n\
    <BtnDown>:      glwInput() \n\
    <BtnUp>:        glwInput() \n\
    <BtnMotion>:    glwInput() \n\
    <PtrMoved>:     glwInput()

When the callback is passed an X event, the callback interprets the X event and performs the appropriate action. It is your application's responsibility to interpret the event—for example, to convert an X key code into a key symbol and to decide what to do with it.

Example 3-1 is from motif/mouse.c, a double-buffered RGBA program that uses mouse motion events.

static void
input(Widget w, XtPointer client_data, XtPointer call) {
   char buffer[31];
   KeySym keysym;
   XEvent *event = ((GLwDrawingAreaCallbackStruct *) call)->event;
   static mstate, omx, omy, mx, my;

   switch(event->type) {
   case KeyRelease:
      XLookupString(&event->xkey, buffer, 30, &keysym, NULL);
      switch(keysym) {
      case XK_Escape:
         exit(EXIT_SUCCESS);
         break;
      default: break;
      }
      break;
    case ButtonPress:
        if (event->xbutton.button == Button2) {
            mstate |= 2;
            mx = event->xbutton.x;
            my = event->xbutton.y;
        } else if (event->xbutton.button == Button1) {
            mstate |= 1;
            mx = event->xbutton.x;
            my = event->xbutton.y;
        }
        break;
    case ButtonRelease:
        if (event->xbutton.button == Button2)
            mstate &= ~2;
        else if (event->xbutton.button == Button1)
            mstate &= ~1;
        break;
    case MotionNotify:
        if (mstate) {
            omx = mx;
            omy = my;
            mx = event->xbutton.x;
            my = event->xbutton.y;
            update_view(mstate, omx,mx,omy,my);
        }
        break;
   }

Actions and translations provide a mechanism for binding a key or mouse event to a function call. For example, you can structure your program to take the following actions:

The translations need to be combined with an action task that maps string names like quit() to real function pointers. Below is an example of a translation table:

program*glwidget*translations:      #override \n
    <Btn1Down>:        start_rotate()   \n\
    <Btn1Up>:          stop_rotate()    \n\
    <Btn1Motion>:      rotate()         \n\
    <Key>f:            zoom_in()        \n\
    <Key>b:            zoom_out()       \n\
    <KeyUp>osfCancel:  quit()

When you press the left mouse button, the start_rotate() action is called; when it is released, the stop_rotate() action is called.

The last entry is a little cryptic. It specifies that when the user presses the Esc key, quit() is called. However, OSF has implemented virtual bindings, which allow the same programs to work on computers with different keyboards that may be missing various keys. If a key has a virtual binding, the virtual binding name must be specified in the translation. Thus, the example above specifies osfCancel rather than Esc. To use the above translation in a program that is not based on IRIS IM or OSF/Motif, replace KeyUp+osfCancel with KeyUp+Esc.

The translation is only half of what it takes to set up this binding. Although the translation table above contains apparent function names, they are really action names. Your program must also create an action table to bind the action names to actual functions in the program.

For more information on actions and translations, see O'Reilly, X Toolkit Intrinsics Programming Manual (Volume Four), most notably Chapter 4, “An Example Application,” and Chapter 8, “Events, Translations, and Accelerators.” You can view this manual on the SGI Technical Publications Library.

A common problem in IRIS IM programs is that keyboard input disappears. This is caused by how IRIS IM handles keyboard focus. When a widget hierarchy has keyboard focus, only one component of the hierarchy receives the keyboard events. The keyboard input might be going to the wrong widget. The following are two solutions to this problem:

In Xt, shell widgets include top-level windows, popup windows, and menus. Shell widgets inherit their colormap and pixel depth from their parent widget and inherit their visual from the parent window. If the visual does not match the colormap and depth, this leads to a BadMatch X protocol error.

In a typical IRIS IM program, everything runs in the default visual, and the inheritance from two different places does not cause problems. However, when a program uses both OpenGL and IRIS IM, it requires multiple visuals, and you must be careful. Whenever you create a shell widget as a child of a widget in a non-default visual, specify pixel depth, colormap, and a visual for that widget explicitly. This happens with menus or popup windows that are children of OpenGL widgets. See “Using Popup Menus With the GLwMDrawingArea Widget” in Chapter 4.

If you do get a bad match error, follow these steps to determine its cause:

Applications should generally rely on the window manager to install the colormaps instead of calling XInstallColormap() directly. The window manager automatically installs the appropriate colormaps for a window whenever that window gets keyboard focus. Popup overlay menus are an exception.

By default, the window manager looks at the top-level window of a window hierarchy and installs that colormap when the window gets keyboard focus. For a typical X-based application, this is sufficient, but an application based on OpenGL typically uses multiple colormaps: the top-level window uses the default X colormap, and the Open GL window uses a colormap suitable for OpenGL.

To address this multiple colormap issue, call the function XSetWMColormapWindows() to pass the display, the top-level window, a list of windows whose colormaps should be installed, and the number of windows in the list.

The list of windows should include one window for each colormap, including the top-level window's colormap (normally represented by the top-level window). For a typical OpenGL program that does not use overlays, the list contains two windows: the OpenGL window and the top-level window. The top-level window should normally be last in the list. Xt programs may use XtSetWMColormapWindows() instead of XSetWMColormapWindows(), which uses widgets instead of windows.

---

Note: The program must call XSetWMColormapWindows() even if it is using a TrueColor visual. Some hardware simulates TrueColor through the use of a colormap. Even though the application does not interact with the colormap directly, it is still there. If you do not call XSetWMColormapWindows(), your program may run correctly only some of the time and only on some systems.

---

Use the xprop program to determine whether XSetWMColormapWindows() was called. Click the window and look for the WM_COLORMAP_WINDOWS property. This should be a list of the windows. The last one should be the top-level window. Use xwininfo, providing the ID of the window as an argument, to determine what colormap the specified window is using and whether that colormap is installed.

To handle mouse events, your program first has to request them and then use them in the main (event handling) loop. Here is an example code fragment from Xlib/mouse.c, an Xlib program that uses mouse motion events. Example 3-3 shows how the mouse processing, along with the other event processing, is defined.

static int
process_input(Display *dpy) {
    XEvent event;
    Bool redraw = 0;
    static int mstate, omx, omy, mx, my;

    do {
        char buf[31];
        KeySym keysym;
        XNextEvent(dpy, &event);
        switch(event.type) {
        case Expose:
            redraw = 1;
            break;
        case ConfigureNotify:
            glViewport(0, 0, event.xconfigure.width,
                       event.xconfigure.height);
            redraw = 1;
            break;
        case KeyPress:
            (void) XLookupString(&event.xkey, buf, sizeof(buf),
                   &keysym, NULL);
            switch (keysym) {
            case XK_Escape:
                exit(EXIT_SUCCESS);
            default:
                break;
            }
        case ButtonPress:
            if (event.xbutton.button == Button2) {
                mstate |= 2;
                mx = event.xbutton.x;
                my = event.xbutton.y;
            } else if (event.xbutton.button == Button1) {
                mstate |= 1;
                mx = event.xbutton.x;
                my = event.xbutton.y;
            }
            break;
        case ButtonRelease:
            if (event.xbutton.button == Button2)
                mstate &= ~2;
            else if (event.xbutton.button == Button1)
                mstate &= ~1;
            break;
        case MotionNotify:
            if (mstate) {
                omx = mx;
                omy = my;
                mx = event.xbutton.x;
                my = event.xbutton.y;
                update_view(mstate, omx,mx,omy,my);
                redraw = 1;
            }
            break;
        default:
            break;
        }
    } while (XPending(dpy));
    return redraw;
}

The process_input() function is then used by the main loop:

 while (1) {
        if (process_input(dpy)) {
            draw_scene();
            ...
           }
}

When a user selects a window that has been completely or partly covered, the X server generates one or more Expose events. It is difficult to determine exactly what was drawn in the now-exposed region and redraw only that portion of the window. Instead, OpenGL programs usually just redraw the entire window.

If redrawing is not an acceptable solution, the OpenGL program can do all your rendering into a GLXPixmap instead of directly to the window; then, any time the program needs to redraw the window, you can simply copy the GLXPixmap's contents into the window using XCopyArea(). For more information, see “Using Pixmaps” in Chapter 4.

---

Note: Rendering to a GLXPixmap is much slower than rendering to a window and may not allow access to many features of the graphics hardware.

---

When handling X events for OpenGL programs, remember that Expose events come in batches. When you expose a window that is partly covered by two or more other windows, two or more Expose events are generated, one for each exposed region. Each one indicates a simple rectangle in the window to be redrawn. If you are going to redraw the entire window, read the entire batch of Expose events. It is wasteful and inefficient to redraw the window for each Expose event.