1XXX - Not complete. 2 3Name 4 5 SGIX_dmbuffer 6 7Name Strings 8 9 GLX_SGIX_dm_buffer 10 11Version 12 13 $Date: 1997/09/26 09:48:00 $ $Revision: 1.6 $ 14 15Number 16 17 86 18 19Dependencies 20 21 SGIX_FBConfig is required 22 SGI_make_current_read is required. 23 SGIX_pbuffer 24 25Overview 26 27 This extension introduces a new type of GLXPbuffer, a DM or Digital 28 Media pbuffer. A DM pbuffer is a GLXPbuffer that adopts one or more 29 of its buffers from an externally defined and allocated DMbuffer. 30 In this way it resembles a GLXPixmap that attaches to an existing 31 X pixmap. Like a standard pbuffer it can be used as a non-displayable 32 rendering area, or as a read source for pixel data. The externally 33 defined buffers of the DM pbuffer can be sequentially associated 34 with other DM buffers of the same size and configuration. 35 36 . The DM pbuffer is described with a new attrib passed to 37 glXCreateGLXPbuffer. 38 39 . A new GLX command allows associating a compatible DMbuffer with 40 the DM GLXPbuffer. At associate time the DM buffers described 41 by the DMparams are used directly as the corresponding 42 buffers of the GLXPbuffer drawable, as described by the FBconfig. 43 All other buffers that are part of the config will be created by 44 GL without externally referenceable names. A DM pbuffer must be 45 associated with a compatible DMbuffer before it can be made current 46 to a GLX context. 47 48 . The externally defined buffers of the DM pbuffer can be changed at 49 any time by successfully associating a new DMbuffer with the GLXPbuffer 50 through the associate command. It will be the application's 51 responsibility to synchronize DMedia, GLX, and GL commands that 52 effect the contents of the DM pbuffer. 53 54 . Any direct GLX rendering context that satisfies config compatibility 55 can be used to render to or read from a DM GLXPbuffer. 56 A currently associated DMbuffer may simultaneously be in use by 57 other clients on the same Display, but will not be destroyed 58 while associated with a GLXPbuffer. When the GLXpbuffer is 59 destroyed, all buffers that have no remaining clients, including 60 the DMbuffer, will be freed. 61 62 DM GLXPbuffers are proposed as a means for OpenGL to access buffers 63 generated by the VL, compression, and other digital media libraries in 64 a uniform way. The DMbuffer and DMparams descriptors are left 65 intentionally abstract so that the GLX extension can adapt to future 66 DM library changes. 67 The initial implementation will require that the DMparams descriptor 68 supply at least pixel format and packing information, and that the 69 DMbuffer provide the size and location of a colorbuffer. GLX will do 70 compatibility checking when possible based on the config, params, and 71 buffer information at associate time. 72 73Issues 74 75 76New Procedures and Functions 77 78 Bool glXAssociateDMPbufferSGIX(Display *dpy, 79 GLXPbufferSGIX pbuffer, 80 DMparams *params, 81 DMbuffer dmbuffer); 82 83New Tokens 84 85 Accepted by the <attrib_list> parameter of glXCreateGLXPbufferSGIX 86 and by the <attribute> parameter of glXQueryGLXPbufferSGIX: 87 88 GLX_DIGITAL_MEDIA_PBUFFER_SGIX 0x8024 89 90 91Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) 92 93 None 94 95Additions to Chapter 3 of the 1.0 Specification (Rasterization) 96 97 None 98 99Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations 100and the Frame buffer) 101 102Additions to Chapter 5 of the 1.0 Specification (Special Functions) 103 104 None. 105 106Additions to Chapter 6 of the 1.0 Specification (State and State Requests) 107 108 None. 109 110Additions to the GLX Specification 111 112 XXX - not complete yet 113 114 [Add the following to section 3.2.3 on Offscreen Rendering] 115 116 To create a GLXPbuffer call: 117 118 GLXPbuffer glXCreateGLXPbufferSGIX(Display *dpy, 119 GLXFBConfig config, 120 unsigned int width, 121 unsigned int height, 122 int *attrib_list); 123 124 This creates a single GLXPbuffer and returns its XID. <width> and <height> 125 specify the pixel width and height of the rectangular pbuffer and 126 <attrib_list> specifies a list of attributes for the pbuffer. Currently 127 only three attributes can be specified in <attrib_list>: 128 GLX_PRESERVED_CONTENTS_SGIX, GLX_LARGEST_PBUFFER_SGIX and 129 GLX_DIGITAL_MEDIA_PBUFFER_SGIX. 130 131 [Add following the section on the GLX_PRESERVED_CONTENTS_SGIX attrib] 132 133 The resulting pbuffer, when made current, will contain color buffers 134 and ancillary buffers as specified by <config>. It is possible to create 135 a pbuffer with back buffers and to swap the front and back buffers by 136 calling glXSwapBuffers. Note that some pbuffers use framebuffer resources 137 so applications should consider deallocating them when they are not in use. 138 139 If the GLX_DIGITAL_MEDIA_PBUFFER_SGIX attribute is set to True in 140 <attrib_list>, then one or more of the pbuffer's color or ancillary 141 buffers may be shared with those of a currently associated DMbuffer. 142 Buffers described by the pbuffer's GLXFBConfig which are not defined 143 by the DMbuffer, are GLX resources that remain associated with the 144 DM pbuffer until it is destroyed. 145 An implementation may fail glXCreateGLXPbufferSGIX and generate a 146 BadMatch error when the sepcified <config> does not describe a 147 drawable that is compatible with any supported DMbuffers. 148 149 The GLXPbuffer is associated with a DMbuffer by calling: 150 151 Bool glXAssociateDMPbufferSGIX(Display *dpy, 152 GLXPbufferSGIX pbuffer, 153 DMparams *params, 154 DMbuffer dmbuffer); 155 156 The parameter <display> specifies a connection to an X server, and must 157 match the display used to create the GLXPbuffer <pbuffer>. The 158 DMparams <params> arg specifies the digital media characteristics 159 of the <dmbuffer> that will be associated with the DM pbuffer. 160 If glXAssociateDMbufferSGIX succeeds, any previously associated DMbuffer 161 is released and a value of True is returned. Subsequent GL commands 162 effect <dmbuffer> as they would any standard pbuffer. If a newly 163 released DMbuffer has no remaining clients, its buffers will also be freed. 164 A BadMatch error is generated when the specified DMparams or DMbuffer 165 are not compatible with the <pbuffer>, and a value of False is returned. 166 167 Before the DM pbuffer can be made current to a GLXContext, it must 168 be associated with a compatible DMbuffer. glXMakeCurrentReadSGI will 169 return False and generate a GLXBadDrawable error when a DM pbuffer 170 drawable has no associated DMbuffer. 171 172 A GLXPbuffer is destroyed by calling: 173 174 void glXDestroyGLXPbufferSGIX(Display *dpy, 175 GLXPbuffer pbuf); 176 177 The GLXPbuffer will be destroyed once it is no longer current to any 178 client. When a GLXPbuffer is destroyed, any memory resources that 179 attached to it, are freed, and its XID is made available for reuse. 180 Associated DMbuffers are released, and if they no lonnger have a 181 client, are also freed. 182 183Errors 184 185 XXX - not complete yet 186 187New State 188 189 None. 190 191New Implementation Dependent State 192 193 None. 194 195