IRIS GL can draw in X11 windows with routines such as GLXgetconfig(), GLXlink(), GLXunlink(), and GLXwinset(). These functions don't have exact equivalents in OpenGL; see Appendix A for approximate equivalents.

The naming conventions for X-related functions may be confusing, as they depend largely on capitalization to differentiate between groups of functions:

Note that the glX*() routines are, collectively referred to as “GLX.” Note, too, that GLXgetconfig() (an IRIS GL mixed-model routine) isn't at all the same function as glXGetConfig() (an OpenGL GLX routine). The command

IRIS% man glxgetconfig

on a system with both IRIS GL and OpenGL lists both reference pages, one following the other.

When integrating your OpenGL program with the X Window System, you have two choices:

The first method, using Xt and a widget set, is easier and is commonly used by developers. It's recommended particularly for programmers with little or no previous experience with X.

---

Note: The manual OpenGL on Silicon Graphics Systems explores both approaches in some detail.

---

Whichever method you choose, you'll find more information on programming with Xlib and Xt in the X Window System series from O'Reilly & Associates. The material in this chapter is intended as a supplement to the O'Reilly guides, detailing X development features available on Silicon Graphics workstations.

In OpenGL programs that use the X Window System, window depth and display mode are window attributes that are defined when the window is created, and they cannot be changed. To change these attributes, you must create a new window. If you need multiple display modes in your application, you can create multiple windows, then map and unmap them, or raise one above the others.

It's a good idea to call XSetWMColormapWindows(); this ensures that its color maps are installed. If you don't call XSetWMColormapWindows(), the default X color map is used. Even if your program uses RGB mode, you should still call XSetWMColormapWindows() because some hardware (such as IRIS Indigo) simulates RGB with a color map.

The examples shown in this chapter use Xt and IRIS IM. Although knowing Xt and IRIS IM isn't required to read this chapter, understanding the details of the examples does require some Xt and IRIS IM knowledge. This chapter points out a few areas of the Xt and IRIS IM toolkits relevant for OpenGL programmers; it doesn't provide a tutorial on Xt and IRIS IM.

For more information on the relevant features of Xt and IRIS IM, consult the OSF/Motif series, and Digital's X Window System Toolkit: The Complete Programmer's Guide and Specification, or O'Reilly's Volumes 4 and 5 on the X Toolkit Intrinsics, or refer to the OpenGL on Silicon Graphics Systems manual.

This section refers frequently to IRIS IM because it is commonly used with OpenGL programs; however, unless otherwise specified, you can use the features discussed here with other widget sets, such as the Athena widget set. The features discussed in this chapter exist either within the widget itself or are based on the X toolkit. You therefore have a choice:

Combining OpenGL and Motif is made easier by a specially supplied OpenGL drawing area widget, GLwDrawingArea. Use the GLwDrawingArea widget when integrating your OpenGL program with Xt. The GLwDrawingArea widget sets up a configuration for GL drawing and provides resources and callbacks that are useful to the OpenGL programmer. The GLwDrawingArea widget also provides support for overlays.

There are actually two GLwDrawingArea widgets. The widget known as GLwDrawingArea is a generic widget, suitable for use with any widget set that's based on the Xt intrinsics. There is also a version known as GLwMDrawingArea (note the M) for use with IRIS IM programs.

The two widgets are very similar, but they do have these differences:

In all other respects, the two widgets are identical. The remainder of this chapter refers to the GlxMDraw widget, but unless otherwise specified, everything stated refers to both.

This section discusses the actual conversion process:

% cc -O -o mixed mixed.c -lXm -lGL -lGLw -lGLU

/* mixed.c
 */

#include <Xm/Xm.h>
#include <Xm/Form.h>
#include <X11/keysym.h>
#include <X11/StringDefs.h>
#include "GL/GLwMDrawA.h"

#include <GL/gl.h>
#include <GL/glu.h>
#include <stdio.h>
#include <stdlib.h>

static void input(Widget, XtPointer, XtPointer);
static void draw_scene_callback (Widget, XtPointer,
                                 XtPointer);
static void do_resize(Widget, XtPointer, XtPointer);
static void init_window(Widget, XtPointer, XtPointer);

static GLXContext glx_context;

