The X server provided by Silicon Graphics includes some enhancements that not all servers have: Support for visuals with different colormaps, overlay windows, the Display PostScript extension, the Shape extension, the X input extension, the Shared Memory extension, the SGI video control extension, and simultaneous displays on multiple graphics monitors. Specifically for working with OpenGL programs, Silicon Graphics offers the GLX extension discussed in the next section.

To see what extensions to the X Window System are available on your current system, execute xdpyinfo and check the extensions named below the “number of extensions” line.

The GLX extension, which integrates OpenGL and X, is used by X servers that support OpenGL. GLX is both an API and an X extension protocol for supporting OpenGL. GLX routines provide basic interaction between X and OpenGL. Use them, for example, to create a rendering context and bind it to a window.

To compile a program that uses the GLX extension, include the GLX header file (/usr/include/GL/glx.h), which includes relevant X header files and the standard OpenGL header files. If desired, include also the GLU utility library header file (/usr/include/GL/glu.h).

Table 2-1 provides an overview of the headers and libraries you need to include.

A standard X visual specifies how the server should map a given pixel value to a color to be displayed on the screen. Different windows on the screen can have different visuals.

Currently, GLX allows RGB rendering to TrueColor and DirectColor visuals and color index rendering to StaticColor or PseudoColor visuals. See Table 4-1 for information about the visuals and their supported OpenGL rendering modes. The framebuffer configuration extension allows additional combinations. See “SGIX_fbconfig—The Framebuffer Configuration Extension”.

GLX overloads X visuals to include both the standard X definition of a visual and OpenGL specific information about the configuration of the framebuffer and ancillary buffers that might be associated with a drawable. Only those overloaded visuals support both OpenGL and X rendering—GLX therefore requires that an X server support a high minimum baseline of OpenGL functionality.

When you need visual information,

Not all X visuals support OpenGL rendering, but all X servers capable of OpenGL rendering have at least two OpenGL capable visuals. The exact number and type vary among different hardware systems. A Silicon Graphics system typically supports many more than the two required Open GL capable visuals. An RGBA visual is required for any hardware system that supports OpenGL; a color index visual is required only if the hardware requires color index. To determine the OpenGL configuration of a visual, you must use a GLX function.

Visuals are discussed in some detail in “Using Visuals”. Table 4-1 illustrates which X visuals support which type of OpenGL rendering and whether the colormaps for those visuals are writable or not.

As a rule, a drawable is something X can draw into, either a window or a pixmap (an exception is pbuffers, which are GLX drawables but cannot be used for X rendering). A GLX drawable is something both OpenGL can draw into, either an OpenGL capable window or a GLX pixmap. (A GLX pixmap is a handle to an X pixmap that is allocated in a special way; see Figure 4-2.) Different ways of creating a GLX drawable are discussed in “Drawing-Area Widget Setup and Creation”, “Creating a Colormap and a Window”, and “Using Pixmaps”.

Another kind of GLX drawable is the pixel buffer (or pbuffer), which permits hardware-accelerated off-screen rendering. See “SGIX_pbuffer—The Pixel Buffer Extension”.

A rendering context (GLXContext) is an OpenGL data structure that contains the current OpenGL rendering state; an instance of an OpenGL state machine. (For more information, see the section “OpenGL as a State Machine” in Chapter 1, “Introduction to OpenGL,” of the OpenGL Programming Guide.) Think of a context as a complete description of how to draw what the drawing commands specify.

At most one rendering context can be bound to at most one window or pixmap in a given thread. If a context is bound, it is considered the current context.

OpenGL routines don't specify a drawable or rendering context as parameters. Instead, they implicitly affect the current bound drawable using the current rendering context of the calling thread.

Resources, in X, are data structures maintained by the server rather than by client programs. Colormaps (as well as windows, pixmaps, and fonts) are implemented as resources.

Rather than keeping information about a window in the client program and sending an entire window data structure from client to server, for instance, window data is stored in the server and given a unique integer ID called an XID. To manipulate or query the window data, the client sends the window's ID number; the server can then perform any requested operation on that window. This reduces network traffic.

Because pixmaps and windows are resources, they are part of the X server and can be shared by different processes (or threads). OpenGL contexts are also resources. In standard OpenGL, they can be shared by threads in the same process but not by separate processes because the API doesn't support this. (Sharing by different processes is possible if the import context extension is supported. See “SGIX_fbconfig—The Framebuffer Configuration Extension”.)

---

Note: The term “resource” can, in other X-related contexts, refer to items handled by the Resource Manager, items that users can customize for their own use. Don't confuse the two meanings of the word.

---

A colormap maps pixel values from the framebuffer to intensities on screen. Each pixel value indexes into the colormap to produce intensities of red, green, and blue for display. Depending on hardware limitations, one or more colormaps may be installed at one time, such that windows associated with those maps display with the correct colors. If there is only one colormap, two windows that load colormaps with different values look correct only when they have their particular colormap is installed. The X window manager takes care of colormap installation and tries to make sure that the X client with input focus has its colormaps installed. On all systems, the colormap is a limited resource.

Every X window needs a colormap. If you are using the OpenGL drawing area-widget to render in RGB mode into a TrueColor visual, you may not need to worry about the colormap. In other cases, you may need to assign one. For additional information, see “Using Colormaps”. Colormaps are also discussed in detail in O'Reilly, Volume One.

Widgets are built using Xt, the X Toolkit Intrinsics, a library of routines for creating and using widgets. Xt is a “meta” toolkit used to build toolkits like Motif or IRIS IM; you can, in effect, use it to extend the existing widgets in your widget sets. Xt uses a callback-driven programming model. It provides tools for common tasks like input handling and animation and frees you from having to handle a lot of the details of Xlib programming.

