blob: 4d52de7476d1381e489bc9ff6cd4cdbdadaefa79 [file] [log] [blame]
XXX - Not complete.
Name
SGIX_dmbuffer
Name Strings
GLX_SGIX_dm_buffer
Version
$Date: 1997/09/26 09:48:00 $ $Revision: 1.6 $
Number
86
Dependencies
SGIX_FBConfig is required
SGI_make_current_read is required.
SGIX_pbuffer
Overview
This extension introduces a new type of GLXPbuffer, a DM or Digital
Media pbuffer. A DM pbuffer is a GLXPbuffer that adopts one or more
of its buffers from an externally defined and allocated DMbuffer.
In this way it resembles a GLXPixmap that attaches to an existing
X pixmap. Like a standard pbuffer it can be used as a non-displayable
rendering area, or as a read source for pixel data. The externally
defined buffers of the DM pbuffer can be sequentially associated
with other DM buffers of the same size and configuration.
. The DM pbuffer is described with a new attrib passed to
glXCreateGLXPbuffer.
. A new GLX command allows associating a compatible DMbuffer with
the DM GLXPbuffer. At associate time the DM buffers described
by the DMparams are used directly as the corresponding
buffers of the GLXPbuffer drawable, as described by the FBconfig.
All other buffers that are part of the config will be created by
GL without externally referenceable names. A DM pbuffer must be
associated with a compatible DMbuffer before it can be made current
to a GLX context.
. The externally defined buffers of the DM pbuffer can be changed at
any time by successfully associating a new DMbuffer with the GLXPbuffer
through the associate command. It will be the application's
responsibility to synchronize DMedia, GLX, and GL commands that
effect the contents of the DM pbuffer.
. Any direct GLX rendering context that satisfies config compatibility
can be used to render to or read from a DM GLXPbuffer.
A currently associated DMbuffer may simultaneously be in use by
other clients on the same Display, but will not be destroyed
while associated with a GLXPbuffer. When the GLXpbuffer is
destroyed, all buffers that have no remaining clients, including
the DMbuffer, will be freed.
DM GLXPbuffers are proposed as a means for OpenGL to access buffers
generated by the VL, compression, and other digital media libraries in
a uniform way. The DMbuffer and DMparams descriptors are left
intentionally abstract so that the GLX extension can adapt to future
DM library changes.
The initial implementation will require that the DMparams descriptor
supply at least pixel format and packing information, and that the
DMbuffer provide the size and location of a colorbuffer. GLX will do
compatibility checking when possible based on the config, params, and
buffer information at associate time.
Issues
New Procedures and Functions
Bool glXAssociateDMPbufferSGIX(Display *dpy,
GLXPbufferSGIX pbuffer,
DMparams *params,
DMbuffer dmbuffer);
New Tokens
Accepted by the <attrib_list> parameter of glXCreateGLXPbufferSGIX
and by the <attribute> parameter of glXQueryGLXPbufferSGIX:
GLX_DIGITAL_MEDIA_PBUFFER_SGIX 0x8024
Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)
None
Additions to Chapter 3 of the 1.0 Specification (Rasterization)
None
Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations
and the Frame buffer)
Additions to Chapter 5 of the 1.0 Specification (Special Functions)
None.
Additions to Chapter 6 of the 1.0 Specification (State and State Requests)
None.
Additions to the GLX Specification
XXX - not complete yet
[Add the following to section 3.2.3 on Offscreen Rendering]
To create a GLXPbuffer call:
GLXPbuffer glXCreateGLXPbufferSGIX(Display *dpy,
GLXFBConfig config,
unsigned int width,
unsigned int height,
int *attrib_list);
This creates a single GLXPbuffer and returns its XID. <width> and <height>
specify the pixel width and height of the rectangular pbuffer and
<attrib_list> specifies a list of attributes for the pbuffer. Currently
only three attributes can be specified in <attrib_list>:
GLX_PRESERVED_CONTENTS_SGIX, GLX_LARGEST_PBUFFER_SGIX and
GLX_DIGITAL_MEDIA_PBUFFER_SGIX.
[Add following the section on the GLX_PRESERVED_CONTENTS_SGIX attrib]
The resulting pbuffer, when made current, will contain color buffers
and ancillary buffers as specified by <config>. It is possible to create
a pbuffer with back buffers and to swap the front and back buffers by
calling glXSwapBuffers. Note that some pbuffers use framebuffer resources
so applications should consider deallocating them when they are not in use.
If the GLX_DIGITAL_MEDIA_PBUFFER_SGIX attribute is set to True in
<attrib_list>, then one or more of the pbuffer's color or ancillary
buffers may be shared with those of a currently associated DMbuffer.
Buffers described by the pbuffer's GLXFBConfig which are not defined
by the DMbuffer, are GLX resources that remain associated with the
DM pbuffer until it is destroyed.
An implementation may fail glXCreateGLXPbufferSGIX and generate a
BadMatch error when the sepcified <config> does not describe a
drawable that is compatible with any supported DMbuffers.
The GLXPbuffer is associated with a DMbuffer by calling:
Bool glXAssociateDMPbufferSGIX(Display *dpy,
GLXPbufferSGIX pbuffer,
DMparams *params,
DMbuffer dmbuffer);
The parameter <display> specifies a connection to an X server, and must
match the display used to create the GLXPbuffer <pbuffer>. The
DMparams <params> arg specifies the digital media characteristics
of the <dmbuffer> that will be associated with the DM pbuffer.
If glXAssociateDMbufferSGIX succeeds, any previously associated DMbuffer
is released and a value of True is returned. Subsequent GL commands
effect <dmbuffer> as they would any standard pbuffer. If a newly
released DMbuffer has no remaining clients, its buffers will also be freed.
A BadMatch error is generated when the specified DMparams or DMbuffer
are not compatible with the <pbuffer>, and a value of False is returned.
Before the DM pbuffer can be made current to a GLXContext, it must
be associated with a compatible DMbuffer. glXMakeCurrentReadSGI will
return False and generate a GLXBadDrawable error when a DM pbuffer
drawable has no associated DMbuffer.
A GLXPbuffer is destroyed by calling:
void glXDestroyGLXPbufferSGIX(Display *dpy,
GLXPbuffer pbuf);
The GLXPbuffer will be destroyed once it is no longer current to any
client. When a GLXPbuffer is destroyed, any memory resources that
attached to it, are freed, and its XID is made available for reuse.
Associated DMbuffers are released, and if they no lonnger have a
client, are also freed.
Errors
XXX - not complete yet
New State
None.
New Implementation Dependent State
None.