glXAssociateDMPbufferSGIX(3G)
glXAssociateDMPbufferSGIX - associate a DMbuffer with a GLX pixel buffer
As shipped in IRIX 6.5.15. Unchanged since IRIX 6.5.
NAME glXAssociateDMPbufferSGIX - associate a DMbuffer with a GLX pixel buffer C SPECIFICATION Bool glXAssociateDMPbufferSGIX( Display *dpy, GLXPbufferSGIX pbuffer, DMparams *params, DMbuffer dmbuffer ) PARAMETERS dpy A connection to an X server. pbuffer The GLX pixel buffer target of the associate operation. params A parameter list that describes the format of the images in the DMbuffer that is to be associated with the pixel buffer. dmbuffer The DMbuffer that will be used as the front left color buffer. DESCRIPTION glXAssociateDMPbufferSGIX associates a DMbuffer with a GLX pixel buffer. While associated, pbuffer adopts dmbuffer as its front left color buffer, which may then be used as a non-displayable GL rendering area, or as a copy source for pixel or texture image data through glXMakeCurrentReadSGI. glXAssociateDMPbufferSGIX returns True if it is successful, False otherwise. To succeed, pbuffer must have been created with the GLX_DIGITAL_MEDIA_PBUFFER_SGIX attribute set to True, and params must describe a DMbuffer that is compatible with the GLXFBConfigSGIX used to create pbuffer. Compatibility is defined as follows: (1) DM_IMAGE_WIDTH and DM_IMAGE_HEIGHT must exactly match the width and height of the pbuffer, as passed to glXCreateGLXPbufferSGIX; (2) DM_IMAGE_LAYOUT must be set to DM_IMAGE_LAYOUT_GRAPHICS; and (3) DM_IMAGE_PACKING must be set to match the red, green, blue, and alpha depths of the pbuffer. The packing to use is determined by the pixel depths: ________________________________________________________ Red Green Blue Alpha Packing ________________________________________________________ 8 8 8 8 DM_IMAGE_PACKING_RGBA 5 5 5 1 DM_IMAGE_PACKING_XRGB1555 3 3 2 0 DM_IMAGE_PACKING_RGB332 ________________________________________________________ | | When glXAssociateDMPbufferSGIX succeeds, any previously associated DMbuffer is released - and freed if it has no remaining clients. The pbuffer drawable must be associated with a DMbuffer before it can be made current to a GLXContext; and cannot be associated with a dmbuffer parameter of None while it remains current to a context. WARNING: A single DMbuffer should not be used with both glXAssociateDMPbufferSGIX and dmBufferMapData. Cache coherency is not guaranteed if a DMbuffer that has been rendered into is mapped, or if a mapped buffer is rendered into. NOTES glXAssociateDMPbufferSGIX is part of the SGIX_dm_pbuffer extension. ERRORS BadDrawable is generated if pbuffer was not created with the Digital Media attribute, or was created using a different Display. BadMatch is generated if pbuffer and dmbuffer are incompatible. MACHINE DEPENDENCIES On O2 systems, when the current read drawable is a DM pbuffer, using glXCopyTexSubImage2D or glXCopyTexSubImage2DEXT to copy into a full texture image whose dimensions and format match those of the pbuffer causes a copy-by-reference. This has performance advantages, especially for video-generated DMbuffers, because it provides a DMA path for updating textures. Following the copy, rendering to the pbuffer or otherwise modifying the DMbuffer, will directly affect texture memory. However, this behavior is essentially an unspecified side-effect of the implementation on O2, and cannot be used on other systems. The SGIX_dm_pbuffer extension is currently supported only on O2 systems. SEE ALSO glXCreateGLXPbufferSGIX, glXMakeCurrentReadSGI, dmParamsCreate, dmSetImageDefaults, DMbuffer, VLintro(3dm)