Note that in most (but not all) cases, using Xlib is necessary only for colormap manipulation, fonts, and 2D rendering. Otherwise, Xt and IRIS IM are enough, though you may pay a certain performance penalty for using widgets instead of programming directly in Xlib.

Standard Xt is discussed in detail in O'Reilly, Volume Four. Standard Motif widgets are discussed in more detail in O'Reilly, Volume Six. See “Background Reading” for full bibliographic information and for pointers to additional documents about Motif and IRIS IM. The recently published book on OpenGL and X (Kilgard 1996) is particularly helpful for OpenGL developers.

Before making any GLX (or OpenGL) calls, a program must open a display (required) and should find out whether the X server supports GLX (optional).

To open a display, use XOpenDisplay() if you are programming with Xlib, or XtOpenApplication() if you are working with widgets as in Example 2-1 above. XtOpenApplication() actually opens the display and performs some additional setup:

It is recommend (but not required) that you find out whether the X server supports GLX by calling glXQueryExtension().

Bool glXQueryExtension ( Display *dpy, int *errorBase, int *eventBase )

In most cases, NULL is appropriate for both errorBase and eventBase. See the glXQueryExtension reference page for more information.

---

Note: This call is not required (and therefore not part of motif/simplest.c), because glXChooseVisual() simply fails if GLX is not supported. It is included here because it is recommended for the sake of portability.

---

If glXQueryExtension() succeeds, use glXQueryVersion() to find out which version of GLX is being used; an older version of the extension may not be able to do everything your version can do.The following pseudo-code demonstrates checking for the version number:

glXQueryVersion(dpy, &major, &minor);
if (((major == 1) && (minor == 0)){
     /*assume GLX 1.0, avoid GLX 1.1 functionality*/
     }
     else{
      /*can use GLX 1.1 functionality*/
     }
 } 

Currently, GLX 1.0 and GLX 1.1 are supported as follows:

GLX 1.1 supports a few additional functions and provides a mechanism for using extensions. See the glxintro reference page.

A visual determines how pixel values are mapped to the screen. The display mode of your OpenGL program (RGBA or color index) determines which X visuals are suitable. To find a visual with the attributes you want, call glXChooseVisual() with the desired parameters. Here is the function prototype:

XVisualInfo* glXChooseVisual(Display *dpy, int screen, int *attribList)

The visual returned by glXChooseVisual() is always a visual that supports OpenGL. It is guaranteed to have Boolean attributes matching those specified, and integer attributes with values at least as large as those specified. For detailed information, see the glXChooseVisual reference page.

---

Note: Be aware that Xlib provides these three different but related visual data types. glXChooseVisual() actually returns an XVisualInfo*, which is a different entity form a visual* or a visual ID. XCreateWindow(), on the other hand, requires a visual*, not an XVisualInfo*.

---

The framebuffer capabilities and other attributes of a window are determined statically by the visual used to create it. For example, to change a window from single-buffer to double-buffer, you have to switch to a different window created with a different visual.

---

Note: In general, ask for 1 bit of red, green, and blue to get maximum color resolution. Zero matches to the smallest available color resolution.

---

Instead of calling glXChooseVisual(), you can also choose a visual as follows:

There is also an experimental extension that allows you to create and choose a glXFBConfig construct, which packages GLX drawable information, for use instead of a visual. See “SGIX_fbconfig—The Framebuffer Configuration Extension”.

Creating a rendering context is the application's responsibility. Even if you choose to use IRIS IM, the widget does no context management. Before you can draw anything, you must therefore create a rendering context for OpenGL using glXCreateContext(), which has the following function prototype:

GLXContext glXCreateContext(Display *dpy, XVisualInfo *vis,
                            GLXContext shareList, Bool direct)

Here's how you use the arguments:

After picking a visual and creating a context, you need to create a drawable (window or pixmap) that uses the chosen visual. How you create the drawable depends on whether you use Xlib or Motif calls and is discussed, with program examples, in “Drawing-Area Widget Setup and Creation” and “Creating a Colormap and a Window”.

If you are working with Xlib, bind the context to the window by calling glXMakeCurrent(). Example 3-2 is a complete Xlib program and illustrates how the function is used.

If you are working with widgets and have an OpenGL context and a window, bind them together with GLwDrawingAreaMakeCurrent(). This IRIS IM function is a front end to glXMakeCurrent(); it allows you to bind the context to the window without having to know the drawable ID and display.

If GLwDrawingAreaMakeCurrent() is successful, subsequent OpenGL calls use the new context to draw on the given drawable. The call fails if the context and the drawable are mismatched; that is, if they were created with different visuals.

---

Note: Don't make OpenGL calls until the context and window have been bound (made current).

---

For each thread of execution, at most one context can be bound to at most one window or pixmap.

---

Note: “EXT_make_current_read—The Make Current Read Extension” allows you to attach separate read and write drawables to a GLX context.

---

A window can become visible only if it is mapped and all its parent windows are mapped. Note that mapping the window is not directly related to binding it to an OpenGL rendering context, but both need to happen if you want to display an OpenGL application.

Mapping the window or realizing the widget is not synchronous with the call that performs the action. When a window is mapped, the window manager makes it visible if no other actions are specified to happen before. For example, some window managers display just an outline of the window instead of the window itself, letting the user position the window. When the user clicks, the window becomes visible.

If a window is mapped but is not yet visible, you may already set OpenGL state; for example, you may load textures or set colors, but rendering to the window is discarded (this includes rendering to a back buffer if you are doing double-buffering). You need to get an Expose event—if using Xlib—or the expose callback before the window is guaranteed to be visible on the screen. The init callback doesn't guarantee that the window is visible, only that it exists.

How you map the window on the screen depends on whether you have chosen to create an X window from scratch or use a widget: