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
     GLXDIGITALMEDIAPBUFFERSGIX 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) DMIMAGEWIDTH
     and DMIMAGEHEIGHT must exactly match the width and height of the
     pbuffer, as passed to glXCreateGLXPbufferSGIX; (2) DMIMAGELAYOUT must
     be set to DMIMAGELAYOUTGRAPHICS; and (3) DMIMAGEPACKING 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 SGIXdmpbuffer 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 SGIXdmpbuffer extension is currently supported only on O2 systems.


SEE ALSO
     glXCreateGLXPbufferSGIX, glXMakeCurrentReadSGI, dmParamsCreate,
     dmSetImageDefaults, DMbuffer, VLintro(3dm)




















                                                                        Page 2