[Previous Section] [Back to Table of Contents] [Next Section]

OpenGL Reference Manual (Addison-Wesley Publishing Company)


Chapter 7
GLX Reference Pages

This chapter contains the reference pages, in alphabetical order, for all the routines comprising the OpenGL extension to X (GLX). Note that there is a glXIntro page, which gives an overview of OpenGL in the X Window System; you might want to start with this page.


glXChooseVisual

NAME

glXChooseVisual - return a visual that matches specified attributes

C SPECIFICATION

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

PARAMETERS

dpy

Specifies the connection to the X server.

screen

Specifies the screen number.

attribList

Specifies a list of Boolean attributes and integer attribute/value pairs. The last attribute must be None.

DESCRIPTION

glXChooseVisual returns a pointer to an XVisualInfo structure describing the visual that best meets a minimum specification. The Boolean GLX attributes of the visual that is returned will match the specified values, and the integer GLX attributes will meet or exceed the specified minimum values. If all other attributes are equivalent, then TrueColor and PseudoColor visuals have priority over DirectColor and StaticColor visuals, respectively. If no conforming visual exists, NULL is returned. To free the data returned by this function, use XFree.

All Boolean GLX attributes default to False except GLX_USE_GL, which defaults to True. All integer GLX attributes default to zero. Default specifications are superseded by attributes included in attribList. Boolean attributes included in attribList are understood to be True. Integer attributes are followed immediately by the corresponding desired or minimum value. The list must be terminated with None.

The interpretations of the various GLX visual attributes are as follows:

GLX_USE_GL

Ignored. Only visuals that can be rendered with GLX are considered.

GLX_BUFFER_SIZE

Must be followed by a nonnegative integer that indicates the desired color index buffer size. The smallest index buffer of at least the specified size is preferred. Ignored if GLX_RGBA is asserted.

GLX_LEVEL

Must be followed by an integer buffer-level specification. This specification is honored exactly. Buffer level zero corresponds to the default frame buffer of the display. Buffer level one is the first overlay frame buffer, level two the second overlay frame buffer, and so on. Negative buffer levels correspond to underlay frame buffers.

GLX_RGBA

If present, only TrueColor and DirectColor visuals are considered. Otherwise, only PseudoColor and StaticColor visuals are considered.

GLX_DOUBLEBUFFER

If present, only double-buffered visuals are considered. Otherwise, only single-buffered visuals are considered.

GLX_STEREO

If present, only stereo visuals are considered. Otherwise, only monoscopic visuals are considered.

GLX_AUX_BUFFERS

Must be followed by a nonnegative integer that indicates the desired number of auxiliary buffers. Visuals with the smallest number of auxiliary buffers that meets or exceeds the specified number are preferred.

GLX_RED_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available red buffer is preferred. Otherwise, the largest available red buffer of at least the minimum size is preferred.

GLX_GREEN_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available green buffer is preferred. Otherwise, the largest available green buffer of at least the minimum size is preferred.

GLX_BLUE_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available blue buffer is preferred. Otherwise, the largest available blue buffer of at least the minimum size is preferred.

GLX_ALPHA_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available alpha buffer is preferred. Otherwise, the largest available alpha buffer of at least the minimum size is preferred.

GLX_DEPTH_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, visuals with no depth buffer are preferred. Otherwise, the largest available depth buffer of at least the minimum size is preferred.

GLX_STENCIL_SIZE

Must be followed by a nonnegative integer that indicates the desired number of stencil bitplanes. The smallest stencil buffer of at least the specified size is preferred. If the desired value is zero, visuals with no stencil buffer are preferred.

GLX_ACCUM_RED_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, visuals with no red accumulation buffer are preferred. Otherwise, the largest possible red accumulation buffer of at least the minimum size is preferred.

GLX_ACCUM_GREEN_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, visuals with no green accumulation buffer are preferred. Otherwise, the largest possible green accumulation buffer of at least the minimum size is preferred.

GLX_ACCUM_BLUE_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, visuals with no blue accumulation buffer are preferred. Otherwise, the largest possible blue accumulation buffer of at least the minimum size is preferred.

GLX_ACCUM_ALPHA_SIZE

Must be followed by a nonnegative minimum size specification. If this value is zero, visuals with no alpha accumulation buffer are preferred. Otherwise, the largest possible alpha accumulation buffer of at least the minimum size is preferred.

EXAMPLES

attribList =

