A double-buffered animation displays one buffer while drawing into another (undisplayed) buffer then swaps the displayed buffer with the other. In OpenGL, the displayed buffer is called the front buffer, and the undisplayed buffer is called the back buffer. This sort of action is common in OpenGL programs; however, swapping buffers is a window-related function, not a rendering function; therefore, you cannot do it directly with OpenGL.

To swap buffers, use glXSwapBuffers() or, when using the widget, the convenience function GLwDrawingAreaSwapBuffers(). The glXSwapBuffers() function takes a display and a window as input—pixmaps do not support buffer swapping—and swaps the front and back buffers in the drawable. All renderers bound to the window in question continue to have the correct idea of the front buffer and the back buffer. Note that once you call glXSwapBuffers(), any further drawing to the given window is suspended until after the buffers have been swapped.

Silicon Graphics systems support hardware double buffering; this means the buffer swap is instantaneous during the vertical retrace of the monitor. As a result, there are no tearing artifacts; that is, you do not simultaneously see part of one buffer and part of the next.

---

Note: If the window's visual allows only one color buffer, or if the GLX drawable is a pixmap, glXSwapBuffers() has no effect (and generates no error).

---

There is no need to worry about which buffer the X server draws into if you are using X drawing functions as well as OpenGL; the X server draws only to the current front buffer and prevents any program from swapping buffers while such drawing is going on. Using the X double buffering extension (DBE), it is possible to render X into the back buffer.

Note that users like uniform frame rates such as 60 Hz, 30 Hz, or 20 Hz. Animation may otherwise look jerky. A slower consistent rate is therefore preferable to a faster but inconsistent rate. For additional information about optimizing frame rates, see “Optimizing Frame Rate Performance” in Chapter 15. See “SGI_swap_control—The Swap Control Extension” in Chapter 11 to learn how to set a minimum period of buffer swaps.

A workproc (work procedure) is a procedure that Xt calls when the application is idle. The application registers workprocs with Xt and unregisters them when it is time to stop calling them.

Note that workprocs do not provide constant-speed animation but animate as fast as the application can.

XtWorkProcId XtAppAddWorkProc(XtAppContext app_context,
                              XtWorkProc proc, XtPointer client_data)
void XtRemoveWorkProc(XtWorkProcId id)

Workproc Example

This section illustrates the use of workprocs. The example, motif/animate.c, is a simple animation driven by a workproc. When the user selects “animate” from the menu, the workproc is registered, as follows:

static void menu(Widget w, XtPointer clientData, XtPointer callData) { int entry = (int) clientData; switch (entry) { case 0: if (state.animate_wpid) { XtRemoveWorkProc(state.animate_wpid); state.animate_wpid = 0; } else { /* register workproc */ state.animate_wpid = XtAppAddWorkProc(state.appctx, redraw_proc, &state.glxwidget); } break; case 1: exit(EXIT_SUCCESS); break; default: break; } }

The workproc starts executing if the window is mapped (that is, it could be visible but it may be overlapped):

static void map_change(Widget w, XtPointer clientData, XEvent *event, Boolean *cont) { switch (event->type) { case MapNotify: /* resume animation if we become mapped in the animated state */ if (state.animate_wpid != 0) state.animate_wpid = XtAppAddWorkProc(state.appctx, redraw_proc, &state.glxwidget); break; case UnmapNotify: /* don't animate if we aren't mapped */ if (state.animate_wpid) XtRemoveWorkProc(state.animate_wpid); break; } }

If the window is mapped, the workproc calls redraw_proc():

static Boolean redraw_proc(XtPointer clientData) { Widget *w = (Widget *)clientData; draw_scene(*w); return False; /*call the workproc again as possible*/ }

The redraw_proc() function, in turn, calls draw_scene(), which swaps the buffers. Note that this program does not use glXSwapBuffers(), but instead the convenience function GLwDrawingAreaSwapBuffers().

static void draw_scene(Widget w) { static float rot = 0.; glClear(GL_COLOR_BUFFER_BIT); glColor3f(.1, .1, .8); glPushMatrix(); if ((rot += 5.) > 360.) rot -= 360.; glRotatef(rot,0.,1.,0.); cube(); glScalef(0.3,0.3,0.3); glColor3f(.8, .8, .1); cube(); glPopMatrix(); GLwDrawingAreaSwapBuffers(w); }

