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