The Pixel Buffer Extension

The Pixel Buffer Extension

You can use the pixel buffer extension, SGIX_pbuffer, to define a pixel buffer (GLXPbuffer or pbuffer for short).

Caution: 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. 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 only be described with a GLXFBConfig; 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():

GLXPbuffer glXCreateGLXPbufferSGIX(Display *dpy, GLXFBConfig config, 
                  unsigned int *width, unsigned int *height, int attrib_list)

This 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.

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 GLXFBConfig then a GLXBadFBConfigSGIX error is generated; if config does not support pbuffers, a BadMatch X protocol error is generated.

Rendering to a GLXPbuffer
Directing the Buffer Clobber Event
New Functions