{GLX_RGBA, GLX_RED_SIZE, 4, GLX_GREEN_SIZE, 4, GLX_BLUE_SIZE, 4, None};

Specifies a single-buffered RGB visual in the normal frame buffer, not an overlay or underlay buffer. The returned visual supports at least four bits each of red, green, and blue, and possibly no bits of alpha. It does not support color index mode, double-buffering, or stereo display. It may or may not have one or more auxiliary color buffers, a depth buffer, a stencil buffer, or an accumulation buffer.

NOTES

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen, and depth elements.

glXChooseVisual is implemented as a client-side utility using only XGetVisualInfo and glXGetConfig. Calls to these two routines can be used to implement selection algorithms other than the generic one implemented by glXChooseVisual.

GLX implementers are strongly discouraged, but not proscribed, from changing the selection algorithm used by glXChooseVisual. Therefore, selections may change from release to release of the client-side library.

There is no direct filter for picking only visuals that support GLXPixmaps. GLXPixmaps are supported for visuals whose GLX_BUFFER_SIZE. is one of the Pixmap depths supported by the X server.

ERRORS

NULL is returned if an undefined GLX attribute is encountered in attribList.

SEE ALSO

"glXCreateContext", "glXGetConfig"


glXCopyContext

NAME

glXCopyContext - copy state from one rendering context to another

C SPECIFICATION

void glXCopyContext( Display *dpy, GLXContext src, GLXContext dst, GLuint mask )

PARAMETERS

dpy

Specifies the connection to the X server.

src

Specifies the source context.

dst

Specifies the destination context.

mask

Specifies which portions of src state are to be copied to dst.

DESCRIPTION

glXCopyContext copies selected groups of state variables from src to dst. mask indicates which groups of state variables are to be copied. mask contains the bitwise OR of the same symbolic names that are passed to the OpenGL command glPushAttrib. The single symbolic constant GL_ALL_ATTRIB_BITS can be used to copy the maximum possible portion of rendering state.

The copy can be done only if the renderers named by src and dst share an address space. Two rendering contexts share an address space if both are nondirect using the same server, or if both are direct and owned by a single process. Note that in the nondirect case it is not necessary for the calling threads to share an address space, only for their related rendering contexts to share an address space.

Not all values for OpenGL state can be copied. For example, pixel pack and unpack state, render mode state, and select and feedback state are not copied. The state that can be copied is exactly the state that is manipulated by OpenGL command glPushAttrib.

An implicit glFlush is done by glXCopyContext if src is the current context for the calling thread.

If src is not the current context for the thread issuing the request, then the state of the src context is undefined.

NOTES

Two rendering contexts share an address space if both are nondirect using the same server, or if both are direct and owned by a single process.

A process is a single execution environment, implemented in a single address space, consisting of one or more threads.

A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread that is the only member of its subprocess group is equivalent to a process.

ERRORS

BadMatch is generated if rendering contexts src and dst do not share an address space or were not created with respect to the same screen.

BadAccess is generated if dst is current to any thread (including the calling thread) at the time glXCopyContext is called.

GLXBadCurrentWindow is generated if src is the current context and the current drawable is a window that is no longer valid.

GLX_Bad_Context is generated if either src or dst is not a valid GLX context.

BadValue is generated if undefined mask bits are specified.

SEE ALSO

"glPushAttrib", "glXCreateContext", "glXIsDirect"


glXCreateContext

NAME

glXCreateContext - create a new GLX rendering context

C SPECIFICATION

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

PARAMETERS

dpy

Specifies the connection to the X server.

vis

Specifies the visual that defines the frame buffer resources available to the rendering context. It is a pointer to an XVisualInfo structure, not a visual ID or a pointer to a Visual.

shareList

Specifies the context with which to share display lists. NULL indicates that no sharing is to take place.

direct

Specifies whether rendering is to be done with a direct connection to the graphics system if possible (True) or through the X server (False).

DESCRIPTION

glXCreateContext creates a GLX rendering context and returns its handle. This context can be used to render into both windows and GLX pixmaps. If glXCreateContext fails to create a rendering context, NULL is returned.

If direct is True, then a direct rendering context is created if the implementation supports direct rendering and the connection is to an X server that is local. If direct is False, then a rendering context that renders through the X server is always created. Direct rendering provides a performance advantage in some implementations. However, direct rendering contexts cannot be shared outside a single process, and they cannot be used to render to GLX pixmaps.