void main(int argc, char** argv)
{
    Arg args[20];
    int n;
    Widget glw, toplevel, form;
    static XtAppContext app_context;
    static String fallback_resources[] = {
        "*glwidget*width: 300",
        "*glwidget*height: 300",
        "*glwidget*rgba: TRUE",
        "*glwidget*doublebuffer: TRUE",
        "*glwidget*allocateBackground: TRUE",
        NULL
    };

    toplevel = XtAppInitialize(&app_context, "Mixed", NULL,
                               0, &argc, argv,
                               fallback_resources, NULL, 0);
    n = 0;
    form = XmCreateForm(toplevel, "form", args, n);
    XtManageChild(form);

    n = 0;
    XtSetArg(args[n], XmNbottomAttachment, XmATTACH_FORM);
    n++;
    XtSetArg(args[n], XmNtopAttachment, XmATTACH_FORM);
    n++;
    XtSetArg(args[n], XmNleftAttachment, XmATTACH_FORM);
    n++;
    XtSetArg(args[n], XmNrightAttachment, XmATTACH_FORM);
    n++;
    glw = GLwCreateMDrawingArea(form, "glwidget", args, n);
    XtManageChild (glw);
    XtAddCallback(glw, GLwNexposeCallback,
                  draw_scene_callback, (XtPointer) NULL);
    XtAddCallback(glw, GLwNresizeCallback, do_resize,
                  (XtPointer) NULL);
    XtAddCallback(glw, GLwNginitCallback, init_window,
                  (XtPointer) NULL);
    XtAddCallback(glw, GLwNinputCallback, input,
                  (XtPointer) NULL);

    XtRealizeWidget(toplevel);
    XtAppMainLoop(app_context);
}

static int rotation = 0;

void spin (void)
{
    rotation = (rotation + 5) % 360;
}

static void draw_scene (Widget w)
{
    GLUquadricObj *quadObj;

    glClear(GL_COLOR_BUFFER_BIT);
    glColor3f (1.0, 1.0, 1.0);
    glPushMatrix();
    glTranslatef (0.0, 0.0, -5.0);
    glRotatef ((GLfloat) rotation, 1.0, 0.0, 0.0);

    glPushMatrix ();
    glRotatef (90.0, 1.0, 0.0, 0.0);
    glTranslatef (0.0, 0.0, -1.0);
    quadObj = gluNewQuadric ();
    gluQuadricDrawStyle (quadObj, GLU_LINE);
    gluCylinder (quadObj, 1.0, 1.0, 2.0, 12, 2);
    glPopMatrix ();

    glPopMatrix();
    glFlush();
    glXSwapBuffers (XtDisplay(w), XtWindow(w));
}

/* Process all Input callbacks*/
static void input(Widget w, XtPointer client_data,
                  XtPointer call)
{
    char buffer[1];
    KeySym keysym;
    GLwDrawingAreaCallbackStruct *call_data;

    call_data = (GLwDrawingAreaCallbackStruct *) call;

    switch(call_data->event->type)
    {
    case KeyRelease:
         /* It is necessary to convert the keycode to a
          * keysym before it is possible to check if it is
          * an escape.
          */
         if (XLookupString( (XKeyEvent *) call_data->event,
                            buffer, 1, &keysym,
                            (XComposeStatus *) NULL ) == 1
             && keysym == (KeySym) XK_Escape)
             exit(0);
    break;

    case ButtonPress:
        switch (call_data->event->xbutton.button)
        {
        case Button1:
            spin();
            draw_scene(w);
        break;
        }
    break;

    default:
    break;
    }
}

static void draw_scene_callback(Widget w, XtPointer client_data, XtPointer call)
{
    static char firstTime = 0x1;
    GLwDrawingAreaCallbackStruct *call_data;

    call_data = (GLwDrawingAreaCallbackStruct *) call;
    GLwDrawingAreaMakeCurrent(w, glx_context);

    if (firstTime) {
        glViewport(0, 0, call_data->width,call_data->height);
        glMatrixMode(GL_PROJECTION);
        glLoadIdentity();
        gluPerspective(65.0, (float) call_data->width /
                       (float)call_data->height, 1.0, 20.0);
        glMatrixMode(GL_MODELVIEW);
        glLoadIdentity();
        firstTime = 0;
    }
    draw_scene (w);
}

static void do_resize(Widget w, XtPointer client_data,
                      XtPointer call)
{
    GLwDrawingAreaCallbackStruct *call_data;

    call_data = (GLwDrawingAreaCallbackStruct *) call;

    GLwDrawingAreaMakeCurrent(w, glx_context);
    glViewport(0, 0, call_data->width, call_data->height);
    glMatrixMode(GL_PROJECTION);
    glLoadIdentity();
    gluPerspective(65.0, (GLfloat) call_data->width /
                   (GLfloat)call_data->height, 1.0, 20.0);
    glMatrixMode(GL_MODELVIEW);
    glLoadIdentity();
}

static void init_window(Widget w, XtPointer client_data,
                        XtPointer call_data)
{
    Arg args[1];
    XVisualInfo *vi;
    GLUquadricObj *quadObj;

    XtSetArg(args[0], GLwNvisualInfo, &vi);
    XtGetValues(w, args, 1);
    glx_context = glXCreateContext(XtDisplay(w), vi, 0,
                                   GL_FALSE);
}

The most complete information about OpenGL and X can be found in