---

Note: If an animation is running and the user selects a menu command, the event handling for the command and the animation may end up in a race condition.

---

The program that performs an animation using timeouts is actually quite similar to the one using workprocs. The main difference is that the timeout interval has to be defined and functions that relied on the workproc now have to be defined to rely on the timeout. Note especially that redraw_proc() has to register a new timeout each time it is called.

You may find it most helpful to compare the full programs using xdiff or a similar tool. This section briefly points out the main differences between two example programs.

An overlay plane is a set of bitplanes displayed preferentially to the normal planes. Non-transparent pixels in the overlay plane are displayed in preference to the underlying pixels in the normal planes. Windows in the overlay planes do not damage windows in the normal plane.

If you have something in the main window that is fairly expensive to draw into and want to have something else on top, such as an annotation, you can use a transparent overlay plane to avoid redrawing the more expensive main window. Overlays are well-suited for popup menus, dialog boxes, and “rubber-band” image resizing rectangles. You can also use overlay planes for text annotations floating “over” an image and for certain transparency effects.

Notes:

A special value in the overlay planes indicates transparency. On Silicon Graphics systems, it is always the value zero. Any pixel with the value zero in the overlay plane is not painted to allow the color of the corresponding pixel in the normal planes to show.

The concepts discussed in this section apply more generally to any number of framebuffer layers, for example, underlay planes (which are covered up by anything in equivalent regions of higher-level planes).

You can use overlays in the following two ways:

This section explains how to create overlay planes, using an example program based on Motif. If you create the window using Xlib, the same process is valid (and a parallel example program is available in the example program directory).

The example program from which the code fragments are taken, motif/overlay.c, uses the visual info extension to find a visual with a transparent pixel. See “EXT_visual_info—The Visual Info Extension” in Chapter 6 for more information.

---

Note: This example uses the visual info extension, which is supported on all current Silicon Graphics graphics systems. The visual info extension has also been promoted to a core feature of GLX 1.3. With new applications, use the GLX 1.3 interface instead of the extension.

---

To create the overlay, follow these steps:

This section gives some advice on issues that can easily cause problems in a program using overlays:

Rubber banding can be used for cases where applications have to draw a few lines over a scene in response to a mouse movement. An example is the movable window outline that you see when resizing or moving a window. Rubber banding is also used frequently by drawing programs.

The 4Dwm window manager provides rubber banding for moving and resizing windows. However, if you need rubber banding features inside your application, you must manage it yourself.

The following procedure is the best way to perform rubber banding with overlays (this is the method used by 4Dwm, the default Silicon Graphics window manager):

Popups are used by many applications to allow user input. A sample program, simple-popup.c, is included in the source tree. It uses the function XmCreateSimplePopupMenu() to add a popup to a drawing area widget.

Note that if you are not careful when you create a popup menu as a child of GLwMDrawingArea widget, you may get a BadMatch X protocol error. The menu (like all other Xt shell widgets) inherits its default colormap and depth from the GLwMDrawingArea widget but its default visual from the parent (root) window. Because the GLwMDrawingArea widget is normally not the default visual, the menu inherits a nondefault depth and colormap from the GLwMDrawingArea widget but also inherits its visual from the root window (that is, inherits the default visual); this leads to a BadMatch X protocol error. For more details and for information on finding the error, see “Inheritance Issues” in Chapter 3.

The following are two ways to work around this problem:

An X visual defines how pixels in a window are mapped to colors on the screen. Each window has an associated visual, which determines how pixels within the window are displayed on screen. GLX overloads X visuals with additional framebuffer capabilities needed by OpenGL.

Table 4-1 lists the X visuals supported for different types of OpenGL rendering, indentifies the Silicon Graphics systems supporting the X visuals, and indicates whether the colormaps for those visuals are writable or not.

Depending on the available hardware and software, an X server can provide multiple visuals. Each server has a default visual, which can be specified when the server starts. You can determine the default visual with the Xlib macro DefaultVisual().

Because you cannot predict the configuration of every X server, and you may not know the system configuration where your program will run , it is best to find out what visual classes are available on a case-by-case basis.

---

Note: This section applies only to IRIS IM.

---