If shareList is not NULL, then all display-list indexes and definitions are shared by context shareList and by the newly created context. An arbitrary number of contexts can share a single display-list space. However, all rendering contexts that share a single display-list space must themselves exist in the same address space. Two rendering contexts share an address space if both are nondirect using the same server, or if both are direct and owned by a single process. Note that in the nondirect case, it is not necessary for the calling threads to share an address space, only for their related rendering contexts to share an address space.

NOTES

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen, and depth elements.

A process is a single execution environment, implemented in a single address space, consisting of one or more threads.

A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread that is the only member of its subprocess group is equivalent to a process.

ERRORS

NULL is returned if execution fails on the client side.

BadMatch is generated if the context to be created would not share the address space or the screen of the context specified by shareList.

BadValue is generated if vis is not a valid visual (e.g., if the GLX implementation does not support it).

GLX_Bad_Context is generated if shareList is not a GLX context and is not NULL.

BadAlloc is generated if the server does not have enough resources to allocate the new context.

SEE ALSO

"glXDestroyContext", "glXGetConfig", "glXIsDirect", "glXMakeCurrent"


glXCreateGLXPixmap

NAME

glXCreateGLXPixmap - create an off-screen GLX rendering area

C SPECIFICATION

GLXPixmap glXCreateGLXPixmap( Display *dpy, XVisualInfo *vis, Pixmap pixmap )

PARAMETERS

dpy

Specifies the connection to the X server.

vis

Specifies the visual that defines the structure of the rendering area. It is a pointer to an XVisualInfo structure, not a visual ID or a pointer to a Visual.

pixmap

Specifies the X pixmap that will be used as the front left color buffer of the off-screen rendering area.

DESCRIPTION

glXCreateGLXPixmap creates an off-screen rendering area and returns its XID. Any GLX rendering context that was created with respect to vis can be used to render into this off-screen area. Use glXMakeCurrent to associate the rendering area with a GLX rendering context.

The X pixmap identified by pixmap is used as the front left buffer of the resulting off-screen rendering area. All other buffers specified by vis, including color buffers other than the front left buffer, are created without externally visible names. GLX pixmaps with double-buffering are supported. However, glXSwapBuffers is ignored by these pixmaps.

Direct rendering contexts cannot be used to render into GLX pixmaps.

NOTES

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen, and depth elements.

ERRORS

BadMatch is generated if the depth of pixmap does not match the GLX_BUFFER_SIZE value of vis, or if pixmap was not created with respect to the same screen as vis.

BadValue is generated if vis is not a valid XVisualInfo pointer (e.g., if the GLX implementation does not support this visual).

BadPixmap is generated if pixmap is not a valid pixmap.

BadAlloc is generated if the server cannot allocate the GLX pixmap.

SEE ALSO

"glXCreateContext", "glXIsDirect", "glXMakeCurrent"


glXDestroyContext

NAME

glXDestroyContext - destroy a GLX context

C SPECIFICATION

void glXDestroyContext( Display *dpy, GLXContext ctx )

PARAMETERS

dpy

Specifies the connection to the X server.

ctx

Specifies the GLX context to be destroyed.

DESCRIPTION

If GLX rendering context ctx is not current to any thread, glXDestroyContext destroys it immediately. Otherwise, ctx is destroyed when it becomes not current to any thread. In either case, the resource ID referenced by ctx is freed immediately.

ERRORS

GLX_Bad_Context is generated if ctx is not a valid GLX context.

SEE ALSO

"glXCreateContext", "glXMakeCurrent"


glXDestroyGLXPixmap

NAME

glXDestroyGLXPixmap - destroy a GLX pixmap

C SPECIFICATION

void glXDestroyGLXPixmap( Display *dpy, GLXPixmap pix )

PARAMETERS

dpy

Specifies the connection to the X server.

pix

Specifies the GLX pixmap to be destroyed.

DESCRIPTION

If GLX pixmap pix is not current to any client, glXDestroyGLXPixmap destroys it immediately. Otherwise, pix is destroyed when it becomes not current to any client. In either case, the resource ID is freed immediately.

ERRORS

GLX_Bad_Pixmap is generated if pix is not a valid GLX pixmap.

SEE ALSO

"glXCreateGLXPixmap", "glXMakeCurrent"


glXGetClientString

NAME

glXGetClientString- return a string describing the client

C SPECIFICATION

const char *glXGetClientString( Display *dpy, int name )

PARAMETERS

dpy

Specifies the connection to the X server.

