glXIntro - Introduction to OpenGL in the X window system
OVERVIEW
OpenGL (called GL in other pages) is a high-performance
3D-oriented renderer. It is available in the X window
system through the GLX extension. To determine whether
the GLX extension is supported by an X server, and if so,
what version is supported, call glXQueryExtension and
glXQueryVersion.
GLX extended X servers make a subset of their visuals
available for OpenGL rendering. Drawables created with
these visual can also be rendered into using the core X
renderer and or any other X extension that is compatible
with all core X visuals.
GLX extends a drawable's standard color buffer with addi-
tional buffers. These buffers include back and auxiliary
color buffers, a depth buffer, a stencil buffer, and a
color accumulation buffer. Some or all of the buffers
listed are included in each X visual that supports OpenGL.
GLX supports rendering into three types of drawables: win-
dows, pixmaps and pbuffers (pixel buffers). GLX windows
and pixmaps are X resources, and capable of accepting core
X rendering as well as OpenGL rendering. GLX pbuffers are
GLX only resources, and might not accept core X rendering.
To render using OpenGL into a GLX drawable, you must
determine the appropriate GLXFBConfig which supports the
rendering features your application requires.
glXChooseFBConfig returns a GLXFBConfig matching the
required attributes, or NULL if no match is found. A com-
plete list of GLXFBConfigs supported by a server can be
obtained by calling glXGetFBConfigs. Attributes of a par-
ticular GLXFBConfig can be queried by calling
glXGetFBConfigAttrib.
For GLX windows and pixmaps, a suitable X drawable (using
either XCreateWindow or XCreatePixmap, respectively) with
a matching visual must be created first. Call
glXGetVisualFromFBConfig to obtain the necessary XVisual-
Info structure for creating the X drawable. For pbuffers,
no underlying X drawable is required.
To create a GLX window from an X window, call
glXCreateWindow. Likewise, to create a GLX pixmap, call
glXCreatePixmap. Pbuffers are created by calling
glXCreatePbuffer. Use glXDestroyWindow, glXDestroyPixmap,
and glXDestroyPbuffer to release previously allocated
resources.
ified using by calling glXWaitGL, glXWaitX, XSync, and
XFlush.
EXAMPLES
Below is a minimal example of creating an RGBA-format, X
window that's compatible with OpenGL using GLX 1.3 com-
mands. The window is cleared to yellow when the program
runs. The program does minimal error checking; all return
values should be checked.
#include <stdio.h> #include <stdlib.h> #include <GL/gl.h>
#include <GL/glx.h>
int singleBufferAttributess[] = {
GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
GLX_RENDER_TYPE, GLX_RGBA_BIT,
GLX_RED_SIZE, 1, /* Request a single buffered
color buffer */
GLX_GREEN_SIZE, 1, /* with the maximum number of
color bits */
GLX_BLUE_SIZE, 1, /* for each component
*/
None };
int doubleBufferAttributes[] = {
GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
GLX_RENDER_TYPE, GLX_RGBA_BIT,
GLX_DOUBLEBUFFER, True, /* Request a double-buffered
color buffer with */
GLX_RED_SIZE, 1, /* the maximum number of
bits per component */
GLX_GREEN_SIZE, 1,
GLX_BLUE_SIZE, 1,
None };
static Bool WaitForNotify( Display *dpy, XEvent *event,
XPointer arg ) {
return (event->type == MapNotify) && (event->xmap.win-
dow == (Window) arg); }
GLXContext context;
GLXWindow glxWin;
int swaMask;
int numReturned;
int swapFlag = True;
/* Open a connection to the X server */
dpy = XOpenDisplay( NULL );
if ( dpy == NULL ) {
printf( "Unable to open a connection to the X
server0 );
exit( EXIT_FAILURE );
}
/* Request a suitable framebuffer configuration - try
for a double
** buffered configuration first */
fbConfigs = glXChooseFBConfig( dpy, Default-
Screen(dpy),
doubleBufferAttributes,
&numReturned );
if ( fbConfigs == NULL ) { /* no double buffered con-
figs available */
fbConfigs = glXChooseFBConfig( dpy, Default-
Screen(dpy),
singleBufferAttribut-
ess, &numReturned );
swapFlag = False;
}
/* Create an X colormap and window with a visual
matching the first
** returned framebuffer config */
vInfo = glXGetVisualFromFBConfig( dpy, fbConfigs[0] );
swa.border_pixel = 0;
swa.event_mask = StructureNotifyMask;
swa.colormap = XCreateColormap( dpy, RootWindow(dpy,
vInfo->screen),
vInfo->visual, Alloc-
None );
swaMask = CWBorderPixel | CWColormap | CWEventMask;
xWin = XCreateWindow( dpy, RootWindow(dpy,
vInfo->screen), 0, 0, 256, 256,
0, vInfo->depth, InputOutput,
vInfo->visual,
swaMask, &swa );
/* Create a GLX context for OpenGL rendering */
/* Bind the GLX context to the Window */
glXMakeContextCurrent( dpy, glxWin, glxWin, context );
/* OpenGL rendering ... */
glClearColor( 1.0, 1.0, 0.0, 1.0 );
glClear( GL_COLOR_BUFFER_BIT );
glFlush();
if ( swapFlag )
glXSwapBuffers( dpy, glxWin );
sleep( 10 );
exit( EXIT_SUCCESS ); }
NOTES
An X color map must be created and passed to XCreateWin-
dow.
A GLX context must be created and bound to a GLX drawable
before OpenGL commands can be executed. OpenGL commands
executed while no context/drawable pair is current result
in undefined behavior.
Exposure events indicate that all buffers associated with
the specified window may be damaged and should be
repainted. Although certain buffers of some visuals on
some systems may never require repainting (the depth
buffer, for example), it is incorrect to write a program
assuming that these buffers will not be damaged.
GLX commands utilize XVisualInfo structures rather than
pointers to visuals or visualIDs directly. XVisualInfo
structures contain visual, visualID, screen, and depth
elements, as well as other X-specific information.
USING GLX EXTENSIONS
All supported GLX extensions will have a corresponding
definition in glx.h and a token in the extension string
returned by glXQueryExtensionsString. For example, if the
EXT_visual_info extension is supported, then this token
will be defined in glx.h and EXT_visual_info will appear
in the extension string returned by
glXQueryExtensionsString. The definitions in glx.h can be
used at compile time to determine if procedure calls cor-
responding to an extension exist in the library.
OpenGL itself is capable of being extended. Refer to
glIntro for more information.
glXQueryDrawable, glXCreateNewContext,
glXMakeContextCurrent, glXGetCurrentReadDrawable,
glXGetCurrentDisplay, glXQueryContext, glXSelectEvent,
glXGetSelectedEvent.
GLX 1.2 corresponds to OpenGL version 1.1 and introduced
the following new call: glGetCurrentDisplay.
GLX 1.1 corresponds to OpenGL version 1.0 and introduces
the following new calls: glXQueryExtensionsString,
glXQueryServerString, and glXGetClientString.
Call glQueryVersion to determine at runtime what version
of GLX is available. glQueryVersion returns the version
that is supported on the connection. Thus if 1.3 is
returned, both the client and server support GLX 1.3. You
can also check the GLX version at compile time: GLX_VER-
SION_1_1 will be defined in glx.h if GLX 1.1 calls are
supported, GLX_VERSION_1_2 will be defined if GLX 1.2
calls are supported, and GLX_VERSION_1_3 will be defined
if GLX 1.3 calls are supported.
SEE ALSO
glIntro, glFinish, glFlush, glXChooseVisual,
glXCopyContext, glXCreateContext, glXCreateGLXPixmap,
glXDestroyContext, glXGetClientString, glXGetConfig,
glXIsDirect, glXMakeCurrent, glXQueryExtension,
glXQueryExtensionsString, glXQueryServerString,
glXQueryVersion, glXSwapBuffers, glXUseXFont, glXWaitGL,
glXWaitX, glXGetFBConfigs, glXGetFBConfigAttrib,
glXGetVisualFromFBConfig, glXCreateWindow,
glXDestroyWindow, glXCreatePixmap, glXDestroyPixmap,
glXCreatePbuffer, glXDestroyPbuffer, glXQueryDrawable,
glXCreateNewContext, glXMakeContextCurrent,
glXGetCurrentReadDrawable, glXGetCurrentDisplay,
glXQueryContext, glXSelectEvent, glXGetSelectedEvent.
XCreateColormap, XCreateWindow, XSync
1