In previous chapters, this guide has assumed separate visuals for the X and OpenGL portions of the program. The top-level windows and all parts of the application that are not written in OpenGL use the default visual (typically 8-bit PseudoColor, but it depends on the configuration of the server). OpenGL runs in a single window that uses an OpenGL visual.

An alternative approach is to run the whole application using an OpenGL visual. To do this, determine the suitable OpenGL visual (and colormap and pixel depth) at the start of the program and create the top-level window using that visual (and colormap and pixel depth). Other windows, including the OpenGL window, inherit the visual. When you use this approach, there is no need to use the GLwMDrawingArea widget; the standard IRIS IM XmDrawingArea works just as well.

The advantages of using a single visual include the following:

The advantages of using separate visuals for X and OpenGL include the following:

The framebuffer configuration functions in GLX 1.3 are analogous to GLX visuals but provide the following additional features:

The following are reasons to use framebuffer configurations:

This section briefly describes the following features framebuffer configurations provide:

FBConfig Constructs

An FBConfig describes the format, type, and size of the color and ancillary buffers for a GLX drawable. If the GLX drawable is a window, then the FBConfig that describes it has an associated X visual; for a GLXPixmap or GLXPbuffer, there may or may not be an X visual associated with the FBConfig.

Choosing an FBConfig Construct

Use glXGetFBConfigs() to get a list of all FBConfigs that are available on the specified screen. The format of the function is as follows:

GLXFBConfig *glXGetFBConfigs(Display *dpy, int screen,int *nitems)

The number of FBConfigs returned is stored in the value nitems.

Use glXChooseFBConfig() to get FBConfig constructs that match a specified list of attributes:

GLXFBConfig *glXChooseFBConfig(Display *dpy, int screen, const int *attrib_list, int *nitems)

Like glXGetFBConfigs(), function glXChooseFBConfig() returns an array of FBConfigs that are available on the specified screen if attrib_list is NULL; otherwise, this call returns an array of FBConfigs that match the specified attributes. Table 4-2 shows only attributes specific to FBConfigs; additional attributes are listed on the glXChooseVisual man page.

Table 4-2. Visual Attributes Introduced by the FBConfigs

Attribute	Type	Description
GLX_DRAWABLE_TYPE	bitmask	Mask indicating which GLX drawables are supported. Valid bits are GLX_WINDOW_BIT and GLX_PIXMAP_BIT.
GLX_RENDER_TYPE	bitmask	Mask indicating which OpenGL rendering modes are supported. Valid bits are GLX_RGBA_BIT and GLX_COLOR_INDEX_BIT.
GLX_X_RENDERABLE	boolean	True if X can render to drawable.
GLX_FBCONFIG_ID	XID	XID of the FBConfig.

The attributes are matched in an attribute-specific manner. Some attributes, such as GLX_LEVEL, must match the specified value exactly; others, such as GLX_RED_SIZE, must meet or exceed the specified minimum values.

The sorting criteria are defined as follows:

smaller		FBConfigs with an attribute value that meets or exceeds the specified value are matched. Precedence is given to smaller values. When a value is not explicitly requested, the default is implied.
larger		When the value is requested explicitly, only FBConfigs with a corresponding attribute value that meets or exceeds the specified value are matched. Precedence is given to larger values. When the value is not requested explicitly, larger behaves exactly smaller.
exact		Only FBConfigs whose corresponding attribute value exactly matches the requested value are considered.
mask		For an FBConfig to be considered, all the bits that are set in the requested value must be set in the corresponding attribute. Additional bits might be set in the attribute.

Table 4-3 illustrates how each attribute is matched. Note that “No effect” means that the default behavior is to have no preference when searching for a matching FBConfig.

Table 4-3. FBConfig Attribute Defaults and Sorting Criteria

Attribute	Default	Sorting Criteria
GLX_BUFFER_SIZE	0	Smaller
GLX_LEVEL	0	Smaller
GLX_DOUBLEBUFFER	No effect	Smaller
GLX_STEREO	False	Exact
GLX_AUX_BUFFERS	0	Smaller
GLX_RED_SIZE	0	Larger
GLX_GREEN_SIZE	0	Larger
GLX_BLUE_SIZE	0	Larger
GLX_ALPHA_SIZE	0	Larger
GLX_DEPTH_SIZE	0	Larger
GLX_STENCIL_SIZE	0	Larger
GLX_ACCUM_RED_SIZE	0	Larger
GLX_ACCUM_GREEN_SIZE	0	Larger
GLX_ACCUM_BLUE_SIZE	0	Larger
GLX_ACCUM_ALPHA_SIZE	0	Larger
GLX_SAMPLE_BUFFERS_ARB	0 if GLX_SAMPLES_ARB = 0; otherwise, 1.	Smaller
GLX_SAMPLES_ARB	0	Smaller
GLX_X_VISUAL_TYPE	No effect	Exact
GLX_TRANSPARENT_TYPE	GLX_NONE	Exact
GLX_TRANSPARENT_INDEX_VALUE	No effect	Exact
GLX_TRANSPARENT_RED_VALUE	No effect	Exact
GLX_TRANSPARENT_GREEN_VALUE	No effect	Exact
GLX_TRANSPARENT_BLUE_VALUE	No effect	Exact
GLX_TRANSPARENT_ALPHA_VALUE	No effect	Exact
GLX_VISUAL_CAVEAT	GLX_NONE	Exact if specified; otherwise, minimum
GLX_DRAWABLE_TYPE	GLX_WINDOW_BIT	Mask
GLX_RENDER_TYPE	GLX_RGBA_BIT	Mask
GLX_X_RENDERABLE	No effect	Exact
GLX_FBCONFIG_ID	No effect	Exact

There are several uses for the glXChooseFBConfig() function:

• Retrieve an FBConfig with a given ID specified with GLX_FBCONFIG_ID.

• Retrieve the FBConfig that is the best match for a given list of visual attributes.

• Retrieve first a list of FBConfigs that match some criteria—for example, each FBConfig available on the screen or all double-buffered visuals available on the screen. Then call glXGetFBConfigAttrib() to find their attributes and choose the one that best fits your needs.

Once the FBConfig is obtained, you can use it to create a GLX pixmap, window, or pbuffer (see “Using Pixel Buffers”).

Below is a description of what happens when you call glXChooseFBConfig():

• If no matching FBConfig exists or if an error occurs (that is, an undefined GLX attribute is encountered in attrib_list, screen is invalid, or dpy does not support the GLX extension), then NULL is returned.

• If attrib_list is not NULL and more than one FBConfig is found, then an ordered list is returned with the FBConfigs that form the “best” match at the beginning of the list. (“How an FBConfig Is Selected” describes the selection process.) Use XFree() to free the memory returned by glXChooseFBConfig().

• If GLX_RENDER_TYPE is in attrib_list, the value that follows is a mask indicating which types of drawables will be created with it. For example, if GLX_RGBA_BIT | GLX_COLOR_INDEX_BIT is specified as the mask, then glXChooseFBConfig() searches for FBConfigs that can be used to create drawables that work with both RGBA and color index rendering contexts. The default value for GLX_RENDER_TYPE is GLX_RGBA_BIT.

  The attribute GLX_DRAWABLE_TYPE as as its value a mask indicating which drawables to consider. Use it to choose FBConfigs that can be used to create and render to a particular GLXDrawable. For example, if GLX_WINDOW_BIT | GLX_PIXMAP_BIT is specified as the mask for GLX_DRAWABLE_TYPE then glXChooseFBConfig() searches for FBConfigs that support both windows and GLX pixmaps. The default value for GLX_DRAWABLE_TYPE is GLX_WINDOW_BIT.

If an FBConfig supports windows it has an associated X visual. Use the GLX_X_VISUAL_TYPE attribute to request a particular type of X visual.

Note that RGBA rendering may be supported for any of the six visual types, but color index rendering can be supported only for PseudoColor, StaticColor, GrayScale, and StaticGray visuals (that is, single-channel visuals). The GLX_X_VISUAL_TYPE attribute is ignored if GLX_DRAWABLE_TYPE is specified in attrib_list and the mask that follows does not have GLX_WINDOW_BIT set.

GLX_X_RENDERABLE is a Boolean indicating whether X can be used to render into a drawable created with the FBConfig. This attribute is always true if the FBConfig supports windows and/or GLX pixmaps.

Retrieving FBConfig Attribute Values