name

Specifies which string is returned. One of GLX_VENDOR, GLX_VERSION, or GLX_EXTENSIONS.

DESCRIPTION

The glXGetClientString subroutine returns a string describing some aspect of the client library. The possible values for name are GLX_VENDOR, GLX_VERSION, and GLX_EXTENSIONS. If name is not set to one of these values, glXGetClientString returns NULL. The format and contents of the vendor string is implementation dependent.

The extensions string is null-terminated and contains a space-separated list of extension names. (The extension names never contain spaces.) If there are no extensions to GLX, then the empty string is returned.

The version string is laid out as follows:

<major_version.minor_version><space><vendor-specific_info>

Both the major and minor portions of the version number are of arbitrary length. The vendor-specific information is optional. However, if it is present, the format and contents are implementation specific.

NOTES

The glXGetClientString subroutine is available only if the GLX version is 1.1 or greater.

If the GLX version is 1.1 or 1.0, the GL version must be 1.0. If the GLX version is 1.2, then the GL version must be 1.1.

The glXGetClientString subroutine only returns information about GLX extensions supported by the client. Call glGetString to get a list of GL extensions supported by the server.

SEE ALSO

"glXQueryVersion", "glXQueryExtensionsString", "glXQueryServerString"


glXGetConfig

NAME

glXGetConfig - return information about GLX visuals

C SPECIFICATION

int glXGetConfig( Display *dpy, XVisualInfo *vis, int attrib, int *value )

PARAMETERS

dpy

Specifies the connection to the X server.

vis

Specifies the visual to be queried. It is a pointer to an XVisualInfo structure, not a visual ID or a pointer to a Visual.

attrib

Specifies the visual attribute to be returned.

value

Returns the requested value.

DESCRIPTION

glXGetConfig sets value to the attrib value of windows or GLX pixmaps created with respect to vis. glXGetConfig returns an error code if it fails for any reason. Otherwise, zero is returned.

attrib is one of the following:

GLX_USE_GL

True if OpenGL rendering is supported by this visual, False otherwise.

GLX_BUFFER_SIZE

Number of bits per color buffer. For RGBA visuals, GLX_BUFFER_SIZE is the sum of GLX_RED_SIZE, GLX_GREEN_SIZE, GLX_BLUE_SIZE, and GLX_ALPHA_SIZE. For color index visuals, GLX_BUFFER_SIZE is the size of the color indexes.

GLX_LEVEL

Frame buffer level of the visual. Level zero is the default frame buffer. Positive levels correspond to frame buffers that overlay the default buffer, and negative levels correspond to frame buffers that underlay the default buffer.

GLX_RGBA

True if color buffers store red, green, blue, and alpha values, False if they store color indexes.

GLX_DOUBLEBUFFER

True if color buffers exist in front/back pairs that can be swapped, False otherwise.

GLX_STEREO

True if color buffers exist in left/right pairs, False otherwise.

GLX_AUX_BUFFERS

Number of auxiliary color buffers that are available. Zero indicates that no auxiliary color buffers exist.

GLX_RED_SIZE

Number of bits of red stored in each color buffer. Undefined if GLX_RGBA is False.

GLX_GREEN_SIZE

Number of bits of green stored in each color buffer. Undefined if GLX_RGBA is False.

GLX_BLUE_SIZE

Number of bits of blue stored in each color buffer. Undefined if GLX_RGBA is False.

GLX_ALPHA_SIZE

Number of bits of alpha stored in each color buffer. Undefined if GLX_RGB is False.

GLX_DEPTH_SIZE

Number of bits in the depth buffer.

GLX_STENCIL_SIZE

Number of bits in the stencil buffer.

GLX_ACCUM_RED_SIZE

Number of bits of red stored in the accumulation buffer.

GLX_ACCUM_GREEN_SIZE

Number of bits of green stored in the accumulation buffer.

GLX_ACCUM_BLUE_SIZE

Number of bits of blue stored in the accumulation buffer.

GLX_ACCUM_ALPHA_SIZE

Number of bits of alpha stored in the accumulation buffer.

The X protocol allows a single visual ID to be instantiated with different numbers of bits per pixel. Windows or GLX pixmaps that will be rendered with OpenGL, however, must be instantiated with a color buffer depth of GLX_BUFFER_SIZE.

