1Name 2 3 IMG_bindless_texture 4 5Name Strings 6 7 GL_IMG_bindless_texture 8 9Contact 10 11 Tobias Hector (tobias.hector 'at' imgtec.com) 12 13Contributors 14 15 Contributors to the original ARB_bindless_texture 16 17Notice 18 19 Copyright (c) 2013 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Status 23 24 Draft 25 26Version 27 28 Last Modified Date: May 23, 2016 29 Author Revision: 4 30 31Number 32 33 OpenGL ES Extension #270 34 35Dependencies 36 37 OpenGL ES 3.1 is required. 38 39 This extension is written against the OpenGL ES Shading Language 40 specification, Language Version 3.10, Document Revision 3 and the 41 OpenGL ES 3.1 API specification. 42 43 This extension interacts with EXT/OES_gpu_shader5. 44 45 This extension interacts with EXT/OES_texture_buffer and EXT_buffer_storage. 46 47 This extension interacts with OpenGL ES 3.2 48 49Overview 50 51 This extension allows OpenGL ES applications to access texture objects in 52 shaders without first binding each texture to one of a limited number of 53 texture image units. Using this extension, an application can query a 54 64-bit unsigned integer texture handle for each texture that it wants to 55 access and then use that handle directly in GLSL ES. This extensions 56 significantly reduces the amount of API and internal GL driver overhead 57 needed to manage resource bindings. 58 59 This extension adds no new data types to GLSL. Instead, it uses existing 60 sampler data types and allows them to be populated with texture handles. 61 This extension also permits sampler types to be used as uniform block 62 members as well as default uniforms. Additionally, new APIs are provided to 63 load values for sampler uniforms with 64-bit handle inputs. The use of 64 existing integer-based Uniform* APIs is still permitted, in which case the 65 integer specified will identify a texture image. For samplers with values 66 specified as texture image units, the GL implementation will translate the 67 unit number to an internal handle as required. 68 69New Procedures and Functions 70 71 uint64 GetTextureHandleIMG(uint texture); 72 uint64 GetTextureSamplerHandleIMG(uint texture, uint sampler); 73 74 void UniformHandleui64IMG(int location, uint64 value); 75 void UniformHandleui64vIMG(int location, sizei count, const uint64 *value); 76 77 void ProgramUniformHandleui64IMG(uint program, int location, 78 uint64 value); 79 void ProgramUniformHandleui64vIMG(uint program, int location, 80 sizei count, const uint64 *values); 81 82New Tokens 83 84 None 85 86Additions to Chapter 5 of the OpenGL ES 3.1 API Specification, "Shared Objects 87and Multiple Contexts" 88 89 Insert a new section 5.4, "Object use by GPU Handles" 90 91 GPU handles to objects are valid in all contexts in the share group that 92 the originating object belongs to, irrespective of whether the object 93 itself is shared. If the originating object for a handle is deleted or 94 becomes otherwise invalid, the handle becomes immediately invalid in all 95 contexts. Using an invalid handle can lead to undefined results, 96 including program termination. 97 98Additions to Chapter 7 of the OpenGL ES 3.1 API Specification, "Variables and 99Types" 100 101 Add the following sentence to Section 7.6, Uniform Variables, immediately 102 before the error block on page 97: 103 104 A sampler uniform will consume no more than 2 components. 105 106 Add the following commands to the list of Uniform* functions in section 107 7.6.1, Loading Uniform Variables in the Default Uniform Block: 108 109 void UniformHandleui64IMG(int location, uint64 value); 110 void UniformHandleui64vIMG(int location, sizei count, 111 const uint64 *value); 112 113 Delete the sentence "Only the Uniform1i{v} commands can be used to load 114 sampler values (see section 7.9)", and add the following paragraph: 115 116 The UniformHandleui64{v}IMG commands will load <count> 64-bit unsigned 117 integer handles into a uniform location corresponding to sampler types. 118 Only the UniformHandleui64{v}IMG and Uniform1i{v} commands can be used 119 to load sampler values (see section 7.9). 120 121 Add the following error condition to the list of errors for Uniform* 122 functions: 123 124 An INVALID_OPERATION error is generated if the UniformHandleui64{v}IMG 125 commands are used on a sampler variable with the "bound_sampler" layout 126 qualifier (see the Language specification, section 4.4.5bindless). 127 128 Add the following commands to the list of ProgramUniform* functions in 129 section 7.6.1, Loading Uniform Variables in the Default Uniform Block: 130 131 void ProgramUniformHandleui64IMG(uint program, int location, 132 uint64 value); 133 void ProgramUniformHandleui64vIMG(uint program, int location, 134 sizei count, const uint64 *values); 135 136 Edit section 7.6.2.1, "Uniform Buffer Object Storage", to add the following 137 rules for sampler types to the list at the beginning of p105: 138 139 * Members of sampler types are extracted from a buffer object by 140 reading a single 64-bit value at the specified offset. 141 142 Replace Section 7.9, Samplers, with the following, adding the ability to use 143 samplers in new places as well as describing the behavior of the new 144 UniformHandleui64{v}IMG APIs: 145 146 Samplers are special data types used by the OpenGL ES Shading Language to 147 identify the texture object used for each texture lookup. Sampler 148 variables may be used as uniforms in the default block or in user-defined 149 blocks. 150 151 When used as uniforms in the default block, the value of sampler 152 variables may be specified with either Uniform1i{v} or 153 UniformHandleui64{v}IMG. If a sampler uniform value is specified by 154 Uniform1i{v}, the value passed to Uniform1i{v} indicates a texture image 155 unit that will be accessed, and the value must be in the range from zero 156 to the implementation-dependent maximum supported number of texture image 157 units. If a sampler uniform value is specified by UniformHandleui64{v}IMG, 158 the value passed to UniformHandleui64{v}IMG directly specifies a texture 159 object by handle, as defined in Section 8.2bindless (Bindless Textures). 160 When a program is linked, all sampler uniforms are initialized to zero and 161 considered to be references to texture image units. When used as uniform 162 block members, the value of the sampler is a 64-bit unsigned integer handle 163 and never refers to a texture image unit. 164 165 When the value of a sampler indicates a texture image unit, the type of 166 the sampler identifies the target on the texture image unit. The texture 167 object bound to that texture image unit's target is used for any texture 168 accesses using that sampler. For example, a variable of type sampler2D 169 selects the target TEXTURE_2D on its texture image unit. Binding of 170 texture objects to targets is done as usual with BindTexture. Selecting 171 the texture image unit to bind to is done as usual with ActiveTexture. 172 173 When the value of a sampler indicates a texture handle, the target of the 174 texture referred to by the handle must match the type of the sampler. For 175 example, a variable of type sampler2D must be used in conjunction with a 176 handle of a texture of target TEXTURE_2D. If the value of a sampler 177 variable is not a valid texture handle, the results of using that sampler 178 during shader execution are undefined and may lead to program termination. 179 If the value of a sampler variable is a valid handle of a texture with a 180 target different from the variable type, the results of using that handle 181 are undefined but may not include program termination. 182 183 Sampler uniforms specified using handles do not count as using any texture 184 image unit, even if a texture referred to by a handle is currently bound to 185 one or more texture image units. 186 187 Errors 188 189 The error INVALID_VALUE is generated if a Uniform1i{v} call is used to 190 set a sampler uniform to a value less than zero or greater than or 191 equal to the value of MAX_TEXTURE_IMAGE_UNITS. 192 193 It is not allowed to have uniform variables of different sampler types 194 pointing to the same texture image unit within a program object. This 195 situation can only be detected at the next rendering command issued, 196 and an INVALID_OPERATION error will then be generated. 197 198 Active samplers are those samplers actually being used in a program 199 object. When a program is linked by LinkProgram, the GL determines 200 whether each sampler is active or not. There is no limit on the number of 201 active sampler variables that may be used by a program or by any 202 particular shader. However, restrictions on the use of texture image 203 units imposes an effective limit on the number of non-handle sampler 204 uniforms. Active samplers used uniforms in the default uniform block are 205 counted toward implementation-dependent limits on the total number of 206 uniform components supported by the program. Each active sampler variable 207 may count as two components against such limits. 208 209Additions to Chapter 8 of the OpenGL ES 3.1 API Specification, "Textures and 210Samplers" 211 212 Insert a new section 8.2bindless, Bindless Textures, after Section 8.2, 213 Sampler Objects: 214 215 The previous sections describe mechanisms to make texture and sampler 216 objects available to shaders or fixed-function fragment processing by 217 binding the objects to texture image units. Additionally, texture objects 218 may be accessed by shader using texture handles, which are 64-bit unsigned 219 integers identifying the state of a texture and/or sampler object. The 220 handle zero is reserved and will never be assigned to a valid texture 221 handle. To obtain a texture handle, use the commands: 222 223 uint64 GetTextureHandleIMG(uint texture); 224 uint64 GetTextureSamplerHandleIMG(uint texture, uint sampler); 225 226 GetTextureHandleIMG will create a texture handle using the current state of 227 the texture named <texture>, including any embedded sampler state. 228 GetTextureSamplerHandleIMG will create a texture handle using the current 229 non-sampler state from the texture named <texture> and the sampler state 230 from the sampler object <sampler>. In both cases, a 64-bit unsigned 231 integer handle is returned. If an error occurs, a handle of zero is 232 returned. 233 234 The handle for each texture or texture/sampler pair is unique; the same 235 handle will be returned if GetTextureHandleIMG is called multiple times 236 for the same texture or if GetTextureSamplerHandleIMG is called multiple 237 times for the same texture/sampler pair. 238 239 When a texture object is referenced by one or more texture handles, the 240 texture parameters of the object (Section 8.9) may not be changed. The 241 contents of the images in a texture object may still be updated via commands 242 such as TexSubImage*, CopyTexSubImage*, and CompressedTexSubImage*, and by 243 rendering to a framebuffer object, even if the texture object is referenced 244 by one or more texture handles. However, once a handle references a texture 245 object, texel updates via API commands are no longer implicitly 246 synchronised by the API. Updates to the texture will become visible to the 247 server after an unspecified period of time, and may occur during other 248 server operations - though they are guaranteed to be visible to subsequently 249 issued GL commands with no further action. Applications are responsible for 250 synchronizing access, to ensure operations have completed in the desired 251 order - for instance by using FenceSync (see Chapter 4 - Event Model). 252 253 [[ If EXT/OES_texture_buffer or OpenGL ES 3.2, and EXT_buffer_storage are supported ]] 254 If the texture object is a buffer texture, the contents of the buffer object 255 may still be updated by using MapBuffer* commands with the 256 MAP_PERSISTENT_BIT_EXT, or via the texture update commands in the same way 257 as other bindless textures, even if the buffer is bound to a texture while 258 that buffer texture object is referenced by one or more texture handles. 259 260 When a sampler object is referenced by one or more texture handles, the 261 sampler parameters of the object may not be changed. 262 263 Errors 264 265 An INVALID_VALUE error is generated if <texture> is zero or is not the 266 name of an existing texture object or if <sampler> is zero or is not the 267 name of an existing sampler object. 268 269 [[ If EXT/OES_texture_buffer or OpenGL ES 3.2, and EXT_buffer_storage are supported ]] 270 An INVALID_OPERATION error is generated if the value of <texture>'s 271 TEXTURE_IMMUTABLE_FORMAT is FALSE (section 8.17), or if <texture> is 272 a texture buffer and the values of the backing buffer's BUFFER_- 273 IMMUTABLE_STORAGE_EXT is FALSE, BUFFER_ACCESS_FLAGS includes 274 DYNAMIC_STORAGE_BIT or does not include MAP_PERSISTENT_BIT_EXT. 275 [[ Else ]] 276 An INVALID_OPERATION error is generated if the value of <texture>'s 277 TEXTURE_IMMUTABLE_FORMAT is FALSE (section 8.17). 278 279 [[ If EXT/OES_texture_border_clamp or OpenGL ES 3.2 are supported ]] 280 An INVALID_OPERATION error is generated if the border color (taken from 281 the embedded sampler for GetTextureHandleIMG or from the <sampler> for 282 GetTextureSamplerHandleIMG) is not one of the following allowed values. 283 If the texture's base internal format is signed or unsigned integer, 284 allowed values are (0,0,0,0), (0,0,0,1), (1,1,1,0), and (1,1,1,1). If 285 the base internal format is not integer, allowed values are 286 (0.0,0.0,0.0,0.0), (0.0,0.0,0.0,1.0), (1.0,1.0,1.0,0.0), and 287 (1.0,1.0,1.0,1.0). 288 289Additions to Chapter 11 of the OpenGL ES 3.1 API Specification, "Programmable 290Vertex Processing" 291 292 Add the following sentence to the end of the paragraph in Section 11.1.3.5, 293 Texture Access, beginning "All active shaders combined cannot use more than 294 the value of MAX_COMBINED_TEXTURE_IMAGE_UNITS...": 295 296 Samplers accessed using texture handles (section 3.9.X) are not counted 297 against this limit. 298 299Modifications to The OpenGL ES 3.10 Shading Language Specification 300 301 Including the following line in a shader can be used to control the 302 language features described in this extension: 303 304 #extension GL_IMG_bindless_texture : <behavior> 305 306 where <behavior> is as specified in section 3.4. 307 308 New preprocessor #defines are added to the OpenGL ES Shading Language: 309 310 #define GL_IMG_bindless_texture 1 311 312 313Additions to Chapter 4 of the OpenGL ES 3.1 Language Specification, "Variables 314and Types" 315 316 Add the following paragraph to the end of section 4.1.7.1, Samplers: 317 318 The OpenGL ES API allows default block sampler uniforms to be assigned 319 values referencing either a texture image unit number or a bindless 320 texture handle, depending on the API function used. All other sampler 321 variables must be assigned a texture handle. A layout qualifier 322 specifies which of these is used in the program. 323 324 Remove the bullet point "sampler types are not allowed" Section 4.3.7, 325 Interface Blocks. 326 327 Add the following paragraph to the end of section 4.4.5, "Opaque Uniform 328 Layout Qualifiers": 329 330 Sampler variables declared in uniform blocks may not be qualified with 331 a binding, and a compile-time error will be generated if a shader 332 specifies this. 333 334 Insert a new section 4.4.5bindless, "Bindless Sampler Layout Qualifiers", 335 after section 4.4.5, "Opaque Uniform Layout Qualifiers": 336 337 Sampler types accept a uniform layout qualifier identifier controlling 338 whether the uniform may be used with a bindless handle: 339 340 layout-qualifier-id 341 bindless_sampler 342 bound_sampler 343 344 These modifiers control whether default-block uniforms of the 345 corresponding types may have their values set via both UniformHandle* 346 and Uniform1i (bindless_sampler) or only via Uniform1i (bound_sampler). 347 These layouts may be specified at global scope to control the default 348 behavior of uniforms of the corresponding types, e.g. 349 350 layout (bindless_sampler) uniform; 351 352 They may also be specified on a uniform variable declaration of a 353 corresponding type, e.g. 354 355 layout (bindless_sampler) uniform sampler2D mySampler; 356 357 If both bindless_sampler and bound_sampler are declared at global scope 358 in any compilation unit, a link- time error will be generated. If these 359 layout qualifiers are applied to other types of default block uniforms, 360 a compile-time error will be generated. In the absence of these 361 qualifiers, sampler uniforms are considered "bound". Additionally, if 362 GL_IMG_bindless_texture is not enabled, these uniforms are considered 363 "bound". 364 365 Declaring a sampler in the uniform default-block with a binding point 366 qualifier implicitly also declares it with "bound_sampler". 367 368Errors 369 370 The error INVALID_OPERATION is generated by SamplerParameter* if <sampler> 371 identifies a sampler object referenced by one or more texture handles. 372 373 The error INVALID_OPERATION is generated by TexParameter* if <target> 374 identifies a texture object referenced by one or more texture handles. 375 376 377 The error INVALID_OPERATION is generated by {Program}UniformHandleui64{v}IMG 378 if the sampler or image uniform being updated has the "bound_sampler" layout 379 qualifier, or an explicit binding qualifier. 380 381 [[ If EXT/OES_texture_buffer or OpenGL ES 3.2, and EXT_buffer_storage are supported ]] 382 The error INVALID_OPERATION is generated by TexBuffer*EXT if <target> 383 identifies a texture object referenced by one or more texture handles. 384 385 The error INVALID_OPERATION is generated by MapBuffer* if <target> 386 identifies a buffer object bound to a texture that is referenced by one or 387 more texture handles, and access does not include MAP_PERSISTENT_BIT_EXT. 388 389Examples 390 391 To loop through a collection of 256 textures in the OpenGL API using a 392 conventional GLSL shader and without calling glBindTexture, one might do: 393 394 #define NUM_TEXTURES 256 395 GLuint textures[NUM_TEXTURES]; 396 GLuint64 texHandles[NUM_TEXTURES]; 397 398 // Initialize the texture objects and handles. 399 glGenTextures(NUM_TEXTURES, textures); 400 for (int i = 0; i < NUM_TEXTURES; i++) { 401 402 // Initialize the texture images with glTexStorage. 403 // Initialize the texture parameters as required. 404 405 // Get a handle for the texture. 406 texHandles[i] = glGetTextureHandleIMG(textures[i]); 407 408 // At this point, it's no longer possible to modify texture parameters 409 // for "textures[i]". However, it's still possible to update texture 410 // data via glTexSubImage. 411 } 412 413 // Compile GLSL shader using sampler uniform <u>. The shader itself 414 // needs no special #extension directive as long as <u> is a uniform in 415 // the default partition, and doesn't declare an explicit binding point. 416 // Link the program, and query the location of <u>, which we will store 417 // in <location>. 418 419 // Render a little bit using each of the texture handles in turn. 420 for (int i = 0; i < NUM_TEXTURES; i++) { 421 422 // Update the single sampler uniform <u> to point at "texHandles[i]". 423 glUniformHandleui64IMG(location, texHandles[i]); 424 425 drawStuff(); 426 } 427 428 The GLSL portion of this extension removes the restriction that sampler 429 variables must be uniforms in the default block. You can store a large 430 collection of samplers in a uniform block. 431 432 To use a "dictionary" of samplers in a uniform block (in combination with 433 either EXT_gpu_shader5, or OpenGL ES 3.2), you could use a shader like: 434 435 #version 310 es 436 #extension GL_IMG_bindless_texture : require 437 #extension GL_EXT_gpu_shader5 : require 438 #define NUM_TEXTURES 256 439 440 uniform int whichSampler; 441 in highp vec2 texCoord; 442 out lowp vec4 finalColor; 443 444 uniform Samplers { 445 sampler2D allTheSamplers[NUM_TEXTURES]; 446 }; 447 448 void main() 449 { 450 finalColor = texture(allTheSamplers[whichSampler], texCoord); 451 } 452 453New State 454 455 Add new table, Bindless Texture Handles 456 457 Initial 458 Get Value Type Get Command Value Description Sec. Attribute 459 ------------ ---- -------------------- ------- ------------------------- ----------- ------- 460 - Z64 GetTextureHandleIMG n/a texture handle 8.2bindless - 461 or GetTextureSampler- 462 HandleIMG 463 - Z+ - n/a texture object used 8.2bindless - 464 - Z+ - n/a sampler object used 8.2bindless - 465 466Issues 467 468 See original issues in ARB_bindless_texture. 469 470 (1) How does IMG_bindless_texture differ from ARB_bindless_texture? 471 472 RESOLVED: 473 474 - Bindless images are not supported. 475 - Bindless samplers are only supported via uniforms/uniform buffers. 476 - No constructors between opaque and integer types 477 - No residency functions 478 - This extension does not add dynamic indexing, as it is introduced by EXT/OES_shader_gpu5 (or OpenGL ES 3.2) 479 - Only immutable textures and buffers (for buffer textures) are usable with bindless handles. 480 - Texture uploads are considered asynchronous to usage, and must be manually synchronized with fences in order to avoid race conditions 481 - For buffer texture objects, the only allowed buffer update mechanism is persistent mapping 482 483 (2) Should texture uploads/copies still be allowed? 484 485 RESOLVED: 486 487 The original ARB_bindless_texture allows texture uploads, with the 488 expectation that the commands are still serialized relative to surrounding 489 draw calls. 490 491 Such an implementation would prove difficult for a tile-based 492 architecture; attempting to serialize resource updates between draw calls 493 requires significant amounts of additional overhead. Without bindless, 494 the driver is able to track resources to make it work as expected - which 495 is impossible with bindless textures. 496 497 So we've decided to remove this particular requirement, instead 498 saying that texture uploads and copies occur asynchronously to other 499 commands, and require explicit synchronisation, in order to be 500 completed at predictable times. 501 502 (2) Should buffer uploads/copies for buffer texture objects still be allowed? 503 504 RESOLVED: 505 506 Only persistent mapping is allowed. 507 508Revision History 509 510 Rev. Date Author Changes 511 ---- ---------- -------- ----------------------------------------- 512 1 2015-08-21 thector Initial revision 513 2 2015-08-24 thector Fixed references to "EXT_buffer_storage", added error for TexBuffer*EXT functions 514 3 2015-12-04 thector Texture data uploads are now entirely asynchronous 515 4 2016-05-23 thector Ensured that example in spec is actually compilable 516