To get the value of a GLX attribute for an FBConfig, call the following function:

int glXGetFBConfigAttrib(Display *dpy, GLXFBConfig config, int attribute, int *value)

If glXGetFBConfigAttrib() succeeds, it returns Success, and the value for the specified attribute is returned in value; otherwise, it returns an error.

---

Note: An FBConfig has an associated X visual if and only if the GLX_DRAWABLE_TYPE value has the GLX_WINDOW_BIT bit set.

---

To retrieve the associated visual, call the following function:

XVisualInfo *glXGetVisualFromFBConfig(Display *dpy, GLXFBConfig config)

If config is a valid FBConfig and it has an associated X visual, then information describing that visual is returned; otherwise, NULL is returned. Use XFree() to free the returned data.

To create a GLX rendering context, a GLX window, or a GLX pixmap using an FBConfig, call glXCreateNewContext(), glXCreateWindow(), or glXCreatePixmap(). Their formats follow:

GLXContext glXCreateNewContext( Display *dpy, GLXFBConfig config, int render_type, GLXContext share_list, Bool direct ) GLXWindow glXCreateWindow( Display *dpy,GLXFBConfig config, Window win, const int *attrib_list) GLXPixmap glXCreatePixmap( Display *dpy,GLXFBConfig config, Pixmap pixmap, const int *attrib_list)

The window passed to glXCreateWindow() must be created with an X visual corresponding to config; that is, it should be created using the same visual returned by glXGetVisualFromFBConfig() for that FBConfig. Similarly, the pixmap passed to glXCreatePixmap() must have the same color depth as config. If these requirements are not met, creating the window or pixmap will fail with an X BadMatch error.

The attrib_list argument specifies optional additional attributes to use in creating windows or pixmaps. Currently no additional attributes are defined; so, this parameter must always be NULL.

These functions are analogous to the glXCreateContext() and glXCreateGLXPixmap() functions, but they use GLXFBConfigs instead of visuals. See the glXCreateNewContext, glXCreateWindow, and glXCreatePixmap man pages for detailed information.

To create a pixel buffer using an FBConfig, see “Using Pixel Buffers”.

The FBConfig feature introduces the following functions:

OpenGL supports two rendering modes: RGBA mode and color-index mode.

OpenGL color modes are described in some detail in the section “RGBA versus Color-Index Mode” in Chapter 5, “Color,” of the OpenGL Programming Guide.

The X Window System supports six different types of visuals, with each type using a different type of colormap (see Table 4-1). Although working with X colormaps may initially seem somewhat complicated, the X Window System does allow you a great deal of flexibility in choosing and allocating colormaps. Colormaps are described in detail with example programs in Chapter 7, “Color,” of O'Reilly
Volume One.

The rest of this section addresses some issues having to do with X colormaps.

Colormap
getColormap(XVisualInfo * vi)
{
    Status          status;
    XStandardColormap *standardCmaps;
    Colormap        cmap;
    int             i, numCmaps;

    /* be lazy; using DirectColor too involved for this example */
    if (vi->class != TrueColor)
        fatalError(“no support for non-TrueColor visual”);
    /* if no standard colormap but TrueColor, make an unshared one */
    status = XmuLookupStandardColormap(dpy, vi->screen, vi->visualid,
        vi->depth, XA_RGB_DEFAULT_MAP, 
        /* replace */ False, /* retain */ True);
    if (status == 1) {
        status = XGetRGBColormaps(dpy, RootWindow(dpy, vi->screen),
                             &standardCmaps, &numCmaps, 
                             XA_RGB_DEFAULT_MAP);
        if (status == 1)
            for (i = 0; i < numCmaps; i++)
                if (standardCmaps[i].visualid == vi->visualid) {
                    cmap = standardCmaps[i].colormap;
                    XFree(standardCmaps);
                    return cmap;
                }
    }
    cmap = XCreateColormap(dpy, RootWindow(dpy, vi->screen),
        vi->visual, AllocNone);
    return cmap;
}

When choosing which colormap to use, follow these heuristics:

Many OpenGL applications use a 24-bit TrueColor visual (by specifying GLX_RGBA in the visual attribute list when choosing a visual). Colors usually look right in TrueColor, and some overhead is saved by not having to look up values in a table. On some systems, using 24-bit color can slow down the frame rate because more bits must be updated per pixel, but this is not usually a problem.