Although a GLX implementation can export many visuals that support OpenGL rendering, it must support at least two. One is an RGBA visual with at least one color buffer, a stencil buffer of at least 1 bit, a depth buffer of at least 12 bits, and an accumulation buffer. Alpha bitplanes are optional in this visual. However, its color buffer size must be as great as that of the deepest TrueColor, DirectColor, PseudoColor, or StaticColor visual supported on level zero, and it must itself be made available on level zero.

The other required visual is a color index one with at least one color buffer, a stencil buffer of at least 1 bit, and a depth buffer of at least 12 bits. This visual must have as many color bitplanes as the deepest PseudoColor or StaticColor visual supported on level zero, and it must itself be made available on level zero.

Applications are best written to select the visual that most closely meets their requirements. Creating windows or GLX pixmaps with unnecessary buffers can result in reduced rendering performance as well as poor resource allocation.

NOTES

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen, and depth elements.

ERRORS

GLX_NO_EXTENSION is returned if dpy does not support the GLX extension. GLX_BAD_SCREEN is returned if the screen of vis does not correspond to a screen. GLX_BAD_ATTRIB is returned if attrib is not a valid GLX attribute. GLX_BAD_VISUAL is returned if vis doesn't support GLX and an attribute other than GLX_USE_GL is requested.

SEE ALSO

"glXChooseVisual", "glXCreateContext"


glXGetCurrentContext

NAME

glXGetCurrentContext - return the current context

C SPECIFICATION

GLXContext glXGetCurrentContext( void )

DESCRIPTION

glXGetCurrentContext returns the current context, as specified by glXMakeCurrent. If there is no current context, NULL is returned. glXGetCurrentContext returns client-side information. It does not make a round trip to the server.

SEE ALSO

"glXCreateContext", "glXMakeCurrent"


glXGetCurrentDisplay

NAME

glXGetCurrentDisplay - get display for current context

C SPECIFICATION

Display *glXGetCurrentDisplay( void )

DESCRIPTION

The glXGetCurrentDisplay subroutine returns the display for the current context. If no context is current, NULL is returned.

The glXGetCurrentDisplay subroutine returns client-side information. It does not make a round trip to the server, and therefore does not flush any pending events.

NOTES

The glXGetCurrentDisplay subroutine is only supported if the GLX version is 1.2 or greater.

SEE ALSO

"glXQueryVersion", "glXQueryExtensionsString",


glXGetCurrentDrawable

NAME

glXGetCurrentDrawable - return the current drawable

C SPECIFICATION

GLXDrawable glXGetCurrentDrawable( void )

DESCRIPTION

glXGetCurrentDrawable returns the current drawable, as specified by glXMakeCurrent. If there is no current drawable, None is returned. glXGetCurrentDrawable returns client-side information. It does not make a round trip to the server.

SEE ALSO

"glXCreateGLXPixmap", "glXMakeCurrent"


glXIntro

NAME

glXIntro - Introduction to OpenGL in the X window system

OVERVIEW

OpenGL is a high-performance 3-D-oriented renderer. It is available in the X window system through the GLX extension. Use glXQueryExtension and glXQueryVersion to establish whether the GLX extension is supported by an X server, and if so, what version is supported. GLX extended servers make a subset of their visuals available for OpenGL rendering. Drawables created with these visuals can also be rendered using the core X renderer and with the renderer of any other X extension that is compatible with all core X visuals. GLX extends drawables with several buffers other than the standard color buffer. These buffers include back and auxiliary color buffers, a depth buffer, a stencil buffer, and a color accumulation buffer. Some or all are included in each X visual that supports OpenGL. To render using OpenGL into an X drawable, you must first choose a visual that defines the required OpenGL buffers. glXChooseVisual can be used to simplify selecting a compatible visual. If more control of the selection process is required, use XGetVisualInfo and glXGetConfig to select among all the available visuals. Use the selected visual to create both a GLX context and an X drawable. GLX contexts are created with glXCreateContext, and drawables are created with either XCreateWindow or glXCreateGLXPixmap. Finally, bind the context and the drawable together using glXMakeCurrent. This context/drawable pair becomes the current context and current drawable, and it is used by all OpenGL commands until glXMakeCurrent is called with different arguments. Both core X and OpenGL commands can be used to operate on the current drawable. The X and OpenGL command streams are not synchronized, however, except at explicitly created boundaries generated by calling glXWaitGL, glXWaitX, XSync, and glFlush.

EXAMPLES

Below is the minimum code required to create an RGBA-format, OpenGL-compatible X window and clear it to yellow. The code is correct, but it does not include any error checking. Return values dpy, vi, cx, cmap, and win should all be tested.

