glXCreatePbuffer Subroutine

OpenGL 1.2 for AIX: Reference Manual

glXCreatePbuffer Subroutine

Purpose

Creates an off-screen GLX rendering area in a non-visible framebuffer area.

Library

OpenGL C bindings library: libGL.a

C Syntax

GLXPbuffer glXCreatePbuffer(Display *dpy,

                            GLXFBConfig config,

                            const int *AttributeList)

Description

The glXCreatePbuffer subroutine creates an off-screen rendering area in a non-visible area of the framebuffer and returns its XID. Any GLX rendering context that was created with respect to the config parameter can be used to render into this off-screen area. Use the glXMakeContextCurrent subroutine to associate the rendering area with a GLX rendering context.

The resulting pbuffer will contain color buffers and ancillary buffers as specified by the config parameter, GLX pbuffers with double-buffering are supported. The glXSwapBuffers subroutine can be called to swap the front and back buffers.

Parameters

dpy

Specifies the connection to the X server.

config

Specifies the GLX FBConfig that defines the structure of the rendering area.

AttributeList

Specifies a list of GLX attribute/value pairs that help define the GLX Pbuffer. The list has the same structure as described for the glXChooseFBConfig subroutine. The following attributes can be used in the attribute list:

Attributes	Description
GLX_PBUFFER_WIDTH	Specifies the pixel width of the rectangular pbuffer. This defaults to 0.
GLX_PBUFFER_HEIGHT	Specifies the pixel height of the rectangular pbuffer. This defaults to 0.
GLX_LARGEST_PBUFFER	A boolean value that specifies that the largest available pbuffer should be gotten if the allocation of the pbuffer would otherwise fail. The width and height of the allocated pbuffer will never exceed the values of GLX_PBUFFER_WIDTH and GLX_PBUFFER_HEIGHT, respectively. Use glXQueryDrawable to retrieve the dimensions of the allocated pbuffer. By default, GLX_LARGEST_PBUFFER is set to False.
GLX_PRESERVED_CONTENTS	A boolean value. If it is specified as False, then an unpreserved pbuffer is created and the contents of the pbuffer may be lost at any time. Once the contents of an unpreserved pbuffer have been lost, it is considered to be in a damaged state. It is not an error to render to a pbuffer that is in this state but the effect of rendering to it is the same as if the pbuffer were destroyed: the context state will be updated but the frame buffer state becomes undefined. It is also not an error to query the pixel contents of such a pbuffer, but the values of the returned pixels are undefined. If it is specified as True (the default value), then when a resource conflict occurs the contents of the pbuffer will be preserved. In either case, the application can register to receive a pbuffer clobber event, which is generated when the pbuffer contents have been preserved or have been damaged. (See glXSelectEvent for more information). Since the contents of an unpreserved pbuffer can be lost at any time with only asynchronous notification (via the pbuffer clobber event), the only way an application can guarantee that valid pixels are read back with glReadPixels is by grabbing the X server. Applications that don't wish to do this can check if the data returned by glReadPixels is valid by calling XSync and then checking the event queue for pbuffer clobber events (assuming that these events had been pulled off of the queue prior to the call to glReadPixels.

Error Codes

BadAlloc	Is generated if the server cannot allocate the GLX pbuffer.
BadFBConfig	Is generated if config is not a valid GLX FBConfig.
BadMatch	Is generated if config does not support pbuffer rendering.
BadValue	Is generated if the value for GLX_PBUFFER_WIDTH or GLX_PBUFFER_HEIGHT is zero or less (IBM X server only). Note that, by default, the values of these attributes are zero.

Files

/usr/include/GL/gl.h	Contains C language constants, variable type definitions, and ANSI function prototypes for OpenGL.
/usr/include/GL/glx.h	Contains C language constants, variable type definitions, and ANSI function prototypes for GLX.

Related Information

The glXCreateNewContext subroutine, glXMakeContextCurrent subroutine, glXChooseFBConfig subroutine, glXSelectEvent subroutine.

OpenGL in the AIXwindows (GLX) Environment.

OpenGL Overview.