This chapter discusses resource control extensions, which are extensions to GLX. GLX is an extension to the X Window System that makes OpenGL available in an X Window System environment. All GLX functions and other elements have the prefix glX (just as all OpenGL elements have the prefix gl).
You can find information on GLX in several places:
Introductory information—See the glxintro reference page
In-depth coverage—See Appendix C, “OpenGL and Window Systems,” of the OpenGL Programming Guide and OpenGL Programming for the X Window System
See “OpenGL and Associated Tools and Libraries” for bibliographical information).
This chapter explains how to use extensions to GLX. The extensions are presented in alphabetical order. You learn about
The following sections describe extensions that are experimental:
 | Note: Using OpenGL in an X Window System environment is discussed in the following chapters of this guide: |
The import context extension, EXT_import_context, allows multiple X clients to share an indirect rendering context. The extension also adds some query routines to retrieve information associated with the current context.
To work effectively with this extension, you must first understand direct and indirect rendering. See “Direct and Indirect Rendering” for some background information.
You can use the extension to import another process' OpenGL context, as follows:
To retrieve the XID for a GLX context, call glXGetContextIDEXT():
GLXContextID glXGetContextIDEXT(const GLXContext ctx)
This function is client-side only. No round trip is forced to the server; unlike most X calls that return a value, glXGetContextIDEXT() does not flush any pending events.
To create a GLX context, given the XID of an existing GLX context, call glXImportContextEXT(). You can use this function in place of glXCreateContext() to share another process' indirect rendering context:
GLXContext glXImportContextEXT( Display *dpy, GLXContextID contextID)
Only the server-side context information can be shared between X clients; client-side state, such as pixel storage modes, cannot be shared. Thus, glXImportContextEXT() must allocate memory to store client-side information.
A call to glXImportContextEXT() doesn't create a new XID. It merely makes an existing XID available to the importing client. The XID goes away when the creating client drops its connection or the ID is explicitly deleted. The object goes away when the XID goes away and the context is not current to any thread.
To free the client-side part of a GLX context that was created with glXImportContextEXT(), call glXFreeContextEXT():
void glXFreeContextEXT(Display *dpy, GLXContext ctx)
glXFreeContextEXT() doesn't free the server-side context information or the XID associated with the server-side context.
Use the extension to retrieve the display of the current context, or other information about the context, as follows:
To retrieve the current display associated with the current context, call glXGetCurrentDisplayEXT(), which has the following prototype:
Display * glXGetCurrentDisplayEXT( void );
If there is no current context, NULL is returned. No round trip is forced to the server; unlike most X calls that return a value, glXGetCurrentDisplayEXT() doesn't flush any pending events.
To obtain the value of a context's attribute, call glXQueryContextInfoEXT():
int glXQueryContextInfoEXT( Display *dpy, GLXContext ctx, int attribute,int *value )The values and types corresponding to each GLX context attribute are listed in Table 6-1.
Table 6-1. Type and Context Information for GLX Context Attributes
GLX Context Attribute
Type
Context Information
XID
XID of the share list context
XID
visual ID
int
screen number
The make current read extension, SGI_make_current_read, allows you to attach separate read and write drawables to a GLX context by calling glXMakeCurrentReadSGI(), which has the following prototype:
Bool glXMakeCurrentReadSGI( Display *dpy,GLXDrawable draw,
GLXDrawable read, GLXContext gc )
|
where
| dpy | Specifies the connection to the X server. | |
| draw | A GLX drawable that receives the results of OpenGL drawing operations. | |
| read | A GLX drawable that provides pixels for glReadPixels() and glCopyPixels() operations. | |
| gc | A GLX rendering context to be attached to draw and read. |
In GLX 1.1, you associate a GLX context with one drawable (window or pixmap) by calling glXMakeCurrent(). glXMakeCurrentReadSGI() lets you attach a GLX context to two drawables: The first is the one you draw to, the second serves as a source for pixel data.
In effect, the following calls are equivalent:
MakeCurent(context, win) MakeCurrentRead(context, win, win) |
Having both a read and a write drawable is useful, for example, to copy the contents of a window to another window, to stream video to a window, and so on.
The write drawable is used for all OpenGL operations. Accumulation buffer operations fetch data from the write drawable and are not allowed when the read and write drawable are not identical.
The read drawable is used for any color, depth, or stencil values that are retrieved by glReadPixels(), glCopyPixels(), glCopyTexImage(), or glCopyTexSubImage(). It is also use by any OpenGL extension that sources images from the framebuffer in the manner of glReadPixels(), glCopyPixels(), glCopyTexImage(), or glCopyTexSubImage().
Here is some additional information about the two drawables:
The two drawables do not need to have the same ancillary buffers (depth buffer, stencil buffer, and so on).
The read drawable does not have to contain a buffer corresponding to the current GL_READ_BUFFER of a GLX context. For example, the current GL_READ_BUFFER may be GL_BACK, and the read drawable may be single-buffered.
If a subsequent command sets the read buffer to a color buffer that does not exist on the read drawable—even if set implicitly by glPopAttrib()—or if an attempt is made to source pixel values from an unsupported ancillary buffer, a GL_INVALID_OPERATION error is generated.
If the current GL_READ_BUFFER does not exist in the read drawable, pixel values extracted from that drawable are undefined, but no error is generated.
Operations that query the value of GL_READ_BUFFER use the value set last in the context, regardless of whether the read drawable has the corresponding buffer.
When glXMakeCurrentReadSGI() associates two GLX drawables with a single GLX context, a BadMatch X protocol error is generated if either drawable was not created with the same X screen.
The color, depth, stencil, and accumulation buffers of the two drawables don't need to match. Certain implementations may impose additional constraints. For example, the current RealityEngine implementation requires that the color component resolution of both drawables be the same. If it is not, glXMakeCurrentReadSGI() generates a BadMatch X protocol error.
glXGetCurrentReadDrawableSGI() returns the name of the GLXDrawable currently being used as a pixel query source.
If glXMakeCurrent() specified the current rendering context, then glXGetCurrentReadDrawableSGI() returns the drawable specified as draw by that glXMakeCurrent call.
If glXMakeCurrentReadSGI() specified the current rendering context, then glXGetCurrentReadDrawableSGI() returns the drawable specified as read by that glXMakeCurrentReadSGI() call.
If there is no current read drawable, glXGetCurrentReadDrawableSGI() returns None.
The visual info extension, EXT_visual_info, enhances the standard GLX visual mechanism as follows:
You can request that a particular X visual type be associated with a GLX visual.
You can query the X visual type underlying a GLX visual.
You can query whether a visual supports a transparent pixel value and query the value of the transparent pixel.
Note that the notions of level and transparent pixels are orthogonal as both level 1 and level 0 visuals may or may not support transparent pixels.
To find a visual that best matches specified attributes, call glXChooseVisual():
XVisualInfo* glXChooseVisual( Display *dpy, int screen, int *attrib_list ) |
The following heuristics determine which visual is chosen:
Table 6-2. Heuristics for Visual Selection
If an undefined GLX attribute, or an unacceptable enumerated attribute value is encountered, NULL is returned.
More attributes may be specified in the attribute list. If a visual attribute is not specified, a default value is used. See the glXChooseVisual reference page for more detail.
To free the data returned from glXChooseVisual(), use XFree().
Note that GLX_VISUAL_TYPE_EXT can also be used with glXGetConfig().
How you specify that you want a visual with transparent pixels depends on the existing attributes:
If... | Then call glXChooseVisual() and specify as the value of GLX_TRANSPARENT_TYPE_EXT... |
GLX_RGBA is in attrib_list | GLX_TRANSPARENT_RGB_EXT |
GLX_RGBA is not in attrib_list | GLX_TRANSPARENT_INDEX_EXT |
Don't specify one of the following values in attrib_list because typically only one transparent color or index value is supported:
GLX_TRANSPARENT_INDEX_VALUE_EXT, GLX_TRANSPARENT_{RED|GREEN|BLUE|ALPHA}_VALUE_EXT
Once you have a transparent visual, you can query the transparent color value by calling glXGetConfig(). To get the transparent index value for visuals that support index rendering, use GLX_TRANSPARENT_INDEX_VALUE_EXT. For visuals that support RGBA rendering, use GLX_TRANSPARENT_{RED|GREEN|BLUE}_VALUE_EXT. The visual attribute GLX_TRANSPARENT_ALPHA_VALUE_EXT is included in the extension for future use.
“Creating Overlays” presents an example program that uses a transparent visual for the overlay window.
The visual rating extension, EXT_visual_rating, 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. It is intended to ensure that most—but possibly not all—applications get the “right” visual.
You can use this extension during visual selection, keeping in mind that while you will get a good match for most systems, you may not get the best match for all systems.
To determine the rating for a visual, call glXGetConfig() with attribute set to GLX_VISUAL_CAVEAT_EXT. glXGetConfig() returns the rating of the visual in the parameter value: GLX_NONE_EXT or GLX_SLOW_EXT.
If the GLX_VISUAL_CAVEAT_EXT attribute is not specified in the attrib_list parameter of glXChooseVisual(), preference is given to visuals with no caveats (that is, visuals with the attribute set to GLX_NONE_EXT). If the GLX_VISUAL_CAVEAT_EXT attribute is specified, then glXChooseVisual() matches the specified value exactly. For example, if the value is specified as GLX_NONE_EXT, only visuals with no caveats are considered.
The Digital Media Pbuffer extension, SGIX_dm_pbuffer, introduces a new type of GLXPbuffer, the DMbuffer. Images generated by digital media libraries in DMbuffer form can be used directly by OpenGL as renderable buffers or as the pixel source for texture images.
| Note: Note: |
The SGIX_dm_pbuffer extension is currently supported only on O2 systems. This discussion therefore focuses on the buffer configurations available on O2 systems.
This section explains how to use the Digital Media Pbuffer extension in the following sections:
“Creating a Digital Media Pbuffer” provides a conceptual introduction to the steps involved in using the extension.
“Compatibility Conditions” discusses image layout and pixel formats in for the different libraries. This background information is used when an application creates DMbuffers that are compatible with DMPbuffers.
“OpenGL Rendering to DMbuffers” provides an example program that illustrates the material discussed in the other two sections.
“DMbuffers as OpenGL Textures” explains conditions under which DMbuffers can be used as OpenGL textures. It also includes an example code fragment.
Creating a digital media Pbuffer involves three separate conceptual steps, explained in the following sections. “OpenGL Rendering to DMbuffers” further illustrates each step in the context of an example program.
DMbuffers are a class of buffer common to video, JPEG decompression and other digital media libraries. They permit the sharing and exchange of images in various formats. A graphical DMbuffer is essentially a chunk of memory used to store a single image or, in the special case of mipmapped DMbuffers, a set of images.
To use the dm_pbuffer extension, you have to create a DMbufferPool with characteristics that match the Pbuffer you want to associate with the DMbuffer. Follow these conceptual steps (in an actual program, memory allocation and other issues are also part of the process):
Call dmBufferSetPoolDefaults() to specify the parameters of the DMbuffers you want to create.
The DMparams identify the DMbuffer when it is passed to OpenGL. (see Example 6-1). The following elements in the structure must be compatible with the characteristics of the Pbuffer:
DM_IMAGE_WIDTH and DM_IMAGE_HEIGHT
DM_IMAGE_PACKING—(see “Pixel Formats”)
DM_IMAGE_LAYOUT—(see “Compatibility Conditions”)
Call dmBufferCreatePool() to create a DMbufferPool.
All the buffers in the pool will have the characteristics specified in step 1.
Once the buffer pool is created, DMbuffers are obtained with a call to either dmBufferAllocate(), vlEventToDMBuffer(), or dmICReceive(), depending on the application generating DMbuffers for OpenGL.
A pixel buffer, or Pbuffer, is a window-independent, non-visible rendering buffer for an OpenGL renderer. Pbuffers are supported by the Pbuffer extension; see “SGIX_pbuffer—The Pixel Buffer Extension”. A digital media Pbuffer is a special kind of Pbuffer.
To create a digital media Pbuffer, an application calls glXCreateGLXPbufferSGIX(), specifying the GLX_DIGITAL_MEDIA_PBUFFER_SGIX attribute.
The resulting Pbuffer is identical in all respects to a standard Pbuffer except that its primary color buffer does not exist until the Pbuffer is associated with a compatible DMbuffer for the first time. All other buffers (depth, stencil, accumulation) defined by the FBConfig for the pbuffer are allocated by OpenGL.
To associate a Pbuffer with a compatible DMbuffer, applications call glXAssociateDMPbufferSGIX() which has the following prototype:
Bool glXAssociateDMPbufferSGIX( Display *dpy,GLXPbufferSGIX pbuffer,
DMparams *params,DMbuffer dmbuffer )
|
where
| dpy | Connection to an X server. | |
| pbuffer | GLX pixel buffer target of the associate operation. | |
| params | Parameter list that describes the format of the images in the DMbuffer that is to be associated with the pixel buffer. | |
| dmbuffer | DMbuffer to be used as the front left color buffer. |
The call to glXAssociateDMPbufferSGIX() must be issued before the pbuffer can be made current for the first time, as either a read or write drawable. Once associated with a pbuffer, all rendering to, or read and copy operations from the pbuffer's color buffer will access the DMbuffer directly.
Compatible DMbuffers can be associated in sequence with the same pbuffer while the pbuffer is current. A DMbuffer remains associated either until it is replaced by another associate command, or until the pbuffer is destroyed. Once the DMbuffer is released, it is freed only if it has no remaining clients on the system. DMbuffers are local resources, and a DMPbuffer can be current only to a direct GLXContext.
A pbuffer and DMbuffer can be associated only if their image layout and pixel formats are compatible. This section provides some background information on these two topics.
When an application creates a pool of DMbuffers, it has to choose between two types of DMbuffer image layout, linear and graphics, specified with the DM_IMAGE_LAYOUT parameter in the DMparams structure. Table 6-4 lists OpenGL commands that are compatible with DMbuffers of each layout.
Table 6-4. Linear and Graphics Layout
| Linear Layout | Graphics Layout |
|---|---|---|
VL Layout |
| |
DM image Layout | ||
OpenGL commands |
Only DMbuffers with a graphics layout can be associated with a DMPbuffer. These DMbuffers cannot be mapped, and so can be accessed only through digital media or graphics library commands, not directly by the application.
DMbuffers with linear image layout can be mapped, and can be passed by address as the pixels parameter to glDrawPixels(), glReadPixels() and glTexImage2D().
There are three internal pixel formats that are shared by the video, digital media and graphics libraries. The video library (libvl), the digital media library (libdmedia), and the graphics library (libGL) each have different designations for the same internal format, as illustrated in Table 6-5.
Table 6-5. Pixel and Texel Formats (Video, Digital Media and Graphics)
| libvl | libmedia | libGL- texel, pixel |
|---|---|---|---|
rgba-8888 | |||
rgba-5551 | |||
rgb-332 | (332 texel not supported) GL_RGB with GL_UNSIGNED_BYTE_3_ 3_2_EXT |
The DM_IMAGE_PACKING parameter of the DMparams structure should be set to a format that matches the component depths described by the DMPbuffer FBConfig. Video applications also need to initialize the path to a matching video library format.
Setup required for rendering to a DMPbuffer involves three basic steps, illustrated by example code fragments in the following section:
The following sample code fragment creates a DMparams structure, and a pool of DMbuffers that are suitable for use by video and GL. The buffers are 640 x 480 with a graphics layout and 32-bit RGBA format.
DMparams *imageParams, *poolParams; DMbufferpool bufferPool; DMpacking dmPacking = DM_IMAGE_PACKING_RGBA; DMimagelayout dmLayout = DM_IMAGE_LAYOUT_GRAPHICS; DMboolean cacheable = DM_FALSE; DMboolean mapped = DM_FALSE; int bufferCount = NUMBER_OF_BUFFERS_NEEDED_BY_APPLICATION; DMbuffer buffer[NUMBER_OF_BUFFERS_NEEDED_BY_APPLICATION]; DMstatus s; /* Create and initialize image params. */ s = dmParamsCreate( &imageParams ); s = dmSetImageDefaults( imageParams, 640, 480, dmPacking ); s = dmParamsSetEnum( imageParams, DM_IMAGE_LAYOUT, dmLayout ); /* Set up a VL video path before creating the DMbuffer pool. */ /* Create and initialize pool params using VL & GL dm utilities. */ s = dmParamsCreate( &poolParams ); s = dmBufferSetPoolDefaults( count, 0, cacheable, mapped ); s = vlDMPoolGetParams( vlServer, vlPath, vlNode, poolParams ); s = dmBufferGetGLPoolParams( imageParams, poolParams ); /* Set buffer count and create pool. */ bufferCount += dmParamsGetInt( poolParams, DM_BUFFER_COUNT ); dmParamsSetInt( poolParams, DM_BUFFER_COUNT, bufferCount ); s = dmBufferCreatePool( poolParams, &bufferPool ); dmParamsDestroy( poolParams ); |
The next step is to create a DMPbuffer with the same size and format as the DMbuffers that are to be rendered to.
GLXFBConfigSGIX *config;
GLXPbufferSGIX pbuffer;
GLXContext context;
int configAttribs [] = {
GLX_DOUBLEBUFFER, True,
GLX_RED_SIZE, 8,
GLX_GREEN_SIZE, 8,
GLX_BLUE_SIZE, 8,
GLX_ALPHA_SIZE, 8,
GLX_DRAWABLE_TYPE_SGIX, GLX_PBUFFER_BIT_SGIX,
(int) None };
int pbufAttribs [] = {
GLX_DIGITAL_MEDIA_PBUFFER_SGIX, True,
(int) None };
config = glXChooseFBConfigSGIX(display, screen, configAttribs);
pbuffer = glXCreateGLXPbufferSGIX(display, *config, 640, 480, pbufAttribs);
context = glXCreateContextWithConfigSGIX(display, *config, GLX_RGBA_TYPE_SGIX, NULL, True);
|
Finally the DMbuffer is allocated and associated with the DMPbuffer and made current to a context. Applications typically cycle through a sequence of DMbuffers, rendering to them, or copying them to OpenGL textures. Freeing the DMbuffer after it has been associated allows the buffer to return to the pool for reuse once it is released by the OpenGL pbuffer or texture object.
DMparams *imageParams = ...;
DMbufferpool bufferPool = ...;
DMbuffer dmBuffer;
DMstatus s;
/* associate the first DMbuffer before making current */
s = dmBufferAllocate( bufferPool, &dmBuffer );
glXAssociateDMPbufferSGIX( display, pbuffer, imageParams, dmBuffer);
glXMakeCurrent( display, pbuffer, context );
for(i = 0; i < bufferCount; i++)i {
/* perform GL rendering operations to the DMbuffer */
dmBufferFree( dmBuffer );
s = dmBufferAllocate( bufferPool, &dmBuffer );
glXAssociateDMPbufferSGIX(display, pbuffer, imageParams, dmBuffer);
}
|
Under certain conditions, the SGIX_dm_pbuffer implementation on O2 permits the direct use of a DMbuffer as a GL texture. The benefits are optimized texture loading for DMbuffers generated as video and JPEG images, and for textures rendered as images to a DMPbuffer.
After DMBuffer and pbuffer have been associated, applications can call glXMakeCurrentReadSGI() with a DMPbuffer as the read drawable, then call glCopyPixels() or glCopyTexImage2D() to copy the contents of the associated DMbuffer to another drawable or to a texture. These copy operations behave as they would with any standard read drawable.
The following conditions allow for a “copy by reference” of the currently associated DMbuffer to a texture object (also see the reference page for glCopyTexSubImage2D):
glCopyTexSubImage2D() is used to copy the entire texture image from the DMPbuffer.
The DMPbuffer and target 2D texture object match in terms of width, height, and depth of RGBA components. See “Pixel Formats” for comparable formats.
The texture object is 64 (or more) texels in its largest dimension.
If the DMbuffer image layout is DM_IMAGE_LAYOUT_MIPMAP, then the GL_GENERATE_MIPMAP_SGIS texture parameter must also be set to TRUE for the texture object at the time of the copy.
Only the default pixel transfer operations are enabled at the time of the copy.
After a DMbuffer is copied by reference to the texture object it remains associated as the texture, even once the association to the source DMPbuffer changes, and until the texture object is destroyed or the texture image is updated through another OpenGL command.
The following example demonstrates the optimized case for copying a DMbuffer by reference to a texture object. The source DMPbuffer and DMbuffer differ from previous examples only in size; they are 512 square to allow for direct use as a OpenGL texture.
/* Make DMPbuffer current as a read drawable */
pbuffer = glXCreateGLXPbufferSGIX(display, *config, 512, 512, attribs);
glXAssociateDMPbufferSGIX( display, pbuffer, imageParams, dmBuffer);
glXMakeCurrentReadSGI( display, drawable, pbuffer, context );
/* Create and init a compatible GL texture object with NULL image */
glGenTextures(1, &texObj);
glBindTexture(GL_TEXTURE_2D, texObj);
glTexImage2D(GL_TEXTURE_2D, level = 0, GL_RGBA8, w = 512, h = 512, GL_RGBA, GL_UNSIGNED_BYTE, NULL);
/* copy the DMbuffer by reference to the texture object */
glCopyTexSubImage(GL_TEXTURE_2D, level = 0, xoff = 0, yoff = 0,
x = 0, y = 0, w = 512, h = 512);
|
The framebuffer configuration extension, SGIX_fbconfig, provides three new features:
It introduces a new way to describe the capabilities of a GLX drawable, that is, to describe the resolution of color buffer components and the type and size of ancillary buffers by providing a GLXFBConfigSGIX construct (also called FBConfig).
It relaxes the “similarity” requirement when associating a current context with a drawable.
It supports RGBA rendering to one- and two-component windows (luminance and luminance alpha rendering) and GLX pixmaps as well as pbuffers (pixel buffers). Pbuffers are discussed in “SGIX_pbuffer—The Pixel Buffer Extension”.
 | Caution: This extension is an SGIX (experimental) extension. The interface may change, or some other details of the extension may change. |