#include  <GL/glx.h>
#include  <GL/gl.h>
#include  <unistd.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);
    /* get an appropriate visual */
    vi = glXChooseVisual(dpy, DefaultScreen(dpy), attributeList);
    /* create a GLX context */
    cx = glXCreateContext(dpy, vi, 0, GL_FALSE);
    /* create a color map */
    cmap = XCreateColormap(dpy, RootWindow(dpy, vi->screen),
     vi->visual, AllocNone);
    /* create a window */
    swa.colormap = cmap;
    swa.border_pixel = 0;
    swa.event_mask = StructureNotifyMask;
    win = XCreateWindow(dpy, RootWindow(dpy, vi->screen), 0, 0, 100, 100,
                        0, vi->depth, InputOutput, vi->visual,
                        CWBorderPixel|CWColormap|CWEventMask, &swa);
    XMapWindow(dpy, win);
    XIfEvent(dpy, &event, WaitForNotify, (char*)win);
    /* 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 a while */
    sleep(10);
}

NOTES

A color map must be created and passed to XCreateWindow. See the example code above.

A GLX context must be created and attached to an X drawable before OpenGL commands can be executed. OpenGL commands issued while no context/drawable pair is current are ignored.

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 code assuming that these buffers will not be damaged.

GLX commands manipulate XVisualInfo structures rather than pointers to visuals or visual IDs. XVisualInfo structures contain visual, visualID, screen, and depth elements, as well as other X-specific information.

SEE ALSO

"glFinish", "glFlush", "glXChooseVisual", "glXCopyContext", "glXCreateContext", "glXCreateGLXPixmap", "glXDestroyContext", "glXGetConfig", "glXIsDirect", "glXMakeCurrent", "glXQueryExtension", "glXQueryVersion", "glXSwapBuffers", "glXUseXFont", "glXWaitGL", "glXWaitX", XCreateColormap, XCreateWindow, XSync


glXIsDirect

NAME

glXIsDirect - indicate whether direct rendering is enabled

C SPECIFICATION

Bool glXIsDirect( Display *dpy, GLXContext ctx )

PARAMETERS

dpy

Specifies the connection to the X server.

ctx

Specifies the GLX context that is being queried.

DESCRIPTION

glXIsDirect returns True if ctx is a direct rendering context, False otherwise. Direct rendering contexts pass rendering commands directly from the calling process's address space to the rendering system, bypassing the X server. Nondirect rendering contexts pass all rendering commands to the X server.

ERRORS

GLX_Bad_Context is generated if ctx is not a valid GLX context.

SEE ALSO

"glXCreateContext"


glXMakeCurrent

NAME

glXMakeCurrent - attach a GLX context to a window or a GLX pixmap

C SPECIFICATION

Bool glXMakeCurrent( Display *dpy, GLXDrawable drawable, GLXContext ctx )

PARAMETERS

dpy

Specifies the connection to the X server.

drawable

Specifies a GLX drawable. Must be either an X window ID or a GLX pixmap ID.

ctx

Specifies a GLX rendering context that is to be attached to drawable.

DESCRIPTION

glXMakeCurrent does two things: It makes ctx the current GLX rendering context of the calling thread, replacing the previously current context if there was one, and it attaches ctx to a GLX drawable, either a window or a GLX pixmap. As a result of these two actions, subsequent OpenGL rendering calls use rendering context ctx to modify GLX drawable drawable. Because glXMakeCurrent always replaces the current rendering context with ctx, there can be only one current context per thread.

Pending commands to the previous context, if any, are flushed before it is released.

The first time ctx is made current to any thread, its viewport is set to the full size of drawable. Subsequent calls by any thread to glXMakeCurrent with ctx have no effect on its viewport.

To release the current context without assigning a new one, call glXMakeCurrent with drawable and ctx set to None and NULL respectively.

glXMakeCurrent returns True if it is successful, False otherwise. If False is returned, the previously current rendering context and drawable (if any) remain unchanged.

NOTES

A process is a single-execution environment, implemented in a single address space, consisting of one or more threads.

A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread that is the only member of its subprocess group is equivalent to a process.

ERRORS

BadMatch is generated if drawable was not created with the same X screen and visual as ctx. It is also generated if drawable is None and ctx is not None.

BadAccess is generated if ctx was current to another thread at the time glXMakeCurrent was called.

