glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)NAME
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 additional 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: windows, 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 complete list
of GLXFBConfigs supported by a server can be obtained by calling
glXGetFBConfigs. Attributes of a particular 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
XVisualInfo 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.
A GLX context is required to bind OpenGL rendering to a GLX resource. A
GLX resource and rendering context must have compatible GLXFBConfigs. To
create a GLX context, call glXCreateNewContext. A context may be bound
to a GLX drawable by using glXMakeContextCurrent. This context/drawable
pair becomes the current context and current drawable, and is used by all
Page 1
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
OpenGL rendering commands until glXMakeContextCurrent is called with
different arguments.
Both core X and OpenGL commands can be used to operate on drawables,
however, the X and OpenGL command streams are not synchronized.
Synchronization can be explicitly specified 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 commands. 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.window == (Window) arg);
}
Page 2
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
int main( int argc, char *argv[] )
{
Display *dpy;
Window xWin;
XEvent event;
XVisualInfo *vInfo;
XSetWindowAttributes swa;
GLXFBConfig *fbConfigs;
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 server\n" );
exit( EXIT_FAILURE );
}
/* Request a suitable framebuffer configuration - try for a double
** buffered configuration first */
fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
doubleBufferAttributes, &numReturned );
if ( fbConfigs == NULL ) { /* no double buffered configs available */
fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
singleBufferAttributess, &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, AllocNone );
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 */
context = glXCreateNewContext( dpy, fbConfigs[0], GLX_RGBA_TYPE,
NULL, True );
/* Create a GLX window to associate the frame buffer configuration
Page 3
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
** with the created X window */
glxWin = glXCreateWindow( dpy, fbConfigs[0], xWin, NULL );
/* Map the window to the screen, and wait for it to appear */
XMapWindow( dpy, xWin );
XIfEvent( dpy, &event, WaitForNotify, (XPointer) xWin );
/* 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 XCreateWindow.
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.
GLX EXTENSIONS
The SGI_video_sync extension provides a means for synchronization with
the video frame rate of a monitor--or, in the case of an interlaced
monitor, with the field rate of the monitor. For more information see:
glXGetVideoSyncSGI, glXWaitVideoSyncSGI.
The SGI_swap_control extension provides new parameters that modify the
semantics of glXSwapBuffers. With this extension an application can
specify a minimum periodicity for color buffer swaps, measured in display
Page 4
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
retrace periods. For more information see glXSwapIntervalSGI.
The EXT_import_context allows multiple X clients to share an indirect
rendering context. Also, two convenience routines are added: one to get
the display for the current context and one to retrieve the attributes
that a context was created with. For more information see
glXGetCurrentDisplayEXT, glXQueryContextInfoEXT, glXGetContextIDEXT,
glXImportContextEXT, and glXFreeContextEXT.
The EXT_visual_rating extension allows servers to identify a particular
GLX visual as undesirable. A new visual attribute is introduced,
providing a way for servers to specify caveats (e.g., slow or non-
conformant) for a visual. The attribute may be queried using
glXGetConfig; it is also used by glXChooseVisual to discriminate against
visuals with caveats.
This extension allows servers to export visuals with improved features or
image quality, but lower performance or greater system burden, without
having to have these visuals selected preferentially.
The EXT_visual_info extension allows the user to request a particular X
visual type to be associated with a GLX visual, and allows the user to
query the X visual type underlying a GLX visual. In addition, this
extension provides a means to request a visual with a transparent pixel
and to query whether a visual supports a transparent pixel value and the
value of the transparent pixel.
The SGIX_fbconfig extension introduces a new way to describe the
capabilities of a GLX drawable (i.e., to describe the depth of color
buffer components and the type and size of ancillary buffers), removes
the "similarity" requirement when making a context current to a drawable,
and supports RGBA rendering to one- and two-component Windows and GLX
Pixmaps. For more information see glXGetFBConfigAttribSGIX,
glXChooseFBConfigSGIX, glXCreateGLXPixmapWithConfigSGIX,
glXCreateContextWithConfigSGIX, glXGetVisualFromFBConfigSGIX,
glXGetFBConfigFromVisualSGIX.
The SGIX_pbuffer extension defines GLX pixel buffers, which are
additional non-visible rendering buffers for an OpenGL renderer. GLX
pixel buffers are typically allocated in non-visible frame buffer memory.
They are intended to be "static" resources, in that a program will
typically allocate them only once, rather than as a part of its rendering
loop. Also the frame buffer resources that are associated with a GLX
pixel buffer are static, and are deallocated only when the GLXPbuffer is
destroyed, or, in the case of a unpreserved GLX pixel buffer, as a result
of X server activity that changes its frame buffer requirements. For
more information see glXCreateGLXPbufferSGIX, glXDestroyGLXPbufferSGIX,
glXQueryGLXPbufferSGIX, glXSelectEventSGIX, glXGetSelectedEventSGIX.
SGIX_pbuffer is only supported on RealityEngine, RealityEngine2, and VTX
systems, InfiniteReality systems, Solid Impact systems, High Impact and
Maximum Impact systems, O2 systems, and Octane2 VPro systems.
Page 5
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
The SGIX_dm_pbuffer extension, with the addition of a DigitalMedia
attribute, defines a type of GLX pixel buffer that can acquire one or
more of its renderable buffers from a DMbuffer generated by video,
compression, or other media library. A single DigitalMedia pixel buffer
can be associated with a sequence of DMbuffers having the same
configuration, making them directly OpenGL readable and renderable.
Frame buffer resources that are not acquired from the DMbuffer are
identical to those of a standard GLX pixel buffer. For more information
see glXCreateGLXPbufferSGIX, glXAssociateDMPbufferSGIX, DMbuffer,
dmBufferGetGLPoolParams. SGIX_dm_pbuffer is only supported on O2
systems.
The SGIS_multisample extension provides a mechanism to antialias all
primitives. (This extension is described in more detail in glIntro.) In
order to support multisampling both GLX and OpenGL had to be extended.
The GLX portion of the extension, designated as GLX_SGIS_multisample,
includes new visual attributes which can be specified when calling
glXChooseVisual and glXGetConfig. SGIS_multisample is only supported on
RealityEngine, RealityEngine2, and VTX systems, and InfiniteReality
systems.
The SGI_make_current_read extension allows OpenGL pixel operations to
read pixel data from the buffers of one drawable and draw into the
buffers of another. For example, pixels can be copied from one window
into another, or from a GLX pixel buffer into a window. For more
information see glXMakeCurrentReadSGI and glXGetCurrentReadDrawableSGI.
SGI_make_current_read is only supported on RealityEngine, RealityEngine2,
and VTX systems, InfiniteReality systems, Solid Impact systems, High
Impact and Maximum Impact systems, O2 systems, and Octane2 VPro systems.
The SGIX_video_source extension allows pixel data to be sourced from a
video input stream. It defines a new type of drawable,
GLXVideoSourceSGIX, that represents the drain node of a Video Library
(VL) path. A GLXVideoSourceSGIX may be passed as a parameter to
glXMakeCurrentReadSGI to indicate that pixel data should be read from the
specified video source instead of from the framebuffer. For more
information, see glXCreateGLXVideoSourceSGIX and
glXDestroyGLXVideoSourceSGIX. SGIX_video_source is only supported on
RealityEngine, RealityEngine2, and VTX systems, and InfiniteReality
systems.
The SGIX_video_resize extension allows the frame buffer to be resized to
the output resolution of the video channel when glXSwapBuffers is called
for the window that is bound to the video channel. SGIX_video_resize is
only supported on InfiniteReality systems.
USING GLX EXTENSIONS
Procedure names and tokens for GLX extensions are either suffixed with
EXT, SGI, SGIS or SGIX. The meaning of these suffixes is described in
glIntro.
Page 6
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
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 corresponding to an extension exist
in the library.
OpenGL itself is capable of being extended. Refer to glIntro for more
information.
GLX 1.1, GLX 1.2, GLX 1.3
GLX 1.3 is now supported, and is backward compatible with GLX 1.1 and GLX
1.2. It introduces new functionality (namely GLXFBConfigs) that
supersedes the GLX 1.2 functionality. GLX 1.2 commands are supported,
but their use in new application development is not recommended.
GLX 1.3 corresponds to OpenGL versions 1.2, and introduces the following
new calls: glXGetFBConfigs, glXGetFBConfigAttrib,
glXGetVisualFromFBConfig, glXCreateWindow, glXDestroyWindow,
glXCreatePixmap, glXDestroyPixmap, glXCreatePbuffer, glXDestroyPbuffer,
glXQueryDrawable, glXCreateNewContext, glXMakeContextCurrent,
glXGetCurrentReadDrawable, glXGetCurrentDisplay, glXQueryContext,
glXSelectEvent, glXGetSelectedEvent.
GLX 1.2 corresponds to OpenGL version 1.1 and introduced the following
new call: glXGetCurrentDisplay.
GLX 1.1 corresponds to OpenGL version 1.0 and introduces the following
new calls: glXQueryExtensionsString, glXQueryServerString, and
glXGetClientString.
Call glXQueryVersion to determine at runtime what version of GLX is
available. glXQueryVersion 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_VERSION_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
glXIntro, glXFinish, glXFlush, 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,
Page 7
glXIntro(3G) OpenGL Reference - GLX glXIntro(3G)
glXGetSelectedEvent. XCreateColormap, XCreateWindow, XSync
Page 8
