1Name 2 3 ARB_render_texture 4 5Name Strings 6 7 WGL_ARB_render_texture 8 9Contact 10 11 Bimal Poddar, Intel, bimal.poddar@intel.com 12 Paula Womack, Nvidia, PWomack@nvidia.com 13 14Notice 15 16 Copyright (c) 2001-2013 The Khronos Group Inc. Copyright terms at 17 http://www.khronos.org/registry/speccopyright.html 18 19Specification Update Policy 20 21 Khronos-approved extension specifications are updated in response to 22 issues and bugs prioritized by the Khronos OpenGL Working Group. For 23 extensions which have been promoted to a core Specification, fixes will 24 first appear in the latest version of that core Specification, and will 25 eventually be backported to the extension document. This policy is 26 described in more detail at 27 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 28 29Status 30 31 Complete. Approved by ARB on June 13, 2001 32 33Version 34 35 Last Modified Date: July 16, 2001 36 37Number 38 39 ARB Extension #20 40 41Dependencies 42 43 OpenGL 1.1 is required. 44 WGL_ARB_extension_string is required. 45 WGL_ARB_pixel_format is required. 46 WGL_ARB_pbuffer is required. 47 WGL_ARB_make_current_read affects the definition of this extension. 48 GL_ARB_texture_cube_map affects the definition of this extension 49 The extension is written against the OpenGL 1.2.1 Specification. 50 51Overview 52 53 This extension allows a color buffer to be used for both rendering and 54 texturing. When a color buffer is bound to a texture target it cannot 55 be rendered to. Once it has been released from the texture it can be 56 rendered to once again. 57 58 This extension may provide a performance boost and reduce memory 59 requirements on architectures that support rendering to the same 60 memory where textures reside and in the same memory format and layout 61 required by texturing. The functionality is similar to CopyTexImage1D 62 and CopyTexImage2D. However, some changes were made to make it easier 63 to avoid copying data: 64 65 - Only color buffers of a pbuffer can be bound as a texture. It is 66 not possible to use the color buffer of a window as a texture. 67 68 - The texture internal format is determined when the color buffer 69 is associated with the texture, guaranteeing that the color 70 buffer format is equivalent to the texture internal format. 71 72 - When a color buffer of a pbuffer is being used as a texture, 73 the pbuffer can not be used for rendering; this makes it 74 easier for implementations to avoid a copy of the image 75 since the semantics of the pointer swap are clear. 76 77 - The application must release the color buffer from the texture 78 before it can render to the pbuffer again. When the color buffer 79 is bound as a texture, draw and read operations on the pbuffer 80 are undefined. 81 82 - A mipmap attribute can be set, in which case memory will be 83 allocated up front for mipmaps. The application can render 84 the mipmap images or, if SGIS_generate_mipmap is supported, 85 they can be automatically generated when the color buffer is 86 bound as a texture. 87 88 - A texture target is associated with the pbuffer, so that cubemap 89 images can be rendered into a single color buffer. 90 91 Note that this extension may be used in conjunction with other 92 extensions to associate video images/buffers to pbuffers. Once the 93 video image is associated with a pbuffer it can be used as a texture. 94 Also, if SGIX_generate_mipmap is supported, it is possible to 95 create a complete set of mipmap images from a single color buffer. 96 97IP Status 98 99 There are no known IP issues. 100 101Issues 102 103 1. Should we support 3D textures? What about 1D textures? 104 105 3D textures - No. This adds a lot of implementation burden without 106 having a good usage model. 107 108 1D textures - Yes. Just a special case of 2D texture. 109 110 2. Should we allow a portion of the color buffer to be used as a texture? 111 No, if a different size texture is needed the application can just 112 create another pbuffer. 113 114 3. Do we need the MIPMAP_TEXTURE attribute? 115 116 Yes this is good to have since some architectures may require all or 117 some of the mipmaps to be stored together in memory. 118 119 4. Should we require power of 2 textures? 120 121 Yes, we will allow an implementation to fail if the texture size is 122 not a power of 2. This restriction can be relaxed later by the 123 exension that allows non-power of 2 texture. 124 125 5. Should the render texture attributes be per color buffer or per drawable? 126 127 There really isn't a mechanism for associating attributes with the color 128 buffer. Also, allowing different render texture attributes for each 129 color buffer makes the extension more difficult to implement without 130 providing a very useful tool for applications. 131 132 6. What should happen if the color buffer is used for rendering before it 133 is released from the texture? 134 135 There are three reasonable options: generate an error, create another 136 buffer or have the rendering results be undefined. Since this is an 137 error condition, and not a useful feature, we should pick the option 138 that is easiest to implement. For now, we choose to have the rendering 139 results be undefined--the rendering commands will be processed and the 140 context will be updated but the pbuffer may or may not be updated. 141 Note that the pbuffer that contains the color buffer can be bound to a 142 different context, so the invalid state must be stored with the pbuffer, 143 not the context.. (Also the texture object that contains the 144 color buffer's image may be released from the current context). 145 146 7. Should the new pbuffer attributes be available through GL queries? 147 148 No, like other pbuffer attributes you need to query them through the 149 window system extension. This extension does not make any changes to 150 OpenGL. 151 152 8. Should we allow a subset of mipmaps to be defined? 153 154 No. 155 156 9. What happens when a pbuffer is bound as a texture and then a mode 157 change occurs and the pbuffer is lost? 158 159 The texture is not lost in this case. OpenGL doesn't have the notion 160 of volatile textures and this extension should not introduce them. 161 (It may be an interesting additional extension). When a color buffer 162 is bound to a texture, it must be saved and restored by the driver, 163 whenever texture memory is lost (even on a windows mode change). 164 16510. Should there be any restrictions on the texture operations that 166 can be performed on a color buffer? 167 168 Yes. We allow TexSubImage and CopyTexSubImage calls but disallow 169 TexImage and CopyTexImage calls. When a TexImage or CopyTexImage call 170 is made then the color buffer is released back to the pbuffer and 171 new memory is allocated for the texture. No mixing and matching of 172 images is allowed. In other words, it is not possible to render a 173 non-mipmapped image to a pbuffer, bind it to a texture and then 174 call TexImage2D to create the other mipmap levels. Modifying any 175 mipmap level via TexImage or CopyTexImage will cause the color 176 buffer to be released back to the pbuffer, even if that level 177 was not defined by the color buffer. 178 179 Also, if DeleteTextures is called on the texture target, then the 180 color buffer that is bound to the texture target is released back 181 to the pbuffer. 182 183 The implicit release of the color buffer is intended to work just 184 like an explicit release - i.e. the color buffer is available for 185 rendering without the app having to call ReleaseTexImage. 186 18711. When the color buffer is released from the texture (back to the pbuffer) 188 should the contents be preserved? 189 190 No, this may prove difficult to implement on some architectures. 191 19212. Should releasing the color buffer from the texture (back to the pbuffer) 193 affect the scissor or viewport? 194 195 No, since releasing the color buffer, does not change its size, it 196 should not affect the scissor or viewport. The application is also 197 responsible for updating the viewport and scissor when changing which 198 mipmap level it is rendering to (this is similar to window resize, 199 where the application is responsible for updating the scissor and 200 viewport). 201 20213. How should swap buffers work when a color buffer is bound as a texture? 203 204 Since a color buffer (not a pbuffer) is bound to a texture, swap buffers 205 should be a no-op. Otherwise the name of the bound buffer (FRONT, BACK) 206 will change while it is bound. Note that swap buffers works just as 207 for a pbuffer when the color buffer is not bound as a texture. 208 20914. What happens when the application binds one color buffer of a pbuffer 210 to a texture and then tries to render to another color buffer of the 211 pbuffer? 212 213 If any of the pbuffer's color buffers are bound to a texture, then 214 rendering results are undefined for all color buffers of the pbuffer. 215 21615. Should it be an error to bind a color buffer of a pbuffer to a 217 texture, if that pbuffer is current to another thread? 218 219 No. It is not an error to make a drawable current to two threads right 220 now. Read and draw operations produce indeterminate results when the 221 pbuffer is bound to a texture. 222 22316. Should we allow color buffers of all drawables (pbuffers and windows) 224 to be bound to textures? 225 226 For now we just allow pbuffers. This is simpler since they are not 227 shared with the window system and the color buffers are not part of the 228 visible framebuffer. Also, windows can be resized at any time and 229 handling this resize would unnecessarily complicate this extension. 230 23117. Should we allow depth buffers to be bound as textures? 232 233 This extension does not provide for this but it would be an interesting 234 additional extension. When a color buffer is bound to a texture, only 235 the color buffer is moved--ancillary buffers continue to be bound to 236 the pbuffer. 237 238 This extension is written such that adding depth textures should 239 be very easy. 240 24118. What happens when a color buffer is bound to a shared texture object? 242 243 Since the color buffer is associated with the texture object itself, 244 it should be shared. 245 24619. Should we specify how this extension interacts with SGIS_generate_mipmap? 247 248 No, since this is a potential ARB extension and SGIS_generate_mipmap 249 is not. If SGIS_generate_mipmap is supported along with this extension, 250 then if wglBindTexImageARB is called and both GENERATE_MIPMAP_SGIS and 251 WGL_MIPMAP_TEXTURE_ARB are TRUE, then a set of mipmaps should be 252 generated. This behaviour needs to be documented in the 253 SGIS_generate_mipmap (or equivalent) extension. 254 25520. Should we support borders on render textures? 256 257 No. Although borders are part of 1.2.1, they are often not supported 258 and better techniques (such as virtual textures) are starting to 259 become available for paging in large textures. 260 26121. Should wglBindTexImageARB take an attribute indicating whether 262 mipmaps are defined or should this be implied from the 263 WGL_MIPMAP_TEXTURE_ARB attribute of the pbuffer? 264 265 This should be implied from the WGL_MIPMAP_TEXTURE_ARB attribute 266 since GL allows controls for the applications to use only level zero 267 image even if the pbuffer has been defined large enough to 268 store mipmaps. 269 27022. This extension introduces pbuffer attributes that can be modified. 271 (Previously all pbuffer attributes were static and could not be 272 changed.) Should we allow the non-static attributes to be set when the 273 pbuffer is created or should we require the application to call 274 wglSetPbufferAttribARB? 275 276 We require the application to call wglSetPbufferAttribARB to set 277 non-static Pbuffer attributes since this seems to be more consistent 278 with OpenGL specification. 279 28023. Do we need WGL_TEXTURE_FORMAT_ARB or is WGL_ALPHA_BITS_ARB enough 281 to distinguish between selecting RGB vs. RGBA textures? Additionally, 282 how is this parameter defined for non texture buffers. 283 284 Resolved: In order to accommodate RGBA visuals to support RGB textures 285 (i.e. ignore alpha) and to allow the specification to be extensible 286 for depth textures, WGL_TEXTURE_FORMAT_ARB is required in this 287 specification. This parameter is defined as WGL_NO_TEXTURE_ARB for 288 non texture buffers. 289 29024. Should luminance and Intensity texture formats be allowed? 291 292 No. WGL doesn't support single-channel framebuffer formats. Allowing 293 these formats would require a copy to reformat a RGB/RGBA framebuffer 294 to a Luminance or Intensity format. If luminance framebuffer gets 295 added to WGL, then this feature can be added at that time. 296 297Implementation Notes 298 299 1. In order to prevent releases of a pbuffer from the texture object 300 and to deal with implicit release followed by an explicit release, 301 the GL implementation can keep a reference to any texture pbuffer 302 in the texture object. When the pbuffer is released, this handle 303 is set to NULL. Subsequent requests for releasing the texture 304 pbuffer are ignored. 305 306 2. The implicit release of the color buffers has been specifed to 307 work just like the explicit release so that the implementation 308 can delete a texture object (one of the implicit free cases) without 309 having to track whether the texture was associated with any color buffers. 310 311Intended Usage 312 313 To define a cube map texture, single threaded case 314 315 1) Create the rendering window. Call wglChoosePixelFormatARB and 316 find a suitable pixel format for rendering the image. Set the pixel 317 format for the rendering window to this pixel format. 318 319 2) Create the pbuffer. Call wglChoosePixelFormatARB and find a 320 suitable pixel format for rendering the texture. 321 WGL_DRAW_TO_PBUFFER and WGL_BIND_TO_TEXTURE_RGB_ARB or 322 WGL_BIND_TO_TEXTURE_RGBA_ARB must be TRUE. Create the pbuffer 323 with this pixel format. Set the pbuffer width and height to the 324 width and height of the level zero image. Set WGL_TEXTURE_FORMAT_ARB 325 to be WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB. Also set 326 WGL_TEXTURE_TARGET_ARB to WGL_TEXTURE_CUBE_MAP_ARB. 327 328 3) Create a context for the pbuffer. Make the context current to the 329 pbuffer and initialize the context's attributes. 330 331 4) Render all the cube map faces to the pbuffer. Call 332 wglSetPbufferAttribARB to set the cube map face before rendering 333 each face. Call glFlush. 334 335 5) Create a context for the window. Make the context current to the 336 window and intialize the contexts attributes. Bind a texture object 337 to the TEXTURE_CUBE_MAP_ARB target and set the texture parameters 338 to the desired values. 339 340 6) Call wglBindTexImageARB to bind the pbuffer drawable to the cube 341 map texture. Set <iBuffer> to WGL_FRONT or WGL_BACK depending upon 342 which color buffer was used for rendering the cube map. 343 344 7) Render to the window using the cube map texture. 345 346 8) Call wglReleaseTexImageARB to release the color buffer of the 347 pbuffer. Goto step 4 to generate more frames. 348 349 To define a 2D texture, single threaded case 350 351 In step 2, set the WGL_TEXTURE_TARGET_ARB to WGL_TEXTURE_2D_ARB. 352 353 Since a 2D texture does not have multiple faces, in step 5 354 there is no need to call wglSetPbufferAttribARB. 355 356 In addition, if mipmaps are to be generated, the step 5 should 357 be repeated multiple times with calls to wglSetPbufferAttribARB 358 to set different mip levels. 359 360New Procedures and Functions 361 362 BOOL wglBindTexImageARB (HPBUFFERARB hPbuffer, int iBuffer) 363 364 BOOL wglReleaseTexImageARB (HPBUFFERARB hPbuffer, int iBuffer) 365 366 BOOL wglSetPbufferAttribARB (HPBUFFERARB hPbuffer, 367 const int *piAttribList) 368 369New Tokens 370 371 Accepted by the <piAttributes> parameter of wglGetPixelFormatAttribivARB, 372 wglGetPixelFormatAttribfvARB, and the <piAttribIList> and <pfAttribIList> 373 parameters of wglChoosePixelFormatARB: 374 375 WGL_BIND_TO_TEXTURE_RGB_ARB 0x2070 376 WGL_BIND_TO_TEXTURE_RGBA_ARB 0x2071 377 378 Accepted by the <piAttribList> parameter of wglCreatePbufferARB and 379 by the <iAttribute> parameter of wglQueryPbufferARB: 380 381 WGL_TEXTURE_FORMAT_ARB 0x2072 382 WGL_TEXTURE_TARGET_ARB 0x2073 383 WGL_MIPMAP_TEXTURE_ARB 0x2074 384 385 Accepted as a value in the <piAttribList> parameter of 386 wglCreatePbufferARB and returned in the value parameter of 387 wglQueryPbufferARB when <iAttribute> is WGL_TEXTURE_FORMAT_ARB: 388 389 WGL_TEXTURE_RGB_ARB 0x2075 390 WGL_TEXTURE_RGBA_ARB 0x2076 391 WGL_NO_TEXTURE_ARB 0x2077 392 393 Accepted as a value in the <piAttribList> parameter of 394 wglCreatePbufferARB and returned in the value parameter of 395 wglQueryPbufferARB when <iAttribute> is WGL_TEXTURE_TARGET_ARB: 396 397 WGL_TEXTURE_CUBE_MAP_ARB 0x2078 398 WGL_TEXTURE_1D_ARB 0x2079 399 WGL_TEXTURE_2D_ARB 0x207A 400 WGL_NO_TEXTURE_ARB 0x2077 401 402 Accepted by the <piAttribList> parameter of wglSetPbufferAttribARB and 403 by the <iAttribute> parameter of wglQueryPbufferARB: 404 405 WGL_MIPMAP_LEVEL_ARB 0x207B 406 WGL_CUBE_MAP_FACE_ARB 0x207C 407 408 Accepted as a value in the <piAttribList> parameter of 409 wglSetPbufferAttribARB and returned in the value parameter of 410 wglQueryPbufferARB when <iAttribute> is WGL_CUBE_MAP_FACE_ARB: 411 412 WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB 0x207D 413 WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB 0x207E 414 WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB 0x207F 415 WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB 0x2080 416 WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB 0x2081 417 WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB 0x2082 418 419 Accepted by the <iBuffer> parameter of wglBindTexImageARB and 420 wglReleaseTexImageARB: 421 422 WGL_FRONT_LEFT_ARB 0x2083 423 WGL_FRONT_RIGHT_ARB 0x2084 424 WGL_BACK_LEFT_ARB 0x2085 425 WGL_BACK_RIGHT_ARB 0x2086 426 WGL_AUX0_ARB 0x2087 427 WGL_AUX1_ARB 0x2088 428 WGL_AUX2_ARB 0x2089 429 WGL_AUX3_ARB 0x208A 430 WGL_AUX4_ARB 0x208B 431 WGL_AUX5_ARB 0x208C 432 WGL_AUX6_ARB 0x208D 433 WGL_AUX7_ARB 0x208E 434 WGL_AUX8_ARB 0x208F 435 WGL_AUX9_ARB 0x2090 436 437Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 438 439 None. 440 441Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 442 443 None. 444 445Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 446Operations and the Frame Buffer) 447 448 None. 449 450Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 451 452 None. 453 454Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and State 455Requests) 456 457 None. 458 459Additions to the WGL Specification 460 461 Add to the description of <piAttributes> in wglGetPixelFormatAttribivARB 462 and <pfAttributes> in wglGetPixelFormatfv: 463 464 WGL_BIND_TO_TEXTURE_RGB_ARB 465 WGL_BIND_TO_TEXTURE_RGBA_ARB 466 467 True if the color buffers can be bound to a RGB/RGBA texture. 468 Currently only pbuffers can be bound as textures so this attribute 469 will only be TRUE if WGL_DRAW_TO_PBUFFER is also TRUE. It is 470 possible to bind a RGBA visual to a RGB texture in 471 which case the values in the alpha component of the visual 472 are ignored when the color buffer is used as a RGB texture. 473 474 Implementations may choose not to support WGL_BIND_TO_TEXTURE_RGB_ARB 475 for RGBA visuals. 476 477 Add new table entries to match criteria in description of 478 wglChoosePixelFormatARB: 479 480 Attribute Type Match Criteria 481 482 WGL_BIND_TO_TEXTURE_RGB_ARB boolean exact 483 WGL_BIND_TO_TEXTURE_RGBA_ARB boolean exact 484 485 Modify wglCreatePbufferARB: 486 487 HPBUFFERARB wglCreatePbufferARB (HDC hDC, int iPixelFormat, 488 int iWidth, int iHeight, const int *piAttribList); 489 490 ... 491 492 <iWidth> and <iHeight> specify the pixel width and height of the 493 rectangular pbuffer. If the texture format is set to 494 WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB using 495 WGL_TEXTURE_FORMAT_ARB, then the pbuffer width and height 496 specify the size of the level zero texture image or, in the 497 case of a cube map texture, each level zero image. 498 499 <piAttribList> is a list of attribute {type, value} pairs containing 500 integer attribute values. All of the attributes in <piAttribList> 501 are followed by the corresponding required value. The list is 502 terminated with a value of 0. 503 504 <piAttribList> may be NULL or empty in which case all attributes assume 505 their default values as described below. 506 507 The following attributes are supported by wglCreatePbufferARB: 508 509 WGL_TEXTURE_FORMAT_ARB 510 511 This attribute indicates the format of the texture that will be 512 created when a pbuffer is bound to a texture map. 513 It can be set to WGL_TEXTURE_RGB_ARB, WGL_TEXTURE_RGBA_ARB or 514 WGL_NO_TEXTURE_ARB. The default value is WGL_NO_TEXTURE_ARB. 515 516 WGL_TEXTURE_TARGET_ARB 517 518 This attribute indicates the target for the texture that will be 519 created when the pbuffer is created with a texture format of 520 WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB. This attribute can 521 be set to WGL_NO_TEXTURE_ARB, WGL_TEXTURE_1D_ARB, WGL_TEXTURE_2D_ARB 522 or WGL_TEXTURE_CUBE_MAP_ARB. The default value is WGL_NO_TEXTURE_ARB. 523 524 WGL_MIPMAP_TEXTURE_ARB 525 526 If this attribute is set to a non-zero value, and the texture format 527 is set to WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB, then storage 528 for mipmaps will be allocated. The default value is FALSE. 529 530 WGL_PBUFFER_LARGEST_ARB 531 532 If this attribute is set to a non-zero value, the largest 533 available pbuffer is allocated when the allocation of the pbuffer 534 would otherwise fail due to insufficient resources. The width or 535 height of the allocated pbuffer never exceeds <iWidth> and <iHeight>, 536 respectively. Also, if the pbuffer will be used as a texture 537 (i.e., the value of the WGL_TEXTURE_TARGET_ARB attribute is 538 WGL_TEXTURE_1D_ARB, WGL_TEXTURE_2D_ARB or WGL_TEXTURE_CUBE_MAP_ARB 539 and texture format is WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB), 540 then the aspect ratio will be preserved and the new width and 541 height will be valid sizes for the corresponding texture target. 542 (e.g. Both the width and height will be a power of 2 if the 543 implementation only supports power of 2 textures. Similarily, 544 the width and height will be equal for a cube map texture). 545 Use wglQueryPbufferARB to retrieve the dimensions of the 546 allocated pbuffer. The default value for this attribute is FALSE. 547 548 The resulting pbuffer will contain color buffers and ancillary 549 buffers as specified by <iPixelFormat>. Note that pbuffers use 550 framebuffer resources so applications should consider deallocating 551 them when they are not in use. 552 553 It is possible to create a pbuffer with back buffers and to swap the 554 front and back buffers by calling wglSwapLayerBuffers. The 555 contents of the back buffers after the swap depends on the 556 <iPixelFormat>. (Pbuffers are the same as windows in this respect.) 557 558 The contents of the depth and stencil buffers may not be preserved 559 when rendering a texture to the pbuffer and switching which image 560 of the texture is rendered to (e.g., switching from rendering one 561 mipmap level to rendering another). 562 563 When wglCreatePbufferARB fails to create a pbuffer, NULL is returned. 564 To get extended error information, call GetLastError. Possible 565 errors are as follows: 566 567 ERROR_INVALID_PIXEL_FORMAT Pixel format is not valid. 568 569 ERROR_NO_SYSTEM_RESOURCES Insufficient resources exist. 570 571 ERROR_INVALID_DATA <iWidth> or <iHeight> is negative or zero. 572 573 ERROR_INVALID_DATA WGL_TEXTURE_TARGET_ARB attribute is 574 set to WGL_TEXTURE_CUBE_MAP_ARB, and 575 iWidth does not equal iHeight. 576 577 ERROR_INVALID_DATA WGL_TEXTURE_TARGET_ARB attribute is set 578 to WGL_TEXTURE_1D_ARB, and iHeight is 579 not set to one. 580 581 ERROR_INVALID_DATA The pixel format attribute 582 WGL_TEXTURE_FORMAT_ARB is 583 WGL_TEXTURE_RGB_ARB or WGL_TEXTURE_RGBA_ARB 584 and WGL_PBUFFER_WIDTH and/or 585 WGL_PBUFFER_HEIGHT specify an invalid 586 size for the implementation (e.g., the 587 texture size is not a power of 2). 588 589 ERROR_INVALID_DATA An attribute in <piAttribList> is not a 590 valid attribute. 591 592 ERROR_INVALID_DATA The texture format is set to 593 WGL_NO_TEXTURE_ARB and texture target 594 is set to something other than 595 WGL_NO_TEXTURE_ARB. 596 597 ERROR_INVALID_DATA The texture format is set to some target 598 besides WGL_NO_TEXTURE_ARB and texture 599 target is set to WGL_NO_TEXTURE_ARB. 600 601 .... 602 603 Modify wglDestroyPbufferARB: 604 605 A pbuffer is destroyed by calling 606 607 BOOL wglDestroyPbufferARB(HPBUFFERARB hPbuffer); 608 609 The pbuffer is destroyed once it is no longer current to any 610 rendering context and once all color buffers that are bound to a 611 texture object have been released. When a pbuffer is destroyed, 612 any memory resources that are attached to it are freed 613 and its handle is no longer valid. 614 615 .... 616 617 Add wglSetPbufferAttribARB: 618 619 To set an attribute of a pbuffer call 620 621 BOOL wglSetPbufferAttribARB (HPBUFFERARB hPbuffer, 622 const int *piAttribList); 623 624 with <hPbuffer> set to a previously returned pbuffer handle. 625 <piAttribList> is a list of attribute {type, value} pairs containing 626 integer values. All the attributes in <piAttribList> are followed by 627 the corresponding desired value. The list is terminated with 0. 628 If <piAttribList> is NULL or empty then this function is a no-op. 629 630 The following values are accepted: 631 632 WGL_MIPMAP_LEVEL_ARB 633 634 For mipmap textures, this attribute indicates which level of the 635 mipmap should be rendered. The default value is zero. If the value 636 of this attribute is outside the range of supported mipmap level, 637 the closest valid mipmap level is selected for rendering. 638 639 WGL_CUBE_MAP_FACE_ARB 640 641 For cube map textures, this attribute indicates which face of the 642 cube map should be rendered; it must be set to one of 643 644 WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB, 645 WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB, 646 WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB, 647 WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB, 648 WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB, 649 WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB. 650 651 The default value is WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB. 652 653 If wglSetPbufferAttribARB fails, FALSE is returned. To get extended 654 error information, call GetLastError. Possible errors are as follows: 655 656 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 657 658 ERROR_INVALID_DATA Bad attribute specified in <piAttribList>. 659 660 ERROR_INVALID_DATA WGL_MIPMAP_LEVEL_ARB does not specify 661 a valid mipmap level. 662 663 ERROR_INVALID_DATA WGL_CUBE_MAP_IMAGE_ARB is not set to a 664 valid value. 665 666 .... 667 668 Modify wglQueryPbufferARB: 669 670 To query an attribute associated with a specific pbuffer, call 671 672 BOOL wglQueryPbufferARB(HPBUFFERARB hPbuffer, int iAttribute, 673 int *piValue); 674 675 with <hPbuffer> set to a previously returned pbuffer handle. 676 <iAttribute> must be set to one of WGL_PBUFFER_WIDTH_ARB, 677 WGL_PBUFFER_HEIGHT_ARB, WGL_PBUFFER_LOST_ARB, WGL_TEXTURE_TARGET_ARB, 678 WGL_MIPMAP_TEXTURE_ARB, WGL_MIPMAP_LEVEL_ARB, WGL_CUBE_MAP_FACE_ARB 679 or WGL_TEXTURE_FORMAT_ARB. 680 681 The WGL_PBUFFER_LOST_ARB query can be used to determine if the pixel 682 buffer memory was lost due to a display mode change. A value of 683 TRUE is returned in buffer <piValue> if the display mode change lost 684 the memory for the pixel buffer. It is not an error to render to a 685 pixel buffer in this state, but the effect of rendering to it is the 686 same as if the pixel buffer was destroyed: the context state will 687 be updated, but the values of the returned pixels are undefined. 688 The pixel buffer must be destroyed and recreated if the pixel buffer 689 memory has been lost. A value of FALSE is returned to indicate 690 that the contents of the pixel buffer are unaffected by the display 691 mode change. 692 693 When a color buffer of a pbuffer is bound as a texture, then the 694 contents of that texture must be preserved until the color buffer is 695 released. If the pbuffer is lost, any color buffers that are bound 696 to textures will be freed when they are released back to the pbuffer 697 by calling wglReleaseTexImage. 698 699 If wglPbufferAttribARB fails, FALSE is returned. To get extended 700 error information, call GetLastError. Possible errors are as follows: 701 702 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 703 704 ERROR_INVALID_DATA <iAttribute> is not a valid attribute. 705 706 .... 707 708 Add wglBindTexImageARB and wglReleaseTexImageARB: 709 710 The command 711 712 BOOL wglBindTexImageARB (HPBUFFERARB hPbuffer, int iBuffer) 713 714 defines a one-dimensional texture image or two-dimensional 715 texture image or a set of two-dimensional cube map texture images. 716 The texture image or images consist of the image data in <iBuffer> 717 for the specified pbuffer, <hPbuffer>, and need not be copied. 718 The texture target, the texture format and the size of the 719 texture components are derived from attributes of pbuffer 720 specified by <hPbuffer>. 721 722 Note that any existing images associated with the different 723 mipmap levels of the texture object are freed (it is as if 724 TexImage was called with an image of zero width). 725 726 The pbuffer attribute WGL_TEXTURE_FORMAT_ARB determines the base 727 internal format of the texture. The component sizes are also 728 determined by pbuffer attributes as shown in the table below. 729 730 Texture Component Size 731 732 R WGL_RED_BITS_ARB 733 G WGL_GREEN_BITS_ARB 734 B WGL_BLUE_BITS_ARB 735 A WGL_ALPHA_BITS_ARB 736 737 738 Table x.x: Size of texture components 739 740 The texture targets are derived from the WGL_TEXTURE_TARGET_ARB 741 attribute of <hPbuffer>. If the texture target for the pbuffer is 742 WGL_TEXTURE_CUBE_MAP_ARB then <iBuffer> defines a set of cubemap 743 images for the cube map texture objects which are bound to the 744 current context (hereafter referred to as the current texture 745 object). Note that when the texture target is 746 WGL_TEXTURE_CUBE_MAP_ARB, all cube map texture targets are defined 747 by a single call to wglBindTexImageARB. If the texture target is 748 WGL_TEXTURE_2D_ARB, then <iBuffer> defines a 2D texture for the 749 current 2D texture object; if the texture target is WGL_TEXTURE_1D_ARB, 750 then <iBuffer> defines a 1D texture for the current 1D texture object. 751 752 The possible values for <iBuffer> are WGL_FRONT_LEFT_ARB, 753 WGL_FRONT_RIGHT_ARB, WGL_BACK_LEFT_ARB, WGL_BACK_RIGHT_ARB, and 754 WGL_AUX0_ARB through WGL_AUXn_ARB. 755 756 If <hPbuffer> is the calling thread's current drawable, 757 wglBindTexImageARB performs an implicit glFlush. 758 759 After this function is called, the pbuffer associated with <iBuffer> 760 is no longer available for reading or writing. Any read 761 operation, such as glReadPixels, which reads values from any of the 762 pbuffer's color buffers or ancillary buffers, will produce 763 indeterminate results. In addition, any draw operation that is 764 done to the pbuffer prior to wglReleaseTexImageARB being called, 765 produces indeterminant results. Specifically, if the pbuffer is 766 current to a context and thread then rendering commands will be 767 processed and the context state will be updated but the pbuffer may 768 or may not be written. Also, SwapBuffers is a no-op if it is called 769 on this pbuffer. 770 771 Note that the color buffer is bound to a texture object. If the 772 texture object is shared between contexts, then the 773 color buffer is also shared. If a texture object is deleted 774 before wglReleaseTexImageARB is called, then the color buffer is 775 released and the pbuffer is made available for reading and writing. 776 777 It is not an error to call TexImage2D, TexImage1D, 778 CopyTexImage1D or CopyTexImage2D to replace an image of a texture 779 object that has a color buffer bound to it. However, these calls 780 will cause the color buffer to be released back to the pbuffer and 781 new memory will be allocated for the texture. Note that the color 782 buffer is released even if the image that is being defined is a 783 mipmap level that was not defined by the color buffer. 784 785 wglBindTexImageARB is ignored if there is no current rendering 786 context. 787 788 If wglBindTexImageARB fails, FALSE is returned. To get extended 789 error information, call GetLastError. Possible errors are as follows: 790 791 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 792 793 ERROR_INVALID_DATA <iBuffer> is not a valid value. 794 795 ERROR_INVALID_OPERATION The pbuffer attribute 796 WGL_TEXTURE_FORMAT_ARB is set to 797 WGL_NO_TEXTURE_ARB. 798 799 ERROR_INVALID_OPERATION <iBuffer> is already bound to the texture 800 801 802 To release a color buffer that is being used as a texture call 803 804 BOOL wglReleaseTexImageARB (HPBUFFERARB hPbuffer, int iBuffer) 805 806 This releases the specified color buffer back to the pbuffer. The 807 pbuffer is made available for reading and writing when it no 808 longer has any color buffers bound as textures. 809 810 <iBuffer> must be one of WGL_FRONT_LEFT_ARB, WGL_FRONT_RIGHT_ARB, 811 WGL_BACK_LEFT_ARB, WGL_BACK_RIGHT_ARB, or WGL_AUX0_ARB through 812 WGL_AUXn_ARB. 813 814 The contents of the color buffer are undefined when it is first 815 released. In particular there is no guarantee that the texture 816 image is still present. However, the contents of other color 817 buffers is unaffected by this call. Also, the contents of the depth, 818 stencil and accumulation buffers are not affected by 819 wglBindTexImageARB and wglReleaseTexImageARB. 820 821 If the specified color buffer is no longer bound to a texture (e.g., 822 because the texture object was deleted) then this call is a 823 noop; no error is generated. 824 825 After a color buffer is released from a texture (either explicitly 826 by calling wglReleaseTexImageARB or implicitly by calling a 827 routine such as TexImage2D), all texture images that were defined 828 by the color buffer become NULL (it is as if TexImage was 829 called with an image of zero width). 830 831 If wglReleaseTexImageARB fails, FALSE is returned. To get extended 832 error information, call GetLastError. Possible errors are as follows: 833 834 ERROR_INVALID_HANDLE <hPbuffer> is not a valid handle. 835 836 ERROR_INVALID_DATA <iBuffer> is not a valid value. 837 838 ERROR_INVALID_OPERATION The pbuffer attribute 839 WGL_TEXTURE_FORMAT_ARB is set to 840 WGL_NO_TEXTURE_ARB. 841 842New State 843 844 None 845 846Dependencies on GL_ARB_texture_cube_map 847 848 If GL_ARB_texture_cube_map is not supported then all references to 849 WGL_TEXTURE_CUBE_MAP_POSITIVE_X_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_X_ARB, 850 WGL_TEXTURE_CUBE_MAP_POSITIVE_Y_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_Y_ARB, 851 WGL_TEXTURE_CUBE_MAP_POSITIVE_Z_ARB, WGL_TEXTURE_CUBE_MAP_NEGATIVE_Z_ARB, 852 WGL_TEXTURE_CUBE_MAP_ARB and WGL_CUBE_MAP_FACE_ARB are deleted. 853 854Revision History 855 07/16/01 bpoddar 1. Added WGL_TEXTURE_CUBE_MAP_POSITIVE_*_ARB 856 enums to the new tokens section. 857 2. Added clarification on MIPMAP_LEVEL_ARB usage. 858 3. Removed 1 invalid error condition from 859 wglBindTexImage. 860 4. Changed parameter references to <parameter>. 861 862 07/12/01 bpoddar Fixed minor typos and added enum values. 863 864 06/22/01 bpoddar Minor language edits from ARB participants. 865 866 04/09/01 bpoddar 1. Renamed WGL_TEXTURE_TYPE_ARB to 867 WGL_TEXTURE_TARGET_ARB. 868 2. Cleaned up behavior of WGL_TEXTURE_FORMAT_ARB. 869 870 03/23/01 bpoddar 1. Updated the implementation notes section 871 with the discussion at the ARB. 872 2. Replaced ERROR_??? with specified errors 873 3. Clarified width and height selection rules 874 for WGL_PBUFFER_LARGEST. 875 4. Added policy for dealing with mip levels 876 both on Bind and Release. 877 5. Specified behavior for implicit release and 878 added comment to implementation section. 879 6. Added couple of errors to SetPbufferAttrib. 880 881 03/06/01 bpoddar 1. Deleted references to 3D texture 882 2. Deleted references to LUMINANCE, INTENSITY 883 textures. 884 3. wglBindTexImageARB no longer provides a 885 separate mipmap attribute (issue #21). 886 4. Removed references to multiple texture 887 objects for cube maps. 888 5. Added issue # 23. 889 6. Added implementation notes section. 890 891 12/01/00 pwomack Updated issues list. Require non-static pbuffer 892 attributes to be set via SetPbufferAttrib (they 893 cannot be set when the pbuffer is created.) 894 The WGL_TEXTURE_TARGET_ARB attribute now takes 895 WGL_NO_TEXTURE_ARB as a value, so the app can 896 indicate that the pbuffer will never be bound 897 as a texture. If a pbuffer is created with 898 WGL_TEXTURE_TARGET_ARB set to WGL_NO_TEXTURE_ARB, 899 then an error results if an attempt is made to 900 bind it as a texture. Specified default values 901 for all attribute lists. When a color buffer is 902 bound as a texture then drawing to the pbuffer 903 gives undefined results (previously the 904 rendering was lost). When a color buffer is 905 bound as a texture, calling TexImage or 906 CopyTexImage releases the color buffer back to 907 the pbuffer. 908 909 11/12/00 pwomack Created. Copied from GLX extension. Added WGL 910 calls and removed all GLX-centric stuff. 911