GLX_Bad_Drawable is generated if drawable is not a valid GLX drawable.

GLX_Bad_Context is generated if ctx is not a valid GLX context.

GLX_Bad_Context_State is generated if the rendering context current to the calling thread has OpenGL renderer state GL_FEEDBACK or GL_SELECT.

GLX_Bad_Current_Window is generated if there are pending OpenGL commands for the previous context and the current drawable is a window that is no longer valid.

BadAlloc may be generated if the server has delayed allocation of ancillary buffers until glXMakeCurrent is called, only to find that it has insufficient resources to complete the allocation.

SEE ALSO

"glXCreateContext", "glXCreateGLXPixmap"


glXQueryExtension

NAME

glXQueryExtension - indicate whether the GLX extension is supported

C SPECIFICATION

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

PARAMETERS

dpy

Specifies the connection to the X server.

errorBase

Returns the base error code of the GLX server extension.

eventBase

Returns the base event code of the GLX server extension.

DESCRIPTION

glXQueryExtension returns True if the X server of connection dpy supports the GLX extension, False otherwise. If True is returned, then errorBase and eventBase return the error base and event base of the GLX extension. Otherwise, errorBase and eventBase are unchanged.

errorBase and eventBase do not return values if they are specified as NULL.

NOTES

eventBase is included for future extensions. GLX does not currently define any events.

SEE ALSO

"glXQueryVersion"


glXQueryExtensionsString

NAME

glXQueryExtensionsString - return a list of supported extensions

C SPECIFICATION

const char *glXQueryExtensionsString( Display *dpy, int screen )

PARAMETERS

dpy

Specifies the connection to the X server.

screen

Specifies the screen.

DESCRIPTION

The glXQueryExtensionsString subroutine returns a pointer to a string describing which GLX extensions are supported on the connection. The string is null-terminated and contains a space-separated list of extension names. (The extension names themselves never contain spaces.) If there are no extensions to GLX, then the empty string is returned.

NOTES

The glXQueryExtensionsString subroutine is available only if the GLX version is 1.1 or greater.

The glXQueryExtensionsString subroutines only returns information about GLX extensions. Call glGetString to get a list of GL extensions.

SEE ALSO

"glGetString", "glXQueryVersion", "glXQueryServerString", "glXGetClientString"


glXQueryServerString

NAME

glXQueryServerString - return a string describing the server

C SPECIFICATION

const char *glXQueryServerString( Display *dpy, int screen, int name )

PARAMETERS

dpy

Specifies the connection to the X server.

screen

Specifies the screen number.

name

Specifies which string is returned. One of GLX_VENDOR, GLX_VERSION, or GLX_EXTENSIONS.

DESCRIPTION

The glXQueryServerString subroutine returns a pointer to a static, null-terminated string describing some aspect of the server's GLX extension. The possible values for name and the format of the strings is the same as for glXGetClientString. If name is not set to a recognized value, NULL is returned.

NOTES

The glXQueryServerString subroutine is available only if the GLX version is 1.1 or greater.

If the GLX version is 1.1 or 1.0, the GL version must be 1.0. If the GLX version is 1.2, the GL version must be 1.1.

The glXQueryServerString subroutine only returns information about GLX extensions supported by the server. Call glGetString to get a list of GL extensions. Call glXGetClientString to get a list of GLX extensions supported by the client.

SEE ALSO

"glXQueryVersion", "glXGetClientString", "glXQueryExtensionsString"


glXQueryVersion

NAME

glXQueryVersion - return the version numbers of the GLX extension

C SPECIFICATION

Bool glXQueryVersion( Display *dpy, int *major, int *minor )

PARAMETERS

dpy

Specifies the connection to the X server.

major

Returns the major version number of the GLX server extension.

minor

Returns the minor version number of the GLX server extension.

DESCRIPTION

glXQueryVersion returns the major and minor version numbers of the GLX extension implemented by the server associated with connection dpy. Implementations with the same major version number are upward compatible, meaning that the implementation with the higher minor number is a superset of the version with the lower minor number.

major and minor do not return values if they are specified as NULL.

ERRORS

glXQueryVersion returns False if it fails, True otherwise. major and minor are not updated when False is returned.

SEE ALSO

"glXQueryExtension"


glXSwapBuffers

NAME

glXSwapBuffers - make back buffer visible

C SPECIFICATION

void glXSwapBuffers( Display *dpy, GLXDrawable drawable )

PARAMETERS

dpy