Use this extension
if you want to use pbuffers (see “SGIX_pbuffer—The Pixel Buffer Extension”)
if you want to render luminance data to a TrueColor visual
instead of glXChooseVisual(), because it provides visual selection for all GLX drawables, including pbuffers, and incorporates the visual info and visual rating extensions.
This section briefly explores the three new features the extension provides.
Currently GLX overloads X visuals so they have additional buffers and other characteristics needed for OpenGL rendering. This extension packages GLX drawables by defining a new construct, a GLXFBConfigSGIX, that encapsulates GLX drawable capabilities and has the following properties:
It may or may not have an associated X visual. If it does have an associated X visual, then it is possible to create windows that have the capabilities described by the FBConfig.
A particular FBConfig is not required to work with all GLX drawables. For example, it is possible for implementations to export FBConfigs that work only with GLX pixmaps.
In OpenGL without the extension, if you associate a drawable with a GLX context by calling glXMakeCurrent(), the two have to be “similar”; that is, they must have been created with the same visual. This extension relaxes the requirement; it only requires the context and drawable to be compatible. This is less restrictive and implies the following:
The render_type attribute for the context must be supported by the FBConfig that the drawable was created with. For example, if the context was created for RGBA rendering, it can be used only if the FBConfig supports RGBA rendering.
All color buffers and ancillary buffers that exist in both FBConfigs must have the same size. For example, a GLX drawable that has a front left buffer and a back left buffer with red, green, and blue sizes of 4 is not compatible with an FBConfig that has only a front left buffer with red, green, and blue sizes of 8. However, it is compatible with an FBConfig that has only a front left buffer if the red, green, and blue sizes are 4.
Note that when a context is created, it has an associated rendering type: GLX_RGBA_TYPE_SGIX or GLX_COLOR_INDEX_TYPE_SGIX.
The current GLX specification requires that the GLX_RGBA visual attribute be associated only with TrueColor and DirectColor X visuals. This extension makes it possible to do RGBA rendering to windows created with visuals of type PseudoColor, StaticColor, GrayScale, and StaticGray. In each case, the red component is used to generate the framebuffer values and the green and blue fragments are discarded.
The OpenGL RGBA rendering semantics are more powerful than the OpenGL index rendering semantics. By extending the X visual types that can be associated with an RGBA color buffer, this extension allows RGBA rendering semantics to be used with pseudo-color and gray-scale displays. A particularly useful application of this extension is that it allows you to work with single-component images with texture mapping, then use a pseudo-color visual to map the luminance values to color.
A GLXFBConfigSGIX (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.
Use glXChooseFBConfigSGIX() to get GLXFBConfigSGIX constructs that match a list of attributes or to get the list of GLXFBConfigSGIX constructs (FBConfigs) that are available on the specified screen.
GLXFBConfigSGIX *glXChooseFBConfigSGIX(Display *dpy, int screen,
const int *attrib_list, int *nitems)
|
If attrib_list is NULL, glXChooseFBConfigSGIX() returns an array of FBConfigs that are available on the specified screen; otherwise this call returns an array of FBConfigs that match the specified attributes. Table 6-6 shows only attributes added by this extension; additional attributes are listed on the glXChooseVisual reference page.
Table 6-6. Visual Attributes Introduced by the FBConfig Extension
Attribute | Type | Description |
|---|---|---|
bitmask | Mask indicating which GLX drawables are supported. Valid bits are GLX_WINDOW_BIT_SGIX and GLX_PIXMAP_BIT_SGIX. | |
bitmask | Mask indicating which OpenGL rendering modes are supported. Valid bits are GLX_RGBA_BIT_SGIX and GLX_COLOR_INDEX_BIT_SGIX. | |
boolean | True if X can render to drawable. | |
XID | XID of 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, behaves exactly like the “smaller” criterion. | |
| exact | Only FBConfigs whose corresponding attribute value exactly matches the requested value are considered. | |
| mask | For a config 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.) |
Note that “don't care” means that the default behavior is to have no preference when searching for a matching FBConfig.
Table 6-7 illustrates how each attribute is matched.
Table 6-7. FBConfig Attribute Defaults and Sorting Criteria
Attribute | Default | Sorting Criteria |
|---|---|---|
GLX_BUFFER_SIZE | 0 | Smaller |
GLX_LEVEL | 0 | Smaller |
GLX_DOUBLEBUFFER | Don't care | 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_SGIS | 0 if GLX_SAMPLES_ SGIS = 0, | Smaller |
GLX_SAMPLES_SGIS | 0 | Smaller |
GLX_X_VISUAL_TYPE_EXT | Don't care | Exact |
GLX_TRANSPARENT_TYPE_EXT | GLX_NONE_EXT | Exact |
GLX_TRANSPARENT_INDEX_VALUE_EXT | Don't care | Exact |
GLX_TRANSPARENT_RED_VALUE_EXT | Don't care | Exact |
GLX_TRANSPARENT_GREEN_VALUE_EXT | Don't care | Exact |
GLX_TRANSPARENT_BLUE_VALUE_EXT | Don't care | Exact |
GLX_TRANSPARENT_ALPHA_VALUE_EXT | Don't care | Exact |
GLX_VISUAL_CAVEAT_EXT | GLX_NONE_EXT | Exact, if specified, otherwise minimum |
GLX_DRAWABLE_TYPE_SGIX | GLX_WINDOW_BIT_ SGIX | Mask |
GLX_RENDER_TYPE_SGIX | GLX_RGBA_BIT_SGIX | Mask |
GLX_X_RENDERABLE_SGIX | Don't care | Exact |
GLX_FBCONFIG_ID_SGIX | Don't care | Exact |
There are several uses for the glXChooseFBConfigSGIX() function:
Retrieve all FBConfigs on the screen (attrib_list is NULL).
Retrieve an FBConfig with a given ID specified with GLX_FBCONFIG_ID_SGIX.
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 glXGetFBConfigAttribSGIX() 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 “SGIX_pbuffer—The Pixel Buffer Extension”). In the case of a window, you must first get the associated X visual by calling glXGetVisualFromFBConfigSGIX().
Below is a description of what happens when you call glXChooseFBConfigSGIX():
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 doesn't 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 glXChooseFBConfigSGIX().
If GLX_RENDER_TYPE_SGIX 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_SGIX | GLX_COLOR_INDEX_BIT_SGIX is specified as the mask, then glXChooseFBConfigSGIX() 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_SGIX is GLX_RGBA_BIT_SGIX.
The attribute GLX_DRAWABLE_TYPE_SGIX has 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_SGIX | GLX_PIXMAP_BIT_SGIX is specified as the mask for GLX_DRAWABLE_TYPE_SGIX then glXChooseFBConfigSGIX() searches for FBConfigs that support both windows and GLX pixmaps. The default value for GLX_DRAWABLE_TYPE_SGIX is GLX_WINDOW_BIT_SGIX.
If an FBConfig supports windows it has an associated X visual. Use the GLX_X_VISUAL_TYPE_EXT 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_EXT attribute is ignored if GLX_DRAWABLE_TYPE_SGIX is specified in attrib_list and the mask that follows doesn't have GLX_WINDOW_BIT_SGIX set.
GLX_X_RENDERABLE_SGIX 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.
To get the value of a GLX attribute for an FBConfig, call
int glXGetFBConfigAttribSGIX(Display *dpy, GLXFBConfigSGIX config,
int attribute, int *value)
|
If glXGetFBConfigAttribSGIX() 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_SGIX value has the GLX_WINDOW_BIT_SGIX bit set. |
To retrieve the associated visual, call
XVisualInfo *glXGetVisualFromFBConfigSGIX(Display *dpy,
GLXFBConfigSGIX 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.
It is also possible to get an FBConfig, given visual information:
GLXFBConfigSGIX glXGetFBConfigFromVisualSGIX(Display *dpy, XVisualInfo *vis) |
If the visual is valid and supports OpenGL rendering (that is, if the GLX visual attribute GLX_USE_GL is GL_TRUE) then the associated FBConfig is returned; otherwise NULL is returned.
To create a GLX rendering context or a GLX pixmap using an FBConfig, call glXCreateContextWithConfigSGIX() or glXCreateGLXPixmapWithConfigSGIX(), which have the following prototypes:
GLXContext glXCreateContextWithConfigSGIX( Display *dpy,
GLXFBConfigSGIX config,
int render_type,
GLXContext share_list,
Bool direct )
GLXPixmap glXCreateGLXPixmapWithConfigSGIX( Display *dpy,
GLXFBConfigSGIX config,
Pixmap pixmap )
|
The functions are similar to glXCreateContext() and glXCreateGLXPixmap(). See the glXCreateContextWithConfigSGIX and glXCreateGLXPixmapWithConfigSGIX reference pages for detailed information.
If more than one FBConfig matches the specification, they are prioritized as follows (Table 6-7 summarizes this information):
Preference is given to FBConfigs with the largest GLX_RED_SIZE, GLX_GREEN_SIZE, and GLX_BLUE_SIZE.
If the requested GLX_ALPHA_SIZE is zero, preference is given to FBConfigs that have GLX_ALPHA_SIZE set to zero; otherwise preference is given to FBConfigs that have the largest GLX_ALPHA_SIZE value.
If the requested number of GLX_AUX_BUFFERS is zero, preference is given to FBConfigs that have GLX_AUX_BUFFERS set to zero; otherwise preference is given to FBConfigs that have the smallest GLX_AUX_BUFFERS value.
If the requested size of a particular ancillary buffer is zero (for example, GLX_DEPTH_BUFFER is zero), preference is given to FBConfigs that also have that size set to zero; otherwise preference is given to FBConfigs that have the largest size.
If the requested value of either GLX_SAMPLE_BUFFERS_SGIS or GLX_SAMPLES_SGIS is zero, preference is given to FBConfigs that also have these attributes set to zero; otherwise preference is given to FBConfigs that have the smallest size.
If GLX_X_VISUAL_TYPE_EXT is not specified but there is an X visual associated with the FBConfig, the visual type is used to prioritize the FBConfig.
If GLX_RENDER_TYPE_SGIX has GLX_RGBA_BIT_SGIX set, the visual types are prioritized as follows: TrueColor, DirectColor, PseudoColor, StaticColor, GrayScale, and StaticGray.
If only the GLX_COLOR_INDEX_SGIX is set in GLX_RENDER_TYPE_SGIX, visual types are prioritized as PseudoColor, StaticColor, GrayScale, and StaticGray.
If GLX_VISUAL_CAVEAT_EXT is set, the implementation for the particular system on which you run determines which visuals are returned. See “EXT_visual_rating—The Visual Rating Extension” for more information.
You can use the pixel buffer extension, SGIX_pbuffer, to define a pixel buffer (GLXPbuffer or pbuffer for short).
| Note: This extension is an SGIX (experimental) extension. The interface or other aspects of the extension may change. |
A GLXPbuffer is an additional non-visible rendering buffer for an OpenGL renderer. It has the following distinguishing characteristics:
Support hardware-accelerated rendering. Pbuffers support hardware-accelerated rendering in an off-screen buffer, unlike pixmaps, which typically do not allow accelerated rendering.
Window independent. Pbuffers differ from auxiliary buffers (aux buffers) because they are not related to any displayable window, so a pbuffer may not be the same size as the application's window, while an aux buffer must be the same size as its associated window.
A pbuffer is equivalent to a GLXPixmap, with the following exceptions:
There is no associated X pixmap. Also, since pbuffers are a GLX resource, it may not be possible to render to them using X or an X extension other than GLX.
The format of the color buffers and the type and size of associated ancillary buffers for a pbuffer can be described only with an FBConfig; an X visual cannot be used.
It is possible to create a pbuffer whose contents may be arbitrarily and asynchronously lost at any time.
A pbuffer works with both direct and indirect rendering contexts.
A pbuffer is allocated in non-visible framebuffer memory, that is, areas for which hardware-accelerated rendering is possible. Applications include additional color buffers for rendering or image processing algorithms.
Pbuffers can be either “volatile,” that is, their contents can be destroyed by another window or pbuffer, or “preserved,” that is, their contents are guaranteed to be correct and are swapped out to virtual memory when other windows need to share the same framebuffer space. The contents of a preserved pbuffer are swapped back in when the pbuffer is needed. The swapping operation incurs a performance penalty, so preserved pbuffers should be used only if re-rendering the contents is not feasible.
A pbuffer is intended to be a “static” resource: a program typically allocates it only once, rather than as a part of its rendering loop. The framebuffer resources that are associated with a GLXPbuffer are also static. They are deallocated only when the GLXPbuffer is destroyed, or, in the case of volatile pbuffers, as the result of X server activity that changes framebuffer requirements of the server.
To create a GLXPbuffer, call glXCreateGLXPbufferSGIX():
GLXPbufferSGIX glXCreateGLXPbufferSGIX(Display *dpy, GLXFBConfigSGIX config,
unsigned int *width, unsigned int *height, int attrib_list)
|
This call creates a single GLXPbuffer and returns its XID.
width and height specify the pixel width and height of the rectangular GLXPbuffer.
attrib_list specifies a list of attributes for the GLXPbuffer. (Note that the attribute list is defined in the same way as the list for glXChooseFBConfigSGIX(): attributes are immediately followed by the corresponding desired value and the list is terminated with None.)
Currently only two attributes can be specified in attrib_list: GLX_CONTENTS_PRESERVED_SGIX and GLX_GET_LARGEST_PBUFFER_SGIX.
Use GLX_GET_LARGEST_PBUFFER_SGIX to get the largest available GLXPbuffer when the allocation of the pbuffer would otherwise fail. The width and height of the pbuffer (if one was allocated) are returned in width and height. Note that these values can never exceed the width and height that were initially specified. By default, GLX_GET_LARGEST_PBUFFER_SGIX is False.
If the GLX_CONTENTS_PRESERVED_SGIX attribute is set to False in attrib_list, a “volatile” GLXPbuffer is created and the contents of the pbuffer may be lost at any time. If this attribute is not specified, or if it is specified as True in attrib_list, the contents of the pbuffer are preserved, most likely by swapping out portions of the buffer to main memory when a resource conflict occurs. In either case, the client can register to receive a “buffer clobber” event and be notified when the pbuffer contents have been swapped out or have been damaged.
The resulting GLXPbuffer 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 glXCreateGLXPbufferSGIX() fails to create a GLXPbuffer due to insufficient resources, a BadAlloc X protocol error is generated and NULL is returned. If config is not a valid FBConfig then a GLXBadFBConfigSGIX error is generated; if config doesn't 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 reference pages for glXCreateContextWithConfigSGIX, glXMakeCurrent, and glXMakeCurrentReadSGI.
If a GLXPbuffer is created with GLX_CONTENTS_PRESERVED_SGIX 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 GLXPbuffer 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 GLXPbuffer, but the values of the returned pixels are undefined.
Because the contents of a volatile GLXPbuffer can be lost at any time with only asynchronous notification (via 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 don't 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 GLXPbuffer call glXDestroyGLXPbufferSGIX():
void glXDestroyGLXPbufferSGIX(Display *dpy, GLXPbufferSGIX pbuf) |
To query an attribute associated with a GLXPbuffer, call glXQueryGLXPbufferSGIX():
void glXQueryGLXPbufferSGIX(Display *dpy, GLXPbufferSGIX pbuf, int attribute
unsigned int *value)
|
To get the FBConfig for a GLXPbuffer, first retrieve the ID for the FBConfig and then call glXChooseFBConfigSGIX(). See “SGIX_fbconfig—The Framebuffer Configuration Extension”.
An X client can ask to receive GLX events on a window or GLXPbuffer by calling glXSelectEventSGIX():
void glXSelectEventSGIX(Display *dpy, GLXDrawable drawable, unsigned long mask) |
Currently you can only select the GLX_BUFFER_CLOBBER_BIT_SGIX GLX event as the mask. The event structure is
typdef struct {
int event_type; /* GLX_DAMAGED_SGIX or GLX_SAVED_SGIX */
int draw_type; /* GLX_WINDOW_SGIX or GLX_PBUFFER_SGIX */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if it came for SendEvent request */
Display *display; /* display the event was read from */
GLXDrawable drawable; /* i.d. of Drawable */
unsigned int mask; /* mask indicating which buffers are affected*/
int x, y;
int width, height;
int count; /* if nonzero, at least this many more */
} GLXBufferRestoreEvent;
|
A single X server operation can cause several buffer clobber events to be sent, for example, a single GLXPbuffer 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 even commands (XNextEvent(), XPending(), and so on). The 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_SGIX GLX_FRONT_RIGHT_BUFFER_BIT_SGIX GLX_BACK_LEFT_BUFFER_BIT_SGIX GLX_BACK_RIGHT_BUFFER_BIT_SGIX GLX_AUX_BUFFERS_BIT_SGIX GLX_DEPTH_BUFFER_BIT_SGIX GLX_STENCIL_BUFFER_BIT_SGIX GLX_ACCUM_BUFFER_BIT_SGIX GLX_SAMPLE_BUFFERS_BIT_SGIX |
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:
For a preserved GLXPbuffer, a buffer clobber event, with type GLX_SAVED_SGIX, is generated whenever the contents of the GLXPbuffer are swapped out to host memory. The event(s) describes which portions of the GLXPbuffer were affected. Clients who receive many buffer clobber events, referring to different save actions, should consider freeing the GLXPbuffer resource to prevent the system from thrashing due to insufficient resources.
For a volatile GLXPbuffer, a buffer clobber event with type GLX_DAMAGED_SGIX is generated whenever a portion of the GLXPbuffer becomes invalid. The client may wish to regenerate the invalid portions of the GLXPbuffer.
Calling glXSelectEventSGIX() overrides any previous event mask that was set by the client for the drawable. Note that it doesn't 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 GLXPbuffer, call glXGetSelectedEventSGIX():
void glXSelectEventSGIX(Display *dpy, GLXDrawable drawable,
unsigned long mask)
|