1Name 2 3 EXT_texture_from_pixmap 4 5Name Strings 6 7 GLX_EXT_texture_from_pixmap 8 9Contributors 10 11 James Jones, NVIDIA 12 Aaron Plattner, NVIDIA 13 Andy Ritger, NVIDIA 14 15Contact 16 17 David Reveman, Novell, Inc. (davidr 'at' novell.com) 18 19Status 20 21 Complete 22 23Version 24 25 17 (10 Feb 2009) 26 27Number 28 29 344 30 31Dependencies 32 33 OpenGL 1.1 is required. 34 GLX 1.3 is required. 35 GL_EXT_framebuffer_object affects the definition of this extension. 36 GL_ARB_texture_rectangle affects the definition of this extension. 37 GL_ARB_texture_non_power_of_two affects the definition of this extension. 38 GL_SGIS_generate_mipmap affects the definition of this extension. 39 40Overview 41 42 This extension allows a color buffer to be used for both rendering and 43 texturing. 44 45 Only color buffers of pixmaps can be used for texturing by this extension 46 but other types of drawables can be supported by future extensions layered 47 on top of this extension. 48 49 The functionality of this extension is similar to WGL_ARB_render_texture. 50 However, the purpose of this extension is not to provide 51 "render to texture" like functionality but rather the ability to bind 52 an existing X drawable to a texture. Though, there is nothing that 53 prohibits it from being used for "render to texture". 54 55 - Windows are problematic as they can change size and therefore are not 56 supported by this extension. 57 58 - Only a color buffer of a GLX pixmap created using an FBConfig with 59 attribute GLX_BIND_TO_TEXTURE_RGB_EXT or GLX_BIND_TO_TEXTURE_RGBA_EXT 60 set to TRUE can be bound as a texture. 61 62 - The texture internal format is determined when the color buffer 63 is associated with the texture, guaranteeing that the color 64 buffer format is equivalent to the texture internal format. 65 66 - A client can create a complete set of mipmap images if 67 EXT_framebuffer_object is supported. 68 69 70IP Status 71 72 There are no known IP issues. 73 74Issues 75 76 1. What should this extension be called? 77 78 Even though it is very similar to WGL_ARB_render_texture that name is 79 not appropriate as the intention of this extension is not 80 "render to texture" like functionality. 81 82 EXT_texture_from_pixmap seams most appropriate. Layering of future 83 extensions on top of this extension for using other type of drawables 84 as textures follows the same conventions as vertex/pixel buffer objects 85 and vertex/fragment programs. 86 87 88 2. Should we allow applications to render to different mipmap levels and 89 cube map faces? 90 91 In order to discourage the use of this extension as a render to texture 92 mechanism, cube maps and rendering directly to mip-map levels > 0 will 93 not be supported. A new FBConfig attribute is introduced that specifies 94 whether or not drawables created with that config will support multiple 95 mipmap levels when bound to a texture. The other mipmap levels can be 96 filled in by the EXT_framebuffer_object GenerateMipmapEXT function. 97 98 Specifying which level of a pixmap was being rendered to on a per-drawable 99 basis, as was done in the WGL_ARB_render_texture extension, also 100 introduces concurrency issues. The state of the drawable when it was 101 being rendered two by two separate threads of execution and both were 102 changing the mipmap level was difficult to define. 103 104 It is also desireable to keep this extension as simple as possible. 105 Adding functionality that complicates the implementation and that is not 106 directly relevenat to the goal of exposing a mechanism for texturing from 107 arbitrary X pixmaps is not productive. If the ability to render directly 108 to all levels of a texture is needed, EXT_framebuffer_object is the 109 extension that should be used. 110 111 112 3. Should 1D textures be supported? 113 114 X servers layered on top of an OpenGL implementation might not be able 115 to support this. A new FBConfig attribute is introduced specifying 116 which texture targets a drawable created with the given FBConfig can 117 be bound to. 118 119 120 4. What should the default value for GLX_TEXTURE_TARGET_EXT be? Should 121 users be required to set this value if GLX_TEXTURE_FORMAT_EXT is not 122 GLX_TEXTURE_FORMAT_NONE_EXT? 123 124 The implementation is capable of choosing a reasonable default, we simply 125 need to specify the correct way to do so. We can base the ordering on 126 the properties of the pixmap and the texturing capabilities of the 127 pixmap's FBConfig and the implementation. 128 129 The order is: 130 131 - If GL_ARB_texture_non_power_of_two is supported GL_TEXTURE_2D will 132 be used for all pixmap sizes. 133 134 - If only GL_ARB_texture_rectangle is supported GL_TEXTURE_2D will 135 be used for all power of two pixmap sizes and GL_TEXTURE_RECTANGLE_ARB 136 will be used for all non power of two pixmap sizes. 137 138 139 5. Should users be required to re-bind the drawable to a texture after 140 the drawable has been rendered to? 141 142 It is difficult to define what the contents of the texture would be if 143 we don't require this. Also, requiring this would allow implementations 144 to perform an implicit copy at this point if they could not support 145 texturing directly out of renderable memory. 146 147 The problem with defining the contents of the texture after rendering 148 has occured to the associated drawable is that there is no way to 149 synchronize the use of the buffer as a source and as a destination. 150 Direct OpenGL rendering is not necessarily done in the same command 151 stream as X rendering. At the time the pixmap is used as the source 152 for a texturing operation, it could be in a state halfway through a 153 copyarea operation in which half of it is say, white, and half is the 154 result of the copyarea operation. How is this defined? Worse, some 155 other OpenGL application could be halfway through a frame of rendering 156 when the composite manager sources from it. The buffer might just 157 contain the results of a "glClear" operation at that point. 158 159 To gurantee tear-free rendering, a composite manager would run as follows: 160 161 -receive request for compositing: 162 XGrabServer() 163 glXWaitX() or XSync() 164 glXBindTexImageEXT() 165 166 <Do rendering/compositing> 167 168 glXReleaseTexImageEXT() 169 XUngrabServer() 170 171 Apps that don't synchronize like this would get what's available, 172 and that may or may not be what they expect. 173 174 175 6. What is the result of calling GenerateMipmapEXT on a drawable that 176 was not created with mipmap levels? 177 178 The results are undefined. 179 180 181 7. Rendering done by the window system may be y-inverted compared 182 to the standard OpenGL texture representation. More specifically: 183 the X Window system uses a coordinate system where the origin is in 184 the upper left; however, the GL uses a coordinate system where the 185 origin is in the lower left. Should we define the contents of the 186 texture as the y-inverted contents of the drawable? 187 188 X implementations may represent their drawables differently internally, 189 so y-inversion should be exposed as an FBConfig attribute. 190 Applications will need to query this attribute and adjust their rendering 191 appropriately. 192 193 If a drawables is y-inverted and is bound to a texture, the contents of the 194 texture will be y-inverted with respect to the standard GL memory layout. 195 This means the contents of a pixmap of size (width, height) at pixmap 196 coordinate (x, y) will be at location (x, height-y-1) in the texture. 197 Applications will need to adjust their texture coordinates accordingly to 198 avoid drawing the texture contents upside down. 199 200 201 8. Why wasn't this extension based on FBO instead of ARB_render_texture? 202 Isn't the render_texture extension deprecated? 203 204 At first glance, FBO may seem like the perfect framework to base a spec 205 for texturing from pixmap surfaces on. It replaced the 206 WGL_ARB_render_texture specification, which provided a mechanism to 207 texture from pbuffer surfaces. However, this train of thought is another 208 side effect of the unfortunate naming of the WGL_ARB_render_texture 209 specification. FBO and the orginal render_texture specification were 210 two different solutions to the problem of how to render to and texture 211 from the same surface. WGL_ARB_render_texture provided a method to bind 212 a texture to a drawable surface, as this extension does. FBO provides the 213 opposite solution, allowing rendering to arbitrary surfaces including 214 textures. In the case of FBO, the application doing the rendering knows 215 that it needs to render to an alternate surface. In our usage case, the 216 application doing the rendering is arbitrary, and has no knowledge that another 217 application wants to use the surface it is rendering to as a texture. The 218 only application able to name the surface is the one texturing from it. 219 Therefore, it makes sense to provide a mechanism for binding a texture to 220 an arbitrary surface in general, and a pixmap in this particular case. 221 222 223 9. Why not allow binding directly to an X pixmap without creating an 224 intermediate GLX pixmap? 225 226 Architecturally, GLX has moved away from operating directly on X 227 drawables. This allows GLX specific attributes to be associated with the 228 GLX drawables. In this case, it is important to associate an FBConfig 229 with the drawable. The FBConfig contains attributes specifying the 230 internal format the GL will use when utilizing the drawable's framebuffer 231 as a texture. 232 233 234New Procedures and Functions 235 236 void glXBindTexImageEXT (Display *display, 237 GLXDrawable drawable, 238 int buffer, 239 const int *attrib_list) 240 241 void glXReleaseTexImageEXT (Display *display, 242 GLXDrawable drawable, 243 int buffer) 244 245 246New Tokens 247 248 Accepted by the <Attribute> parameter of glXGetFBConfigAttrib and 249 the <attrib_list> parameter of glXChooseFBConfig: 250 251 GLX_BIND_TO_TEXTURE_RGB_EXT 0x20D0 252 GLX_BIND_TO_TEXTURE_RGBA_EXT 0x20D1 253 GLX_BIND_TO_MIPMAP_TEXTURE_EXT 0x20D2 254 GLX_BIND_TO_TEXTURE_TARGETS_EXT 0x20D3 255 GLX_Y_INVERTED_EXT 0x20D4 256 257 Accepted as an attribute in the <attrib_list> parameter of 258 glXCreatePixmap, and by the <attribute> parameter of glXQueryDrawable: 259 260 GLX_TEXTURE_FORMAT_EXT 0x20D5 261 GLX_TEXTURE_TARGET_EXT 0x20D6 262 GLX_MIPMAP_TEXTURE_EXT 0x20D7 263 264 Accepted as a value in the <attrib_list> parameter of glXCreatePixmap 265 and returned in the <value> parameter of glXQueryDrawable when 266 <attribute> is GLX_TEXTURE_FORMAT_EXT: 267 268 GLX_TEXTURE_FORMAT_NONE_EXT 0x20D8 269 GLX_TEXTURE_FORMAT_RGB_EXT 0x20D9 270 GLX_TEXTURE_FORMAT_RGBA_EXT 0x20DA 271 272 Accepted as bits in the GLX_BIND_TO_TEXTURE_TARGETS_EXT variable: 273 274 GLX_TEXTURE_1D_BIT_EXT 0x00000001 275 GLX_TEXTURE_2D_BIT_EXT 0x00000002 276 GLX_TEXTURE_RECTANGLE_BIT_EXT 0x00000004 277 278 Accepted as a value in the <attrib_list> parameter of glXCreatePixmap 279 and returned in the <value> parameter of glXQueryDrawable when 280 <attribute> is GLX_TEXTURE_TARGET_EXT: 281 282 GLX_TEXTURE_1D_EXT 0x20DB 283 GLX_TEXTURE_2D_EXT 0x20DC 284 GLX_TEXTURE_RECTANGLE_EXT 0x20DD 285 286 Accepted by the <Buffer> parameter of glXBindTexImageEXT and 287 glXReleaseTexImageEXT: 288 289 GLX_FRONT_LEFT_EXT 0x20DE 290 GLX_FRONT_RIGHT_EXT 0x20DF 291 GLX_BACK_LEFT_EXT 0x20E0 292 GLX_BACK_RIGHT_EXT 0x20E1 293 GLX_FRONT_EXT GLX_FRONT_LEFT_EXT 294 GLX_BACK_EXT GLX_BACK_LEFT_EXT 295 GLX_AUX0_EXT 0x20E2 296 GLX_AUX1_EXT 0x20E3 297 GLX_AUX2_EXT 0x20E4 298 GLX_AUX3_EXT 0x20E5 299 GLX_AUX4_EXT 0x20E6 300 GLX_AUX5_EXT 0x20E7 301 GLX_AUX6_EXT 0x20E8 302 GLX_AUX7_EXT 0x20E9 303 GLX_AUX8_EXT 0x20EA 304 GLX_AUX9_EXT 0x20EB 305 306 307GLX Protocol 308 309 Two new GLX protocol commands are added. 310 311 BindTexImageEXT 312 1 CARD8 opcode (X assigned) 313 1 16 GLX opcode (glXVendorPrivate) 314 2 6+n request length 315 4 1330 vendor specific opcode 316 4 CARD32 context tag 317 4 GLX_DRAWABLE drawable 318 4 INT32 buffer 319 4 CARD32 num_attributes 320 4*n LISTofATTRIBUTE_PAIR attribute, value pairs. 321 322 ReleaseTexImageEXT 323 1 CARD8 opcode (X assigned) 324 1 16 GLX opcode (glXVendorPrivate) 325 2 5 request length 326 4 1331 vendor specific opcode 327 4 CARD32 context tag 328 4 GLX_DRAWABLE drawable 329 4 INT32 buffer 330 331 332Errors 333 334Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 335 336 None. 337 338Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 339 340 None. 341 342Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 343Operations and the Frame Buffer) 344 345 None. 346 347Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 348 349 None. 350 351Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State 352Requests) 353 354 None. 355 356Additions to the GLX Specification 357 358 Add to table 3.1, GLXFBConfig Attributes: 359 360 Attribute Type Notes 361 ------------------------------- ------- ------------------------------------------------------------------- 362 GLX_BIND_TO_TEXTURE_RGB_EXT boolean True if color buffers can be bound to RGB texture 363 GLX_BIND_TO_TEXTURE_RGBA_EXT boolean True if color buffers can be bound to RGBA texture 364 GLX_BIND_TO_MIPMAP_TEXTURE_EXT boolean True if color buffers can be bound to textures with multiple levels 365 GLX_BIND_TO_TEXTURE_TARGETS_EXT bitmask Bitmask of texture targets color buffers can be bound to 366 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. 367 368 Additions to table 3.4, Default Match Criteria for GLXFBConfig attributes: 369 370 Attribute Default Selection Criteria Priority 371 ------------------------------- -------------------- ------------------ --------- 372 GLX_BIND_TO_TEXTURE_RGB_EXT GLX_DONT_CARE Exact 373 GLX_BIND_TO_TEXTURE_RGBA_EXT GLX_DONT_CARE Exact 374 GLX_BIND_TO_MIPMAP_TEXTURE_EXT GLX_DONT_CARE Exact 375 GLX_BIND_TO_TEXTURE_TARGETS_EXT - Mask 376 GLX_Y_INVERTED_EXT GLX_DONT_CARE Exact 377 378 Modifications to 3.3.3, "Configuration Management" 379 380 Add after paragraph 17 in the description of FBConfigs: 381 382 GLX_Y_INVERTED_EXT is a boolean describing the memory layout used for 383 drawables created with the GLXFBConfig. The attribute is True if the 384 drawable's framebuffer will be y-inverted. This can be used to determine 385 if y-inverted texture coordinates need to be used when texturing from this 386 drawable when it is bound to a texture target. 387 388 Modifications to 3.3.5, "Offscreen Rendering" 389 390 Modify paragraph 3 of the description of glXCreatePixmap: 391 392 <attrib_list> specifies a list of attributes for the pixmap. The list has 393 the same structure as described for glXChooseFBConfig. Currently the 394 following attributes can be specified in attrib_list: 395 GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT, GLX_MIPMAP_TEXTURE_EXT, 396 attrib_list may be NULL or empty (first attribute of None), in which case 397 all attributes assume their default values as described below. 398 399 GLX_TEXTURE_FORMAT_EXT describes the texture format this pixmap can be 400 bound to. Valid values are GLX_TEXTURE_FORMAT_RGB_EXT, 401 GLX_TEXTURE_FORMAT_RGBA_EXT, and GLX_TEXTURE_FORMAT_NONE_EXT. 402 403 GLX_TEXTURE_TARGET_EXT can be set to GLX_TEXTURE_1D_EXT, 404 GLX_TEXTURE_2D_EXT, or GLX_TEXTURE_RECTANGLE_EXT; it indicates the type 405 of texture that will be created when GLX_TEXTURE_FORMAT_EXT is not 406 GLX_TEXTURE_FORMAT_NONE_EXT. The default value of GLX_TEXTURE_TARGET_EXT 407 depends on the capabilities in <config> and the dimensions of the pixmap. 408 If <config> has GLX_TEXTURE_2D_BIT set and one or more of the following is 409 true: 410 411 * GLX_TEXTURE_RECTANGLE_BIT_EXT is not set in <config> 412 413 * GL_ARB_texture_non_power_of_two is supported 414 415 * the pixmap's width and height are powers of 2 416 417 the default value for GLX_TEXTURE_TARGET_EXT is GLX_TEXTURE_2D_EXT. 418 419 Otherwise, the first supported target is chosen in this order: 420 GLX_TEXTURE_RECTANGLE_EXT, GLX_TEXTURE_1D_EXT. 421 422 GLX_MIPMAP_TEXTURE_EXT indicates that storage for mipmaps should be 423 allocated. Space for mipmaps will be set aside if GLX_TEXTURE_FORMAT_EXT 424 is not GLX_TEXTURE_FORMAT_NONE_EXT and GLX_MIPMAP_TEXTURE_EXT is TRUE. 425 The default value is FALSE. 426 427 Modify paragraph 5 of the description of glXCreatePixmap: 428 429 ...If <pixmap> is not a valid Pixmap XID, then a BadPixmap error is 430 generated. A BadConfig error is generated if any of the following 431 conditions are true: 432 433 * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGB_EXT and 434 <config> does not have GLX_BIND_TO_TEXTURE_RGB set to TRUE. 435 436 * GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_RGBA_EXT and 437 <config> does not have GLX_BIND_TO_TEXTURE_RGBA set to TRUE. 438 439 * GLX_MIPMAP_TEXTURE_EXT is set to TRUE and <config> does not 440 have GLX_BIND_TO_MIPMAP_EXT set to TRUE. 441 442 * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_1D_EXT 443 and <config> does not have GLX_TEXTURE_1D_BIT_EXT set. 444 445 * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_2D_EXT 446 and <config> does not have GLX_TEXTURE_2D_BIT_EXT set. 447 448 * GLX_TEXTURE_TARGET_EXT is set to GLX_TEXTURE_RECTANGLE_EXT 449 and <config> does not have GLX_TEXTURE_RECTANGLE_BIT_EXT set. 450 451 A BadValue error is generated if GLX_TEXTURE_FORMAT_EXT is not 452 GLX_TEXTURE_FORMAT_NONE_EXT and the width or height of <pixmap> are 453 incompatible with the specified value of GLX_TEXTURE_TARGET_EXT on this 454 implementation. (e.g., the pixmap size is not a power of 2 and 455 GL_ARB_texture_rectangle is not supported). 456 457 Modify paragraph 1 of the description of glXDestroyPixmap: 458 459 ...The storage for the GLX pixmap will be freed when it is not current 460 to any client and all color buffers that are bound to a texture object 461 have been released. 462 463 464 Modifications to seciton 3.3.6, "Querying Attributes" 465 466 Modify paragraph 1 of the description of glXQueryDrawable: 467 468 ...<attribute> must be set to one of GLX_WIDTH, GLX_HEIGHT, 469 GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID, 470 GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_TARGET_EXT or GLX_MIPMAP_TEXTURE_EXT 471 or a BadValue error is generated. 472 473 Modify paragraph 3 of the description of glXQueryDrawable: 474 475 ...If <draw> is a GLXWindow or GLXPixmap and <attribute> is set to 476 GLX_PRESERVED_CONTENTS or GLX_LARGEST_PBUFFER, or if <draw> is a 477 GLXWindow or GLXPbuffer and <attribute> is set to GLX_TEXTURE_FORMAT_EXT, 478 GLX_TEXTURE_TARGET_EXT, or GLX_MIPMAP_TEXTURE_EXT, the contents of <value> 479 are undefined. 480 481 Add a new section 3.3.6.1, "Texturing From Drawables" 482 483 The command 484 485 void glXBindTexImageEXT (Display *dpy, 486 GLXDrawable draw, 487 int buffer, 488 int *attrib_list); 489 490 defines a one- or two-dimensional texture image. The texture image is taken 491 from <buffer> and need not be copied. The texture target, the texture 492 format, and the size of the texture components are derived from attributes 493 of <draw>. 494 495 The drawable attribute GLX_TEXTURE_FORMAT_EXT determines the base internal 496 format of the texture. The component sizes are also determined by drawable 497 attributes as shown in table 3.4a. 498 499 Add new table 3.4a: Size of texture components: 500 501 Texture component Size 502 ----------------- -------------- 503 R GLX_RED_SIZE 504 G GLX_GREEN_SIZE 505 B GLX_BLUE_SIZE 506 A GLX_ALPHA_SIZE 507 508 The texture target is derived from the GLX_TEXTURE_TARGET_EXT attribute of 509 <draw>. If the texture target for the drawable is GLX_TEXTURE_2D_EXT or 510 GLX_TEXTURE_RECTANGLE_EXT, then buffer defines a 2D texture for the current 511 2D or rectangle texture object respectively; if the texture target is 512 GLX_TEXTURE_1D_EXT, then buffer defines a 1D texture for the current 1D 513 texture object. 514 515 If <buffer> is not one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT, 516 GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, or GLX_AUX0_EXT through 517 GLX_AUXn_EXT, where n is one less than the number of AUX buffers supported 518 by the FBConfig used to create <draw>, or if the requested buffer is 519 missing, a BadValue error is generated. 520 521 <attrib_list> specifies a list of attributes for the texture. The list has 522 the same structure as described for glXChooseFBConfig. If <attrib_list> is 523 NULL or empty (first attribute of None), then all attributes assume their 524 default values. <attrib_list> must be NULL or empty. 525 526 If <dpy> and <draw> are the display and drawable for the calling thread's 527 current context, glXBindTexImageEXT performs an implicit glFlush. 528 529 The contents of the texture after the drawable has been bound are defined 530 as the result of all rendering that has completed before the call to 531 glXBindTexImageEXT. In other words, the results of any operation which 532 has caused damage on the drawable prior to the glXBindTexImageEXT call 533 will be represented in the texture. 534 535 Rendering to the drawable while it is bound to a texture will leave the 536 contents of the texture in an undefined state. However, no 537 synchronization between rendering and texturing is done by GLX. It is 538 the application's responsibility to implement any synchronization 539 required. 540 541 If a texture object is deleted before glXReleaseTexImageEXT is called, 542 the color buffer is released. 543 544 It is not an error to call TexImage2D, TexImage1D, CopyTexImage1D, or 545 CopyTexImage2D to replace an image of a texture object that has a color 546 buffer bound to it. However, these calls will cause the color buffer to be 547 released and new memory to be allocated for the texture. Note that the 548 color buffer is released even if the image that is being defined is a mipmap 549 level that was not defined by the color buffer. GenerateMipmapEXT is an 550 exception. GenerateMipmapEXT can be used to define mipmap levels for 551 drawables that have been created with GLX_MIPMAP_TEXTURE_EXT set. Calling 552 GenerateMipmapEXT on a drawable that was created without 553 GLX_MIPMAP_TEXTURE_EXT is undefined. 554 555 The results of calling glXBindTexImageEXT when GENERATE_MIPMAP_SGIS is TRUE 556 are undefined. 557 558 If glXBindTexImageEXT is called and the drawable attribute 559 GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch 560 error is generated. 561 562 Currently, only pixmaps can be bound to textures. If <draw> is not a 563 valid GLXPixmap, then a GLXBadPixmap error is generated. 564 565 glXBindTexImageEXT is ignored if there is no current GLX rendering context. 566 567 To release a color buffer that is being used as a texture, call 568 569 void glXReleaseTexImageEXT (Dislpay *dpy, GLXDrawable draw, int buffer); 570 571 <buffer> must be one of GLX_FRONT_LEFT_EXT, GLX_FRONT_RIGHT_EXT, 572 GLX_BACK_LEFT_EXT, GLX_BACK_RIGHT_EXT, and GLX_AUX0_EXT through 573 GLX_AUXn_EXT, where n is one less than the number of AUX buffers 574 supported by the FBConfig used to create <draw> or a BadValue error 575 is generated. 576 577 The contents of the color buffer are unaffected by glXReleaseTexImageEXT. 578 579 If the specified color buffer is no longer bound to a texture (e.g., 580 because the texture object was deleted), then glXReleaseTexImageEXT has no effect; 581 no error is generated. 582 583 When a color buffer is released (e.g., by calling glXReleaseTexImageEXT or 584 implicitly by calling a routine such as TexImage2D), all textures that were 585 defined by the color buffer become NULL. 586 587 If glXReleaseTexImageEXT is called and the drawable attribute 588 GLX_TEXTURE_FORMAT_EXT is GLX_TEXTURE_FORMAT_NONE_EXT, then a BadMatch 589 error is generated. 590 591 Currently, only pixmaps can be bound to textures. If <draw> is not a 592 valid GLXPixmap, then a GLXBadPixmap error is generated. 593 594 595Usage Examples 596 597 Example 1: Bind redirected window to texture: 598 599 XGetWindowAttributes (display, window, &attrib); 600 601 visualid = XVisualIDFromVisual (attrib.visual); 602 603 fbconfigs = glXGetFBConfigs (display, screen, &nfbconfigs); 604 for (i = 0; i < nfbconfigs; i++) 605 { 606 visinfo = glXGetVisualFromFBConfig (display, fbconfigs[i]); 607 if (!visinfo || visinfo->visualid != visualid) 608 continue; 609 610 glXGetFBConfigAttrib (display, fbconfigs[i], GLX_DRAWABLE_TYPE, &value); 611 if (!(value & GLX_PIXMAP_BIT)) 612 continue; 613 614 glXGetFBConfigAttrib (display, fbconfigs[i], 615 GLX_BIND_TO_TEXTURE_TARGETS_EXT, 616 &value); 617 if (!(value & GLX_TEXTURE_2D_BIT_EXT)) 618 continue; 619 620 glXGetFBConfigAttrib (display, fbconfigs[i], 621 GLX_BIND_TO_TEXTURE_RGBA_EXT, 622 &value); 623 if (value == FALSE) 624 { 625 glXGetFBConfigAttrib (display, fbconfigs[i], 626 GLX_BIND_TO_TEXTURE_RGB_EXT, 627 &value); 628 if (value == FALSE) 629 continue; 630 } 631 632 glXGetFBConfigAttrib (display, fbconfigs[i], 633 GLX_Y_INVERTED_EXT, 634 &value); 635 if (value == TRUE) 636 { 637 top = 0.0f; 638 bottom = 1.0f; 639 } 640 else 641 { 642 top = 1.0f; 643 bottom = 0.0f; 644 } 645 646 break; 647 } 648 649 if (i == nfbconfigs) 650 /* error 1 */ 651 652 pixmap = XCompositeNameWindowPixmap (display, window); 653 pixmapAttribs = { GLX_TEXTURE_TARGET_EXT, GLX_TEXTURE_2D_EXT, 654 GLX_TEXTURE_FORMAT_EXT, GLX_TEXTURE_FORMAT_RGBA_EXT, 655 None }; 656 glxpixmap = glXCreatePixmap (display, fbconfigs[i], pixmap, pixmapAttribs); 657 658 glGenTextures (1, &texture); 659 glBindTexture (GL_TEXTURE_2D, texture); 660 661 glXBindTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT, NULL); 662 663 glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR); 664 glTexParameteri (GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR); 665 666 /* draw using pixmap as texture */ 667 glBegin (GL_QUADS); 668 669 glTexCoord2d (0.0f, bottom); 670 glVertex2d (0.0f, 0.0f); 671 672 glTexCoord2d (0.0f, top); 673 glVertex2d (0.0f, 1.0f); 674 675 glTexCoord2d (1.0f, top); 676 glVertex2d (1.0f, 1.0f); 677 678 glTexCoord2d (1.0f, bottom); 679 glVertex2d (1.0f, 0.0f); 680 681 glEnd (); 682 683 glXReleaseTexImageEXT (display, glxpixmap, GLX_FRONT_LEFT_EXT); 684 685 686Version History 687 688 1. 26 Nov 2005 - DavidR 689 Initial version 690 2. 01 Dec 2005 - JamesJ 691 -Adapted spec language from draft version of GLX_ARB_render_texture. 692 -Added glXDrawableAttribute to set attributes. 693 -Modified glXBindTexImageEXT to take an attrib_list parameter. 694 -Added support for cubemap and 1D texture targets. 695 -Added attribute to set the texture target when creating the 696 drawable. 697 -Updated the issues section. 698 -Added mipmap support. Support is not required. 699 -Specified results of texturing from a drawable when it has been 700 rendered to while bound to a texture as undefined until 701 glXReleaseTexImageEXT has been called. Allows implementations 702 that need to perform an implicit copy after rendering occurs 703 to be compatible with this specification. 704 3. 04 Dec 2005 - DavidR 705 -Changed name to GLX_EXT_texture_from_pixmap. 706 -Changed spec regarding what happens when a pixmap that is bound 707 to a texture is rendered to. Having textures be undefined once 708 they are rendered to makes it useless for a compositing manager, 709 which is a major use case for this extension. 710 -Added support for not specifying texture target when creating a 711 pixmap. Allows implementations to select whatever target it 712 finds most suitable. 713 4. 05 Dec 2005 - JamesJ 714 -Changed the default value of GLX_TEXTURE_TARGET_EXT from 715 GLX_NO_TEXTURE_EXT to something usable. Eliminated 716 GLX_NO_TEXTURE_EXT. 717 -Eliminated GLX_TEXTURE_NONE_EXT. 718 -Removed language referring to sharing of color buffers when 719 pixmaps are bound to textures. 720 -Updated issues. 721 722 5. 13 Dec 2005 - JamesJ 723 -Removed cube map support and rendering to multiple mipmap 724 levels support. 725 726 6. 20 Jan 2006 - JamesJ 727 -Specified textures are y-inverted. 728 729 7. 23 Jan 2006 - AaronP 730 -Fix typos, make some things clearer. Replace ocurrences of "released 731 back to the drawable" with "released". 732 733 8. 01 Feb 2006 - AndyR 734 -Fix minor typos. 735 736 9. 03 Feb 2006 - JamesJ 737 -Added some new issues and their resolutions. 738 -Finalized some issues that had been in discussion. 739 -Made drawable y-inversion a queryable attribute of the drawable. 740 -Moved detailed explanation of y-inverted addressing to the issues 741 section 742 -Updated example to demonstrate proper use of the y-inverted 743 attribute. 744 745 10. 06 Feb 2006 - DavidR 746 -Made GLX_Y_INVERTED_EXT an FBConfig attribute instead of a drawable 747 attribute. 748 -Removed GLX_TEXTURE_CUBE_MAP_EXT. 749 -Fix minor typo. 750 751 11. 07 Feb 2006 - JamesJ 752 -Added description of GLX_Y_INVERTED_EXT GLXFBConfig attribute, based 753 on description of the drawable attribute of the same name from 754 and earlier version of the specification. 755 -Removed language requiring applications to re-bind a pixmap to a 756 texture to gurantee contents of the texture are updated after a 757 pixmap has been rendered to. 758 -Added Aaron Plattner and Andy Ritger to contributors section. 759 760 12. 14 Feb 2006 - JamesJ 761 -Disallowed rendering to a drawable while it is bound as a texture 762 and defined the exact contents of a texture after a drawable has 763 been bound to it. 764 765 13. 09 Mar 2006 - JamesJ 766 -Add a context tag member to the vendor private requests. This field 767 is part of the vendor private header, and is needed to specify which 768 context the BindTexImageEXT and ReleaseTexImageEXT requests correspond 769 to. 770 -Changed texture target bitfield values to not skip numbers removed in 771 earlier updates. 772 773 14. 13 Mar 2006 - JamesJ 774 -Only require GLX_SGIX_fbconfig + GLX 1.2. 775 -Clarify language regarding the result of rendering to drawables bound 776 to textures. 777 -Added GLX_FRONT_EXT and GLX_BACK_EXT tokens. 778 779 15. 18 Apr 2006 - JamesJ 780 -Allocated enum values and opcodes. 781 -Require GLX 1.3. GLX_SGIX_fbconfig doesn't allow creating pixmaps 782 with attributes. 783 -Added more arguments for not supporting rendering to multiple levels 784 of a texture with this extension. 785 -Fixed the inconsistencies in the return type of glXBindTexImageEXT 786 and glXReleaseTexImageEXT. It is now listed as void throughout. 787 788 16. 12 Sep 2006 - JamesJ 789 -Fix ordering of GLX protocol 790 791 17. 10 Feb 2009 - Jon Leech 792 -Fix typo reported by Jonathan Knispel. 793