glXAssociateDMPbufferSGIX(3G) OpenGL Reference - GLX
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
Page 1
glXAssociateDMPbufferSGIX(3G) OpenGL Reference - GLX
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)
Page 2