Specifies the connection to the X server.

drawable

Specifies the window whose buffers are to be swapped.

DESCRIPTION

glXSwapBuffers promotes the contents of the back buffer of drawable to become the contents of the front buffer of drawable. The contents of the back buffer then become undefined. The update typically takes place during the vertical retrace of the monitor, rather than immediately after glXSwapBuffers is called. All GLX rendering contexts share the same notion of which are front buffers and which are back buffers.

An implicit glFlush is done by glXSwapBuffers before it returns. Subsequent OpenGL commands can be issued immediately after calling glXSwapBuffers, but are not executed until the buffer exchange is completed.

If drawable was not created with respect to a double-buffered visual, glXSwapBuffers has no effect, and no error is generated.

NOTES

Synchronization of multiple GLX contexts rendering to the same double-buffered window is the responsibility of the clients. The X Synchronization Extension can be used to facilitate such cooperation.

ERRORS

GLX_Bad_Drawable is generated if drawable is not a valid GLX drawable.

GLX_Bad_Current_Window is generated if dpy and drawable are respectively the display and drawable associated with the current context of the calling thread, and drawable identifies a window that is no longer valid.

SEE ALSO

"glFlush"


glXUseXFont

NAME

glXUseXFont - create bitmap display lists from an X font

C SPECIFICATION

void glXUseXFont( Font font, int first, int count, int listBase )

PARAMETERS

font

Specifies the font from which character glyphs are to be taken.

first

Specifies the index of the first glyph to be taken.

count

Specifies the number of glyphs to be taken.

listBase

Specifies the index of the first display list to be generated.

DESCRIPTION

glXUseXFont generates count display lists, named listBase through listBase + count - 1, each containing a single glBitmap command. The parameters of the glBitmap command of display list listBase + i are derived from glyph first + i. Bitmap parameters xorig, yorig, width, and height are computed from font metrics as descent-1, -lbearing,rbearing-lbearing, and ascent+descent, respectively. xmove is taken from the glyph's width metric, and ymove is set to zero. Finally, the glyph's image is converted to the appropriate format for glBitmap.

Using glXUseXFont may be more efficient than accessing the X font and generating the display lists explicitly, both because the display lists are created on the server without requiring a round trip of the glyph data, and because the server may choose to delay the creation of each bitmap until it is accessed.

Empty display lists are created for all glyphs that are requested and are not defined in font. glXUseXFont is ignored if there is no current GLX context.

ERRORS

BadFont is generated if font is not a valid font.

GLX_Bad_Context_State is generated if the current GLX context is in display-list construction mode.

GLX_Bad_Current_Window is generated if the drawable associated with the current context of the calling thread is a window, and that window is no longer valid.

SEE ALSO

"glBitmap", "glXMakeCurrent"


glXWaitGL

NAME

glXWaitGL - complete GL execution prior to subsequent X calls

C SPECIFICATION

void glXWaitGL( void )

DESCRIPTION

OpenGL rendering calls made prior to glXWaitGL are guaranteed to be executed before X rendering calls made after glXWaitGL. Although this same result can be achieved using glFinish, glXWaitGL does not require a round trip to the server, and it is therefore more efficient in cases where client and server are on separate machines.

glXWaitGL is ignored if there is no current GLX context.

NOTES

glXWaitGL may or may not flush the X stream.

ERRORS

GLX_Bad_Current_Window is generated if the drawable associated with the current context of the calling thread is a window, and that window is no longer valid.

SEE ALSO

"glFinish", "glFlush", "glXWaitX", XSync


glXWaitX

NAME

glXWaitX - complete X execution prior to subsequent OpenGL calls

C SPECIFICATION

void glXWaitX( void )

DESCRIPTION

X rendering calls made prior to glXWaitX are guaranteed to be executed before OpenGL rendering calls made after glXWaitX. Although this same result can be achieved using XSync, glXWaitX does not require a round trip to the server, and it is therefore more efficient in cases where client and server are on separate machines.

glXWaitX is ignored if there is no current GLX context.

NOTES

glXWaitX may or may not flush the OpenGL stream.

ERRORS

GLX_Bad_Current_Window is generated if the drawable associated with the current context of the calling thread is a window, and that window is no longer valid.

SEE ALSO

"glFinish", "glFlush", "glXWaitGL", XSync


[Previous Section] [Back to Table of Contents] [Next Section]

OpenGL Reference Manual (Addison-Wesley Publishing Company)