Kilgard, Mark J. OpenGL Programming for the X Window System. Menlo Park, CA: Addison-Wesley Developer's Press. 1996. ISBN 0-201-48369-9

For more information on mixed-model programming in general, you can refer to the OpenGL Reference Manual, which contains reference pages for the OpenGL GLX command, as well as an introductory reference page, glXIntro.

For more detailed information on programming with Xt, see Volume IV of the X Window System Series, X Toolkit Intrinsics Programming Manual, by Adrian Nye and Tim O'Reilly, published by O'Reilly & Associates, Inc. (If you're using IRIS IM, you'll probably want the Motif version of Volume IV.)

For more information on IRIS IM, refer to documentation on Motif, such as the OSF/Motif Series published by Prentice Hall.

---

Note: Another example of using XLib is included in OpenGL on Silicon Graphics Systems.

---

To port your OpenGL code to use Xlib and GLX calls, follow these steps:

Example 4-3 shows a simple way of following the steps given in the previous section.You can find a version of this code in the glXIntro reference page. This sample is more heavily commented than the one in the reference page and contains some additional examples.

#include <X11/Xlib.h>
#include <GL/glx.h>
#include <GL/gl.h>
#include <stdio.h>

static int attributeList[] = { GLX_RGBA, None };

static Bool WaitForNotify(Display *d, XEvent *e, char *arg)
    { return(e->type == MapNotify) && (e->xmap.window == (Window)arg); }

int main(int argc, char**argv)
{
    Display *dpy;
    XVisualInfo *vi;
    Colormap cmap;
    XSetWindowAttributes swa;
    Window win;
    GLXContext cx;
    XEvent event;

/* get a connection   */
    dpy   = XOpenDisplay(0);
    if (!dpy) {
        fprintf(stderr, "Cannot open display.\n");
        exit(-1);
    }

/* get an appropriate visual */
    vi = glXChooseVisual(dpy, DefaultScreen(dpy),
         attributeList);
    if (!vi) {
        fprintf(stderr, "Cannot find visual with desired attributes.\n");
        exit(-1);
    }

/* create a GLX context */
    cx = glXCreateContext(dpy, vi, 0, GL_FALSE);
    if (!cx) {
        fprintf(stderr, "Cannot create context.\n");
        exit(-1);
    }

/* create a colormap -- AllocAll for color index mode */
    cmap = XCreateColormap(dpy, RootWindow(dpy, vi->screen),
           vi->visual, AllocNone);
    if (!cmap) {
        fprintf(stderr, "Cannot allocate colormap.\n");
        exit(-1);
    }

    /* create a   window */
    swa.colormap = cmap;
    swa.border_pixel = 0;
    /* connect the context to the window */
    glXMakeCurrent(dpy, win, cx);

/* clear the buffer */
    glClearColor(1,1,0,1);
    glClear(GL_COLOR_BUFFER_BIT);
    glFlush();

/wait for a while */
    sleep(10);
/* exit cleanly */
    XCloseDisplay(dpy);
    exit(0);
}

Here's a brief example of OpenGL GLX code that demonstrates the use of color maps:

XColor xc;

display = XOpenDisplay(0);

visual = glXChooseVisual(display,     

    DefaultScreen(display), attributeList);

context = glXCreateContext (display,visual,0,GL_FALSE);

colorMap = XCreateColormap (display,RootWindow(display, 

    visual->screen), visual->visual, AllocAll);

/* Note: if you don't say AllocAll, you can't load */
/* the color maps! */
    ...

if (index < visual->colormap_size) {

    xc.pixel = index;

    xc.red = (unsigned short)(red * 65535.0 + 0.5);

    xc.green = (unsigned short)(green * 65535.0 + 0.5);

    xc.blue = (unsigned short)(blue * 65535.0 + 0.5);

    xc.flags = DoRed | DoGreen | DoBlue;

    XStoreColor (display, colorMap, &xc);

}

Here's a simple example of a program that uses Xlib and OpenGL GLX calls for event handling:

swa.event_mask = ExposureMask | StructureNotifyMask 
                 | KeyPressMask | KeyReleaseMask;
do {
    XNextEvent(dpy, &event);
    switch (event.type) {
        case Expose:
            doRedraw = GL_TRUE;
            break;
        case ConfigureNotify:
            width = event.xconfigure.width;
            height = event.xconfigure.height;
            doRedraw = GL_TRUE;
            break;
        case KeyPress:
        {
            char buf[100];
            int rv;
            KeySym ks;

            rv = XLookupString(&event.xkey, buf, sizeof(buf), &ks, 0);
            switch (ks) {
                case XK_s:
                case XK_S:
                    doSave = GL_TRUE;
                    break;
                case XK_Escape:
                    return 0;
                    break;
            }
        }
    }
} while (XPending(dpy));