1Name 2 3 ARB_sparse_texture2 4 5Name Strings 6 7 GL_ARB_sparse_texture2 8 9Contact 10 11 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 12 Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com) 13 14Contributors 15 16 Jeff Bolz, NVIDIA Corporation 17 Mathias Heyer, NVIDIA Corporation 18 Eric Werness, NVIDIA Corporation 19 20Notice 21 22 Copyright (c) 2015 The Khronos Group Inc. Copyright terms at 23 http://www.khronos.org/registry/speccopyright.html 24 25Specification Update Policy 26 27 Khronos-approved extension specifications are updated in response to 28 issues and bugs prioritized by the Khronos OpenGL Working Group. For 29 extensions which have been promoted to a core Specification, fixes will 30 first appear in the latest version of that core Specification, and will 31 eventually be backported to the extension document. This policy is 32 described in more detail at 33 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 34 35Status 36 37 Complete. Approved by the ARB on June 26, 2015. 38 Ratified by the Khronos Board of Promoters on August 7, 2015. 39 40Version 41 42 Last Modified Date: May 26, 2015 43 Revision: 3 44 45Number 46 47 ARB Extension #186 48 49Dependencies 50 51 This extension is written against the OpenGL 4.5 Specification 52 (Compatibility Profile), dated February 2, 2015. 53 54 This extension is written against the OpenGL Shading Language 55 Specification, version 4.50, revision 5. 56 57 When implemented in OpenGL, this extension requires and extends 58 ARB_sparse_texture. 59 60 This extension interacts trivially with EXT_depth_bounds_test. 61 62 This extension interacts with NV_gpu_program4 and NV_gpu_program5. 63 64Overview 65 66 This extension builds on the ARB_sparse_texture extension, providing the 67 following new functionality: 68 69 * New built-in GLSL texture lookup and image load functions are provided 70 that return information on whether the texels accessed for the texture 71 lookup accessed uncommitted texture memory. 72 73 * New built-in GLSL texture lookup functions are provided that specify a 74 minimum level of detail to use for lookups where the level of detail 75 is computed automatically. This allows shaders to avoid accessing 76 unpopulated portions of high-resolution levels of detail when it knows 77 that the memory accessed is unpopulated, either from a priori 78 knowledge or from feedback provided by the return value of previously 79 executed "sparse" texture lookup functions. 80 81 * Reads of uncommitted texture memory will act as though such memory 82 were filled with zeroes; previously, the values returned by reads were 83 undefined. 84 85 * Standard implementation-independent virtual page sizes for internal 86 formats required to be supported with sparse textures. These standard 87 sizes can be requested by leaving VIRTUAL_PAGE_SIZE_INDEX_ARB at its 88 initial value (0). 89 90 * Support for creating sparse multisample and multisample array textures 91 is added. However, the virtual page sizes for such textures remain 92 fully implementation-dependent. 93 94New Procedures and Functions 95 96 None. 97 98New Tokens 99 100 None. 101 102Modifications to the OpenGL 4.5 Specification (Compatibility Profile) 103 104 Modify Section 8.10, Texture Parameters, p. 264 105 106 (modify the following Errors section entry for TexParameter*, added by 107 ARB_sparse_texture, to allow for sparse multisample and multisample array 108 textures) 109 110 INVALID_VALUE is generated if <pname> is TEXTURE_SPARSE_ARB, <pname> 111 is TRUE and <target> is not one of TEXTURE_2D, TEXTURE_2D_ARRAY, 112 TEXTURE_CUBE_MAP, TEXTURE_CUBE_MAP_ARRAY, TEXTURE_3D, TEXTURE_RECTANGLE, 113 TEXTURE_2D_MULTISAMPLE, or TEXTURE_2D_MULTISAMPLE_ARRAY. 114 115 116 Modify the edits to Section 8.19 (Immutable-Format Texture Images), as 117 made by ARB_sparse_texture 118 119 (remove the following language from the "p. 233" edits starting with "If 120 TEXTURE_SPARSE_ARB is TRUE"; there is no longer a restriction on the base 121 size of a sparse texture allocation) 122 123 [REMOVED LANGUAGE] ... In this case, <width>, <height>, and <depth> must 124 either be integer multiples of the selected virtual page size in the X, Y, 125 and Z dimensions, respectively, or be less than those dimensions. ... 126 127 (remove the following TexStorage error added by ARB_sparse_texture; there 128 is no longer a restriction on the base size of a sparse texture 129 allocation) 130 131 [REMOVED LANGUAGE] An INVALID_VALUE error is generated if 132 TEXTURE_SPARSE_ARB is TRUE and <width>, <height> or <depth> is is not an 133 integer multiple of the page size in the corresponding dimension. 134 135 (remove the error language beginning with "If the value of 136 SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB is FALSE", and replace with 137 the following) 138 139 In older extensions supporting sparse textures, the constant 140 SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB was provided to advertise 141 implementation-dependent limitations potentially prohibiting the 142 allocation of array or cube map textures with full mipmap chains. No such 143 limitations apply in this extension. This constant is retained for 144 backwards compatibility, but all implementations of this extension must 145 return TRUE. 146 147 148 Modify Section 8.20.1 of ARB_sparse_texture (Allocation of and Access to 149 Sparse Textures) 150 151 (insert after the two paragraphs discussing VIRTUAL_PAGE_SIZE_INDEX_ARB) 152 153 When leaving the VIRTUAL_PAGE_SIZE_INDEX_ARB texture parameter at its 154 initial value (0), the virtual page size for many non-multisample sparse 155 textures can be found in Table 8.X. If the internal format of the texture 156 is not listed in Table 8.X or if the texture target is 157 TEXTURE_2D_MULTISAMPLE, TEXTURE_2D_MULTISAMPLE_ARRAY, or TEXTURE_3D, the 158 virtual page size for index zero is fully implementation- 159 dependent. Otherwise, the virtual page size of such a texture comes from 160 the value listed in the value listed in the "2D Page Size" column. 161 162 Internal Format 2D Page Size 163 --------------- ------------- 164 R8 256 x 256 x 1 165 R8_SNORM 166 R8I 167 R8UI 168 169 R16 256 x 128 x 1 170 R16_SNORM 171 RG8 172 RG8_SNORM 173 RGB565 174 R16F 175 R16I 176 R16UI 177 RG8I 178 RG8UI 179 180 RG16 128 x 128 x 1 181 RG16_SNORM 182 RGBA8 183 RGBA8_SNORM 184 RGB10_A2 185 RGB10_A2UI 186 RG16F 187 R32F 188 R11F_G11F_B10F 189 RGB9_E5 190 R32I 191 R32UI 192 RG16I 193 RG16UI 194 RGBA8I 195 RGBA8UI 196 197 RGBA16 128 x 64 x 1 198 RGBA16_SNORM 199 RGBA16F 200 RG32F 201 RG32I 202 RG32UI 203 RGBA16I 204 RGBA16UI 205 206 RGBA32F 64 x 64 x 1 207 RGBA32I 208 RGBA32UI 209 210 Table 8.X, Standard Virtual Page Sizes for Sparse Textures 211 212 213 (modify first bullet under "When a sparsely committed texture is accessed 214 by the GL" at the end of the section) 215 216 * Reads from such regions behave as if the data in texture memory for 217 all components present in the texture format were zero. This 218 includes samples required for the implementation of texture 219 filtering, image loads, mipmap generation, and so on. For texture 220 and image loads, components not present in the texture format (e.g., 221 alpha in a texture with an RGB base internal format) will return 222 default values, as in non-sparse textures. 223 224 (modify third bullet under "When a sparsely committed texture is accessed 225 by the GL" at the end of the section) 226 227 * Atomic operations operating on uncommitted regions will not generate 228 exceptions but will always return zero. The result of the atomic 229 operation, which is normally written to memory, will instead be 230 discarded. 231 232 (add new bullets under "When a sparsely committed texture is accessed by 233 the GL" at the end of the section) 234 235 * When performing the stencil test (section 17.3.5), depth buffer test 236 (section 17.3.6), or depth bounds test on pixels in uncommitted 237 regions, the results of the test will be consistent with reading a 238 value of zero from the framebuffer. No value is written to the 239 depth buffer. 240 241 (add a new paragraph at the end of the section) 242 243 The OpenGL Shading Language provides built-in functions that perform a 244 texture fetch or image load and return sparse texture status information 245 to the caller. The status information can be queried by the built-in 246 function sparseTexelsResidentARB(), which returns false if the lookup 247 function read one or more uncommitted texels and true otherwise. For the 248 purposes of this query, texels addressed by a filter normally computing a 249 weighted average of multiple texels (e.g., LINEAR) will be considered to 250 access only those texels with non-zero weights. 251 252 253 Modify Section 8.20.2 of ARB_sparse_texture (Controlling Sparse Texture 254 Commitment) 255 256 (modify the fifth paragraph of the section from ARB_sparse_texture, 257 starting with "For levels of a sparse texture where..." to guarantee that 258 any level greater than or equal to the page size in all dimensions can be 259 sparsely populated) 260 261 For levels of a sparse texture where each dimension is greater than or 262 equal to of the virtual page size, the residency of individual page-size 263 regions is controlled by TexPageCommitmentARB and such levels may be 264 partially populated. When the mipmap chain reaches a level that is not 265 greater than or equal to the virtual page size in any dimension, padding 266 and memory layout considerations may make it impossible to treat that 267 level and subsequent smaller ones as partially populated. ... 268 269 270Modifications to the OpenGL Shading Language Specification, Version 4.50 271 272 Including the following line in a shader can be used to control the 273 language features described in this extension: 274 275 #extension GL_ARB_sparse_texture2 : <behavior> 276 277 where <behavior> is as specified in section 3.3. 278 279 New preprocessor #defines are added to the OpenGL Shading Language: 280 281 #define GL_ARB_sparse_texture2 1 282 283 Modify Section 8.9.2, Texel Lookup Functions, p. 162 284 285 (This extension adds one new variant of texture lookup functions. The 286 "sparse" functions are like normal texture lookup functions, except that 287 they return a sparse texture residency status to the caller and return the 288 actual filtered texel value in an "out" parameter. 289 290 For each set of texture functions, we provide one to three new variants 291 based on whether sparse functionality is desired. This new variant copies 292 the existing functions, adds suffixes to the function names, and adds one or 293 more new parameters. 294 295 We create a new variant only for the targets for which sparse storage is 296 supported -- no new functions are added for the following sampler types: 297 gsampler1D, sampler1DShadow, gsampler1DArray, sampler1DArrayShadow. 298 Additionally, to reduce the number of new functions added, we are not 299 including any new variants for textureProj*() built-ins. To use the new 300 features with projective texture lookups, shaders can divide through by q 301 and use non-projective variants.) 302 303 (insert new lookup function table cells, at the end of the section, 304 p. 168) 305 306 Syntax: 307 308 int sparseTextureARB(gsampler2D sampler, vec2 P, 309 out gvec4 texel [, float bias]); 310 int sparseTextureARB(gsampler3D sampler, vec3 P, 311 out gvec4 texel [, float bias]); 312 int sparseTextureARB(gsamplerCube sampler, vec3 P, 313 out gvec4 texel [, float bias]); 314 int sparseTextureARB(sampler2DShadow sampler, vec3 P, 315 out float texel [, float bias]); 316 int sparseTextureARB(samplerCubeShadow sampler, vec4 P, 317 out float texel [, float bias]); 318 int sparseTextureARB(gsampler2DArray sampler, vec3 P, 319 out gvec4 texel [, float bias]); 320 int sparseTextureARB(gsamplerCubeArray sampler, vec4 P, 321 out gvec4 texel [, float bias]); 322 int sparseTextureARB(sampler2DArrayShadow sampler, vec4 P, 323 out float texel); 324 int sparseTextureARB(gsampler2DRect sampler, vec2 P, 325 out gvec4 texel); 326 int sparseTextureARB(sampler2DRectShadow sampler, vec3 P, 327 out float texel); 328 int sparseTextureARB(samplerCubeArrayShadow sampler, vec4 P, 329 float compare, out float texel); 330 331 Description: 332 333 Do a filtered texture lookup as in texture(), but return texture access 334 residency information from the function and the filtered lookup result in 335 the out parameter <texel>. 336 337 -- 338 339 340 Syntax: 341 342 int sparseTextureLodARB(gsampler2D sampler, vec2 P, float lod, 343 out gvec4 texel); 344 int sparseTextureLodARB(gsampler3D sampler, vec3 P, float lod, 345 out gvec4 texel); 346 int sparseTextureLodARB(gsamplerCube sampler, vec3 P, float lod, 347 out gvec4 texel); 348 int sparseTextureLodARB(sampler2DShadow sampler, vec3 P, float lod, 349 out float texel); 350 int sparseTextureLodARB(gsampler2DArray sampler, vec3 P, float lod, 351 out gvec4 texel); 352 int sparseTextureLodARB(gsamplerCubeArray sampler, vec4 P, float lod, 353 out gvec4 texel); 354 355 Description: 356 357 Do a filtered texture lookup as in textureLod(), but return texture access 358 residency information from the function and the filtered lookup result in 359 the out parameter <texel>. 360 361 -- 362 363 Syntax: 364 365 int sparseTextureOffsetARB(gsampler2D sampler, vec2 P, 366 ivec2 offset, out gvec4 texel 367 [, float bias]); 368 int sparseTextureOffsetARB(gsampler3D sampler, vec3 P, 369 ivec3 offset, out gvec4 texel 370 [, float bias]); 371 int sparseTextureOffsetARB(gsampler2DRect sampler, vec2 P, 372 ivec2 offset, out gvec4 texel); 373 int sparseTextureOffsetARB(sampler2DRectShadow sampler, vec3 P, 374 ivec2 offset, out float texel); 375 int sparseTextureOffsetARB(sampler2DShadow sampler, vec3 P, 376 ivec2 offset, out float texel 377 [, float bias]); 378 int sparseTextureOffsetARB(gsampler2DArray sampler, vec3 P, 379 ivec2 offset, out gvec4 texel 380 [, float bias]); 381 int sparseTextureOffsetARB(sampler2DArrayShadow sampler, vec4 P, 382 ivec2 offset, out float texel); 383 384 Description: 385 386 Do a filtered texture lookup as in textureOffset(), but return texture 387 access residency information from the function and the filtered lookup 388 result in the out parameter <texel>. 389 390 -- 391 392 Syntax: 393 394 int sparseTexelFetchARB(gsampler2D sampler, ivec2 P, int lod, 395 out gvec4 texel); 396 int sparseTexelFetchARB(gsampler3D sampler, ivec3 P, int lod, 397 out gvec4 texel); 398 int sparseTexelFetchARB(gsampler2DRect sampler, ivec2 P, 399 out gvec4 texel); 400 int sparseTexelFetchARB(gsampler2DArray sampler, ivec3 P, int lod, 401 out gvec4 texel); 402 int sparseTexelFetchARB(gsampler2DMS sampler, ivec2 P, int sample, 403 out gvec4 texel); 404 int sparseTexelFetchARB(gsampler2DMSArray sampler, ivec3 P, int sample, 405 out gvec4 texel); 406 407 Description: 408 409 Do a single texel fetch as in texelFetch(), but return texture access 410 residency information from the function and the fetched texel in the out 411 parameter <texel>. 412 413 -- 414 415 Syntax: 416 417 int sparseTexelFetchOffsetARB(gsampler2D sampler, ivec2 P, int lod, 418 ivec2 offset, out gvec4 texel); 419 int sparseTexelFetchOffsetARB(gsampler3D sampler, ivec3 P, int lod, 420 ivec3 offset, out gvec4 texel); 421 int sparseTexelFetchOffsetARB(gsampler2DRect sampler, ivec2 P, 422 ivec2 offset, out gvec4 texel); 423 int sparseTexelFetchOffsetARB(gsampler2DArray sampler, ivec3 P, int lod, 424 ivec2 offset, out gvec4 texel); 425 426 Description: 427 428 Do a single texel fetch as in texelFetchOffset(), but return texture 429 access residency information from the function and the fetched texel in 430 the out parameter <texel>. 431 432 -- 433 434 Syntax: 435 436 int sparseTextureLodOffsetARB(gsampler2D sampler, vec2 P, 437 float lod, ivec2 offset, 438 out gvec4 texel); 439 int sparseTextureLodOffsetARB(gsampler3D sampler, vec3 P, 440 float lod, ivec3 offset, 441 out gvec4 texel); 442 int sparseTextureLodOffsetARB(sampler2DShadow sampler, vec3 P, 443 float lod, ivec2 offset, 444 out float texel); 445 int sparseTextureLodOffsetARB(gsampler2DArray sampler, vec3 P, 446 float lod, ivec2 offset, 447 out gvec4 texel); 448 449 Description: 450 451 Do a filtered texture lookup as in textureLodOffset(), but return texture 452 access residency information from the function and the filtered lookup 453 result in the out parameter <texel>. 454 455 -- 456 457 Syntax: 458 459 int sparseTextureGradARB(gsampler2D sampler, vec2 P, 460 vec2 dPdx, vec2 dPdy, 461 out gvec4 texel); 462 int sparseTextureGradARB(gsampler3D sampler, vec3 P, 463 vec3 dPdx, vec3 dPdy, 464 out gvec4 texel); 465 int sparseTextureGradARB(gsamplerCube sampler, vec3 P, 466 vec3 dPdx, vec3 dPdy, 467 out gvec4 texel); 468 int sparseTextureGradARB(gsampler2DRect sampler, vec2 P, 469 vec2 dPdx, vec2 dPdy, 470 out gvec4 texel); 471 int sparseTextureGradARB(sampler2DRectShadow sampler, vec3 P, 472 vec2 dPdx, vec2 dPdy, 473 out float texel); 474 int sparseTextureGradARB(sampler2DShadow sampler, vec3 P, 475 vec2 dPdx, vec2 dPdy, 476 out float texel); 477 int sparseTextureGradARB(samplerCubeShadow sampler, vec4 P, 478 vec3 dPdx, vec3 dPdy, 479 out float texel); 480 int sparseTextureGradARB(gsampler2DArray sampler, vec3 P, 481 vec2 dPdx, vec2 dPdy, 482 out gvec4 texel); 483 int sparseTextureGradARB(sampler2DArrayShadow sampler, vec4 P, 484 vec2 dPdx, vec2 dPdy, 485 out float texel); 486 int sparseTextureGradARB(gsamplerCubeArray sampler, vec4 P, 487 vec3 dPdx, vec3 dPdy, 488 out gvec4 texel); 489 490 Description: 491 492 Do a filtered texture lookup as in textureGrad(), but return texture 493 access residency information from the function and the filtered lookup 494 result in the out parameter <texel>. 495 496 -- 497 498 Syntax: 499 500 int sparseTextureGradOffsetARB(gsampler2D sampler, vec2 P, 501 vec2 dPdx, vec2 dPdy, ivec2 offset, 502 out gvec4 texel); 503 int sparseTextureGradOffsetARB(gsampler3D sampler, vec3 P, 504 vec3 dPdx, vec3 dPdy, ivec3 offset, 505 out gvec4 texel); 506 int sparseTextureGradOffsetARB(gsampler2DRect sampler, vec2 P, 507 vec2 dPdx, vec2 dPdy, ivec2 offset, 508 out gvec4 texel); 509 int sparseTextureGradOffsetARB(sampler2DRectShadow sampler, vec3 P, 510 vec2 dPdx, vec2 dPdy, ivec2 offset, 511 out float texel); 512 int sparseTextureGradOffsetARB(sampler2DShadow sampler, vec3 P, 513 vec2 dPdx, vec2 dPdy, ivec2 offset, 514 out float texel); 515 int sparseTextureGradOffsetARB(gsampler2DArray sampler, vec3 P, 516 vec2 dPdx, vec2 dPdy, ivec2 offset, 517 out gvec4 texel); 518 int sparseTextureGradOffsetARB(sampler2DArrayShadow sampler, vec4 P, 519 vec2 dPdx, vec2 dPdy, ivec2 offset, 520 out float texel); 521 522 Description: 523 524 Do a filtered texture lookup as in textureGradOffset(), but return texture 525 access residency information from the function and the filtered lookup 526 result in the out parameter <texel>. 527 528 529 530 Modify Section 8.9.3, Texel Gather Functions, p. 161 531 532 (insert new lookup function table cells, at the end of the section, 533 p. 163) 534 535 Syntax: 536 537 int sparseTextureGatherARB(gsampler2D sampler, vec2 P, 538 out gvec4 texel [, int comp]); 539 int sparseTextureGatherARB(gsampler2DArray sampler, vec3 P, 540 out gvec4 texel [, int comp]); 541 int sparseTextureGatherARB(gsamplerCube sampler, vec3 P, 542 out gvec4 texel [, int comp]); 543 int sparseTextureGatherARB(gsamplerCubeArray sampler, vec4 P, 544 out gvec4 texel [, int comp]); 545 int sparseTextureGatherARB(gsampler2DRect sampler, vec2 P, 546 out gvec4 texel [, int comp]); 547 int sparseTextureGatherARB(gsampler2DShadow sampler, vec2 P, 548 float refZ, out vec4 texel); 549 int sparseTextureGatherARB(gsampler2DArrayShadow sampler, vec3 P, 550 float refZ, out vec4 texel); 551 int sparseTextureGatherARB(gsamplerCubeShadow sampler, vec3 P, 552 float refZ, out vec4 texel); 553 int sparseTextureGatherARB(gsamplerCubeArrayShadow sampler, vec4 P, 554 float refZ, out vec4 texel); 555 int sparseTextureGatherARB(gsampler2DRectShadow sampler, vec2 P, 556 float refZ, out vec4 texel); 557 558 Description: 559 560 Do a texture gather operation as in textureGather(), but return texture 561 access residency information from the function and the filtered lookup 562 result in the out parameter <texel>. 563 564 -- 565 566 Syntax: 567 568 int sparseTextureGatherOffsetARB(gsampler2D sampler, vec2 P, 569 ivec2 offset, out gvec4 texel 570 [, int comp]); 571 int sparseTextureGatherOffsetARB(gsampler2DArray sampler, vec3 P, 572 ivec2 offset, out gvec4 texel 573 [, int comp]); 574 int sparseTextureGatherOffsetARB(gsampler2DRect sampler, vec2 P, 575 ivec2 offset, out gvec4 texel 576 [, int comp]); 577 int sparseTextureGatherOffsetARB(gsampler2DShadow sampler, vec2 P, 578 float refZ, ivec2 offset, 579 out vec4 texel); 580 int sparseTextureGatherOffsetARB(gsampler2DArrayShadow sampler, vec3 P, 581 float refZ, ivec2 offset, 582 out vec4 texel); 583 int sparseTextureGatherOffsetARB(gsampler2DRectShadow sampler, vec2 P, 584 float refZ, ivec2 offset, 585 out vec4 texel); 586 587 Description: 588 589 Do a texture gather operation as in textureGatherOffset(), but return 590 texture access residency information from the function and the filtered 591 lookup result in the out parameter <texel>. 592 593 -- 594 595 Syntax: 596 597 int sparseTextureGatherOffsetsARB(gsampler2D sampler, vec2 P, 598 ivec2 offsets[4], out gvec4 texel 599 [, int comp]); 600 int sparseTextureGatherOffsetsARB(gsampler2DArray sampler, vec3 P, 601 ivec2 offsets[4], out gvec4 texel 602 [, int comp]); 603 int sparseTextureGatherOffsetsARB(gsampler2DRect sampler, vec2 P, 604 ivec2 offsets[4], out gvec4 texel 605 [, int comp]); 606 int sparseTextureGatherOffsetsARB(gsampler2DShadow sampler, vec2 P, 607 float refZ, ivec2 offsets[4], 608 out vec4 texel); 609 int sparseTextureGatherOffsetsARB(gsampler2DArrayShadow sampler, vec3 P, 610 float refZ, ivec2 offsets[4], 611 out vec4 texel); 612 int sparseTextureGatherOffsetsARB(gsampler2DRectShadow sampler, vec2 P, 613 float refZ, ivec2 offsets[4], 614 out vec4 texel); 615 616 Description: 617 618 Do a texture gather operation as in textureGatherOffset(), but return 619 texture access residency information from the function and the filtered 620 lookup result in the out parameter <texel>. 621 622 623 Add to the end of Section 8.12, Image Functions, p. 167 624 625 (insert new lookup function table cells, at the end of the section, 626 p. 170) 627 628 Syntax: 629 630 int sparseImageLoadARB(gimage2D image, ivec2 P, 631 out gvec4 texel); 632 int sparseImageLoadARB(gimage3D image, ivec3 P, 633 out gvec4 texel); 634 int sparseImageLoadARB(gimage2DRect image, ivec2 P, 635 out gvec4 texel); 636 int sparseImageLoadARB(gimageCube image, ivec3 P, 637 out gvec4 texel); 638 int sparseImageLoadARB(gimage2DArray image, ivec3 P, 639 out gvec4 texel); 640 int sparseImageLoadARB(gimageCubeArray image, ivec3 P, 641 out gvec4 texel); 642 int sparseImageLoadARB(gimage2DMS image, ivec2 P, int sample, 643 out gvec4 texel); 644 int sparseImageLoadARB(gimage2DMSArray image, ivec3 P, int sample, 645 out gvec4 texel); 646 647 Description: 648 649 Loads a texel from the image <image> as in imageLoad(), but return texture 650 access residency information from the function and the filtered lookup 651 result in the out parameter <texel>. 652 653 654 Add to the end of Section 8.17, Shader Memory Control Functions, p. 178 655 656 Many of the built-in texture lookup functions in sections 8.9.2 and 8.9.3 657 and the sparseImageLoad() function in section 8.12 can be used to return 658 sparse texture residency information in addition to texel values. In 659 these functions, the sparse texture residency information is returned by 660 the function as an integer and the texel values are returned in the output 661 parameter <texel>. The residency information can be interpreted by a 662 built-in function to determine if the lookup accessed any uncommitted 663 texels. 664 665 Syntax: 666 667 bool sparseTexelsResidentARB(int code); 668 669 Description: 670 671 Returns false if any of the texels accessed by the sparse texture lookup 672 generating <code> were in uncommitted texture memory, and true 673 otherwise. 674 675 676Additions to the AGL/GLX/WGL Specifications 677 678 None. 679 680Errors 681 682 None. 683 684New State 685 686 None. 687 688New Implementation Dependent State 689 690 None. 691 692Dependencies on EXT_depth_bounds_test 693 694 If EXT_depth_bounds_test is not supported, references to the depth bounds 695 test should be removed. 696 697Dependencies on NV_gpu_program4 and NV_gpu_program5 698 699 Modify Section 2.X.2, Program Grammar 700 701 <opModifier> ::= "SPARSE" 702 703 <ccMaskRule> ::= "RESIDENT" 704 | "NONRESIDENT" 705 706 Modify Section 2.X.3.7, Program Condition Code Registers 707 708 (modify the first paragraph) 709 710 There are two general-purpose four-component condition code registers (CC0 711 and CC1), where each component of this register is a collection of 712 single-bit flags, including a sign flag (SF), a zero flag (ZF), an 713 overflow flag (OF), and a carry flag (CF). The values of these registers 714 are undefined at the beginning of program execution. Additionally, there 715 is a special single-component sparse memory condition code register that 716 holds the status of the most recently executed texture or image load 717 instruction using the "SPARSE" opcode modifier. This condition code 718 includes a resident flag (RESF) indicating whether all memory accessed by 719 the instruction was populated. 720 721 Modify Section 2.X.4.1, Program Instruction Modifiers 722 723 (Update the discussion of instruction precision modifiers. If 724 GL_NV_gpu_program_fp64 is not found in the extension string, the "F64" 725 instruction modifier described below is not supported.) 726 727 (add to Table X.14 of the NV_gpu_program4 specification.) 728 729 Modifier Description 730 -------- ------------------------------------------------------ 731 SPARSE Update the sparse memory condition code with status on 732 whether the memory accessed by a texture or image load 733 instruction was fully populated. 734 735 For texture fetch, surface load, and surface atomic instructions, the 736 "SPARSE" modifier specifies that the sparse memory condition code 737 described in Section 2.X.3.7 should be updated to reflect whether the 738 memory accessed by the instruction was fully populated. 739 740 Modify Section 2.X.4.3, Program Destination Variable Update 741 742 (add to Table X.16, Condition Code Tests) 743 744 mask rule test name condition 745 --------------- ---------------------- ----------------- 746 RESIDENT sparse resident RESF 747 NONRESIDENT sparse nonresident !RESF 748 749 (also modify the table description) 750 751 Table X.16, Condition Code Tests. The allowed rules are specified in 752 the "mask rule" column. For "RESIDENT" or "NONRESIDENT", all four 753 components of the test result are loaded from the RESF flag of the 754 sparse condition code. Otherwise, If "0" or "1" is appended ... 755 756 (modify the paragraph about condition code updates) 757 758 A program instruction can also optionally update one of the two general 759 condition code registers ... 760 761 (add a new paragraph about updating CCSPARSE) 762 763 Additionally, a program instruction accessing memory can optionally update 764 the sparse memory condition code register if the "SPARSE" instruction 765 modifier is specified. If the memory accessed by the instruction was 766 fully populated, the resident flag (RESF) is set; otherwise, RESF is 767 cleared. 768 769Issues 770 771 (1) How does this extension compare to the ARB_sparse_texture extension? 772 773 RESOLVED: We extend the mechanisms provided by ARB_sparse_texture in 774 several ways: 775 776 - We add built-in texture and image lookup functions returning 777 information on memory accesses performed by the built-in functions; 778 in particular, whether any uncommitted memory was referenced. 779 780 - We specify that all loads and atomics from uncommitted sparse memory 781 behave as though zero were fetched. 782 783 - We remove the requirement that the base size of a sparse texture 784 must be a multiple of the page size. Implementations are expected 785 to pad mipmap allocations internally to page size boundaries as 786 required, until the tail is reached. 787 788 - We modify the definition of the sparse texture mipmap tail, so that 789 all levels greater than or equal to the page size in all dimensions 790 are guaranteed to be sparsely populated (i.e., not in the tail). 791 The previous spec allowed implementations to put levels in the tail 792 if they were not integer multiples of the page size. 793 794 - We add support for an implementation-independent virtual page size 795 for some formats, instead of depending on querying 796 implementation-dependent page size. For such formats, the default 797 virtual page size index (0) is guaranteed to specify the standard 798 page size. 799 800 - We require that all implementations of this extension return TRUE 801 for the value of the implementation-dependent constant 802 SPARSE_TEXTURE_FULL_ARRAY_CUBE_MIPMAPS_ARB, which removes some 803 potential errors when allocating sparse array or cube map textures. 804 805 - We add support for sparse multisample and multisample array 806 textures, but require no implementation-independent virtual page 807 size. 808 809 (2) How does this extension compare to the AMD_sparse_texture extension? 810 811 RESOLVED: This extension, like the AMD extension, provide built-in 812 texture lookup functions returning information on whether uncommitted 813 memory was accessed. There are several differences between these 814 functions: 815 816 - This extension uses an "ARB" suffix on built-in function names. 817 818 - This extension supports sparse accesses for shadow map sampler types 819 (e.g., sampler2DShadow). 820 821 - This extension supports sparse variants of imageLoad(); the AMD 822 extension does not. 823 824 - This extension doesn't attempt to support sparse variants of 825 projective texture lookups to reduce the number of texture functions 826 added. 827 828 - This extension doesn't attempt to support sparse variants of 829 one-dimensional and one-dimensional array texture lookups. Sparse 830 textures with these targets are explicitly not supported in the ARB 831 extension. 832 833 - This extension returns the texel data in an "out" parameter and 834 returns a value consistent with sampling zero in any uncommitted 835 texels. The AMD extension returns the texel data in an "inout" 836 parameter and guarantees not to write to the return value if any 837 uncommitted texel is accessed. 838 839 - The function sparseTexelResident() from the AMD extension is renamed 840 to sparseTexelsResidentARB(). We use "texels" instead of "texel" in 841 the function name because a texture lookup may access multiple 842 texels, and the code will reflect non-resident status if any of the 843 texels is non-resident. 844 845 The built-in functions returning zero on reads from uncommitted memory, 846 and the standard virtual page size are not provided by the AMD extension, 847 either. 848 849 Neither this extension nor ARB_sparse_texture provide the minimum LOD 850 warning feature provided by the AMD extension or the related built-in 851 functions. 852 853 (3) How should the "sparse" built-in functions return both access status 854 and a texel value? 855 856 RESOLVED: We mostly followed the precedent of the AMD extension, where 857 the sparse access status is returned as an integer and the texel values 858 are returning in a vec4-typed "out" parameter. (This differs slightly 859 from the AMD extension in that it uses an "inout" parameter.) 860 861 We considered included returning the texel values from the function, 862 just like normal texture lookups, and returning status in a separate 863 "out" parameter (reversing the order). We also considered returning a 864 structure type containing both the status and the texel. We ultimately 865 chose to return the status code to more closely match the AMD extension 866 and because we expect that shaders caring to use the "sparse" functions 867 will want to look at the status code first. 868 869 (4) What data type should we use for the access status information 870 returned by the "sparse" built-in functions? 871 872 RESOLVED: We chose to follow the precedent of the AMD extension, where 873 an integer code is returned. Requiring a separate function call 874 (sparseTexelsResidentARB) is required to reason about the code returned 875 is mildly annoying, but we didn't consider it serious enough to warrant 876 a change. 877 878 We could have used a "bool" type instead, but chose to stick with "int" 879 for compatibility and for possible future expansion. The AMD extension 880 also includes built-in functions sparseTexelMinLodWarning() and 881 sparseTexelWarningFetch() that can be used to check the return code for 882 other conditions not supported by this extension. Shaders that only 883 care about residency information can still check the status in a single 884 (long) line: 885 886 if (!sparseTexelsResidentARB(sparseTextureARB(sampler, coords, 887 texel)) 888 { 889 // do something about the failure 890 } 891 892 (5) When using a "sparse" built-in texture function, what RGBA values are 893 generated when the lookup accesses one or more uncommited texels? 894 895 RESOLVED: We return a filtered result vector where memory for 896 uncommitted texels is treated as being filled with zeroes. The data 897 vector returned by the "sparse" functions for this case should exactly 898 match the vector returned by an equivalent non-"sparse" function. 899 900 (6) For "sparse" built-in texture functions, where should the <texel> 901 return value go relative to other parameters? 902 903 RESOLVED: We chose to follow the precedent of the AMD extension, 904 putting it in (approximately) the last parameter. Note that the 905 optional <bias> parameter of texture() breaks this pattern; we chose to 906 keep the optional bias at the end. 907 908 Other options considered included: always first (before the sampler), 909 always second (after the sampler), always third (after the sampler and 910 the base coordinates). For "always third", note there are a couple 911 cases like shadow lookups in cube arrays where the coordinates are split 912 across multiple parameters and "always third" would be awkward. 913 Additional options are discussed in issue (3). 914 915 (7) Should we provide sparse variants of the "2DMS" and "2DMSArray" 916 variants of texelFetch() and imageLoad() in this extension? 917 918 RESOLVED: Yes. ARB_sparse_texture doesn't support multisample 919 textures. In this extension, we lift this restriction, allow them to be 920 accessed using normal built-ins, and provide new functions allowing 921 shaders to determine if uncommitted memory was accessed. 922 923 (8) How does the feedback provided in the "sparse" built-in texture 924 functions interact with texture filtering modes involving multiple 925 texels? 926 927 RESOLVED: The sparse texture lookup status will indicate that 928 uncommitted memory was accessed if any texel read during the filtering 929 operation was uncommitted, but will do so only if the filter weight is 930 non-zero. When applying a texture filter such as LINEAR_MIPMAP_LINEAR, 931 it's possible that the interpolated texture coordinate lines up exactly 932 at the center of a texel and/or exactly at an integer level of detail. 933 According to the standard filtering equations, eight samples are taken 934 -- four in each of two levels. However, it's possible that only one of 935 the eight samples has a non-zero weight (if the coordinates hit a texel 936 center and the LOD is an integer). 937 938 This "non-zero weight" feature may be important for getting proper 939 feedback in some cases, such as displaying a texture tile with an 940 aligned 1:1 mapping of pixels to texels or forcing a specific level of 941 detail in some cases. Note that when attempting to apply a 1:1 mapping 942 of pixels to texels via an interpolated texture attribute, it's possible 943 that small floating-point errors might produce very small but non-zero 944 weights for neighboring texels. If avoiding such errors is important 945 and a 1:1 mapping is required, a single-sample filter like NEAREST 946 should be used. 947 948 (9) Should we support sparse texel fetches and image loads for buffer 949 textures? 950 951 RESOLVED: Not in this extension. This should be handled by a separate 952 extension allowing for the creation and use of sparse buffer resources. 953 Such an extension might also provide the ability to get "sparse" 954 information when non-texture mechanisms are used to access memory (e.g., 955 ARB_shader_storage_buffer_object, NV_shader_buffer_load). 956 957 (10) Should we support "sparse" variants of the image atomic functions 958 that return information on residency as well as the value normally 959 returned by the atomic operation? 960 961 RESOLVED: Not in this extension; it's not clear that there's an 962 important use case for this. If required, a shader can use imageLoad() 963 to probe the residency of a given texel and ignore the data values 964 returned. 965 966 (11) This extension is adding a *large* number of new built-in functions. 967 What can we do to control this? 968 969 RESOLVED: We chose not to add any "sparse" variants of 970 projective texture lookups (e.g., textureProj). If required, you can 971 divide through by the "q" texture coordinate and use an equivalent 972 non-projective lookup. 973 974 We considered the possibility of more significant GLSL syntax changes to 975 reduce the cross-product of different features. For example, the AMD 976 extension has a function: 977 978 int sparseTextureProjGradOffset(...); 979 980 that combines four separate "optional" features (sparse, projection, 981 explicitly specified gradients, and texel offsets) and is supported for 982 six separate texture targets. One might consider an approach like: 983 984 #define TEX_IS_PROJECTIVE 0x1 985 #define TEX_HAS_GRADIENTS 0x2 986 #define TEX_HAS_TEXEL_OFFSET 0x4 987 #define TEX_WANTS_SPARSE_STATUS 0x8 988 struct TexLookup3D { 989 uint flags; /* in */ 990 float q; /* in */ 991 vec3 ddx, ddy; /* in */ 992 ivec3 texelOffset; /* in */ 993 int sparseStatus; /* out */ 994 }; 995 ... 996 TexLookup3D lookup; 997 lookup.flags = (TEX_IS_PROJECTIVE | TEX_HAS_GRADIENTS | 998 TEX_HAS_TEXEL_OFFSET | TEX_WANTS_SPARSE_STATUS); 999 lookup.q = coords.w; 1000 lookup.ddx = ddx; 1001 lookup.ddy = ddy; 1002 lookup.texelOffset = ivec3(-1,+1,+2); 1003 texture(sampler, lookup); 1004 1005 to handle all possible cases in one interface. Alternately, a 1006 "prettier" C++-style approach with methods on sampler classes could be 1007 used. 1008 1009 Given that either such feature might involve a large change to the 1010 shading language, it seems more appropriate to address this issue in a 1011 future core version of a shading language rather than an extension. 1012 1013 (12) How does the "reads produce zero" behave if a sparse texture is bound 1014 to a framebuffer and used for the depth or stencil test? 1015 1016 RESOLVED: The depth and stencil tests act as though zero were read from 1017 the framebuffer. The actual results of the tests depend on the depth 1018 and stencil functions, the incoming depth value, and the stencil 1019 reference value. 1020 1021 There may be cases where it might be advantageous to configure the depth 1022 or stencil tests to fail when touching an unpopulated portion of the 1023 depth/stencil buffer. The "return zero" behavior may work well for some 1024 cases (e.g., returning zero when using a depth test of LESS will cause 1025 the test to almost always fail), but not as well for others (e.g., depth 1026 test of GREATER). We've chosen not to address this case in the current 1027 extension. 1028 1029 (13) How does the "reads produce zero" behave for textures that don't have 1030 all four components? 1031 1032 RESOLVED: Components that are present in the texture will return zero; 1033 others will return default values. For example, an access to an 1034 uncommitted sparse texture whose with a format has no alpha component 1035 (e.g, RGB8) will return 1.0 on the alpha channel of the returned RGBA 1036 vector. The handling of "missing" components is the same as for 1037 non-sparse textures. 1038 1039 (14) Should we provide standard sparse texture page sizes that 1040 applications can rely on without having to query the set of supported 1041 page sizes for each format it uses? If so, how will this be handled? 1042 Will we have some formats that have standard sizes and others that 1043 don't? 1044 1045 RESOLVED: Yes; we will provide standard page sizes for some, but not 1046 all, formats. However, we will still allow for implementation- 1047 dependent page sizes (as in ARB_sparse_textures) for formats that have a 1048 standard page size and allow implementations to support sparse textures 1049 on formats for which a standard page size is not available. The basic 1050 page sizes we use arrange sparse textures into 64KB pages and attempt to 1051 keep the X and Y dimensions of the page roughly equal. 1052 1053 (15) Should we add specific compressed formats to the required formats list 1054 and provide standard page sizes? 1055 1056 RESOLVED: Not in this extension. Note that the current 1057 ARB_sparse_texture extension already allows implementations to support 1058 compressed formats. 1059 1060 We've chosen not to go to the trouble of enumerating standard page sizes 1061 for all the compressed formats (many of which are added by extension), 1062 but one logical approach would be to treat each 64- or 128-bit block in 1063 common formats as a single logical texel and treat the standard page 1064 sizes of 64- and 128-bit texels as being in units of compression blocks. 1065 1066 (16) How do applications get to use the standard page size? 1067 1068 RESOLVED: Applications opt in to using standard page sizes by leaving 1069 VIRTUAL_PAGE_SIZE_INDEX_ARB at its initial value (zero). 1070 1071 In ARB_sparse_texture, there were no standard page sizes. Applications 1072 can use GetInternalformativ() with <pname> of NUM_VIRTUAL_PAGE_SIZES_ARB 1073 to query the implementation-dependent number of page sizes supported for 1074 any given format. Some formats may be unsupported, and the GL will 1075 return a page size count of zero. Other formats may have a page size 1076 count of one, or more than one if the implementation supports multiple 1077 page sizes. An application can query the properties of each page size 1078 index by calling GetInternalFormativ() with <pname> set to 1079 VIRTUAL_PAGE_SIZE_{X,Y,Z}_ARB. When an application determines the page 1080 size it wants to use from the options returned by the GL, it sets the 1081 VIRTUAL_PAGE_SIZE_INDEX_ARB texture parameter prior to calling 1082 TexStorage* to allocate storage for the sparse texture. 1083 1084 If an application doesn't bother setting the VIRTUAL_PAGE_SIZE_INDEX_ARB 1085 texture parameter, the default index of zero will be used and the page 1086 size will be whatever the implementation chooses for its first page size 1087 index. In the absence of this extension, the application still needs to 1088 call GetInternalFormativ() to determine the page size being used so it 1089 can manage texture residency. But in the presence of this extension, page 1090 size index 0 will be a standard size and will be the same on all 1091 implementations supporting the extension. 1092 1093 (17) Should we support sparse multisample textures? If so, should we 1094 support standard virtual page sizes? 1095 1096 RESOLVED: Yes, we add will support for sparse multisample textures, but 1097 will not specify standard page sizes. 1098 1099 Different implementations of this extension may represent multisample 1100 textures in different ways. Some implementations might interleave 1101 samples in memory, while others might have separate "planes" in memory 1102 for each individual sample. If we were to support a standard page size, 1103 the easiest approach might be to have a greatest-common-multiple 1104 standard page size. For example, the standard page size for 1105 single-sample textures with 32-bit texels is 128x128 (64KB total). We 1106 could choose to use the same page size for multisample textures. For 4x 1107 multisample, a page of 128x128 pixels would have an effective page size 1108 of 256KB. If an implementation interleaves samples, each virtual page 1109 might be assembled from four consecutive 64K physical pages. If an 1110 implementation has separate "planes", the virtual page might be 1111 assembled from four 64K physical pages spread out in memory. 1112 1113 (18) Should we require support for sparse depth or stencil textures? 1114 Sparse support for these formats is optional in ARB_sparse_texture. 1115 If so, should we support standard virtual page sizes? 1116 1117 RESOLVED: Not in this extension. 1118 1119 The current ARB_sparse_texture extension already allows implementations 1120 to support sparse depth/stencil formats, so the only things a change 1121 could accomplish is (a) provide standard page sizes that can be used 1122 without querying implementation page sizes, (b) ensure that apps can 1123 rely on *some* support by just checking the extension without querying 1124 the number of supported page sizes via GetInternalFormat. 1125 1126 We expect that different implementations may store depth and stencil 1127 textures in different ways and might have different "natural" page 1128 sizes. We could deal with this by using a greatest-common-multiple 1129 standard page size (i.e., have a standard page size larger than 64K), 1130 but it's not clear if that will fly. 1131 1132 The advantages of (b) seem low relative to (a), so we aren't proposing 1133 to add depth and stencil formats to the required list for this 1134 extension. 1135 1136 (19) Should we make a separate extension for the LOD clamp GLSL functions? 1137 1138 RESOLVED: Yes. See ARB_sparse_texture_clamp. 1139 1140 (20) Should we reconsider re-examining some of the non-orthogonalities in 1141 the current set of texture built-ins, which are being extended for 1142 sparse. For example, the texture() built-in for a sampler type of 1143 samplerCubeArrayShadow does not include an optional LOD bias despite 1144 the fact that cubemap arrays do support multiple LODs. 1145 1146 RESOLVED: Not in this extension. 1147 1148 We chose to create "sparse" variants of existing built-ins without 1149 re-examining current capabilities. It might make sense to have an 1150 extension or future core shading language re-examine things and improve 1151 orthogonality if implementations can support it. 1152 1153Revision History 1154 1155 Revision 1 1156 - Branched from EXT_sparse_texture2 1157 1158 Revision 2 1159 - Split clamp functions into ARB_sparse_texture_clamp 1160 1161 Revision 3 1162 - Remove pre-defined page sizes for 3D textures 1163