If you want to adjust or rearrange values in a colormap, you can use a PseudoColor visual.

Lighting and antialiasing are difficult in color-index mode, and texturing and accumulation do not work at all. It may be easier to use double buffering and redraw to produce a new differently colored image, or use the overlay plane. In general, avoid using PseudoColor visuals if possible. Overlays, which always have PseudoColor colormaps on current systems, are an exception to this.

The following is a brief example that demonstrates how to store colors into a given colormap cell:

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

    ...

if (ind < visual->colormap_size) {

    xc.pixel = ind;

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

}

---

Note: Do not use AllocAll on overlay visuals with transparency. If you do, XCreateColormap() fails because the transparent cell is read-only.

---

Stereo rendering is done only using quad-buffered stereo. Legacy, low-end Silicon Graphics systems support a different stereo interface referred to as divided-screen stereo, which is no longer described in this document.

Quad-buffered stereo uses a separate buffer for the left and right eye; this results in four buffers if the program is already using a front and back buffer for animation. Quad-buffered stereo is supported on all current Silicon Graphics systems .

For more information on stereo rendering, see the man pages for the following functions:

To perform stereo rendering, follow these steps:

For more information, see the glDrawBuffer() man page.

A GLXPbuffer or pbuffer is an additional non-visible rendering pbuffer for an OpenGL renderer. A pbuffer has the following distinguishing characteristics:

To create a pbuffer, call glXCreatePbuffer():

GLXPbuffer glXCreatePbuffer(Display *dpy, GLXFBConfig config,
                             int attrib_list)

This call creates a single pbuffer and returns its XID.

The parameter attrib_list specifies a list of attributes for the pbuffer. Note that the attribute list is defined in the same way as the list for glXChooseFBConfig(): attributes are immediately followed by the corresponding desired value and the list is terminated with None.

The following attributes can be specified in attrib_list:

The resulting pbuffer contains color buffers and ancillary buffers as specified by config. It is possible to create a pbuffer with back buffers and to swap the front and back buffers by calling glXSwapBuffers(). Note that a pbuffer uses framebuffer resources; so, applications should deallocate it when not in use—for example, when the application windows are iconified.

If glXCreatePbuffer() fails to create a pbuffer due to insufficient resources, a BadAlloc X protocol error is generated and NULL is returned. If config is not a valid FBConfig, then a GLXBadFBConfig error is generated; if config does not support pbuffers, a BadMatch X protocol error is generated.

Any GLX rendering context created with an FBConfig or X visual that is compatible with an FBConfig may be used to render into the pbuffer. For the definition of compatible, see the man pages for glXCreateNewContext(), glXMakeCurrent(), and glXMakeCurrentReadSGI().

If a pbuffer is created with GLX_PRESERVED_CONTENTS set to false, the storage for the buffer contents—or a portion of the buffer contents—may be lost at any time. It is not an error to render to a pbuffer that is in this state, but the effect of rendering to it is undefined. It is also not an error to query the pixel contents of such a pbuffer, but the values of the returned pixels are undefined.

Because the contents of a volatile pbuffer can be lost at any time with only asynchronous notification (using the buffer clobber event), the only way a client can guarantee that valid pixels are read back with glReadPixels() is by grabbing the X server. Note that this operation is potentially expensive and you should not do it frequently. Also, because grabbing the X server locks out other X clients, you should do it only for short periods of time. Clients that do not wish to grab the X server can check whether the data returned by glReadPixels() is valid by calling XSync() and then checking the event queue for “ buffer clobber events (assuming that any previous clobber events were pulled off of the queue before the glReadPixels() call).

To destroy a pbuffer call  glXDestroyPbuffer(), whose format follows:

void glXDestroyPbuffer(Display *dpy, GLXPbuffer pbuf)

To query an attribute associated with a GLX drawable (GLXWindow, GLXPixmap, or GLXPbuffer), call glXQueryDrawable(), whose format follows:

void glXQueryDrawable(Display *dpy, GLXDrawable drawable, int attribute
                           unsigned int *value)

The GLX_WIDTH, GLX_HEIGHT, and GLX_FBCONFIG_ID attributes may be queried for all types of drawables. The query returns respectively the allocated pixel width, pixel height, and the XID of the FBConfig with respect to which the drawable was created.

