glXCreateGLXPbufferSGIX(3G)
glXCreateGLXPbufferSGIX - create a GLX pixel buffer
As shipped in IRIX 6.5.22. Unchanged since IRIX 6.5.
NAME glXCreateGLXPbufferSGIX - create a GLX pixel buffer C SPECIFICATION GLXPbufferSGIX glXCreateGLXPbufferSGIX( Display *dpy, GLXFBConfigSGIX config, unsigned int width, unsigned int height, int *attrib_list ) PARAMETERS dpy Specifies the connection to the X server. config Specifies the GLXFBConfig that defines the configuration of the pixel buffer. width Specifies the width of the pixel buffer. height Specifies the height of the pixel buffer. attrib_list Specifies the attributes for the pixel buffer. DESCRIPTION glXCreateGLXPbufferSGIX creates a single GLX pixel buffer and returns its handle. The resulting GLX pixel buffer will contain color buffers and ancillary as specified by config. If glXCreateGLXPbufferSGIX fails to create a GLX pixel buffer, then None is returned. A GLX pixel buffer is a non-visible rendering buffer for an OpenGL renderer. GLX pixel buffers are equivalent to GLX pixmaps with the following exceptions: There is no associated X pixmap. Also, since GLX pixel buffers 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 any associated ancillary buffers for a GLX pixel buffer can only be described with a GLXFBConfig -- an X Visual cannot be used. It is possible to create a GLX pixel buffer whose contents may be arbitrarily and asynchronously lost at any time. GLX pixel buffers must work with both direct and indirect rendering contexts. attrib_list specifies a list of attributes for the GLX pixel buffer. Each attribute in attrib_list is followed by the the corresponding desired value and the list is terminated with None. If attrib_list is NULL, then all the attributes assume their default values as described below. Currently only three attributes can be specified: GLX_LARGEST_PBUFFER_SGIX, GLX_PRESERVED_CONTENTS_SGIX and GLX_DIGITAL_MEDIA_PBUFFER_SGIX. Use GLX_LARGEST_PBUFFER_SGIX to get the largest available GLX pixel buffer when the allocation of the buffer would otherwise fail. The width and height of the pixel buffer (if one was allocated) can be determined by calling glXQueryGLXPbufferSGIX. Note that these values can never exceed the width and height that were initially specified. By default, GLX_LARGEST_PBUFFER_SGIX is False. If the GLX_PRESERVED_CONTENTS_SGIX attribute is set to False, then an unpreserved GLX pixel buffer is created and the contents of the pixel buffer may be lost at any time. If this attribute is not specified, or if it is specified as True, then the contents of the GLX pixel buffer will be preserved, most likely by swapping out the entire buffer, or a portion 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 GLX pixel buffer contents have been swapped out or have been damaged. (See glXSelectEventSGIX.) If the GLX_DIGITAL_MEDIA_PBUFFER_SGIX attribute is set to True, and the SGIX_dm_pbuffer extension is supported, then one or more of the pixel buffer's color or ancillary buffers may be shared with those of a currently associated DMbuffer. (See glXAssociateDMPbufferSGIX.) Buffers described by config that are not shared with the DMbuffer are created as GLX resources, and remain associated with the pixel buffer until it is destroyed. As mentioned above, the contents, or a portion of the contents, for an unpreserved GLX pixel buffer may be lost. It is not an error to render to a GLX pixel buffer 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 buffer, but the values of the returned pixels are undefined. It is possible to create a GLX pixel buffer with back buffers and to swap the front and back buffers by calling glXSwapBuffers. Note that GLX pixel buffers use framebuffer resources so applications should consider deallocating them when they are not in use. Any GLX rendering context created with a GLXFBConfig or X Visual that is compatible with config may be used to render into the GLX pixel buffer. A GLX context and a GLX pixel buffer are compatible if: The context's render_type attribute (either GLX_RGBA_TYPE_SGIX or GLX_COLOR_INDEX_TYPE_SGIX) is supported by the GLXFBConfigSGIX that the pixel buffer was created with. For example, if the context's render_type attribute is GLX_RGBA_TYPE_SGIX, then the GLX_RENDER_TYPE_SGIX attribute of the pixel buffer's GLXFBConfigSGIX must have the GLX_RGBA_BIT_SGIX bit set. All color buffers and ancillary buffers that exist in both GLXFBConfigSGIXs have the same depth. For example, a GLXFBConfigSGIX that has a front left buffer and a back left buffer with red, green and blue sizes of 4 is not compatible with a GLXFBConfigSGIX that has only a front left buffer with red, green and blue sizes of 8. However, it is compatible with a GLXFBConfigSGIX that has only a front left buffer if the red, green and blue sizes are 4. NOTES glXCreateGLXPbufferSGIX is part of the SGIX_pbuffer extension. Since the contents of a unpreserved GLX pixel buffer can be lost at anytime 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 should not be done frequently. Also, since this locks out other X clients, it should only be done for short periods of time.) Clients 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 buffer clobber events (assuming that these events had been pulled off of the queue prior to the glReadPixels call). ERRORS If there are insufficient resources to create the pbuffer, a BadAlloc error is generated and None is returned. A GLXBadFBConfigSGIX error is generated if config is not a valid GLXFBConfig. A BadMatch error is generated if config does not support GLX pixel buffers. ASSOCIATED GETS glXQueryGLXPbufferSGIX MACHINE DEPENDENCIES The SGIX_pbuffer extension is supported only on RealityEngine, RealityEngine2, and VTX systems, on InfiniteReality systems, on High Impact and Maximum Impact systems, and on O2 systems. The SGIX_dm_pbuffer extension is currently supported only on O2 systems. On O2 systems the GLX_LARGEST_PBUFFER_SGIX attribute may incorrectly limit the size of the pbuffer created when the requested dimensions are larger than the screen. It is possible to allocate pbuffers up to 2048 square with the attribute set to False. SEE ALSO glXMakeCurrent, glXCreateContextWithConfigSGIX, glXChooseFBConfigSGIX, glXGetFBConfigAttribSGIX, glXDestroyGLXPbufferSGIX, glXSelectEventSGIX, glXAssociateDMPbufferSGIX.