1Name 2 3 NV_bindless_texture 4 5Name Strings 6 7 GL_NV_bindless_texture 8 9Contact 10 11 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 12 Pat Brown, NVIDIA Coproration (pbrown 'at' nvidia.com) 13 14Contributors 15 16 Daniel Koch, NVIDIA 17 18Status 19 20 Shipping 21 22Version 23 24 Last Modified Date: June 13, 2014 25 Author Revision: 3 26 27Number 28 29 OpenGL Extension #418 30 OpenGL ES Extension #197 31 32Dependencies 33 34 This extension is written against the OpenGL 4.0 (Compatibility Profile) 35 and OpenGL Shading Language 4.00 Specifications. 36 37 OpenGL 4.0 or later is required for an OpenGL implementation. 38 39 The GLSL portion of this extension requires NV_gpu_shader5, or a similar 40 extension providing 64-bit integer support in the shading language. 41 42 This extension interacts with OpenGL 4.0 (Core Profile). 43 44 This extension interacts with OpenGL 3.3 and ARB_sampler_objects. 45 46 This extension interacts with OpenGL 4.2, ARB_shader_image_load_store, and 47 EXT_shader_image_load_store. 48 49 This extension interacts with NV_vertex_attrib_integer_64bit. 50 51 This extension interacts with NV_gpu_shader5. 52 53 This extension interacts with EXT_direct_state_access. 54 55 This extension interacts with ARB_seamless_cube_map and 56 AMD_seamless_cubemap_per_texture. 57 58 This extension interacts with NV_gpu_program4, NV_gpu_program5, and 59 EXT_shader_image_load_store. 60 61 This extension interacts with GLSL 4.20. 62 63 OpenGL ES 3.0 or later is required for an OpenGL ES implementation. 64 65 This extension interacts with OpenGL ES 3.1. 66 67 This extension interacts with OES_shader_image_atomic. 68 69 This extension interacts with EXT_texture_cube_map_array. 70 71 This extension interacts with EXT_texture_buffer. 72 73 This extension interacts with EXT_shader_io_blocks. 74 75Overview 76 77 This extension allows OpenGL applications to access texture objects in 78 shaders without first binding each texture to one of a limited number of 79 texture image units. Using this extension, an application can query a 80 64-bit unsigned integer texture handle for each texture that it wants to 81 access and then use that handle directly in GLSL or assembly-based 82 shaders. The ability to access textures without having to bind and/or 83 re-bind them is similar to the capability provided by the 84 NV_shader_buffer_load extension that allows shaders to access buffer 85 objects without binding them. In both cases, these extensions 86 significantly reduce the amount of API and internal GL driver overhead 87 needed to manage resource bindings. 88 89 This extension also provides similar capability for the image load, store, 90 and atomic functionality provided by OpenGL 4.2, OpenGL ES 3.1 and the 91 ARB_shader_image_load_store and EXT_shader_image_load_store extensions, 92 where a texture can be accessed without first binding it to an image unit. 93 An image handle can be extracted from a texture object using an API with a 94 set of parameters similar to those for BindImageTextureEXT. 95 96 This extension adds no new data types to GLSL. Instead, it uses existing 97 sampler and image data types and allows them to be populated with texture 98 and image handles. This extension does permit sampler and image data 99 types to be used in more contexts than in unextended GLSL 4.00. In 100 particular, sampler and image types may be used as shader inputs/outputs, 101 temporary variables, and uniform block members, and may be assigned to by 102 shader code. Constructors are provided to convert 64-bit unsigned integer 103 values to and from sampler and image data types. Additionally, new APIs 104 are provided to load values for sampler and image uniforms with 64-bit 105 handle inputs. The use of existing integer-based Uniform* APIs is still 106 permitted, in which case the integer specified will identify a texture 107 image or image unit. For samplers and images with values specified as 108 texture image or image units, the GL implemenation will translate the unit 109 number to an internal handle as required. 110 111 To access texture or image resources using handles, the handles must first 112 be made resident. Accessing a texture or image by handle without first 113 making it resident can result in undefined results, including program 114 termination. Since the amount of texture memory required by an 115 application may exceed the amount of memory available to the system, this 116 extension provides API calls allowing applications to manage overall 117 texture memory consumption by making a texture resident and non-resident 118 as required. 119 120 121New Procedures and Functions 122 123 uint64 GetTextureHandleNV(uint texture); 124 uint64 GetTextureSamplerHandleNV(uint texture, uint sampler); 125 126 void MakeTextureHandleResidentNV(uint64 handle); 127 void MakeTextureHandleNonResidentNV(uint64 handle); 128 129 uint64 GetImageHandleNV(uint texture, int level, boolean layered, 130 int layer, enum format); 131 132 void MakeImageHandleResidentNV(uint64 handle, enum access); 133 void MakeImageHandleNonResidentNV(uint64 handle); 134 135 void UniformHandleui64NV(int location, uint64 value); 136 void UniformHandleui64vNV(int location, sizei count, const uint64 *value); 137 void ProgramUniformHandleui64NV(uint program, int location, 138 uint64 value); 139 void ProgramUniformHandleui64vNV(uint program, int location, 140 sizei count, const uint64 *values); 141 142 boolean IsTextureHandleResidentNV(uint64 handle); 143 boolean IsImageHandleResidentNV(uint64 handle); 144 145 146New Tokens 147 148 None. 149 150 151Additions to Chapter 2 of the OpenGL 4.0 (Compatibility Profile) Specification 152(OpenGL Operation) 153 154 Modify Section 2.7, Vertex Specification, p. 30 155 156 Replace the paragraph from NV_vertex_attrib_integer_64bit describing the 157 behavior of VertexAttribL*: 158 159 These commands specify one, two, three or four values. Note that attribute 160 variables declared with "double" types must be loaded with 161 VertexAttribL*d{v}EXT; loading attributes with VertexAttrib*d{v} will 162 produce undefined results. Similarly, attributes declared with 64-bit 163 integer types, sampler types, or image types must be loaded with 164 VertexAttribL*{i64,ui64}{v}. 165 166 ... 167 168 The full set of VertexAttrib* commands specify generic attributes with 169 components one of eight data types: 170 171 * floating-point values (VertexAttrib*), 172 * signed or unsigned integers (VertexAttribI*), 173 * double-precision floating-point values (VertexAttribL*d*), and 174 * 64-bit signed or unsigned integers, images, or samplers 175 (VertexAttribL*{i64,ui64}*). 176 177 178 Modify Section 2.14.3, Vertex Attributes, p. 94 179 180 Edit Table X.1 of NV_vertex_attrib_integer_64bit (Scalar and vector 181 vertex attribute types and VertexAttrib* commands used to set the values 182 of the corresponding generic attribute.). Change the line describing 183 VertexAttribL1ui64NV to allow it for sampler and image types. 184 185 Data type Command 186 ------------------------------- ---------------------------------- 187 uint64_t VertexAttribL1ui64NV 188 sampler* isampler* usampler* 189 image* iimage* uimage* 190 191 Modify Section 2.14.4, Uniform Variables, p. 97 192 193 (Modify second paragraph, p. 98) ... uniform components, respectively. A 194 scalar or vector uniform with double-precision or 64-bit integer 195 components will consume no more than 2n components, where n is 1 for 196 scalars, and the component count for vectors. A sampler or image uniform 197 will consume no more than two components. A link error is generated... 198 199 200 (Edit Table 2.15, "OpenGL Shading Language type tokens returned by 201 GetActiveUniform and GetActiveUniformsiv...", pp. 104-106. In particular, 202 add dots to the "Attrib" and "Xfb" columns for all SAMPLER and IMAGE 203 types.) 204 205 206 (Edit the subsection "Loading Uniform Variables In The Default Uniform 207 Block", p. 108) 208 209 (Add the following commands to the list of uniform functions on p. 108.) 210 211 void UniformHandleui64NV(int location, uint64 value); 212 void UniformHandleui64vNV(int location, sizei count, 213 const uint64 *value); 214 void ProgramUniformHandleui64NV(uint program, int location, 215 uint64 value); 216 void ProgramUniformHandleui64vNV(uint program, int location, 217 sizei count, const uint64 *values); 218 219 (Delete the sentence: "Only the Uniform1i{v} commands can be used to load 220 sampler values (see below)." from p. 108.) 221 222 (Insert a new paragarph after the second paragraph, p. 109) 223 224 The UniformHandleui64{v}NV commands will load <count> 64-bit unsigned 225 integer handles into a uniform location corresponding to sampler or image 226 variable types. Only the UniformHandleui64{v}NV and Uniform1i{v} commands 227 can be used to load sampler and image values as described in Section 228 2.14.6 (Samplers). 229 230 231 Edit Subsection "Uniform Buffer Object Storage", p. 110: 232 233 (Add rules for sampler and image types to the list at the beginning of 234 p. 111.) 235 236 * Members of sampler types are extracted from a buffer object by 237 reading a single uint64-typed value at the specified offset. 238 239 * Members of image types are extracted from a buffer object by reading 240 a single uint64-typed value at the specified offset. 241 242 243 Modify Section 2.14.6, Samplers, p. 117 244 245 (Replace the section with the following, adding the ability to use 246 samplers in new places as well as describing the behavior of the new 247 UniformHandleui64{v}NV APIs.) 248 249 Samplers are special data types used by the OpenGL Shading Language to 250 identify the texture object used for each texture lookup. Sampler 251 variables may be used as shader inputs and outputs, uniforms in the 252 default block or in user-defined blocks, or as temporaries. 253 254 When used as uniforms in the default block, the value of sampler 255 variables may be specified with either Uniform1i{v} or 256 UniformHandleui64{v}NV. If a sampler uniform value is specified by 257 Uniform1i{v}, the value passed to Uniform1i{v} indicates a texture image 258 unit that will be accessed, and the value must be in the range from zero 259 to the implementation-dependent maximum supported number of texture image 260 units. The error INVALID_VALUE is generated if a Uniform1i{v} call is 261 used to set a sampler uniform to a value less than zero or greater than or 262 equal to the value of MAX_TEXTURE_IMAGE_UNITS. If a sampler uniform value 263 is specified by UniformHandleui64{v}NV, the value passed to 264 UniformHandleui64NV{v} directly specifies a texture object by handle, as 265 defined in Section 3.9.X (Bindless Textures). When a program is linked, 266 all sampler uniforms are initialized to zero and considered to be 267 references to texture image units. When used as shader inputs, outputs, 268 uniform block members, or temporaries, the value of the sampler is a 64- 269 bit unsigned integer handle and never refers to a texture image unit. 270 271 When the value of a sampler indicates a texture image unit, the type of 272 the sampler identifies the target on the texture image unit. The texture 273 object bound to that texture image unit's target is used for any texture 274 accesses using that sampler. For example, a variable of type sampler2D 275 selects the target TEXTURE_2D on its texture image unit. Binding of 276 texture objects to targets is done as usual with BindTexture. Selecting 277 the texture image unit to bind to is done as usual with ActiveTexture. 278 279 When the value of a sampler indicates a texture handle, the target of the 280 texture referred to by the handle must match the type of the sampler. For 281 example, a variable of type sampler2D must be used in conjunction with a 282 handle of a texture of target TEXTURE_2D. If the value of a sampler 283 variable is not a valid texture handle or is not resident (section 3.9.X), 284 the results of using that sampler during shader execution are undefined 285 and may lead to program termination. If the value of a sampler variable 286 is a valid handle of a texture with a target different from the variable 287 type, the results of using that handle are undefined but may not include 288 program termination. 289 290 It is not allowed to have uniform variables of different sampler types 291 pointing to the same texture image unit within a program object. This 292 situation can only be detected at the next rendering command issued, and 293 an INVALID_OPERATION error will then be generated. Sampler uniforms 294 specified using handles do not count as using any texture image unit, even 295 if a texture referred to by a handle is currently bound to one or more 296 texture image units. 297 298 Active samplers are those samplers actually being used in a program 299 object. When a program is linked by LinkProgram, the GL determines 300 whether each sampler is active or not. There is no limit on the number of 301 active sampler variables that may be used by a program or by any 302 particular shader. However, restrictions on the use of texture image 303 units imposes an effective limit on the number of non-handle sampler 304 uniforms. Active samplers used as shader inputs, shader outputs, or 305 uniforms in the default uniform block are counted toward 306 implementation-dependent limits on the total number of input, output, or 307 uniform components supported by the program. Each active sampler variable 308 may count as two components against such limits. 309 310 311 Modify Section 2.14.X, Images, from EXT_shader_image_load_store 312 313 (Replace the section with the following, adding the ability to use images 314 in new places as well as describing the behavior of the new 315 UniformHandleui64{v}NV APIs.) 316 317 Images are special data types used in the OpenGL Shading Language to 318 identify a level of a texture to be read or written using image load, 319 store, and atomic built-in functions in the manner described in Section 320 3.9.X of the EXT_shader_image_load_store specification. Image variables 321 may be used as shader inputs and outputs, uniforms in the default block or 322 in user-defined blocks, or as temporaries. 323 324 When used as uniforms in the default block, the value of image variables 325 may be specified with either Uniform1i{v} or UniformHandleui64{v}NV. If 326 an image uniform value is specified by Uniform1i{v}, the value passed to 327 Uniform1i{v} indicates an image unit that will be accessed, and the value 328 must be in the range from zero to the implementation-dependent maximum 329 supported number of image units. The error INVALID_VALUE is generated if 330 a Uniform1i{v} call is used to set an image uniform to a value less than 331 zero or greater than or equal to the value of MAX_IMAGE_UNITS_EXT. Note 332 that image units used for image variables are independent from the texture 333 image units used for sampler variables; the number of units provided by the 334 implementation may differ. Textures are bound independently and 335 separately to image and texture image units. If an image uniform value is 336 specified by UniformHandleui64{v}NV, the value provided directly specifies 337 a texture object by handle, as defined in Section 3.9.X (Bindless 338 Textures). When a program is linked, all image uniforms are initialized 339 to zero and considered to be references to image units. When used as 340 shader inputs, outputs, uniform block members, or temporaries, the value 341 of an image variable is a 64-bit unsigned integer handle and never refers 342 to an image unit. 343 344 The type of an image variable must match the texture target of the image 345 currently bound to the image unit or referenced by the image handle. 346 Otherwise, the results of load, store, or atomic operations using the 347 image variable are undefined (see Section 4.1.X of the OpenGL Shading 348 Language specification edits in EXT_shader_image_load_store for more 349 detail) but may not include program termination. Additionally, if the 350 value of an image variable is not a valid image handle or is not resident 351 (section 3.9.X), the results of using that image variable during shader 352 execution are undefined and may lead to program termination. 353 354 Active image variables are those variables actually being used in a 355 program object. When a program is linked by LinkProgram, the GL 356 determines whether each image variable is active or not. There is no 357 limit on the number of active image variables that may be used by a 358 program or by any particular shader. However, the limited number of image 359 units imposes an effective limit on the number of unique non-handle image 360 variables. Active image variables used as shader inputs, shader outputs, 361 or uniforms in the default uniform block are counted toward 362 implementation-dependent limits on the total number of input, output, or 363 uniform components supported by the program. Each active image variable 364 may count as two components against such limits. 365 366 367 Modify Section 2.14.7, Varying Variables, p. 118 368 369 (modify first paragraph, p. 119) ... Each component of variables declared 370 as double-precision floating-point scalars, vectors, or matrices, as 371 64-bit integer scalars or vectors, or as samplers or images may be counted 372 as consuming two components. 373 374 (replace second paragraph, p. 121) For the purposes of counting the total 375 number of components to capture, each component of outputs declared as 376 double-precision floating-point scalars, vectors, or matrices, as 64-bit 377 integer scalars or vectors, or as samplers or images may be counted as 378 consuming two components. 379 380 381 Modify Section 2.14.8, Shader Execution, p. 122 382 383 (modify second paragraph, p. 126) ... against the 384 MAX_COMBINED_TEXTURE_IMAGE_UNITS limit. Samplers accessed using texture 385 handles (section 3.9.X) are not counted against this limit. 386 387 (modify last paragraph of "Texture Access", p. 127) Using a sampler in a 388 shader will return (R,G,B,A) = (0,0,0,1) if the sampler's associated 389 texture is not complete, as defined in section 3.9.14. Textures referred 390 to by valid texture handles (section 3.9.X) will always be complete. 391 392 393Additions to Chapter 3 of the OpenGL 4.0 Specification (Rasterization) 394 395 Insert new section after Section 3.9.2, Sampler Objects, p. 257 396 397 Section 3.9.X, Bindless Textures 398 399 The previous sections describe mechanisms to make texture and sampler 400 objects available to shaders or fixed-function fragment processing by 401 binding the objects to texture image units. Additionally, texture objects 402 may be accessed by shader using texture handles, which are 64-bit unsigned 403 integers identifying the state of a texture and/or sampler object. The 404 handle zero is reserved and will never be assigned to a valid texture 405 handle. To obtain a texture handle, use the commands: 406 407 uint64 GetTextureHandleNV(uint texture); 408 uint64 GetTextureSamplerHandleNV(uint texture, uint sampler); 409 410 GetTextureHandleNV will create a texture handle using the current state of 411 the texture named <texture>, including any embedded sampler state. 412 GetTextureSamplerHandleNV will create a texture handle using the current 413 non-sampler state from the texture named <texture> and the sampler state 414 from the sampler object <sampler>. In both cases, a 64-bit unsigned 415 integer handle is returned. The error INVALID_VALUE is generated if 416 <texture> is zero or is not the name of an existing texture object or if 417 <sampler> is zero or is not the name of an existing sampler object. The 418 error INVALID_OPERATION is generated if the texture object <texture> is 419 not complete (section 3.9.14). If an error occurs, a handle of zero is 420 returned. 421 422 The handle for each texture or texture/sampler pair is unique; the same 423 handle will be returned if GetTextureHandleNV is called multiple times for 424 the same texture or if GetTextureSamplerHandleNV is called multple times 425 for the same texture/sampler pair. 426 427 When a texture object is referenced by one or more texture handles, the 428 texture parameters of the object (Section 3.9.8) may not be changed, and 429 the size and format of the images in the texture object (Section 3.9.3) 430 may not be re-specified. The error INVALID_OPERATION is generated if the 431 functions TexImage*, CopyTexImage*, CompressedTexImage*, TexBuffer*, or 432 TexParameter* are called to modify a texture object referenced by one or 433 more texture handles. The contents of the images in a texture object may 434 still be updated via commands such as TexSubImage*, CopyTexSubImage*, and 435 CompressedTexSubImage*, and by rendering to a framebuffer object, even if 436 the texture object is referenced by one or more texture handles. 437 438 The error INVALID_OPERATION is generated by BufferData if it is called to 439 modify a buffer object bound to a buffer texture while that texture object 440 is referenced by one or more texture handles. The contents of the buffer 441 object may still be updated via buffer update commands such as 442 BufferSubData and MapBuffer*, or via the texture update commands, even if 443 the buffer is bound to a texture while that buffer texture object is 444 referenced by one or more texture handles. 445 446 When a sampler object is referenced by one or more texture handles, the 447 sampler parameters of the object may not be changed. The error 448 INVALID_OPERATION is generated when calling SamplerParameter* functions to 449 modify a sampler object referenced by one or more texture handles. 450 451 To make a texture handle accessible to shaders for texture mapping 452 operations, a texture handle must first be made resident by calling: 453 454 void MakeTextureHandleResidentNV(uint64 handle); 455 456 While the texture handle is resident, it may be used in texture mapping 457 operations. If a shader attempts to perform a texture mapping operation 458 using a handle that is not resident, the results of that operation are 459 undefined and may lead to application termination. When a texture handle 460 is resident, the texture it references is also considered resident for the 461 purposes of the AreTexturesResident command. The error INVALID_OPERATION 462 is generated if <handle> is not a valid texture handle, or if <handle> is 463 already resident in the current GL context. 464 465 A texture handle may be made inaccessible to shaders by calling: 466 467 void MakeTextureHandleNonResidentNV(uint64 handle); 468 469 The error INVALID_OPERATION is generated if <handle> is not a valid 470 texture handle, or if <handle> is not resident in the current GL context. 471 472 473 Modify Section 3.9.10, Cube Map Texture Selection, p. 291 474 475 (insert new paragraph before last paragraph of section, p. 293) 476 477 When accessing cube map textures using texture handles, the seamless cube 478 map enable is ignored and treated as disabled. 479 480 481 Modify Section 3.9.11, Texture Minification, p. 293 482 483 [[Compatibility profile-only]] 484 (modify last paragraph, p. 293) ... <bias_texunit> is zero for textures 485 referred to by handle, and is otherwise the value of TEXTURE_LOD_BIAS for 486 the current texture unit (as described in section 3.9.16). ... 487 488 489 Add to Section 3.9.X (Texture Image Loads and Stores) of 490 EXT_shader_image_load_store: 491 492 While texture levels may be made available to shaders by binding them to 493 image units using BindImageTextureEXT, they may also be accessed using 494 image handles. Image handles are 64-bit integers that identify a level of 495 a texture object, layer information for array and cube map textures, and 496 an associated image format. The handle zero is reserved and will never be 497 assigned to a valid image handle. The command 498 499 uint64 GetImageHandleNV(uint texture, int level, boolean layered, 500 int layer, enum format); 501 502 creates and returns an image handle for level <level> of the texture 503 named <texture>. If <layered> is TRUE, a handle is created for the 504 entire texture level. If <layered> is FALSE, a handle is created for 505 only the layer <layer> of the texture level. <format> specifies a 506 format used to interpret the texels of the image when used for image 507 loads, stores, and atomics, and has the same meaning as the <format> 508 parameter of BindImageTextureEXT(). A 64-bit unsigned integer handle 509 is returned if the command succeeds; otherwise, zero is returned. 510 511 The error INVALID_VALUE is generated by GetImageHandleNV if: 512 513 * <texture> is zero or not the name of an existing texture object; 514 515 * the image for the texture level <level> doesn't exist (i.e., has a 516 size of zero in <texture>); or 517 518 * <layered> is FALSE and <layer> is greater than or equal to 519 the number of layers in the image at level <level>. 520 521 The error INVALID_OPERATION is generated by GetImageHandleNV if: 522 523 * the texture object <texture> is not complete (section 3.9.14); 524 525 * <layered> is TRUE and the texture is not a three-dimensional, 526 one-dimensional array, two dimensional array, cube map, or cube map 527 array texture. 528 529 When a texture object is referenced by one or more image handles, the 530 texture parameters of the object (Section 3.9.8) may not be changed, and 531 the size and format of the images in the texture object (Section 3.9.3) 532 may not be re-specified. The error INVALID_OPERATION is generated when 533 calling TexImage*, CopyTexImage*, CompressedTexImage*, TexBuffer*, or 534 TexParameter* functions while a texture object is referenced by one or 535 more image handles. The contents of the images in a texture object may 536 still be updated via commands such as TexSubImage*, CopyTexSubImage*, and 537 CompressedTexSubImage*, and by rendering to a framebuffer object, even if 538 the texture object is referenced by one or more image handles. 539 540 The error INVALID_OPERATION is generated by BufferData if it is called to 541 modify a buffer object bound to a buffer texture while that texture object 542 is referenced by one or more image handles. The contents of the buffer 543 object may still be updated via buffer update commands such as 544 BufferSubData and MapBuffer*, or via the texture update commands, even if 545 the buffer is bound to a texture while that buffer texture object is 546 referenced by one or more image handles. 547 548 The handle returned for each combination of <texture>, <level>, <layered>, 549 <layer>, and <format> is unique; the same handle will be returned if 550 GetImageHandleNV is called multiple times with the same parameters. 551 552 To make an image handle accessible to shaders for image loads, stores, and 553 atomic operations, the handle must be made resident by calling: 554 555 void MakeImageHandleResidentNV(uint64 handle, enum access); 556 557 <access> specifies whether the texture bound to the image handle will be 558 treated as READ_ONLY, WRITE_ONLY, or READ_WRITE. If a shader reads from 559 an image handle made resident as WRITE_ONLY, or writes to an image handle 560 made resident as READ_ONLY, the results of that shader operation are 561 undefined and may lead to application termination. The error 562 INVALID_OPERATION is generated if <handle> is not a valid image handle, or 563 if <handle> is already resident in the current GL context. 564 565 While the image handle is resident, it may be used in image load, store, 566 and atomic operations. If a shader attempts to perform an image operation 567 using a handle that is not resident, the results of that operation are 568 undefined and may lead to application termination. When an image handle 569 is resident, the texture it references is not necessarily considered 570 resident for the purposes of the AreTexturesResident command. 571 572 An image handle may be made inaccessible to shaders by calling: 573 574 void MakeImageHandleNonResidentNV(uint64 handle); 575 576 The error INVALID_OPERATION is generated if <handle> is not a valid image 577 handle, or if <handle> is not resident in the current GL context. 578 579 580 Modify Section 3.12.2, Shader Execution, p. 323 581 582 (replace second-to-last paragraph of "Texture Access", p. 324) Using a 583 sampler in a shader will return (R,G,B,A) = (0,0,0,1) if the sampler's 584 associated texture is not complete, as defined in section 3.9.14. 585 Textures referred to by valid texture handles will always be complete. 586 587 588Additions to Chapter 5 of the OpenGL 4.0 Specification (Special Functions) 589 590 Modify Section 5.5.1, Commands Not Usable In Display Lists, p. 413 591 592 (add a new category to the list on pp. 413-414) 593 594 Handle residency management: MakeTextureHandleResidentNV, 595 MakeTextureHandleNonResidentNV, MakeImageHandleResidentNV, 596 MakeImageHandleNonResidentNV. 597 598 (note: GetTextureHandleNV, GetTextureSamplerHandleNV, GetImageHandleNV, 599 IsTextureHandleResidentNV, and IsImageHandleResidentNV are also 600 non-listable, but are covered by the blanket rules for Get* and Is* 601 commands in "Other queries") 602 603 604Additions to Chapter 6 of the OpenGL 4.0 Specification (Queries) 605 606 Modify Section 6.1.4, Texture Queries, p. 427 607 608 (add to the end of the section) The commands: 609 610 boolean IsTextureHandleResidentNV(uint64 handle); 611 boolean IsImageHandleResidentNV(uint64 handle); 612 613 return TRUE if the specified texture or image handle is resident in the 614 current context. The error INVALID_OPERATION will be generated by 615 IsTextureHandleResidentNV or IsImageHandleResidentNV if <handle> is not 616 a valid texture or image handle, respectively. In the case of an error, 617 FALSE is returned. 618 619 620Additions to Appendix D of the OpenGL 4.0 Specification (Shared Objects and 621Multiple Contexts) 622 623 Modify Section D.1.2, Deleted Object and Object Name Lifetimes 624 625 (modify first paragraph, p. 534) ... A buffer, texture, sampler, or 626 renderbuffer object is in use while it is attached to any container object 627 or bound to a context bind point in any context. A texture or sampler 628 object is also in use if any texture or image handle referencing the 629 object is resident for any context. Texture and image handles are not 630 deleted until either the underlying texture or sampler object used to 631 create the handle are deleted. A sync object ... 632 633 Modify/replace Section D.X of NV_shader_buffer_load 634 635 Object Use by GPU Address or Handle 636 637 The GPU address of a buffer object is valid in all contexts in the share 638 group that the buffer belongs to. Similarly, texture and image handles 639 extracted from texture and/or sampler objects are also valid in all 640 contexts in the share group. Buffers, texture handles, and image handles 641 must be made resident separately in each context referencing them by GPU 642 address or handle to allow the GL to determine which resources may be used 643 in each command stream. If a GPU address or handle is used by a given 644 context where the buffer or handle has not been made resident in that 645 context, undefined results including program termination may occur. Such 646 undefined results may occur even if the buffer or handle in question has 647 been made resident for other contexts belonging to the context's share 648 group. 649 650 651Modifications to The OpenGL Shading Language Specification, Version 4.00 652 653 Including the following line in a shader can be used to control the 654 language features described in this extension: 655 656 #extension GL_NV_bindless_texture : <behavior> 657 658 where <behavior> is as specified in section 3.3. 659 660 New preprocessor #defines are added to the OpenGL Shading Language: 661 662 #define GL_NV_bindless_texture 1 663 664 665 Replace Section 4.1.7 (Samplers), p. 25 666 667 Sampler types (e.g., sampler2D) are effectively opaque handles to texture 668 and sampler objects. They are used with the built-in texture functions 669 (described in section 8.9 "Texture Lookup Functions") to specify which 670 texture to access and how it is to be filtered. Samplers are represented 671 using 64-bit integer handles, and may be converted to and from 64-bit 672 integers using constructors. Samplers may not be implicitly converted to 673 and from 64-bit integers, and may not be used in arithmetic expressions. 674 Samplers may be declared as shader inputs and outputs, as uniform 675 variables, as temporary variables, and as function parameters. Samplers 676 aggregated into arrays within a shader (using square brackets []) can be 677 indexed with arbitrary integer expressions. Samplers can be used as 678 l-values, so can be assigned into and used as "out" and "inout" function 679 parameters. As function parameters, samplers may be only passed to 680 samplers of matching type. As uniforms in the default uniform block, 681 samplers may be initialized only with the OpenGL API; they cannot be 682 declared with an initializer in a shader. 683 684 The OpenGL API allows default block sampler uniforms to be assigned values 685 referencing either a texture image unit number or a texture handle, 686 depending on the API function used. All other sampler variables must be 687 assigned a texture handle. When a sampler uniform is assigned to a 688 texture image unit, texture functions using it will reference the texture 689 bound to the corresponding target of the selected texture image unit. 690 When a texture function uses a sampler variable assigned to a texture 691 handle, the value of the handle must be a valid handle returned by the 692 OpenGL API (Section 3.9.X, Bindless Textures) that has been made resident, 693 and that texture must have a target matching the sampler variable type. 694 Using a sampler whose the texture target does not match that sampler type 695 produces undefined results but not program termination. Using a sampler 696 that is not a texture image unit reference and is not a valid and resident 697 texture handle produces undefined results including possible program 698 termination. 699 700 701 Replace Section 4.1.X, (Images) 702 703 Like samplers, images are effectively handles to one-, two-, or three- 704 dimensional images corresponding to all or a portion of a single level of 705 a texture image. Images are represented using 64-bit integer handles, and 706 may be converted to and from 64-bit integers using constructors. Samplers 707 may not be implicitly converted to and from 64-bit integers, and may not 708 be used in arithmetic expressions. There are distinct image variable 709 types for each texture target, and for each of float, integer, and 710 unsigned integer data types. Image accesses should use an image type that 711 matches the target of the texture whose level is being accessed, or for 712 non-layered bindings of 3D or array images should use the image type that 713 matches the dimensionality of the layer of the image (i.e. a layer of 3D, 714 2DArray, Cube, or CubeArray should use image2D, a layer of 1DArray should 715 use image1D, and a layer of 2DMSArray should use image2DMS). If the image 716 target type does not match the image being accessed in this manner, if the 717 data type does not match the bound image, or if the "size" layout 718 qualifier does not match the image format as described in Section 3.9.X of 719 the OpenGL Specification, the results of image accesses are undefined but 720 may not include program termination. 721 722 Image variables are used in the image load, store, and atomic functions 723 described in Section 8.X, "Image Functions" to specify an image to access. 724 Images may be declared as shader inputs and outputs, as uniform variables, 725 as temporary variables, and as function parameters. Images may be 726 aggregated into arrays within a shader (using square brackets []) and can 727 be indexed with general integer expressions. Images can be used as 728 l-values, so can be assigned into and used as "out" and "inout" function 729 parameters. As uniforms in the default uniform block, images may be 730 initialized only with the OpenGL API; they cannot be declared with an 731 initializer in a shader. As function parameters, images may be only 732 passed to images of matching type. 733 734 The OpenGL API allows default block image uniforms to be assigned to 735 reference either an image unit number or an image handle, depending on the 736 API function used. All other image variables must be assigned an image 737 handle. When an image uniform is assigned to an image unit, image 738 functions using it will reference the texture and image state 739 corresponding to the selected image unit. When an image function uses a 740 variable assigned to an image handle, the value of the handle must be a 741 valid handle returned by the OpenGL API (Section 3.9.X of 742 EXT_shader_image_load_store, Texture Image Loads and Stores, as modified 743 by this extension) that has been made resident, and that contains image 744 data compatible with the variable type as described above. Using an image 745 variable that is not an image unit reference and is not a valid and 746 resident image handle produces undefined results including possible 747 program termination. 748 749 750 Modify Section 4.3.4, Inputs, p. 34 751 752 (modify third paragraph of the section to allow sampler and image types) 753 ... Vertex shader inputs can only be float, single-precision 754 floating-point scalars, single-precision floating-point vectors, matrices, 755 signed and unsigned integers and integer vectors, sampler and image types. 756 757 (modify last paragraph, p. 35, allowing samplers and images as fragment 758 shader inputs) ... Fragment inputs can only be signed and unsigned 759 integers and integer vectors, floating point scalars, floating-point 760 vectors, matrices, sampler and image types, or arrays or structures of 761 these. Fragment shader inputs that are signed or unsigned integers, 762 integer vectors, or any double-precision floating- point type, or any 763 sampler or image type must be qualified with the interpolation qualifier 764 "flat". 765 766 767 Modify Section 4.3.6, Outputs, p. 36 768 769 (modify second paragraph, p. 37, to allow sampler and image outputs) 770 ... Output variables can only be floating-point scalars, floating-point 771 vectors, matrices, signed or unsigned integers or integer vectors, sampler 772 or image types, or arrays or structures of any these. 773 774 (do not modify the last paragraph, p. 38; samplers and images are not 775 allowed as fragment shader outputs) 776 777 778 Modify Section 4.3.7, Interface Blocks, p. 38 779 780 (remove the following bullet from the last list on p. 39, thereby 781 permitting sampler types in interface blocks; image types are also 782 permitted in blocks by this extension) 783 784 * sampler types are not allowed 785 786 787 Modify Section 5.4.1, Conversion and Scalar Constructors, p. 60 788 789 (add the following constructors:) 790 791 uint64_t(any sampler type) // Converts a sampler type to a 792 // 64-bit unsigned integer 793 any sampler type(uint64_t) // Converts a 64-bit unsigned integer to 794 // a sampler type 795 uint64_t(any image type) // Converts an image type to a 796 // 64-bit unsigned integer 797 any image type(uint64_t) // Converts a 64-bit unsigned integer to 798 // an image type 799 800 801Additions to the AGL/EGL/GLX/WGL Specifications 802 803 None 804 805Interactions with OpenGL 4.0 (Core Profile) 806 807 If the core profile of OpenGL 4.0 (or any version since 3.0) is supported, 808 references to fixed-function fragment processing and display lists should 809 be removed. References to the TEXTURE_LOD_BIAS for the current texture 810 unit should also be removed. 811 812Interactions with OpenGL 3.3 and ARB_sampler_objects 813 814 If neither OpenGL 3.3 nor ARB_sampler_objects is supported, the portion of 815 this extension referring to the sampler object type introduced in OpenGL 816 3.3 should be removed. In particular, the GetTextureSamplerHandleNV API 817 will not be supported. 818 819Interactions with OpenGL 4.2, OpenGL ES 3.1, ARB_shader_image_load_store, and 820EXT_shader_image_load_store 821 822 If OpenGL 4.2, OpenGL ES 3.1, ARB_shader_image_load_store, and 823 EXT_shader_image_load_store are not supported, the portion of this 824 extension supporting image handles and image loads, stores, and atomics 825 should be removed. In particular, the functions GetImageHandleNV, 826 MakeImageHandleResidentNV, MakeImageHandleNonResidentNV should be removed. 827 828 Portions of this extension have been written against the 829 EXT_shader_image_load_store, since OpenGL 4.2 and the ARB extension did 830 not exist when the specification was first written. Similar edits would 831 apply to the OpenGL 4.2 and ARB_shader_image_load_store specifications. 832 833Interactions with NV_vertex_attrib_integer_64bit 834 835 If NV_vertex_attrib_integer_64bit is not supported, sampler and image 836 variables (which take 64-bit integer handles) are not allowed to be used 837 as vertex shader inputs. Additionally, portions of this extension 838 modifying NV_vertex_attrib_integer_64bit should be ignored. 839 840Interactions with NV_gpu_shader5 841 842 If NV_gpu_shader5 or similar functionality providing 64-bit integer types 843 in the shading language is not supported, the GLSL portion of this 844 extension should be modified. In particular, references to 64-bit integer 845 scalars, vectors or other 64-bit types should be deleted, and the 846 constructors to convert 64-bit unsigned integer handles to and from sampler 847 and image data types (as added in Section 5.4.1), should be removed. 848 849 Default block sampler and image uniforms can still be assigned handles via 850 the UniformHandleui64*NV and ProgramUniformHandleui64*NV functions, and 851 sampler and image types can continue to be used as shader inputs and 852 outputs, uniforms in user-defined blocks, and temporaries. Such uses of 853 these types may consume two components against any relevant limits. 854 Extracting these types from memory locations will be done as if reading 855 a uvec2-typed value at the specified location. 856 857 Additionally, edits to Section 4.1.7 of the GLSL Specification describing 858 sampler indexing should be changed to read "Samplers aggregated into 859 arrays within a shader (using square brackets [ ]) can only be indexed 860 with a dynamically uniform integral expression, otherwise results are 861 undefined." This is the language found in unextended OpenGL 4.0; 862 NV_gpu_shader5 extends it to allow indexing with arbitrary integer 863 expressions. 864 865Interactions with EXT_direct_state_access 866 867 In this extension, INVALID_OPERATION is generated when calling various 868 functions to modify the state of a texture object from which handles have 869 been extracted. If EXT_direct_state_access is suported, this error 870 behavior is further extended to cover similar functions provided by 871 EXT_direct_state access. In particular, this error will be generated by: 872 TextureImage*EXT, CopyTextureImage*EXT, CompressedTextureImage*EXT, 873 TextureBufferEXT, TextureParameterEXT, MultiTexImage*EXT, 874 CopyMultiTexImage*EXT, CompressedMultiTexImage*EXT, MultiTexBufferEXT, and 875 MultiTexParameter*EXT. 876 877Interactions with ARB_seamless_cubemap and AMD_seamless_cubemap_per_texture 878 879 If ARB_seamless_cubemap (or OpenGL 4.0, which includes it) is supported, 880 the per-context seamless cubemap enable is ignored and treated as disabled 881 when using texture handles. 882 883 If AMD_seamless_cubemap_per_texture is supported, the seamless cube map 884 texture parameter of the underlying texture does apply when texture 885 handles are used. 886 887Interactions with NV_gpu_program4, NV_gpu_program5, and 888EXT_shader_image_load_store 889 890 If NV_gpu_program5 is supported, the following edits are made to the 891 NV_gpu_program4, NV_gpu_program5, and EXT_shader_image_load_store 892 specifications: 893 894 Modify Section 2.X.2, Program Grammar of NV_gpu_program5 895 896 (add new grammar rules allowing textures to be referred to by handles, 897 e.g., "TEX result, coords, handle(texHandle.x), 2D") 898 899 <textureUseV> ::= "handle" "(" <addrUseS> ")" 900 901 <imageUnit> ::= "handle" "(" <addrUseS> ")" 902 903 904 Modify Section 2.X.4.4, Program Texture Access, of NV_gpu_program4 905 906 (modify the paragraph beginning with "The texture used by TextureSample" 907 to permit the use of handles) The texture used by TextureSample() is 908 identified according to the <textureUseV> grammar rule. If <textureUseV> 909 expands to the grammar rule containing "handle", the texture used is 910 identified by taking the scalar value specified in that rule as a texture 911 handle. Otherwise, the texture corresponding to the texture image unit 912 specified by <textureUseV> is used. The texture target... 913 914 If the instruction uses a named texture variable, the <nvTexImageUnit> 915 grammar rule, or the "texture" grammar rule, then the texture used by 916 TextureSample() is one of the textures bound to the texture image unit 917 whose number is specified in the instruction according to the 918 <texImageUnit> grammar rule, and the texture target accessed is specified 919 according to the <texTarget> grammar rule and Table X.17. If the 920 instruction uses the "handle" grammar rule, then the specified texture 921 handle will select which texture is used, and the target of that texture 922 must match the target specified by the <texTarget> grammar rule or else 923 the result is undefined. Fixed-function texture enables are always ignored 924 when determining which texture to access in a program. 925 926 927 Section 2.X.5.Y, Program Options 928 929 If a program (in any shader stage) specifies the option 930 "NV_bindless_texture", the grammar edits described in section 2.X.2 931 will apply. 932 933 934 Modify Section 2.X.8.Z, LOADIM: Image Load, of EXT_shader_image_load_store 935 936 (modify the first paragraph) The LOADIM instruction ... from the texture 937 specified by <imageUnit>. If <imageUnit> expands to the grammar rule 938 containing "handle", the texture used is identified by taking the scalar 939 value specified in that rule as an image handle. Otherwise, the texture 940 corresponding to the image unit specified by <imageUnit> is used. 941 Unformatted loads read... 942 943 Modify Section 2.X.8.Z, STOREIM: Image Store, of 944 EXT_shader_image_load_store 945 946 (modify the first paragraph) The STOREIM instruction ... to the texture 947 specified by <imageUnit> using the data specified in the first vector 948 operand. If <imageUnit> expands to the grammar rule containing "handle", 949 the texture used is identified by taking the scalar value specified in 950 that rule as an image handle. Otherwise, the texture corresponding to the 951 image unit specified by <imageUnit> is used. The store is performed in 952 the manner described in Section 3.9.X. 953 954 955 Modify Section 2.X.8.Z, ATOMIM: Image Atomic Memory Operation, of 956 EXT_shader_image_load_store 957 958 (modify the first paragraph) The ATOMIM instruction takes ...image load 959 from the texture specified by <imageUnit>, performs ... returns the loaded 960 value in the vector result. If <imageUnit> expands to the grammar rule 961 containing "handle", the texture used is identified by taking the scalar 962 value specified in that rule as an image handle. Otherwise, the texture 963 corresponding to the image unit specified by <imageUnit> is used. The 964 atomic operation is performed in the manner described in Section 3.9.X. 965 966Interactions with GLSL 4.20 and GLSL ES 3.10 967 968 Without GLSL 4.20 or GLSL ES 3.10 support, sampler and image uniforms 969 may only be initialized through the OpenGL API. With GLSL 4.20 and GLSL 970 ES 3.1, sampler and image uniforms may be initialized in the shader using 971 972 layout(binding = integer-constant) 973 974 as described in section 4.4.4 "Opaque-Uniform Layout Qualifiers". When 975 NV_bindless_texture is supported, these initial binding values are always 976 taken to mean a texture image or image unit number, not a bindless handle. 977 978Interactions with OpenGL ES 979 980 If implemented in an OpenGL ES context, references to the following 981 should be removed: 982 - assembly-based shaders, 983 - display lists, 984 - fixed-function fragment processing, 985 - double-precision floating-point values, 986 - 1D and 1D-array textures and images, 987 - TEXTURE_LOD_BIAS for the current texture unit, 988 - the AreTexturesResident command, 989 unless subsequently added by a later extension or version. 990 991 Modify the edits to Section to 3.9.10 to state that when accessing cube 992 map textures using texture handles in an OpenGL ES context, the cube maps 993 are always treated as seamless. 994 995Interactions with OpenGL ES 3.1 996 997 If OpenGL ES 3.1 is supported, replace references to EXT_image_load_store 998 and BindImageTextureEXT with appropriate references to OpenGL ES 3.1 999 functionality and BindImageTexture. References to assigning a default 1000 block image uniform an image unit number from the OpenGL API with the 1001 Uniform* commands (but not the UniformHandle* commands) should be 1002 removed since OpenGL ES only supports assigning image unit numbers 1003 with the 'binding' layout qualifier in the shading language. 1004 1005 Ignore references to 2DMSArray and 2DMS images as they are not supported 1006 in OpenGL ES. 1007 1008Interactions with OES_shader_image_atomic 1009 1010 If OES_shader_image_atomic or equivalent functionality is not supported, 1011 ignore all references to atomic image operations. 1012 1013Interactions with EXT_texture_cube_map_array 1014 1015 If EXT_texture_cube_map_array or equivalent functionality is not supported, 1016 ignore all references to cube map array textures. 1017 1018Interactions with EXT_texture_buffer 1019 1020 If EXT_texture_buffer or equivalent functionality is not supported, 1021 ignore all references to buffer textures and related buffer functionality. 1022 1023Interactions with EXT_shader_io_blocks 1024 1025 If EXT_shader_io_blocks or equivalent functionality is supported, sampler 1026 and image types are allowed in interface blocks. Otherwise ignore all 1027 references to interface blocks. 1028 1029Errors 1030 1031 The error INVALID_VALUE is generated by GetTextureHandleNV or 1032 GetTextureSamplerHandleNV if <texture> is zero or not the name of an 1033 existing texture object. 1034 1035 The error INVALID_VALUE is generated by GetTextureSamplerHandleNV if 1036 <sampler> is zero or is not the name of an existing sampler object. 1037 1038 The error INVALID_OPERATION is generated by GetTextureHandleNV or 1039 GetTextureSamplerHandleNV if thetexture object specified by <texture> is 1040 not complete. 1041 1042 The error INVALID_OPERATION is generated by TexImage*, CopyTexImage*, 1043 CompressedTexImage*, TexBuffer*, TexParameter*, as well as other functions 1044 defined in terms of these, if the texture object to be modified is 1045 referenced by one or more texture or image handles. 1046 1047 The error INVALID_OPERATION is generated by BufferData, or any function 1048 defined in terms of this, if the buffer object to be modified is bound 1049 to a buffer texture that is referenced by one or more texture or image 1050 handles. 1051 1052 The error INVALID_OPERATION is generated by SamplerParameter* if <sampler> 1053 identifies a sampler object referenced by one or more texture handles. 1054 1055 The error INVALID_OPERATION is generated by MakeTextureHandleResidentNV if 1056 <handle> is not a valid texture handle, or if <handle> is already resident 1057 in the current GL context. 1058 1059 The error INVALID_OPERATION is generated by MakeTextureHandleNonResidentNV 1060 if <handle> is not a valid texture handle, or if <handle> is not resident 1061 in the current GL context. 1062 1063 The error INVALID_VALUE is generated by GetImageHandleNV if <texture> is 1064 zero or not the name of an existing texture object, if the image for 1065 <level> does not existing in <texture>, or if <layered> is FALSE and 1066 <layer> is greater than or equal to the number of layers in the image at 1067 <level>. 1068 1069 The error INVALID_OPERATION is generated by GetImageHandleNV if the 1070 texture object <texture> is not complete or if <layered> is TRUE and 1071 <texture> is not a three-dimensional, one-dimensional array, two 1072 dimensional array, cube map, or cube map array texture. 1073 1074 The error INVALID_OPERATION is generated by MakeImageHandleResidentNV if 1075 <handle> is not a valid image handle, or if <handle> is already resident 1076 in the current GL context. 1077 1078 The error INVALID_OPERATION is generated by MakeImageHandleNonResidentNV 1079 if <handle> is not a valid image handle, or if <handle> is not resident in 1080 the current GL context. 1081 1082 The error INVALID_OPERATION will be generated by IsTextureHandleResidentNV 1083 and IsImageHandleResidentNV if <handle> is not a valid texture or image 1084 handle, respectively. 1085 1086Examples 1087 1088 To loop through a collection of 256 textures in the OpenGL API using a 1089 conventional GLSL shader and without calling glBindTexture, one might do: 1090 1091 #define NUM_TEXTURES 256 1092 GLuint textures[NUM_TEXTURES]; 1093 GLuint64 texHandles[NUM_TEXTURES]; 1094 1095 // Initialize the texture objects and handles. 1096 glGenTextures(NUM_TEXTURES, textures); 1097 for (int i = 0; i < NUM_TEXTURES; i++) { 1098 1099 // Initialize the texture images with glTexImage/glTexStorage. 1100 // Initialize the texture parameters as required. 1101 1102 // Get a handle for the texture. 1103 texHandles[i] = glGetTextureHandleNV(textures[i]); 1104 1105 // At this point, it's no longer possible to resize/reallocate 1106 // texture images or modify texture parameters for "textures[i]". 1107 // However, it's still possible to update texture data via 1108 // glTexSubImage. 1109 1110 // Make the handle resident before using it. 1111 glMakeTextureHandleResidentNV(texHandles[i]); 1112 } 1113 1114 // Compile GLSL shader using sampler uniform <u>. The shader itself 1115 // needs no special #extension directive as long as <u> is a uniform in 1116 // the default partition. Link the program, and query the location of 1117 // <u>, which we will store in <location>. 1118 1119 // Render a little bit using each of the texture handles in turn. 1120 for (int i = 0; i < NUM_TEXTURES; i++) { 1121 1122 // Update the single sampler uniform <u> to point at "texHandles[i]". 1123 glUniformHandleui64NV(location, texHandles[i]); 1124 1125 drawStuff(); 1126 } 1127 1128 ... 1129 1130 // If the application doesn't need to use texHandles[10] for a while, it 1131 // can make it non-resident to reduce the overall memory footprint. 1132 glMakeTextureHandleNonResidentNV(texHandles[10]); 1133 1134 // After this point, the texture data associated with texHandles[10] is 1135 // not guaranteed to be resident, and using it in a draw call could 1136 // result in exceptions. Use glMakeTextureHandleResidentNV() to make it 1137 // resident again before it's needed for rendering. 1138 1139 The GLSL portion of this extension removes the restriction that sampler 1140 variables must be uniforms in the default block. You can store a large 1141 collection of samplers in a uniform block, pass them through the pipeline 1142 as 64-bit integers. 1143 1144 To use a "dictionary" of samplers in a uniform block, you could use a 1145 shader like: 1146 1147 #version 400 1148 #extension GL_NV_bindless_texture : require 1149 #define NUM_TEXTURES 256 1150 1151 flat in int whichSampler; 1152 in vec2 texCoord; 1153 out vec4 finalColor; 1154 1155 uniform Samplers { 1156 sampler2D allTheSamplers[NUM_TEXTURES]; 1157 }; 1158 1159 void main() 1160 { 1161 finalColor = texture(allTheSamplers[whichSampler], texCoord); 1162 } 1163 1164 In the following example, the sampler to use is selected in a vertex 1165 shader, passed to the fragment shader as a (flat) input, and then used for 1166 a texture lookup. 1167 1168 #version 400 1169 #extension GL_NV_gpu_shader5 : require // for 64-bit integer types 1170 #extension GL_NV_bindless_texture : require 1171 1172 flat in sampler2D theSampler; 1173 in vec2 texCoord; 1174 out vec4 finalColor; 1175 1176 void main() 1177 { 1178 finalColor = texture(theSampler, texCoord); 1179 } 1180 1181 1182New State 1183 1184 Add new table, Bindless Texture Handles 1185 1186 Initial 1187 Get Value Type Get Command Value Description Sec. Attribute 1188 ------------ ---- -------------------- ------- ------------------------- ------ ------- 1189 - Z64 GetTextureHandleNV n/a texture handle 3.9.X - 1190 or GetTextureSampler- 1191 HandleNV 1192 - Z+ - n/a texture object used 3.9.X - 1193 - Z+ - n/a sampler object used 3.9.X - 1194 - nxB IsTextureHandle- FALSE is bindless texture handle 3.9.X - 1195 ResidentNV resident for the current 1196 context (separate state per 1197 context/handle pair) 1198 1199 Add new table, Bindless Image Handles 1200 1201 Initial 1202 Get Value Type Get Command Value Description Sec. Attribute 1203 ------------ ---- -------------------- ------- ------------------------- ------ ------- 1204 - Z64 GetImageHandleNV n/a image handle 3.9.X - 1205 - Z+ - n/a texture object used 3.9.X - 1206 - Z+ - n/a texture object level 3.9.X - 1207 - B - n/a is image handle layered? 3.9.X - 1208 - Z+ - n/a selected layer for non- 3.9.X - 1209 layered images 1210 - Z_<n> - n/a image internal format enum 3.9.X - 1211 - nxB IsImageHandle- FALSE is bindless image handle 3.9.X - 1212 ResidentNV resident for the current 1213 context (separate state 1214 per context/handle pair) 1215 1216Issues 1217 1218 (1) Could this have been specified as simply making the maximum number of 1219 texture image units and image units arbitrarily large and then 1220 indexing into an array of samplers or images? 1221 1222 RESOLVED: Perhaps, but this approach doesn't involve any arbitrarily 1223 limits. Allowing the implementation to choose the GPU handle can avoid 1224 the need for some kind of unit->address translation. It's also 1225 beneficial for the GPU handles to be static. 1226 1227 (2) Should we add commands to allow prioritizing which allocations belong 1228 in dedicated video memory? 1229 1230 RESOLVED: Defer to a future extension. 1231 1232 (3) How should we handle separate samplers? 1233 1234 RESOLVED: OpenGL 3.3 created separate sampler objects, and provided 1235 separate binding points in a texture image unit. When referencing a 1236 texture image unit with a sampler object bound, the state of that object 1237 is used; otherwise, sampler state embedded in the texture is used. In 1238 either case, each texture image unit consists of a texture/sampler pair, 1239 and no capability is provided to mix the texture from one unit with 1240 samplers from another. 1241 1242 This extension provides support for use of OpenGL 3.3-style sampler 1243 objects via the GetTextureSamplerHandleNV entry point, which can be used 1244 to create a handle for each pair of texture/sampler objects the 1245 application wishes to use. GLSL samplers can be used with texture 1246 handles in the same way that they can be used with the texture/sampler 1247 object pair associated with a texture image unit. 1248 1249 It's possible that some future extension to OpenGL might allow shaders 1250 to mix and match texture and sampler objects within a shader instead of 1251 using pre-defined pairs. Such shaders would use two different shader 1252 variable types -- one encapsulating texture object state and the other 1253 encapsulating sampler state. To allow bindless texture support in this 1254 mode, we would expect to add a new handle type (sampler handles) and to 1255 provide new APIs to extract sampler handles from sampler objects and to 1256 manage sampler handle residency. (It's not immediately clear whether it 1257 would even be necessary to manage sampler handle residency, since 1258 sampler objects only have a small number of state variables.) 1259 1260 (4) Can texture or sampler objects be modified while they are used by a 1261 texture or image handle? 1262 1263 RESOLVED: No. If such changes were permitted, each modification to the 1264 texture object would require potential synchronization with one or more 1265 texture/image handles extracted from the texture. This seems like a lot 1266 of bookkeeping with little benefit. One exception to this rule is that 1267 individual texels of such texture objects may still be updated with APIs 1268 such as TexSubImage* and by rendering to a framebuffer object to which 1269 the texture is attached. 1270 1271 (5) Is there a way to release a texture or image handle after it is 1272 created? 1273 1274 RESOLVED: No API is provided to release or delete handles once they are 1275 created. Texture and image handles are automatically reclaimed when the 1276 underlying texture or sampler objects are finally deleted. This 1277 deletion will happen only when no handle using the texture or sampler 1278 object is resident on any context. This decision is similar to that of 1279 NV_shader_buffer_load, which didn't provide any mechanism to release the 1280 address of a buffer object. 1281 1282 One consequence of this decision is that structural changes (e.g., image 1283 size and format and parameter changes) to textures from which handles 1284 are extracted are not possible for the lifetime of the texture. 1285 1286 (6) How do texture and image handles work with multiple contexts sharing a 1287 set of texture and sampler objects? 1288 1289 RESOLVED: Texture and image handles are shared by all contexts in a 1290 share group, in the same way that GPU addresses are shared in 1291 NV_shader_buffer_load. Once a handle has been extracted from a texture 1292 or texture/sampler pair in any context, that handle may be used by all 1293 other contexts in the share group. 1294 1295 However, texture and image handle residency is managed per-context. If 1296 a texture or image handle is used in multiple contexts in a share group, 1297 the handle must be made resident in all such contexts. 1298 1299 (7) What happens if you try to delete a texture or sampler object with a 1300 handle that is resident in another context? 1301 1302 RESOLVED: Deleting the texture will remove the texture from the name 1303 space and make all handles using the texture non-resident in the current 1304 context. However, texture or image handles for a deleted texture are 1305 not deleted until the underlying texture or sampler object itself is 1306 deleted. That deletion won't happen until the object is not bound 1307 anywhere and there are no handles using the object that are resident in 1308 any context. 1309 1310 (8) Can you get a handle from a default texture object (numbered zero)? 1311 1312 RESOLVED: No, for several reasons. First, the APIs to extract a 1313 texture handle only take a texture object number, with no target. Since 1314 there is a separate default texture object for each texture target, the 1315 texture object number zero does not identify a unique texture. 1316 Additionally, since the spec forbids modification of textures used with 1317 handles, extracting a handle from a default texture would leave the 1318 texture in a state where it could be neither modified nor deleted. 1319 1320 (9) Can you have multiple handles for the same texture or texture/sampler 1321 pair? 1322 1323 RESOLVED: Any texture object can have at most one handle extracted from 1324 the texture object via GetTextureHandleNV; calling that function 1325 multiple times on a single texture will always return the same handle. 1326 1327 A texture or sampler object may have multiple texture handles extracted 1328 from it via GetTextureSamplerHandleNV, since such handles correspond to 1329 a texture/sampler pair and a single texture or sampler object may be 1330 paired with multiple objects of the other type. However, calling that 1331 function multiple times on a single texture/sampler pair will always 1332 return the same handle. 1333 1334 A texture object may have multiple image handles extracted from it via 1335 GetImageHandleNV; however, each such handle must represent a different 1336 "view" of the texture. If that function is called multiple times with 1337 the same <texture>, <level>, <layered>, <layer>, and <format> 1338 parameters, the same handle will always be returned. 1339 1340 (10) Should we provide <access> parameters for MakeTextureHandleResidentNV 1341 and MakeImageHandleResidentNV? 1342 1343 RESOLVED: For MakeImageHandleResidentNV, yes. It may be useful to be 1344 able to make a given texture resident only for reading or writing. For 1345 MakeTextureHandleResidentNV, no. Texture mapping is a read-only 1346 operation; texture handles can really only be used for reading. So all 1347 calls to MakeTextureHandleResidentNV are considered to use an access 1348 mode of READ_ONLY. 1349 1350 (11) Should implicit conversions be supported for converting uint64-typed 1351 handles to sampler and image types? 1352 1353 RESOLVED: No. An explicit constructor is provided to build a handle 1354 from 64-bit unsigned integer or vice versa. 1355 1356 (12) How do we handle backwards compatibility for sampler uniforms in the 1357 default uniform block, which have historically been set to point at a 1358 texture image unit? 1359 1360 RESOLVED: We allow sampler uniforms to be set either using handles (via 1361 the UniformHandle* APIs) or texture image units (via the previously used 1362 Uniform1i* APIs). If the uniform was last set with a handle, the 1363 specified handle will be used for texture access. Otherwise, the value 1364 of the uniform is treated as a texture image unit when the texture is 1365 accessed, and is resolved to refer to the appropriate texture bound to 1366 that unit. 1367 1368 We expect that implementations will distinguish between the two types of 1369 uniform values either by a per-uniform flag or by reserving a subset of 1370 the 2^64 possible handle values to be used to refer to texture image 1371 units. 1372 1373 We impose no limit on the mixing and matching of texture image unit and 1374 handle-based uniform values; an application is permitted to set some 1375 uniforms via UniformHandle*NV and others via Uniform1i. We don't expect 1376 such mixing and matching to be common. 1377 1378 When a sampler or image uniform's value is queried via any of the 1379 GetUniform* commands, the returned value will reflect the most recently 1380 set value through either UniformHandle* or Uniform1i*, converted to the 1381 requested type. 1382 1383 (13) Should UniformHandleui64{v}NV check the provided uniform value(s) to 1384 determine if they are valid handles? 1385 1386 RESOLVED: No; passing in proper texture or image handles is the 1387 responsibility of the application. Note that even if we did verify that 1388 handles were valid at the time sampler or image uniforms were specified, 1389 there is no guarantee that they would still be valid for texture or 1390 image accesses when they are used. In particular, the texture referred 1391 to by the handle may have be deleted, or may exist without being made 1392 resident for the context in question. 1393 1394 (14) With this extension, GLSL sampler and image variables may be 1395 specified using 64-bit handles and are permitted to count as two 1396 components toward implementation-dependent limits on uniforms, shader 1397 inputs, and shader outputs. Is there a backward compatibility 1398 problem here? 1399 1400 RESOLVED: If there is one, we don't expect it to be very serious. 1401 1402 Prior to this extension, samplers or images could not be used as shader 1403 inputs or outputs, so there is no compatibility problem there. Samplers 1404 and images could be used as uniforms, however. While there is no 1405 explicit spec language describing the amount of storage required for 1406 samplers and images, one might construe this lack of language to mean 1407 that only a single component was previously required. Allowing for 1408 64-bit handles in this extension could double the requirement and cause 1409 shaders that previously just barely fit to exceed implementation 1410 limits. 1411 1412 Implementations that consider this issue serious could increase their 1413 uniform limit slightly to compensate. Note that the number of sampler 1414 variables used prior to this extension was quite limited, so the amount 1415 of extra storage required for 64-bit handles should be small. 1416 1417 (15) What happens if you try to access a texture or image handle that is 1418 (a) invalid, (b) non-resident, or (c) corresponds to a texture of a 1419 target different from the target used for the access (e.g., doing a 1420 3D lookup with a handle referring to a 2D texture)? 1421 1422 RESOLVED: For (a), we specify undefined behavior including possible 1423 program termination. Such accesses are effectively equivalent to 1424 chasing an invalid pointer. 1425 1426 For (b), we treat non-resident handles as invalid. Note that this 1427 extension doesn't require that accesses to non-resident handles fail. 1428 1429 For (c), we specify that loads/stores to textures of the "wrong" type 1430 may have undefined results but should not result in program termination. 1431 This same situation could arise in EXT_shader_image_load_store, where 1432 each image unit has a single attachment point shared by all targets, and 1433 the same behavior was specified there. Similar situations could also 1434 arise for indexed texture accesses in OpenGL 4.0, where out-of-bounds 1435 array indices could cause a shader to use a texture unit whose "active" 1436 target was the wrong kind. 1437 1438 (16) Prior to this extension, there were limits on the number of different 1439 textures that could be accessed at once -- the number of texture 1440 image units and image units were limited by implementation-dependent 1441 constants. What limits apply with this extension? 1442 1443 RESOLVED: Since texture image units and image units need not be used 1444 with this extension, those limits no longer apply to shaders that use 1445 bindless textures. With this extension, there is no longer any direct 1446 limit on the number of textures/images that may be used in any shader 1447 stage. 1448 1449 There may still be indirect limits based on the total amount of storage 1450 available: 1451 1452 * Limits on the total amount of uniform memory imply a limit on the 1453 total number of texture handles stored as uniforms. 1454 1455 * Limits on the number of shader input/output components imply a limit 1456 on the number of texture handles passed as shader inputs and 1457 outputs. 1458 1459 * Limits on the total amount of addressable texture memory imply a 1460 limit on the total number of resident texture handles. 1461 1462 * Implementations may have (high) limits on the total number of 1463 texture handles available in the system. 1464 1465 (17) Should we provide any queries to extract information from texture or 1466 image handles? 1467 1468 RESOLVED: No. 1469 1470 (18) Texture and image handles may be made resident or non-resident. How 1471 does handle residency interact with texture residency queries from 1472 OpenGL 1.1 (AreTexturesResident or TEXTURE_RESIDENT)? 1473 1474 RESOLVED: The residency state for texture and image handles in this 1475 extension is completely independent from OpenGL 1.1's TEXTURE_RESIDENT 1476 query. Residency for texture handles is a function of whether the 1477 MakeTextureHandleResidentNV has been called for the handle. OpenGL 1.1 1478 residency is typically a function of whether the texture data are 1479 resident in GPU-accessible memory. 1480 1481 When a texture handle is not made resident, the texture that it refers 1482 to may or may not be stored in GPU-accessible memory. The 1483 TEXTURE_RESIDENT query may return TRUE in this case. However, it does 1484 not guarantee that the texture handle may be used safely. 1485 1486 When a texture handle is made resident, the texture that it refers to is 1487 also considered resident for the purposes of the old TEXTURE_RESIDENT 1488 query. When an image handle is resident, the texture that it refers to 1489 may or may not be considered resident for the query -- the resident 1490 image handle may refer only to a single layer of a single mipmap level 1491 of the full texture. 1492 1493 1494Revision History 1495 1496 Rev. Date Author Changes 1497 ---- -------- -------- ----------------------------------------- 1498 3 06/12/14 dkoch Add interactions with OpenGL ES. 1499 Define better functionality when NV_gpu_shader5 1500 is not supported. 1501 Fix a variety of typos and missing words. 1502 Merge in typo fixes from v3 of the ARB extn. 1503 Add missing error condition for BufferData and 1504 buffer textures. 1505 1506 2 05/16/13 pbrown Fix typo in spec language. 1507 1508 1 jbolz Internal revisions. 1509 pbrown 1510