The GLX_PRESERVED_CONTENTS and GLX_LARGEST_PBUFFER attributes are meaningful only for GLXPbuffer drawables and return the values specified when the pbuffer was created. The values returned when querying these attributes for GLXWindow or GLXPixmap drawables are undefined.

To find the FBConfig for a drawable, first retrieve the ID for the FBConfig using glXQueryDrawable() and then call glXChooseFBConfig() with that ID specified as the GLX_FBCONFIG_ID attribute value in the attribute list. For more details, see “Using Framebuffer Configurations”.

An X client can ask to receive GLX events on a GLXWindow or GLXPbuffer by calling glXSelectEvent():

void glXSelectEvent(Display *dpy, GLXDrawable drawable,
                       unsigned long event_mask)

Currently, you can only select the GLX_BUFFER_CLOBBER_MASK GLX event bit in event_mask. The event structure is as follows:

typedef struct {
  int event_type;           /* GLX_DAMAGED or GLX_SAVED */
  int draw_type;            /* GLX_WINDOW or GLX_PBUFFER */
  unsigned long serial;     /* Number of last request processed */
                            /* by server */
  Bool send_event;          /* True if event was generated by a */
                            /* SendEvent request */
  Display *display;         /* Display the event was read from */
  GLXDrawable drawable;     /* XID of Drawable */
  unsigned int buffer_mask; /* Mask indicating which buffers are */
                            /* affected */
  unsigned int aux_buffer;  /* Which aux buffer was affected */
  int x, y;
  int width, height;
  int count;                /* If nonzero, at least this many more */
                            /* events*/
} GLXPbufferClobberEvent;

A single X server operation can cause several buffer clobber events to be sent; for example, a single pbuffer may be damaged and cause multiple buffer clobber events to be generated. Each event specifies one region of the GLXDrawable that was affected by the X server operation.

Events are sent to the application and queried using the normal X event commands (XNextEvent(), XPending(), and so on). The event_mask value returned in the event structure indicates which color and ancillary buffers were affected. The following values can be set in the event structure:

GLX_FRONT_LEFT_BUFFER_BIT
GLX_FRONT_RIGHT_BUFFER_BIT
GLX_BACK_LEFT_BUFFER_BIT
GLX_BACK_RIGHT_BUFFER_BIT
GLX_AUX_BUFFERS_BIT
GLX_DEPTH_BUFFER_BIT
GLX_STENCIL_BUFFER_BIT
GLX_ACCUM_BUFFER_BIT

All the buffer clobber events generated by a single X server action are guaranteed to be contiguous in the event queue. The conditions under which this event is generated and the event type vary, depending on the type of the GLXDrawable:

Calling glXSelectEvent() overrides any previous event mask that was set by the client for the drawable. Note that it does not affect the event masks that other clients may have specified for a drawable, because each client rendering to a drawable has a separate event mask for it.

To find out which GLX events are selected for a window or pbuffer, call glXGetSelectedEvent():

void glXSelectEvent(Display *dpy, GLXDrawable drawable,
                       unsigned long event_mask)

The GLX pbuffer feature provides the following functions:

Integrating an OpenGL program with a pixmap is very similar to integrating it with a window. The following steps describe how you create and use pixmaps.

---

Note: Steps 1–3 and step 6 are described in detail in “Integrating Your OpenGL Program With IRIS IM” in Chapter 2.

---

OpenGL rendering is done differently in different rendering contexts (and on different platforms).

In indirect rendering, OpenGL rendering commands are added to the GLX protocol stream, which in turn is part of the X protocol stream. Commands are encoded and sent to the X server. Upon receiving the commands, the X server decodes them and dispatches them to the GLX extension. Control is then given to the GLX process (with a context switch) so that the rendering commands can be processed. The faster the graphics hardware, the higher the overhead from indirect rendering.

You can obtain maximum indirect-rendering speed by using display lists; they require a minimum of interaction with the X server. Unfortunately, not all applications can take full advantage of display lists; this is particularly a problem in applications using rapidly-changing scene structures. Display lists are efficient because they reside in the X server.

You may see multiple X processes on your workstation when you are running indirect rendering OpenGL programs.