xglcomp
diff doc/texture_from_pixmap.txt @ 6:3f908f812ec7
added docs
| author | John Tsiombikas <nuclear@member.fsf.org> |
|---|---|
| date | Fri, 29 Jan 2016 10:23:08 +0200 |
| parents | |
| children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/doc/texture_from_pixmap.txt Fri Jan 29 10:23:08 2016 +0200 1.3 @@ -0,0 +1,792 @@ 1.4 +Name 1.5 + 1.6 + EXT_texture_from_pixmap 1.7 + 1.8 +Name Strings 1.9 + 1.10 + GLX_EXT_texture_from_pixmap 1.11 + 1.12 +Contributors 1.13 + 1.14 + James Jones, NVIDIA 1.15 + Aaron Plattner, NVIDIA 1.16 + Andy Ritger, NVIDIA 1.17 + 1.18 +Contact 1.19 + 1.20 + David Reveman, Novell, Inc. (davidr 'at' novell.com) 1.21 + 1.22 +Status 1.23 + 1.24 + Complete 1.25 + 1.26 +Version 1.27 + 1.28 + 17 (10 Feb 2009) 1.29 + 1.30 +Number 1.31 + 1.32 + 344 1.33 + 1.34 +Dependencies 1.35 + 1.36 + OpenGL 1.1 is required. 1.37 + GLX 1.3 is required. 1.38 + GL_EXT_framebuffer_object affects the definition of this extension. 1.39 + GL_ARB_texture_rectangle affects the definition of this extension. 1.40 + GL_ARB_texture_non_power_of_two affects the definition of this extension. 1.41 + GL_SGIS_generate_mipmap affects the definition of this extension. 1.42 + 1.43 +Overview 1.44 + 1.45 + This extension allows a color buffer to be used for both rendering and 1.46 + texturing. 1.47 + 1.48 + Only color buffers of pixmaps can be used for texturing by this extension 1.49 + but other types of drawables can be supported by future extensions layered 1.50 + on top of this extension. 1.51 + 1.52 + The functionality of this extension is similar to WGL_ARB_render_texture. 1.53 + However, the purpose of this extension is not to provide 1.54 + "render to texture" like functionality but rather the ability to bind 1.55 + an existing X drawable to a texture. Though, there is nothing that 1.56 + prohibits it from being used for "render to texture". 1.57 + 1.58 + - Windows are problematic as they can change size and therefore are not 1.59 + supported by this extension. 1.60 + 1.61 + - Only a color buffer of a GLX pixmap created using an FBConfig with 1.62 + attribute GLX_BIND_TO_TEXTURE_RGB_EXT or GLX_BIND_TO_TEXTURE_RGBA_EXT 1.63 + set to TRUE can be bound as a texture. 1.64 + 1.65 + - The texture internal format is determined when the color buffer 1.66 + is associated with the texture, guaranteeing that the color 1.67 + buffer format is equivalent to the texture internal format. 1.68 + 1.69 + - A client can create a complete set of mipmap images if 1.70 + EXT_framebuffer_object is supported. 1.71 + 1.72 + 1.73 +IP Status 1.74 + 1.75 + There are no known IP issues. 1.76 + 1.77 +Issues 1.78 + 1.79 + 1. What should this extension be called? 1.80 + 1.81 + Even though it is very similar to WGL_ARB_render_texture that name is 1.82 + not appropriate as the intention of this extension is not 1.83 + "render to texture" like functionality. 1.84 + 1.85 + EXT_texture_from_pixmap seams most appropriate. Layering of future 1.86 + extensions on top of this extension for using other type of drawables 1.87 + as textures follows the same conventions as vertex/pixel buffer objects 1.88 + and vertex/fragment programs. 1.89 + 1.90 + 1.91 + 2. Should we allow applications to render to different mipmap levels and 1.92 + cube map faces? 1.93 + 1.94 + In order to discourage the use of this extension as a render to texture 1.95 + mechanism, cube maps and rendering directly to mip-map levels > 0 will 1.96 + not be supported. A new FBConfig attribute is introduced that specifies 1.97 + whether or not drawables created with that config will support multiple 1.98 + mipmap levels when bound to a texture. The other mipmap levels can be 1.99 + filled in by the EXT_framebuffer_object GenerateMipmapEXT function. 1.100 + 1.101 + Specifying which level of a pixmap was being rendered to on a per-drawable 1.102 + basis, as was done in the WGL_ARB_render_texture extension, also 1.103 + introduces concurrency issues. The state of the drawable when it was 1.104 + being rendered two by two separate threads of execution and both were 1.105 + changing the mipmap level was difficult to define. 1.106 + 1.107 + It is also desireable to keep this extension as simple as possible. 1.108 + Adding functionality that complicates the implementation and that is not 1.109 + directly relevenat to the goal of exposing a mechanism for texturing from 1.110 + arbitrary X pixmaps is not productive. If the ability to render directly 1.111 + to all levels of a texture is needed, EXT_framebuffer_object is the 1.112 + extension that should be used. 1.113 + 1.114 + 1.115 + 3. Should 1D textures be supported? 1.116 + 1.117 + X servers layered on top of an OpenGL implementation might not be able 1.118 + to support this. A new FBConfig attribute is introduced specifying 1.119 + which texture targets a drawable created with the given FBConfig can 1.120 + be bound to. 1.121 + 1.122 + 1.123 + 4. What should the default value for GLX_TEXTURE_TARGET_EXT be? Should 1.124 + users be required to set this value if GLX_TEXTURE_FORMAT_EXT is not 1.125 + GLX_TEXTURE_FORMAT_NONE_EXT? 1.126 + 1.127 + The implementation is capable of choosing a reasonable default, we simply 1.128 + need to specify the correct way to do so. We can base the ordering on 1.129 + the properties of the pixmap and the texturing capabilities of the 1.130 + pixmap's FBConfig and the implementation. 1.131 + 1.132 + The order is: 1.133 + 1.134 + - If GL_ARB_texture_non_power_of_two is supported GL_TEXTURE_2D will 1.135 + be used for all pixmap sizes. 1.136 + 1.137 + - If only GL_ARB_texture_rectangle is supported GL_TEXTURE_2D will 1.138 + be used for all power of two pixmap sizes and GL_TEXTURE_RECTANGLE_ARB 1.139 + will be used for all non power of two pixmap sizes. 1.140 + 1.141 + 1.142 + 5. Should users be required to re-bind the drawable to a texture after 1.143 + the drawable has been rendered to? 1.144 + 1.145 + It is difficult to define what the contents of the texture would be if 1.146 + we don't require this. Also, requiring this would allow implementations 1.147 + to perform an implicit copy at this point if they could not support 1.148 + texturing directly out of renderable memory. 1.149 + 1.150 + The problem with defining the contents of the texture after rendering 1.151 + has occured to the associated drawable is that there is no way to 1.152 + synchronize the use of the buffer as a source and as a destination. 1.153 + Direct OpenGL rendering is not necessarily done in the same command 1.154 + stream as X rendering. At the time the pixmap is used as the source 1.155 + for a texturing operation, it could be in a state halfway through a 1.156 + copyarea operation in which half of it is say, white, and half is the 1.157 + result of the copyarea operation. How is this defined? Worse, some 1.158 + other OpenGL application could be halfway through a frame of rendering 1.159 + when the composite manager sources from it. The buffer might just 1.160 + contain the results of a "glClear" operation at that point. 1.161 + 1.162 + To gurantee tear-free rendering, a composite manager would run as follows: 1.163 + 1.164 + -receive request for compositing: 1.165 + XGrabServer() 1.166 + glXWaitX() or XSync() 1.167 + glXBindTexImageEXT() 1.168 + 1.169 + <Do rendering/compositing> 1.170 + 1.171 + glXReleaseTexImageEXT() 1.172 + XUngrabServer() 1.173 + 1.174 + Apps that don't synchronize like this would get what's available, 1.175 + and that may or may not be what they expect. 1.176 + 1.177 + 1.178 + 6. What is the result of calling GenerateMipmapEXT on a drawable that 1.179 + was not created with mipmap levels? 1.180 + 1.181 + The results are undefined. 1.182 + 1.183 + 1.184 + 7. Rendering done by the window system may be y-inverted compared 1.185 + to the standard OpenGL texture representation. More specifically: 1.186 + the X Window system uses a coordinate system where the origin is in 1.187 + the upper left; however, the GL uses a coordinate system where the 1.188 + origin is in the lower left. Should we define the contents of the 1.189 + texture as the y-inverted contents of the drawable? 1.190 + 1.191 + X implementations may represent their drawables differently internally, 1.192 + so y-inversion should be exposed as an FBConfig attribute. 1.193 + Applications will need to query this attribute and adjust their rendering 1.194 + appropriately. 1.195 + 1.196 + If a drawables is y-inverted and is bound to a texture, the contents of the 1.197 + texture will be y-inverted with respect to the standard GL memory layout. 1.198 + This means the contents of a pixmap of size (width, height) at pixmap 1.199 + coordinate (x, y) will be at location (x, height-y-1) in the texture. 1.200 + Applications will need to adjust their texture coordinates accordingly to 1.201 + avoid drawing the texture contents upside down. 1.202 + 1.203 + 1.204 + 8. Why wasn't this extension based on FBO instead of ARB_render_texture? 1.205 + Isn't the render_texture extension deprecated? 1.206 + 1.207 + At first glance, FBO may seem like the perfect framework to base a spec 1.208 + for texturing from pixmap surfaces on. It replaced the 1.209 + WGL_ARB_render_texture specification, which provided a mechanism to 1.210 + texture from pbuffer surfaces. However, this train of thought is another 1.211 + side effect of the unfortunate naming of the WGL_ARB_render_texture 1.212 + specification. FBO and the orginal render_texture specification were 1.213 + two different solutions to the problem of how to render to and texture 1.214 + from the same surface. WGL_ARB_render_texture provided a method to bind 1.215 + a texture to a drawable surface, as this extension does. FBO provides the 1.216 + opposite solution, allowing rendering to arbitrary surfaces including 1.217 + textures. In the case of FBO, the application doing the rendering knows 1.218 + that it needs to render to an alternate surface. In our usage case, the 1.219 + application doing the rendering is arbitrary, and has no knowledge that another 1.220 + application wants to use the surface it is rendering to as a texture. The 1.221 + only application able to name the surface is the one texturing from it. 1.222 + Therefore, it makes sense to provide a mechanism for binding a texture to 1.223 + an arbitrary surface in general, and a pixmap in this particular case. 1.224 + 1.225 + 1.226 + 9. Why not allow binding directly to an X pixmap without creating an 1.227 + intermediate GLX pixmap? 1.228 + 1.229 + Architecturally, GLX has moved away from operating directly on X 1.230 + drawables. This allows GLX specific attributes to be associated with the 1.231 + GLX drawables. In this case, it is important to associate an FBConfig 1.232 + with the drawable. The FBConfig contains attributes specifying the 1.233 + internal format the GL will use when utilizing the drawable's framebuffer 1.234 + as a texture. 1.235 + 1.236 + 1.237 +New Procedures and Functions 1.238 + 1.239 + void glXBindTexImageEXT (Display *display, 1.240 + GLXDrawable drawable, 1.241 + int buffer, 1.242 + const int *attrib_list) 1.243 + 1.244 + void glXReleaseTexImageEXT (Display *display, 1.245 + GLXDrawable drawable, 1.246 + int buffer) 1.247 + 1.248 + 1.249 +New Tokens 1.250 + 1.251 + Accepted by the <Attribute> parameter of glXGetFBConfigAttrib and 1.252 + the <attrib_list> parameter of glXChooseFBConfig: 1.253 + 1.254 + GLX_BIND_TO_TEXTURE_RGB_EXT 0x20D0 1.255 + GLX_BIND_TO_TEXTURE_RGBA_EXT 0x20D1 1.256 + GLX_BIND_TO_MIPMAP_TEXTURE_EXT 0x20D2 1.257 + GLX_BIND_TO_TEXTURE_TARGETS_EXT 0x20D3 1.258 + GLX_Y_INVERTED_EXT 0x20D4 1.259 + 1.260 + Accepted as an attribute in the <attrib_list> parameter of 1.261 + glXCreatePixmap, and by the <attribute> parameter of glXQueryDrawable: 1.262 + 1.263 + GLX_TEXTURE_FORMAT_EXT 0x20D5 1.264 + GLX_TEXTURE_TARGET_EXT 0x20D6 1.265 + GLX_MIPMAP_TEXTURE_EXT 0x20D7 1.266 + 1.267 + Accepted as a value in the <attrib_list> parameter of glXCreatePixmap 1.268 + and returned in the <value> parameter of glXQueryDrawable when 1.269 + <attribute> is GLX_TEXTURE_FORMAT_EXT: 1.270 + 1.271 + GLX_TEXTURE_FORMAT_NONE_EXT 0x20D8 1.272 + GLX_TEXTURE_FORMAT_RGB_EXT 0x20D9 1.273 + GLX_TEXTURE_FORMAT_RGBA_EXT 0x20DA 1.274 + 1.275 + Accepted as bits in the GLX_BIND_TO_TEXTURE_TARGETS_EXT variable: 1.276 + 1.277 + GLX_TEXTURE_1D_BIT_EXT 0x00000001 1.278 + GLX_TEXTURE_2D_BIT_EXT 0x00000002 1.279 + GLX_TEXTURE_RECTANGLE_BIT_EXT 0x00000004 1.280 + 1.281 + Accepted as a value in the <attrib_list> parameter of glXCreatePixmap 1.282 + and returned in the <value> parameter of glXQueryDrawable when 1.283 + <attribute> is GLX_TEXTURE_TARGET_EXT: 1.284 + 1.285 + GLX_TEXTURE_1D_EXT 0x20DB 1.286 + GLX_TEXTURE_2D_EXT 0x20DC 1.287 + GLX_TEXTURE_RECTANGLE_EXT 0x20DD 1.288 + 1.289 + Accepted by the <Buffer> parameter of glXBindTexImageEXT and 1.290 + glXReleaseTexImageEXT: 1.291 + 1.292 + GLX_FRONT_LEFT_EXT 0x20DE 1.293 + GLX_FRONT_RIGHT_EXT 0x20DF 1.294 + GLX_BACK_LEFT_EXT 0x20E0 1.295 + GLX_BACK_RIGHT_EXT 0x20E1 1.296 + GLX_FRONT_EXT GLX_FRONT_LEFT_EXT 1.297 + GLX_BACK_EXT GLX_BACK_LEFT_EXT 1.298 + GLX_AUX0_EXT 0x20E2 1.299 + GLX_AUX1_EXT 0x20E3 1.300 + GLX_AUX2_EXT 0x20E4 1.301 + GLX_AUX3_EXT 0x20E5 1.302 + GLX_AUX4_EXT 0x20E6 1.303 + GLX_AUX5_EXT 0x20E7 1.304 + GLX_AUX6_EXT 0x20E8 1.305 + GLX_AUX7_EXT 0x20E9 1.306 + GLX_AUX8_EXT 0x20EA 1.307 + GLX_AUX9_EXT 0x20EB 1.308 + 1.309 + 1.310 +GLX Protocol 1.311 + 1.312 + Two new GLX protocol commands are added. 1.313 + 1.314 + BindTexImageEXT 1.315 + 1 CARD8 opcode (X assigned) 1.316 + 1 16 GLX opcode (glXVendorPrivate) 1.317 + 2 6+n request length 1.318 + 4 1330 vendor specific opcode 1.319 + 4 CARD32 context tag 1.320 + 4 GLX_DRAWABLE drawable 1.321 + 4 INT32 buffer 1.322 + 4 CARD32 num_attributes 1.323 + 4*n LISTofATTRIBUTE_PAIR attribute, value pairs. 1.324 + 1.325 + ReleaseTexImageEXT 1.326 + 1 CARD8 opcode (X assigned) 1.327 + 1 16 GLX opcode (glXVendorPrivate) 1.328 + 2 5 request length 1.329 + 4 1331 vendor specific opcode 1.330 + 4 CARD32 context tag 1.331 + 4 GLX_DRAWABLE drawable 1.332 + 4 INT32 buffer 1.333 + 1.334 + 1.335 +Errors 1.336 + 1.337 +Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 1.338 + 1.339 + None. 1.340 + 1.341 +Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 1.342 + 1.343 + None. 1.344 + 1.345 +Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 1.346 +Operations and the Frame Buffer) 1.347 + 1.348 + None. 1.349 + 1.350 +Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 1.351 + 1.352 + None. 1.353 + 1.354 +Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State 1.355 +Requests) 1.356 + 1.357 + None. 1.358 + 1.359 +Additions to the GLX Specification 1.360 + 1.361 + Add to table 3.1, GLXFBConfig Attributes: 1.362 + 1.363 + Attribute Type Notes 1.364 + ------------------------------- ------- ------------------------------------------------------------------- 1.365 + GLX_BIND_TO_TEXTURE_RGB_EXT boolean True if color buffers can be bound to RGB texture 1.366 + GLX_BIND_TO_TEXTURE_RGBA_EXT boolean True if color buffers can be bound to RGBA texture 1.367 + GLX_BIND_TO_MIPMAP_TEXTURE_EXT boolean True if color buffers can be bound to textures with multiple levels 1.368 + GLX_BIND_TO_TEXTURE_TARGETS_EXT bitmask Bitmask of texture targets color buffers can be bound to 1.369 + GLX_Y_INVERTED_EXT boolean True if the drawable's framebuffer is y-inverted. This can be used to determine if y-inverted texture coordinates need to be used when texturing from this drawable when it is bound to a texture target. 1.370 + 1.371 + Additions to table 3.4, Default Match Criteria for GLXFBConfig attributes: 1.372 + 1.373 + Attribute Default Selection Criteria Priority 1.374 + ------------------------------- -------------------- ------------------ --------- 1.375 + GLX_BIND_TO_TEXTURE_RGB_EXT GLX_DONT_CARE Exact 1.376 + GLX_BIND_TO_TEXTURE_RGBA_EXT GLX_DONT_CARE Exact 1.377 + GLX_BIND_TO_MIPMAP_TEXTURE_EXT GLX_DONT_CARE Exact 1.378 + GLX_BIND_TO_TEXTURE_TARGETS_EXT - Mask 1.379 + GLX_Y_INVERTED_EXT GLX_DONT_CARE Exact 1.380 + 1.381 + Modifications to 3.3.3, "Configuration Management" 1.382 + 1.383 + Add after paragraph 17 in the description of FBConfigs: 1.384 + 1.385 + GLX_Y_INVERTED_EXT is a boolean describing the memory layout used for 1.386 + drawables created with the GLXFBConfig. The attribute is True if the 1.387 + drawable's framebuffer will be y-inverted. This can be used to determine 1.388 + if y-inverted texture coordinates need to be used when texturing from this 1.389 + drawable when it is bound to a texture target. 1.390 + 1.391 + Modifications to 3.3.5, "Offscreen Rendering" 1.392 + 1.393 + Modify paragraph 3 of the description of glXCreatePixmap: 1.394 + 1.395 + <attrib_list> specifies a list of attributes for the pixmap. The list has 1.396 + the same structure as described for glXChooseFBConfig. Currently the 1.397 + following attributes can be specified in attrib_list: 1.398 + GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT, GLX_MIPMAP_TEXTURE_EXT, 1.399 + attrib_list may be NULL or empty (first attribute of None), in which case 1.400 + all attributes assume their default values as described below. 1.401 + 1.402 + GLX_TEXTURE_FORMAT_EXT describes the texture format this pixmap can be 1.403 + bound to. Valid values are GLX_TEXTURE_FORMAT_RGB_EXT, 1.404 + GLX_TEXTURE_FORMAT_RGBA_EXT, and GLX_TEXTURE_FORMAT_NONE_EXT. 1.405 + 1.406 + GLX_TEXTURE_TARGET_EXT can be set to GLX_TEXTURE_1D_EXT, 1.407 + GLX_TEXTURE_2D_EXT, or GLX_TEXTURE_RECTANGLE_EXT; it indicates the type 1.408 + of texture that will be created when GLX_TEXTURE_FORMAT_EXT is not 1.409 + GLX_TEXTURE_FORMAT_NONE_EXT. The default value of GLX_TEXTURE_TARGET_EXT 1.410 + depends on the capabilities in <config> and the dimensions of the pixmap. 1.411 + If <config> has GLX_TEXTURE_2D_BIT set and one or more of the following is 1.412 + true: 1.413 + 1.414 + * GLX_TEXTURE_RECTANGLE_BIT_EXT is not set in <config> 1.415 + 1.416 + * GL_ARB_texture_non_power_of_two is supported 1.417 + 1.418 + * the pixmap's width and height are powers of 2 1.419 + 1.420 + the default value for GLX_TEXTURE_TARGET_EXT is GLX_TEXTURE_2D_EXT. 1.421 + 1.422 + Otherwise, the first supported target is chosen in this order: 1.423 + GLX_TEXTURE_RECTANGLE_EXT, GLX_TEXTURE_1D_EXT. 1.424 + 1.425 + GLX_MIPMAP_TEXTURE_EXT indicates that storage for mipmaps should be 1.426 + allocated. Space for mipmaps will be set aside if GLX_TEXTURE_FORMAT_EXT 1.427 + is not GLX_TEXTURE_FORMAT_NONE_EXT and GLX_MIPMAP_TEXTURE_EXT is TRUE. 1.428 + The default value is FALSE. 1.429 + 1.430 + Modify paragraph 5 of the description of glXCreatePixmap: 1.431 + 1.432 + ...If <pixmap> is not a valid Pixmap XID, then a BadPixmap error is 1.433 + generated. A BadConfig error is generated if any of the following 1.434 + conditions are true: 1.435 + 1.436 + * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGB_EXT and 1.437 + <config> does not have GLX_BIND_TO_TEXTURE_RGB set to TRUE. 1.438 + 1.439 + * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGBA_EXT and 1.440 + <config> does not have GLX_BIND_TO_TEXTURE_RGBA set to TRUE. 1.441 + 1.442 + * GLX_MIPMAP_TEXTURE_EXT is set to TRUE and <config> does not 1.443 + have GLX_BIND_TO_MIPMAP_EXT set to TRUE. 1.444 + 1.445 + * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_1D_EXT 1.446 + and <config> does not have GLX_TEXTURE_1D_BIT_EXT set. 1.447 + 1.448 + * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_2D_EXT 1.449 + and <config> does not have GLX_TEXTURE_2D_BIT_EXT set. 1.450 + 1.451 + * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_RECTANGLE_EXT 1.452 + and <config> does not have GLX_TEXTURE_RECTANGLE_BIT_EXT set. 1.453 + 1.454 + A BadValue error is generated if GLX_TEXTURE_FORMAT_EXT is not 1.455 + GLX_TEXTURE_FORMAT_NONE_EXT and the width or height of <pixmap> are 1.456 + incompatible with the specified value of GLX_TEXTURE_TARGET_EXT on this 1.457 + implementation. (e.g., the pixmap size is not a power of 2 and 1.458 + GL_ARB_texture_rectangle is not supported). 1.459 + 1.460 + Modify paragraph 1 of the description of glXDestroyPixmap: 1.461 + 1.462 + ...The storage for the GLX pixmap will be freed when it is not current 1.463 + to any client and all color buffers that are bound to a texture object 1.464 + have been released. 1.465 + 1.466 + 1.467 + Modifications to seciton 3.3.6, "Querying Attributes" 1.468 + 1.469 + Modify paragraph 1 of the description of glXQueryDrawable: 1.470 + 1.471 + ...<attribute> must be set to one of GLX_WIDTH, GLX_HEIGHT, 1.472 + GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID, 1.473 + GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT or GLX_MIPMAP_TEXTURE_EXT 1.474 + or a BadValue error is generated. 1.475 + 1.476 + Modify paragraph 3 of the description of glXQueryDrawable: 1.477 + 1.478 + ...If <draw> is a GLXWindow or GLXPixmap and <attribute> is set to 1.479 + GLX_PRESERVED_CONTENTS or GLX_LARGEST_PBUFFER, or if <draw> is a 1.480 + GLXWindow or GLXPbuffer and <attribute> is set to GLX_TEXTURE_FORMAT_EXT, 1.481 + GLX_TEXTURE_TARGET_EXT, or GLX_MIPMAP_TEXTURE_EXT, the contents of <value> 1.482 + are undefined. 1.483 + 1.484 + Add a new section 3.3.6.1, "Texturing From Drawables" 1.485 + 1.486 + The command 1.487 + 1.488 + void glXBindTexImageEXT (Display *dpy, 1.489 + GLXDrawable draw, 1.490 + int buffer, 1.491 + int *attrib_list); 1.492 + 1.493 + defines a one- or two-dimensional texture image. The texture image is taken 1.494 + from <buffer> and need not be copied. The texture target, the texture 1.495 + format, and the size of the texture components are derived from attributes 1.496 + of <draw>. 1.497 + 1.498 + The drawable attribute GLX_TEXTURE_FORMAT_EXT determines the base internal 1.499 + format of the texture. The component sizes are also determined by drawable 1.500 + attributes as shown in table 3.4a. 1.501 + 1.502 + Add new table 3.4a: Size of texture components: 1.503 + 1.504 + Texture component Size 1.505 + ----------------- -------------- 1.506 + R GLX_RED_SIZE 1.507 + G GLX_GREEN_SIZE 1.508 + B GLX_BLUE_SIZE 1.509 + A GLX_ALPHA_SIZE 1.510 + 1.511 + The texture target is derived from the GLX_TEXTURE_TARGET_EXT attribute of 1.512 + <draw>. If the texture target for the drawable is GLX_TEXTURE_2D_EXT or 1.513 + GLX_TEXTURE_RECTANGLE_EXT, then buffer defines a 2D texture for the current 1.514 + 2D or rectangle texture object respectively; if the texture target is 1.515 + GLX_TEXTURE_1D_EXT, then buffer defines a 1D texture for the current 1D 1.516 + texture object. 1.517 + 1.518 + If <buffer> is not one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT, 1.519 + GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, or GLX_AUX0_EXT through 1.520 + GLX_AUXn_EXT, where n is one less than the number of AUX buffers supported 1.521 + by the FBConfig used to create <draw>, or if the requested buffer is 1.522 + missing, a BadValue error is generated. 1.523 + 1.524 + <attrib_list> specifies a list of attributes for the texture. The list has 1.525 + the same structure as described for glXChooseFBConfig. If <attrib_list> is 1.526 + NULL or empty (first attribute of None), then all attributes assume their 1.527 + default values. <attrib_list> must be NULL or empty. 1.528 + 1.529 + If <dpy> and <draw> are the display and drawable for the calling thread's 1.530 + current context, glXBindTexImageEXT performs an implicit glFlush. 1.531 + 1.532 + The contents of the texture after the drawable has been bound are defined 1.533 + as the result of all rendering that has completed before the call to 1.534 + glXBindTexImageEXT. In other words, the results of any operation which 1.535 + has caused damage on the drawable prior to the glXBindTexImageEXT call 1.536 + will be represented in the texture. 1.537 + 1.538 + Rendering to the drawable while it is bound to a texture will leave the 1.539 + contents of the texture in an undefined state. However, no 1.540 + synchronization between rendering and texturing is done by GLX. It is 1.541 + the application's responsibility to implement any synchronization 1.542 + required. 1.543 + 1.544 + If a texture object is deleted before glXReleaseTexImageEXT is called, 1.545 + the color buffer is released. 1.546 + 1.547 + It is not an error to call TexImage2D, TexImage1D, CopyTexImage1D, or 1.548 + CopyTexImage2D to replace an image of a texture object that has a color 1.549 + buffer bound to it. However, these calls will cause the color buffer to be 1.550 + released and new memory to be allocated for the texture. Note that the 1.551 + color buffer is released even if the image that is being defined is a mipmap 1.552 + level that was not defined by the color buffer. GenerateMipmapEXT is an 1.553 + exception. GenerateMipmapEXT can be used to define mipmap levels for 1.554 + drawables that have been created with GLX_MIPMAP_TEXTURE_EXT set. Calling 1.555 + GenerateMipmapEXT on a drawable that was created without 1.556 + GLX_MIPMAP_TEXTURE_EXT is undefined. 1.557 + 1.558 + The results of calling glXBindTexImageEXT when GENERATE_MIPMAP_SGIS is TRUE 1.559 + are undefined. 1.560 + 1.561 + If glXBindTexImageEXT is called and the drawable attribute 1.562 + GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch 1.563 + error is generated. 1.564 + 1.565 + Currently, only pixmaps can be bound to textures. If <draw> is not a 1.566 + valid GLXPixmap, then a GLXBadPixmap error is generated. 1.567 + 1.568 + glXBindTexImageEXT is ignored if there is no current GLX rendering context. 1.569 + 1.570 + To release a color buffer that is being used as a texture, call 1.571 + 1.572 + void glXReleaseTexImageEXT (Dislpay *dpy, GLXDrawable draw, int buffer); 1.573 + 1.574 + <buffer> must be one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT, 1.575 + GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, and GLX_AUX0_EXT through 1.576 + GLX_AUXn_EXT, where n is one less than the number of AUX buffers 1.577 + supported by the FBConfig used to create <draw> or a BadValue error 1.578 + is generated. 1.579 + 1.580 + The contents of the color buffer are unaffected by glXReleaseTexImageEXT. 1.581 + 1.582 + If the specified color buffer is no longer bound to a texture (e.g., 1.583 + because the texture object was deleted), then glXReleaseTexImageEXT has no effect; 1.584 + no error is generated. 1.585 + 1.586 + When a color buffer is released (e.g., by calling glXReleaseTexImageEXT or 1.587 + implicitly by calling a routine such as TexImage2D), all textures that were 1.588 + defined by the color buffer become NULL. 1.589 + 1.590 + If glXReleaseTexImageEXT is called and the drawable attribute 1.591 + GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch 1.592 + error is generated. 1.593 + 1.594 + Currently, only pixmaps can be bound to textures. If <draw> is not a 1.595 + valid GLXPixmap, then a GLXBadPixmap error is generated. 1.596 + 1.597 + 1.598 +Usage Examples 1.599 + 1.600 + Example 1: Bind redirected window to texture: 1.601 + 1.602 + XGetWindowAttributes (display, window, &attrib); 1.603 + 1.604 + visualid = XVisualIDFromVisual (attrib.visual); 1.605 + 1.606 + fbconfigs = glXGetFBConfigs (display, screen, &nfbconfigs); 1.607 + for (i = 0; i < nfbconfigs; i++) 1.608 + { 1.609 + visinfo = glXGetVisualFromFBConfig (display, fbconfigs[i]); 1.610 + if (!visinfo || visinfo->visualid != visualid) 1.611 + continue; 1.612 + 1.613 + glXGetFBConfigAttrib (display, fbconfigs[i], GLX_DRAWABLE_TYPE, &value); 1.614 + if (!(value & GLX_PIXMAP_BIT)) 1.615 + continue; 1.616 + 1.617 + glXGetFBConfigAttrib (display, fbconfigs[i], 1.618 + GLX_BIND_TO_TEXTURE_TARGETS_EXT, 1.619 + &value); 1.620 + if (!(value & GLX_TEXTURE_2D_BIT_EXT)) 1.621 + continue; 1.622 + 1.623 + glXGetFBConfigAttrib (display, fbconfigs[i], 1.624 + GLX_BIND_TO_TEXTURE_RGBA_EXT, 1.625 + &value); 1.626 + if (value == FALSE) 1.627 + { 1.628 + glXGetFBConfigAttrib (display, fbconfigs[i], 1.629 + GLX_BIND_TO_TEXTURE_RGB_EXT, 1.630 + &value); 1.631 + if (value == FALSE) 1.632 + continue; 1.633 + } 1.634 + 1.635 + glXGetFBConfigAttrib (display, fbconfigs[i], 1.636 + GLX_Y_INVERTED_EXT, 1.637 + &value); 1.638 + if (value == TRUE) 1.639 + { 1.640 + top = 0.0f; 1.641 + bottom = 1.0f; 1.642 + } 1.643 + else 1.644 + { 1.645 + top = 1.0f; 1.646 + bottom = 0.0f; 1.647 + } 1.648 + 1.649 + break; 1.650 + } 1.651 + 1.652 + if (i == nfbconfigs) 1.653 + /* error 1 */ 1.654 + 1.655 + pixmap = XCompositeNameWindowPixmap (display, window); 1.656 + pixmapAttribs = { GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT, 1.657 + GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_FORMAT_RGBA_EXT, 1.658 + None }; 1.659 + glxpixmap = glXCreatePixmap (display, fbconfigs[i], pixmap, pixmapAttribs); 1.660 + 1.661 + glGenTextures (1, &texture); 1.662 + glBindTexture (GL_TEXTURE_2D, texture); 1.663 + 1.664 + glXBindTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT, NULL); 1.665 + 1.666 + glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 1.667 + glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR); 1.668 + 1.669 + /* draw using pixmap as texture */ 1.670 + glBegin (GL_QUADS); 1.671 + 1.672 + glTexCoord2d (0.0f, bottom); 1.673 + glVertex2d (0.0f, 0.0f); 1.674 + 1.675 + glTexCoord2d (0.0f, top); 1.676 + glVertex2d (0.0f, 1.0f); 1.677 + 1.678 + glTexCoord2d (1.0f, top); 1.679 + glVertex2d (1.0f, 1.0f); 1.680 + 1.681 + glTexCoord2d (1.0f, bottom); 1.682 + glVertex2d (1.0f, 0.0f); 1.683 + 1.684 + glEnd (); 1.685 + 1.686 + glXReleaseTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT); 1.687 + 1.688 + 1.689 +Version History 1.690 + 1.691 + 1. 26 Nov 2005 - DavidR 1.692 + Initial version 1.693 + 2. 01 Dec 2005 - JamesJ 1.694 + -Adapted spec language from draft version of GLX_ARB_render_texture. 1.695 + -Added glXDrawableAttribute to set attributes. 1.696 + -Modified glXBindTexImageEXT to take an attrib_list parameter. 1.697 + -Added support for cubemap and 1D texture targets. 1.698 + -Added attribute to set the texture target when creating the 1.699 + drawable. 1.700 + -Updated the issues section. 1.701 + -Added mipmap support. Support is not required. 1.702 + -Specified results of texturing from a drawable when it has been 1.703 + rendered to while bound to a texture as undefined until 1.704 + glXReleaseTexImageEXT has been called. Allows implementations 1.705 + that need to perform an implicit copy after rendering occurs 1.706 + to be compatible with this specification. 1.707 + 3. 04 Dec 2005 - DavidR 1.708 + -Changed name to GLX_EXT_texture_from_pixmap. 1.709 + -Changed spec regarding what happens when a pixmap that is bound 1.710 + to a texture is rendered to. Having textures be undefined once 1.711 + they are rendered to makes it useless for a compositing manager, 1.712 + which is a major use case for this extension. 1.713 + -Added support for not specifying texture target when creating a 1.714 + pixmap. Allows implementations to select whatever target it 1.715 + finds most suitable. 1.716 + 4. 05 Dec 2005 - JamesJ 1.717 + -Changed the default value of GLX_TEXTURE_TARGET_EXT from 1.718 + GLX_NO_TEXTURE_EXT to something usable. Eliminated 1.719 + GLX_NO_TEXTURE_EXT. 1.720 + -Eliminated GLX_TEXTURE_NONE_EXT. 1.721 + -Removed language referring to sharing of color buffers when 1.722 + pixmaps are bound to textures. 1.723 + -Updated issues. 1.724 + 1.725 + 5. 13 Dec 2005 - JamesJ 1.726 + -Removed cube map support and rendering to multiple mipmap 1.727 + levels support. 1.728 + 1.729 + 6. 20 Jan 2006 - JamesJ 1.730 + -Specified textures are y-inverted. 1.731 + 1.732 + 7. 23 Jan 2006 - AaronP 1.733 + -Fix typos, make some things clearer. Replace ocurrences of "released 1.734 + back to the drawable" with "released". 1.735 + 1.736 + 8. 01 Feb 2006 - AndyR 1.737 + -Fix minor typos. 1.738 + 1.739 + 9. 03 Feb 2006 - JamesJ 1.740 + -Added some new issues and their resolutions. 1.741 + -Finalized some issues that had been in discussion. 1.742 + -Made drawable y-inversion a queryable attribute of the drawable. 1.743 + -Moved detailed explanation of y-inverted addressing to the issues 1.744 + section 1.745 + -Updated example to demonstrate proper use of the y-inverted 1.746 + attribute. 1.747 + 1.748 + 10. 06 Feb 2006 - DavidR 1.749 + -Made GLX_Y_INVERTED_EXT an FBConfig attribute instead of a drawable 1.750 + attribute. 1.751 + -Removed GLX_TEXTURE_CUBE_MAP_EXT. 1.752 + -Fix minor typo. 1.753 + 1.754 + 11. 07 Feb 2006 - JamesJ 1.755 + -Added description of GLX_Y_INVERTED_EXT GLXFBConfig attribute, based 1.756 + on description of the drawable attribute of the same name from 1.757 + and earlier version of the specification. 1.758 + -Removed language requiring applications to re-bind a pixmap to a 1.759 + texture to gurantee contents of the texture are updated after a 1.760 + pixmap has been rendered to. 1.761 + -Added Aaron Plattner and Andy Ritger to contributors section. 1.762 + 1.763 + 12. 14 Feb 2006 - JamesJ 1.764 + -Disallowed rendering to a drawable while it is bound as a texture 1.765 + and defined the exact contents of a texture after a drawable has 1.766 + been bound to it. 1.767 + 1.768 + 13. 09 Mar 2006 - JamesJ 1.769 + -Add a context tag member to the vendor private requests. This field 1.770 + is part of the vendor private header, and is needed to specify which 1.771 + context the BindTexImageEXT and ReleaseTexImageEXT requests correspond 1.772 + to. 1.773 + -Changed texture target bitfield values to not skip numbers removed in 1.774 + earlier updates. 1.775 + 1.776 + 14. 13 Mar 2006 - JamesJ 1.777 + -Only require GLX_SGIX_fbconfig + GLX 1.2. 1.778 + -Clarify language regarding the result of rendering to drawables bound 1.779 + to textures. 1.780 + -Added GLX_FRONT_EXT and GLX_BACK_EXT tokens. 1.781 + 1.782 + 15. 18 Apr 2006 - JamesJ 1.783 + -Allocated enum values and opcodes. 1.784 + -Require GLX 1.3. GLX_SGIX_fbconfig doesn't allow creating pixmaps 1.785 + with attributes. 1.786 + -Added more arguments for not supporting rendering to multiple levels 1.787 + of a texture with this extension. 1.788 + -Fixed the inconsistencies in the return type of glXBindTexImageEXT 1.789 + and glXReleaseTexImageEXT. It is now listed as void throughout. 1.790 + 1.791 + 16. 12 Sep 2006 - JamesJ 1.792 + -Fix ordering of GLX protocol 1.793 + 1.794 + 17. 10 Feb 2009 - Jon Leech 1.795 + -Fix typo reported by Jonathan Knispel.