1Name 2 3 EXT_external_objects 4 5Name Strings 6 7 GL_EXT_memory_object 8 GL_EXT_semaphore 9 10Contributors 11 12 Carsten Rohde, NVIDIA 13 Dave Airlie, Red Hat 14 James Jones, NVIDIA 15 Jan-Harald Fredriksen, ARM 16 Jeff Juliano, NVIDIA 17 Michael Worcester, Imagination Technologies 18 19Contact 20 21 James Jones, NVIDIA (jajones 'at' nvidia.com) 22 23Status 24 25 Complete 26 27Version 28 29 Last Modified Date: July 18, 2018 30 Revision: 14 31 32Number 33 34 503 35 OpenGL ES Extension #280 36 37Dependencies 38 39 Written against the OpenGL 4.5 and OpenGL ES 3.2 specifications. 40 41 GL_EXT_memory_object requires ARB_texture_storage or a version of 42 OpenGL or OpenGL ES that incorporates it. 43 44 GL_EXT_semaphore requires OpenGL 1.0. 45 46 ARB_direct_state_access (OpenGL) interacts with GL_EXT_memory_object 47 when OpenGL < 4.5 is used. 48 49 ARB_sparse_texture (OpenGL) interacts with GL_EXT_memory_object 50 51 EXT_sparse_texture (OpenGL ES) interacts with GL_EXT_memory_object 52 53 EXT_protected_textures (OpenGL ES) interacts with GL_EXT_memory_object 54 55Overview 56 57 The Vulkan API introduces the concept of explicit memory objects and 58 reusable synchronization objects. This extension brings those 59 concepts to the OpenGL API via two new object types: 60 61 Memory objects 62 Semaphores 63 64 Rather than allocating memory as a response to object allocation, 65 memory allocation and binding are two separate operations in Vulkan. 66 This extension allows an OpenGL application to import a Vulkan 67 memory object, and to bind textures and/or buffer objects to it. 68 69 No methods to import memory objects are defined here. Separate 70 platform-specific extensions are defined for this purpose. 71 72 Semaphores are synchronization primitives that can be waited on and 73 signaled only by the GPU, or in GL terms, in the GL server. They 74 are similar in concept to GL's "sync" objects and EGL's "EGLSync" 75 objects, but different enough that compatibilities between the two 76 are difficult to derive. 77 78 Rather than attempt to map Vulkan semaphores on to GL/EGL sync 79 objects to achieve interoperability, this extension introduces a new 80 object, GL semaphores, that map directly to the semantics of Vulkan 81 semaphores. To achieve full image and buffer memory coherence with 82 a Vulkan driver, the commands that manipulate semaphores also allow 83 external usage information to be imported and exported. 84 85New Procedures and Functions 86 87 The following commands are added if either of the GL_EXT_memory_object 88 or GL_EXT_semaphore strings are reported: 89 90 void GetUnsignedBytevEXT(enum pname, 91 ubyte *data); 92 93 void GetUnsignedBytei_vEXT(enum target, 94 uint index, 95 ubyte *data); 96 97 If the GL_EXT_memory_object string is reported, the following 98 commands are added: 99 100 void DeleteMemoryObjectsEXT(sizei n, 101 const uint *memoryObjects); 102 103 boolean IsMemoryObjectEXT(uint memoryObject); 104 105 void CreateMemoryObjectsEXT(sizei n, 106 uint *memoryObjects); 107 108 void MemoryObjectParameterivEXT(uint memoryObject, 109 enum pname, 110 const int *params); 111 112 void GetMemoryObjectParameterivEXT(uint memoryObject 113 enum pname, 114 int *params); 115 116 void TexStorageMem2DEXT(enum target, 117 sizei levels, 118 enum internalFormat, 119 sizei width, 120 sizei height, 121 uint memory, 122 uint64 offset); 123 124 void TexStorageMem2DMultisampleEXT(enum target, 125 sizei samples, 126 enum internalFormat, 127 sizei width, 128 sizei height, 129 boolean fixedSampleLocations, 130 uint memory, 131 uint64 offset); 132 133 void TexStorageMem3DEXT(enum target, 134 sizei levels, 135 enum internalFormat, 136 sizei width, 137 sizei height, 138 sizei depth, 139 uint memory, 140 uint64 offset); 141 142 void TexStorageMem3DMultisampleEXT(enum target, 143 sizei samples, 144 enum internalFormat, 145 sizei width, 146 sizei height, 147 sizei depth, 148 boolean fixedSampleLocations, 149 uint memory, 150 uint64 offset); 151 152 void BufferStorageMemEXT(enum target, 153 sizeiptr size, 154 uint memory, 155 uint64 offset); 156 157 [[ The following are added if direct state access is supported ]] 158 159 void TextureStorageMem2DEXT(uint texture, 160 sizei levels, 161 enum internalFormat, 162 sizei width, 163 sizei height, 164 uint memory, 165 uint64 offset); 166 167 void TextureStorageMem2DMultisampleEXT(uint texture, 168 sizei samples, 169 enum internalFormat, 170 sizei width, 171 sizei height, 172 boolean fixedSampleLocations, 173 uint memory, 174 uint64 offset); 175 176 void TextureStorageMem3DEXT(uint texture, 177 sizei levels, 178 enum internalFormat, 179 sizei width, 180 sizei height, 181 sizei depth, 182 uint memory, 183 uint64 offset); 184 185 void TextureStorageMem3DMultisampleEXT(uint texture, 186 sizei samples, 187 enum internalFormat, 188 sizei width, 189 sizei height, 190 sizei depth, 191 boolean fixedSampleLocations, 192 uint memory, 193 uint64 offset); 194 195 void NamedBufferStorageMemEXT(uint buffer, 196 sizeiptr size, 197 uint memory, 198 uint64 offset); 199 200 [[ The following are available in OpenGL only ]] 201 202 void TexStorageMem1DEXT(enum target, 203 sizei levels, 204 enum internalFormat, 205 sizei width, 206 uint memory, 207 uint64 offset); 208 209 [[ The following are availble in OpenGL only, and only when 210 direct state access is available ]] 211 212 void TextureStorageMem1DEXT(uint texture, 213 sizei levels, 214 enum internalFormat, 215 sizei width, 216 uint memory, 217 uint64 offset); 218 219 If the GL_EXT_semaphore string is reported, the following 220 commands are added: 221 222 void GenSemaphoresEXT(sizei n, 223 uint *semaphores); 224 225 void DeleteSemaphoresEXT(sizei n, 226 const uint *semaphores); 227 228 boolean IsSemaphoreEXT(uint semaphore); 229 230 void SemaphoreParameterui64vEXT(uint semaphore, 231 enum pname, 232 const uint64 *params); 233 234 void GetSemaphoreParameterui64vEXT(uint semaphore, 235 enum pname, 236 uint64 *params); 237 238 void WaitSemaphoreEXT(uint semaphore, 239 uint numBufferBarriers, 240 const uint *buffers, 241 uint numTextureBarriers, 242 const uint *textures, 243 const GLenum *srcLayouts); 244 245 void SignalSemaphoreEXT(uint semaphore, 246 uint numBufferBarriers, 247 const uint *buffers, 248 uint numTextureBarriers, 249 const uint *textures, 250 const GLenum *dstLayouts); 251 252New Tokens 253 254 If the GL_EXT_memory_object string is reported, the following tokens are 255 added: 256 257 Accepted by the <pname> parameter of TexParameter{ifx}{v}, 258 TexParameterI{i ui}v, TextureParameter{if}{v}, TextureParameterI{i ui}v, 259 GetTexParameter{if}v, GetTexParameterI{i ui}v, GetTextureParameter{if}v, 260 and GetTextureParameterI{i ui}v: 261 262 TEXTURE_TILING_EXT 0x9580 263 264 Accepted by the <pname> parameter of MemoryObjectParameterivEXT, and 265 GetMemoryObjectParameterivEXT: 266 267 DEDICATED_MEMORY_OBJECT_EXT 0x9581 268 269 [[ The following are available when GL_EXT_protected_textures is 270 available ]] 271 272 PROTECTED_MEMORY_OBJECT_EXT 0x959B 273 274 Accepted by the <pname> parameter of GetInternalFormativ or 275 GetInternalFormati64v: 276 277 NUM_TILING_TYPES_EXT 0x9582 278 TILING_TYPES_EXT 0x9583 279 280 Returned in the <params> parameter of GetInternalFormativ or 281 GetInternalFormati64v when the <pname> parameter is TILING_TYPES_EXT, 282 returned in the <params> parameter of GetTexParameter{if}v, 283 GetTexParameterI{i ui}v, GetTextureParameter{if}v, and 284 GetTextureParameterI{i ui}v when the <pname> parameter is 285 TEXTURE_TILING_EXT, and accepted by the <params> parameter of 286 TexParameter{ifx}{v}, TexParameterI{i ui}v, TextureParameter{if}{v}, 287 TextureParameterI{i ui}v when the <pname> parameter is 288 TEXTURE_TILING_EXT: 289 290 OPTIMAL_TILING_EXT 0x9584 291 LINEAR_TILING_EXT 0x9585 292 293 The following tokens are added if either of the GL_EXT_memory_object or 294 GL_EXT_semaphore strings are reported: 295 296 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetFloatv, 297 GetIntegerv, GetInteger64v, GetUnsignedBytevEXT, and the <target> 298 parameter of GetBooleani_v, GetIntegeri_v,GetFloati_v, GetDoublei_v, 299 GetInteger64i_v, and GetUnsignedBytei_vEXT: 300 301 NUM_DEVICE_UUIDS_EXT 0x9596 302 DEVICE_UUID_EXT 0x9597 303 DRIVER_UUID_EXT 0x9598 304 305 Constant values: 306 307 UUID_SIZE_EXT 16 308 309 If the GL_EXT_semaphore string is reported, the following tokens are 310 added: 311 312 Accepted by the <dstLayouts> parameter of SignalSemaphoreEXT and the 313 <srcLayouts> parameter of WaitSemaphoreEXT: 314 315 LAYOUT_GENERAL_EXT 0x958D 316 LAYOUT_COLOR_ATTACHMENT_EXT 0x958E 317 LAYOUT_DEPTH_STENCIL_ATTACHMENT_EXT 0x958F 318 LAYOUT_DEPTH_STENCIL_READ_ONLY_EXT 0x9590 319 LAYOUT_SHADER_READ_ONLY_EXT 0x9591 320 LAYOUT_TRANSFER_SRC_EXT 0x9592 321 LAYOUT_TRANSFER_DST_EXT 0x9593 322 LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_EXT 0x9530 323 LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_EXT 0x9531 324 325Additions to Chapter 2 of the OpenGL 4.5 Specification (OpenGL 326Fundamentals) 327 328 Add two new sections after 2.6.13 (Sync Objects) 329 330 2.6.14 Semaphore Objects 331 332 A /semaphore object/ is a synchronization primitive similar to a 333 /sync object/, but with semantics based on Vulkan semaphores. 334 335 Semaphore objects may be shared. They are described in detail in 336 section 4.2. 337 338 2.6.15 Memory Objects 339 340 Many GL objects have some associated data stored in GL server 341 memory. /Memory objects/ are an abstract representation of GL 342 server memory suitable for use as the backing store of a 343 /buffer object/, a /texture object/, or both, depending on how 344 the memory referred to by the object was allocated. Memory 345 objects can not be created directly within the GL. They must be 346 imported from an API capable of allocating abstract memory, such 347 as Vulkan. 348 349 Memory objects may be shared. They are described in detail in 350 Chapter 6 (Memory Objects). 351 352Additions to Chapter 4 of the OpenGL 4.5 Specification (Event Model) 353 354 Add a new section between sections 4.1, "Sync Objects and Fences" 355 and section 4.2, "Query Objects and Asynchronous Queries" 356 357 4.2 Semaphore Objects 358 359 Like sync objects, a semaphore object acts as a /synchronization 360 primitive/. However, semaphore objects differ from sync objects 361 in several ways: 362 363 * They may only be created by importing an external semaphore 364 handle into the GL. 365 366 * They are reusable. 367 368 * As a corollary to the above behavior, separate commands are 369 provided to create and signal semaphore objects. 370 371 * Their state is reset upon completion of a wait operation. 372 373 * As a corollary to the above behavior, only a single waiter may 374 be associated with a unique signal command. 375 376 * There is no way to wait for a semaphore to become signaled in 377 the GL client. All waits operations execute in the GL server, 378 and semaphores have no queryable state. 379 380 The command 381 382 void GenSemaphoresEXT(sizei n, 383 uint *semaphores); 384 385 returns <n> previous unused semaphore names in <semaphores>. 386 These names are marked as used, for the purposes of 387 GenSemaphoresEXT only, but they are associated with semaphore 388 state only when an external semaphore handle is imported to 389 them. 390 391 Semaphore objects are deleted by calling 392 393 void DeleteSemaphoresEXT(sizei n, 394 const uint *semaphores); 395 396 <semaphores> contains <n> names of semaphores to be deleted. 397 After a semaphore is deleted, it unreferences any external 398 semaphore state it referenced, and its name is again unused. 399 Unused names in <semaphores> are silently ignored, as is the 400 value zero. 401 402 The command 403 404 boolean IsSemaphoreEXT(uint semaphore); 405 406 returns TRUE if <semaphore> is the name of a semaphore. If 407 <semaphore> is zero, or if <semaphore> is a non-zero value that 408 is not the name of a semaphore, IsSemaphore returns FALSE. 409 410 4.2.1 Importing External Semaphore Handles into Semaphores 411 412 A semaphore is created by importing an external semaphore object 413 via a reference to its associated external handle. The 414 supported set of external handle types and associated import 415 functions are listed in table 4.2. 416 417 Table 4.2: Commands for importing external semaphore handles. 418 419 | Handle Type | Import command | 420 +-------------+----------------+ 421 +-------------+----------------+ 422 423 Applications must only import external semaphore handles exported 424 from the same device or set of devices used by the current context, 425 and from compatible driver versions. To determine which devices are 426 used by the current context, first call GetIntegerv with <pname> set 427 to NUM_DEVICE_UUIDS_EXT, then call GetUnsignedBytei_vEXT with <target> 428 set to DEVICE_UUID_EXT, <index> set to a value in the range [0, 429 <number of device UUIDs>), and <data> set to point to an array of 430 UUID_SIZE_EXT unsigned bytes. To determine the driver ID of the 431 current context, call GetUnsignedBytevEXT with <pname> set to 432 DRIVER_UUID_EXT and <data> set to point to an array of UUID_SIZE_EXT 433 unsigned bytes. 434 435 These device and driver ID values can be used to correlate devices 436 and determine driver compatibility across process and API boundaries. 437 438 External handles are often defined using platform-specific 439 types. Therefore, the base GL specification defines no methods 440 to import an external handle. 441 442 4.2.2 Semaphore Parameters 443 444 Semaphore parameters control how semaphore wait and signal 445 operations behave. Table 4.3 defines which parameters are available 446 for a semaphore based on the external handle type from which it was 447 imported. Semaphore parameters are set using the command 448 449 void SemaphoreParameterui64vEXT(uint semaphore, 450 enum pname, 451 const uint64 *params); 452 453 <semaphore> is the name of the semaphore object on which the 454 parameter <pname> will be set to the value(s) in <pname>. 455 456 Table 4.3: Semaphore parameters 457 458 | Name | External Handle Types | Legal Values | 459 +------+-----------------------+--------------+ 460 +------+-----------------------+--------------+ 461 462 Parameters of a semaphore object may be queried with the command 463 464 void GetSemaphoreParameterui64EXT(uint semaphore, 465 enum pname, 466 uint64 *params); 467 468 <semaphore> is the semaphore object from with the parameter <pname> 469 is queried. The value(s) of the parameter are returned in <params>. 470 <pname> may be any value in table 4.3. 471 472 4.2.3 Waiting for Semaphores 473 474 The command 475 476 void WaitSemaphoreEXT(uint semaphore, 477 uint numBufferBarriers, 478 const uint *buffers, 479 uint numTextureBarriers, 480 const uint *textures, 481 const GLenum *srcLayouts); 482 483 Returns immediately but causes GL server to block until 484 <semaphore> is signaled. If an error occurs, WaitSemaphore 485 generates a GL error as specified below, and does not cause the 486 GL server to block. 487 488 After completion of the semaphore wait operation, the semaphore 489 will be returned to the unsignaled state. Calling WaitSemaphore on 490 a semaphore that has not previously had a signal operation flushed 491 to the GL server or submitted by an external semaphore signaler 492 since the semaphore was created or last waited on results in 493 undefined behavior. 494 495 Following completion of the semaphore wait operation, memory will 496 also be made visible in the specified buffer and texture objects. 497 Since texture layout state is managed internally by the GL, but may 498 have been modified by an external API, the current layout of the 499 textures must be specified to initialize internal GL state prior to 500 using the textures after an external access. The valid layouts 501 correspond to those specified by the Vulkan API, as described in 502 table 4.4. However, the layouts do not necessarily correspond to an 503 optimal state for any particular GL operation. The GL will simply 504 perform appropriate transitions internally as necessary based on the 505 specified current layout of the texture. 506 507 Table 4.4: Texture layouts and corresponding Vulkan Image Layouts 508 509 | Texture Layout | Equivalent Vulkan Image Layout | 510 +--------------------------------------------------+----------------------------------------------------------------+ 511 | GL_NONE | VK_IMAGE_LAYOUT_UNDEFINED | 512 | GL_LAYOUT_GENERAL_EXT | VK_IMAGE_LAYOUT_GENERAL | 513 | GL_LAYOUT_COLOR_ATTACHMENT_EXT | VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL | 514 | GL_LAYOUT_DEPTH_STENCIL_ATTACHMENT_EXT | VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT | 515 | GL_LAYOUT_DEPTH_STENCIL_READ_ONLY_EXT | VK_IMAGE_LAYOUT_DEPTH_STENCIL_READ_ONLY_OPTIMAL | 516 | GL_LAYOUT_SHADER_READ_ONLY_EXT | VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL | 517 | GL_LAYOUT_TRANSFER_SRC_EXT | VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL | 518 | GL_LAYOUT_TRANSFER_DST_EXT | VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL | 519 | GL_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_EXT | VK_IMAGE_LAYOUT_DEPTH_READ_ONLY_STENCIL_ATTACHMENT_OPTIMAL_KHR | 520 | GL_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_EXT | VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_STENCIL_READ_ONLY_OPTIMAL_KHR | 521 +-------------------------------------------------------------------------------------------------------------------+ 522 523 4.2.4 Signaling Semaphores 524 525 The command 526 527 void SignalSemaphoreEXT(uint semaphore, 528 uint numBufferBarriers, 529 const uint *buffers, 530 uint numTextureBarriers, 531 const uint *textures, 532 const GLenum *dstLayouts); 533 534 will insert a semaphore signaling operation in the GL command 535 stream, and flush the command stream as if /Flush/ were inserted 536 immediately after the semaphore operation. 537 538 Prior to signaling the semaphore, memory used by the specified 539 buffer objects and textures will be made visible, and textures 540 can be transitioned to a specified internal layout to allow 541 applications to access the textures using a consistent layout in 542 an external API or process. Possible layouts are specified in 543 table 4.3, along with their corresponding layout in the Vulkan 544 API. 545 546Add a new Chapter, "Memory Objects", between Chapter 5 (Shared Objects 547and Multiple Contexts) and Chapter 6 (Buffer Objects) 548 549 Memory objects reference a fixed-size allocation of abstract server 550 memory. The memory may not be accessed directly, but may be bound 551 to other objects that require a data store in server memory. The 552 memory itself is allocated outside the scope of the GL, and is 553 merely referenced by a memory object. 554 555 The command 556 557 void CreateMemoryObjectsEXT(sizei n, uint *memoryObjects); 558 559 returns <n> previously unused memory object names in <memoryObjects>. 560 The memory objects named contain default state, but initially have no 561 external memory associated with them. 562 563 Memory objects are deleted by calling 564 565 void DeleteMemoryObjectsEXT(sizei n, const uint *memoryObjects); 566 567 <memoryObjects> contains <n> names of memory objects to be deleted. 568 After a memory object is deleted, it references no server memory, 569 and its name is again unused. 570 571 Unused names in <memoryObjects> are silently ignored, as is the 572 value zero. 573 574 The command 575 576 boolean IsMemoryObjectEXT(uint memoryObject); 577 578 returns TRUE if <memoryObject> is the name of a memory object. If 579 <memoryObject> is zero, or if <memoryObject> is a non-zero value 580 that is not the name of a memory object, IsMemoryObjectEXT returns 581 FALSE. 582 583 6.1 Importing Abstract Memory into a Memory Object 584 585 A memory object is associated with external memory by importing an 586 externally-allocated abstract memory region via a reference to an 587 associated external handle. The supported set of external handle types 588 and their corresponding import functions are listed in table 6.1. 589 590 Table 6.1: Commands for importing external memory handles. 591 592 | Handle Type | Import command | 593 +-------------+----------------+ 594 +-------------+----------------+ 595 596 Applications must only import external memory handles exported 597 from the same device or set of devices used by the current context. 598 Refer to section 4.2.1 for methods to determine which devices are 599 used by the current context. 600 601 External handles are often defined using platform-specific types. 602 Therefore, the base GL specification defines no methods to import an 603 external handle. 604 605 6.2 Memory object parameters 606 607 Memory object parameters are set using the command 608 609 void MemoryObjectParameterivEXT(uint memoryObject, 610 enum pname, 611 const int *params); 612 613 <memoryObject> is the name of the memory object on which the parameter 614 <pname> will be set to the value(s) in <params>. The possible values for 615 <pname> are specified in table 6.2. 616 617 Table 6.2: Memory Object Parameters. 618 619 | Name | Legal Values | 620 +-----------------------------+--------------+ 621 | DEDICATED_MEMORY_OBJECT_EXT | FALSE, TRUE | 622 | PROTECTED_MEMORY_OBJECT_EXT | FALSE, TRUE | 623 +-----------------------------+--------------+ 624 625 The parameter DEDICATED_MEMORY_OBJECT_EXT must be set to TRUE when the 626 external memory handle from which the object's memory will be imported 627 was created as a dedicated allocation. 628 629 The parameter PROTECTED_MEMORY_OBJECT_EXT must be set to TRUE when the 630 external memory handle from which the object's memory will be imported 631 refers to a protected resource. The definition of a protected resource 632 is outside the scope of this extension. 633 634 Memory object parameters become immutable once the object is associated 635 with external memory by an import operation. An INVALID_OPERATION error 636 is generated if <memoryObject> is immutable. 637 638 The parameters of a memory object may be queried with the command: 639 640 void GetMemoryObjectParameterivEXT(uint memoryObject 641 enum pname, 642 int *params); 643 644 The value(s) of the parameter <pname> from the memory object 645 <memoryObject> are returned in <params>. 646 647Additions to Chapter 6 of the OpenGL 4.5 Specification (Buffer Objects) 648 649 Modify the list of commands described in 6.2 "Creating and Modifying 650 Buffer Object Data Stores" to add the following: 651 652 void BufferStorageMemEXT(enum target, 653 sizeiptr size, 654 uint memory, 655 uint64 offset); 656 657 void NamedBufferStorageMemEXT(uint buffer, 658 sizeiptr size, 659 uint memory, 660 uint64 offset); 661 662 Replace the two paragraphs after the above list of commands with the 663 following: 664 665 "For BufferStorage and BufferStorageMemEXT, the buffer object is 666 that bound to <target>, which must be one of the values listed 667 in table 6.1. For NamedBufferStorage and 668 NamedBufferStorageMemEXT, <buffer> is the name of the buffer 669 object. For all the above commands, <size> is the size of the 670 data store in basic machine units. For BufferStorageMemEXT and 671 NamedBufferStorageMemEXT, <memory> and <offset> define a region 672 of abstract memory that will be used as the data store for 673 <buffer>. The implementation may restrict which values of 674 <offset> are valid for a given memory object and buffer 675 parameter combination. These restrictions are outside the scope 676 of this extension and must be determined by querying the API or 677 mechanism which created the resource which <memory> refers to. 678 If an invalid offset is specified an INVALID_VALUE error is 679 generated. 680 681 "The data store of the buffer object is allocated or referenced 682 as a result of these commands, and cannot be de-allocated or 683 unreferenced until the buffer is deleted with a call to 684 DeleteBuffers." 685 686 Replace the paragraph that beings "BufferStorage and 687 NamedBufferStorage delete..." with the following: 688 689 "BufferStorage, BufferStorageMemEXT, NamedBufferStorage, and 690 NamedBufferStorageMemEXT delete any existing data store, and set 691 the values of the buffer object's state variables as shown in 692 table 6.3." 693 694 Add the following to the list of errors for the BufferStorage 695 functions" 696 697 "An INVALID_VALUE error is generated by BufferStorageMemEXT and 698 NamedBufferStorageMemEXT if <memory> is 0, or if <offset> + 699 <size> is greater than the size of the specified 700 memory object. 701 702 "An INVALID_VALUE error is generated if <offset> is not a valid 703 value for <memory> or the texture." 704 705 "An INVALID_OPERATION error is generated if <memory> names a valid 706 memory object which has no associated memory." 707 708 Modify the header for the third column in table 6.2 to read 709 "Value for *BufferStorage*", and update the table description to 710 include the new memory object buffer storage commands. 711 712 Modify the first sentence of section 6.3, "Mapping and Unmapping 713 Buffer Data", to read as follows: 714 715 "If the data store for a buffer object is not a reference to a 716 memory object, all or part of the data store may be mapped into 717 the client's address space with the commands:" 718 719 Add the following to the list of errors for the MapBufferRange and 720 MapNamedBufferRange commands: 721 722 An INVALID_OPERATION error is generated by Map*BufferRange if 723 the specified buffer is referencing a memory object as its data 724 store. 725 726Additions to Chapter 8 of the OpenGL 4.5 Specification (Textures and 727Samplers) 728 729 For each list of TexStorage* commands in the 1D, 2D, 3D, 730 2DMultisample, and 3DMultisample families, add the following 731 variants: 732 733 void TexStorageMem*EXT(<existing parameters>, 734 uint memory, 735 uint64 offset); 736 737 void TextureStorageMem*EXT(<existing parameters>, 738 uint memory, 739 uint64 offset); 740 741 For each family of TexStorage* commands, add appropriate language to 742 the description based on the following template: 743 744 "Calling TexStorageMem*EXT or TextureStorageMem*EXT is 745 equivalent to calling TexStorage* or TextureStorage* 746 except that rather than allocating new memory for the texture's 747 image data, the memory at <offset> in the memory object 748 specified by <memory> will be used. The implementation may 749 restrict which values of <offset> are valid for a given memory 750 object and texture parameter combination. These restrictions are 751 outside the scope of this extension and must be determined by 752 querying the API or mechanism which created the resource which 753 <memory> refers to. If an invalid offset is specified an 754 INVALID_VALUE error is generated." 755 756 Add errors based on the following template for each family of 757 TexStorage* commands: 758 759 "An INVALID_VALUE error is generated if <memory> is 0, or if 760 the memory object is not large enough to contain the specified 761 texture's image data." 762 763 "An INVALID_VALUE error is generated if <offset> is not a valid 764 value for <memory> or the texture." 765 766 "An INVALID_OPERATION error is generated if <memory> names a valid 767 memory object which has no associated memory." 768 769 "An INVALID_OPERATION error is generated if <memory> is a protected 770 memory object and the texture parameter TEXTURE_PROTECTED_EXT is not 771 TRUE." 772 773 Insert the following before Table 8.17: 774 775 "If <pname> is TEXTURE_TILING_EXT then the state is stored in the 776 texture, but only takes effect the next time storage is allocated 777 from a memory object for the texture object using TexStorageMem*EXT 778 or TextureStorageMem*EXT. If the value of TEXTURE_IMMUTABLE_FORMAT 779 is TRUE, then TEXTURE_TILING_EXT cannot be changed and an 780 INVALID_OPERATION error is generated." 781 782 Add the following to table 8.17: Texture parameters and their values. 783 784 | Name | Type | Legal values | 785 +--------------------+---------+---------------------------------------+ 786 | TEXTURE_TILING_EXT | enum | OPTIMAL_TILING_EXT, LINEAR_TILING_EXT | 787 +--------------------+---------+---------------------------------------+ 788 789Additions to Chapter 21 of the OpenGL 4.5 Specification (Special Functions) 790 791 Add the following to section 21.4.1, Commands Not Usable in Display 792 Lists. 793 794 Under the "Memory objects" section: 795 796 DeleteMemoryObjectsEXT, CreateMemoryObjectsEXT, 797 MemoryObjectParameterivEXT 798 799 Under the "Pixels and textures" section: 800 801 TexStorageMem2DEXT, TexStorageMem2DMultisampleEXT, 802 TexStorageMem3DEXT, TexStorageMem3DMultisampleEXT, 803 TextureStorageMem2DEXT, TextureStorageMem2DMultisampleEXT, 804 TextureStorageMem3DEXT, TextureStorageMem3DMultisampleEXT, 805 TexStorageMem1DEXT, TextureStorageMem1DEXT 806 807 Under the "Buffer objects" section: 808 809 BufferStorageMemEXT, NamedBufferStorageMemEXT 810 811 Under the "GL command stream management" section: 812 813 GenSemaphoresEXT, DeleteSemaphoresEXT, SemaphoreParameterui64vEXT, 814 WaitSemaphoreEXT, SignalSemaphoreEXT 815 816Additions to Chapter 22 of the OpenGL 4.5 Specification (Context state 817Queries) 818 819 Add the following to the end of the first list of functions in section 820 22.1, Simple Queries: 821 822 void GetUnsignedBytevEXT(enum pname, 823 ubyte *data); 824 825 Replace the sentence following that list with: 826 827 The commands obtain boolean, integer, 64-bit integer, floating- 828 point, double-precision, or unsigned byte state variables. 829 830 Add the following to the end of the list of indexed simple state query 831 commands: 832 833 void GetUnsignedBytei_vEXT(enum target, 834 uint index, 835 ubyte *data); 836 837 838 839 Add the following to section 22.3.2, Other Internal Format Queries: 840 841 NUM_TILING_TYPES_EXT: The number of tiling types that would be 842 returned by querying TILING_TYPES_EXT is returned in <params>. 843 844 TILING_TYPES_EXT: The tiling type supported when using memory 845 objects to create textures with <internalFormat> and <target> 846 are written to <params>, in the order in which they occur in 847 table 22.3. Possible values are those listed in table 22.3. 848 849 Table 22.3: Possible tiling types supported by textures using 850 memory objects. 851 852 | Tiling Type | 853 +--------------------+ 854 | OPTIMAL_TILING_EXT | 855 | LINEAR_TILING_EXT | 856 +--------------------+ 857 858Errors 859 860New State 861 862Issues 863 864 1) Should only DSA-style texture and buffer object binding 865 functions be added to keep the number of new functions 866 to a minimum? 867 868 RESOLVED: No. Both DSA and traditional entry points will be added. 869 870 2) Should the type of the memory <size> and <offset> parameters be 871 GLsizeiptr, GLintptr, GLint64, or GLuint64? 872 873 RESOLVED: GLuint64. This matches the VkDeviceSize semantics. 874 875 3) Should there be a way to allocate memory within OpenGL in 876 addition to importing it? 877 878 RESOLVED: No. This could be covered in a separate extension, but 879 this would involve building up all the memory property 880 infrastructure Vulkan already has. Applications wishing to use 881 memory objects in OpenGL will need to leverage the allocation and 882 memory capability querying mechanisms present in Vulkan to perform 883 the actual allocations, and then map the capabilities to GL 884 equivalents when using them. 885 886 4) How are sparse textures handled? 887 888 RESOLVED: Sparse texture support is deferred to a later extension. 889 Late in the development of this specification, it was discovered 890 that naively extending TexPageCommitmentARB to accept an offset 891 and memory object parameter results in a subtly awkward interface 892 when used to build GL sparse textures equivalent to those of Vulkan 893 sparse images, due to the lack of a defined memory layout ordering 894 for array textures. Developing a better interface would have 895 further delayed release of the basic functionality defined here, 896 which is in higher demand. 897 898 5) Do memory objects created as dedicated allocations need special 899 handling? 900 901 RESOLVED: No. Like other memory regions, these allocations must be 902 bound to GL objects compatible with those they are bound to in 903 Vulkan to avoid aliasing issues, but otherwise no special handling 904 is required. 905 906 6) Should the BufferStorage functions still take a flags parameter? 907 908 RESOLVED: No. The flags are not relevant when the memory has 909 already been allocated externally. 910 911 7) Should the Buffer commands be called BufferStorage or BufferData? 912 913 RESOLVED: BufferStorage. GL has both commands, while GL ES has only 914 BufferData. The difference between the two GL commands is 915 immutability. The naming of the BufferStorage seems more consistent 916 with the usage, since data is not specified with these commands, but 917 a backing store is, and immutability for Vulkan memory-backed buffer 918 objects seems desirable. However, if GLES implementations can not 919 support immutable buffers, BufferData() support can be added in a 920 future extension with some added driver complexity. 921 922 8) Can semaphore commands be issued inside of Begin/End, or be 923 included in display lists? 924 925 RESOLVED: No. 926 927 9) Do ownership transfer and memory barrier commands need to be 928 included in the semaphore operations? 929 930 RESOLVED: Yes, these are needed for proper synchronization on some 931 implementations. Presumably only the source side of the barriers 932 needs to be specified when transitioning from external to GL usage, 933 and only the destination side needs to be specified when 934 transitioning from GL to external usage. That should give the 935 OpenGL driver sufficient knowledge to perform any needed automatic 936 transitions based on subsequent usage within the GL API. 937 938 Still, it is unclear how much of the Vulkan pipeline barrier API 939 should be explicitly exposed in the GL API: 940 941 * Should queue ownership be included? There is no equivalent 942 idiom to define this on top of in GL. However, since the 943 external side is the only portion specified by the 944 application, it could be described in Vulkan terms. 945 946 * Should image layout be included? Similar to the above, there 947 is no GL concept of this, but Vulkan terms could be leveraged. 948 949 * Should access type be included? This maps relatively well to 950 OpenGL memory barrier bits, but there is not a 1-1 951 correspondence. 952 953 * Should the pipeline stage be included? This could be mapped 954 to stages defined in the GL state machine, but such explicit 955 references to the stages are not thus far included in GL 956 language or tokens. 957 958 Another option is to require the Vulkan driver to put images, 959 buffers, and their memory in a particular state before sharing 960 them with OpenGL. For example, require applications to 961 transition to the GENERAL image layout, dstStageMask of 962 TOP_OF_PIPE or ALL_COMMANDS, dstAccessMask will include 963 MEMORY_WRITE_BIT | MEMORY_READ_BIT or some new "more external" 964 version of these, and the dstQueueFamilyIndex must be IGNORED 965 while srcQueueFamilyIndex must be a valid queue family (a 966 currently illegal situation). 967 968 10) Should the barrier functionality be included in the semaphore 969 operation commands? 970 971 RESOLVED: Yes. The only time such barriers are required in GL is 972 when synchronizing with external memory accesses, which is also the 973 only time semaphores should be used. For internal synchronization, 974 existing GL and EGL commands should be used. Since the use cases 975 align, it makes sense to make them a single command to cut down on 976 the potential for misuse and keep the API footprint as small as 977 possible. 978 979 11) Must both Gen[MemoryObjects,Semaphores]EXT commands and 980 Create[MemoryObjects,Semaphores]EXT commands be defined, or is 981 one or the other sufficient? 982 983 RESOLVED: One variant is sufficient for each object type. 984 985 12) Should buffer objects backed by memory objects be mappable? 986 987 RESOLVED: No. This would complicate the API as interactions between 988 GL and Vulkan cache flushing semantics would need to be defined. 989 990 13) Does the usage information provided when creating Vulkan images 991 need to be specified when creating textures on memory objects? 992 If so, how is it specified? 993 994 RESOLVED: There are a few options for specifying the usage in 995 OpenGL: 996 997 * Have some sort of GLX/EGL-like attrib list that allows users 998 to specify an arbitrary set of usage parameters. 999 1000 * Allow applications to re-use the Vulkan usage flags directly 1001 in GL. 1002 1003 * Re-define all the Vulkan image usage flags in GL, and update 1004 the list via new GL interop extensions as new Vulkan usage 1005 flags are added by Vulkan extensions. 1006 1007 None of these are very compelling. They all complicate the OpenGL 1008 API significantly and have a high spec maintenance burden as new 1009 extensions are added. 1010 1011 Other options for resolving the overall issue of GL knowing the 1012 usage include: 1013 1014 * Disallow Vulkan implementations from utilizing the usage 1015 information as input when determining the internal parameters of a 1016 Vulkan image used with external memory. 1017 1018 * Only allow Vulkan implementations to utilize the usage information 1019 when using the dedicated allocation path where it can be stored as 1020 a form of metadata along with the memory. 1021 1022 * Require applications to specify all supported usage flags at image 1023 creation time on the Vulkan side for images that are intended to 1024 alias with OpenGL textures. 1025 1026 The first two options have the downside of potentially limiting the 1027 ability of implementations to fully optimize external images 1028 regardless of their use case. The last option constrains the 1029 limitations to the case of interoperation with OpenGL, making it a 1030 less onerous requirement for implementations while still keeping the 1031 OpenGL side of the API relatively simple compared to the options 1032 involving re-specification of image usage on the OpenGL side. 1033 1034 The agreed resolution is to use the final option: Require all 1035 supported usage flags be specified by the application on the Vulkan 1036 side if the image is intended to alias with an OpenGL texture. 1037 1038 14) Are memory barriers for textures and buffer objects needed with 1039 semaphore signal/wait operations, or should a blanket availability/ 1040 visibility rule be applied like in Vulkan<->Vulkan semaphore 1041 synchronization? 1042 1043 RESOLVED: Perhaps extra availability/visibility operations need to 1044 be performed to enable external accesses, so it is safest to require 1045 explicit specification of the resources that need to be made 1046 available and visible as part of a semaphore synchronization 1047 operation. 1048 1049 15) Are OpenGL equivalents of the Vulkan image creation flags related to 1050 sparse properties needed? 1051 1052 RESOLVED: Sparse support is not included in this extension. 1053 1054 Prior to this resolution, the proposed resolution was as follows: 1055 1056 No. For the purposes of OpenGL, the functionality of all the Vulkan 1057 sparse image creation flags is contained in the existing 1058 TEXTURE_SPARSE texture parameter. Because OpenGL does not have the 1059 same sparse feature granularity as Vulkan, applications wishing to 1060 create a sparse image that will alias with an OpenGL sparse texture 1061 will be required to set all of the sparse bits. Images not intended 1062 to alias with an OpenGL texture without the TEXTURE_SPARSE flag set 1063 must have none of the Vulkan sparse bits set. 1064 1065 16) How do Vulkan sparse block sizes and OpenGL virtual page sizes 1066 interact? 1067 1068 RESOLVED: Sparse support is not included in this extension. 1069 1070 Prior to this resolution, the proposed resolution was as follows: 1071 1072 The application must use an OpenGL virtual page size with dimensions 1073 matching those of the Vulkan sparse block size for any Vulkan images 1074 aliasing OpenGL sparse textures. If no such virtual page size exists, 1075 such aliasing is not supported. 1076 1077 17) Is an OpenGL equivalent of the mutable format Vulkan image creation 1078 parameter needed? 1079 1080 RESOLVED: No. However, Vulkan applications will be required to set 1081 the mutable format bit when creating an image that will alias with 1082 an OpenGL texture on an OpenGL implementation that supports 1083 ARB_texture_view, OES_texture_view, EXT_texture_view, or OpenGL 4.3 1084 and above. 1085 1086 18) Is an OpenGL equivalent of the tiling Vulkan image creation 1087 parameter needed? 1088 1089 RESOLVED: Yes. Further, OpenGL implementations may not support 1090 creating textures from Vulkan images using certain tiling types, so 1091 a query is needed to determine the types supported. 1092 1093 19) Is a way to specify dedicated allocation semantics needed? 1094 1095 RESOLVED: Yes. Importing dedicated allocation-style memory may 1096 require the driver to use different paths than importing purely 1097 abstract memory. Additionally, textures and buffer objects may need to derive meta-data from their associated memory object if 1098 it is a dedicated allocation. Therefore, a dedicated allocation 1099 parameter should be added to the memory objects. Additional 1100 parameters for textures and buffer objects are not required because 1101 unlike Vulkan, OpenGL exposes no application-visible texture or 1102 buffer state that would vary depending on whether a dedicated 1103 allocation will be used for their storage. Therefore, they can 1104 inherit the state from the memory object associated with them at 1105 storage specification time. Note that allowing parameters to be 1106 specified on a memory object prior to the import operation requires 1107 separate memory import from memory object instantiation commands. 1108 1109 20) How should devices be correlated between OpenGL Vulkan, and other 1110 APIs? 1111 1112 RESOLVED: Device UUID, LUID, and node mask queries are introduced, 1113 corresponding to those added to the Vulkan API for external memory/ 1114 semaphore purposes. Because contexts may be associated with 1115 multiple physical GPUs in some cases, multiple values are returned 1116 for device UUIDs and multiple bits are set in the device node masks. 1117 It is not expected that a single context will be associated with 1118 multiple DXGI adapters, so only one LUID is returned. 1119 1120 When sharing with Vulkan device groups, the device UUIDs used by the 1121 context must match those of the Vulkan physical devices in the 1122 Vulkan device group. Future extensions could relax this 1123 requirement. 1124 1125 21) How do applications determine valid values for the <offset> 1126 parameter of the new storage allocation/binding functions? 1127 1128 RESOLVED: This is outside the scope of this extension. The API or 1129 mechanism which allocated the memory must provide this information. 1130 However, the GL will generate an error if an invalid offset is used. 1131 1132 22) Are there any interactions with the EXT_protected_textures 1133 extension? 1134 1135 RESOLVED: Yes. Memory objects can be marked as protected or not 1136 protected before import. This state must match that of the 1137 imported resource. For all textures bound to a given memory object, 1138 the value of the TEXTURE_PROTECTED_EXT parameter of the textures 1139 must match the PROTECTED_MEMORY_OBJECT_EXT parameter of the memory 1140 object. 1141 1142 23) How do applications detect when the new texture layouts 1143 corresponding to the image layouts in VK_KHR_maintenance2 are 1144 supported in OpenGL? 1145 1146 RESOLVED: OpenGL contexts that report the GL_EXT_semaphore extension 1147 string and have a DRIVER_UUID_EXT and DEVICE_UUID_EXT corresponding 1148 to a Vulkan driver that supports VK_KHR_maintenance2 must support 1149 the new OpenGL texture layouts. 1150 1151Revision History 1152 1153 Revision 15, 2022-07-15 (James Jones) 1154 - Noted SignalSemaphoreEXT implicitly flushes the command stream 1155 - Added commands to the list of commands not permitted in display 1156 lists. 1157 1158 Revision 14, 2018-07-18 (James Jones) 1159 - Fixed a typo: Replace NamedBufferStroage with NamedBufferStorage 1160 1161 Revision 13, 2017-09-26 (James Jones) 1162 - Added new image layouts corresponding to those from 1163 VK_KHR_maintenance2. 1164 - Added issue 23 and resolution. 1165 1166 Revision 12, 2017-06-08 (Andres Rodriguez) 1167 - Fixed parameter name in MemoryObjectParameterivEXT's description. 1168 - Fixed missing EXT suffix in some mentions of GetUnsignedByte* 1169 1170 Revision 11, 2017-06-02 (James Jones) 1171 - Added extension numbers. 1172 - Fixed the name of GetSemaphoreParameterui64vEXT. 1173 - Clarified which extensions each command and token belongs to. 1174 - Marked complete. 1175 1176 Revision 10, 2017-05-24 (James Jones) 1177 - Added issue 21 and resolution. 1178 - Added issue 22 and resolution. 1179 - Removed sparse texture support. 1180 - Filled in real token values 1181 - Further documented the new LAYOUT tokens. 1182 1183 Revision 9, 2017-04-05 (James Jones) 1184 - Added context device UUID queries. 1185 1186 Revision 8, 2017-04-04 (James Jones) 1187 - Clarified semaphore semantics 1188 1189 Revision 7, 2017-03-28 (James Jones) 1190 - Fixed various typos. 1191 1192 Revision 6, 2017-03-17 (James Jones) 1193 - Renamed from KHR to EXT. 1194 - Added texture tiling parameters. 1195 - Added semaphore parameter manipulation functions. 1196 - Replaced GenMemoryObjectsEXT with CreateMemoryObjectsEXT 1197 - Added memory object parameter manipulation functions. 1198 - Updated issue 13 with a proposed resolution. 1199 - Added issues 15-19 and proposed resolutions. 1200 1201 Revision 5, 2016-10-22 (James Jones) 1202 - Added proposed memory barrier semantics to the semaphore commands. 1203 - Added issue 14. 1204 - Added some clarifications to issue 13 1205 1206 Revision 4, 2016-09-28 (James Jones) 1207 - Merged in GL_KHR_semaphore to reduce number of specs. 1208 - Added spec body describing the new commands. 1209 - Added issues 9-13. 1210 1211 Revision 3, 2016-08-15 (James Jones and Jeff Juliano) 1212 - Clarified overview text. 1213 1214 Revision 2, 2016-08-07 (James Jones) 1215 - Added non-contiguous sparse binding support via 1216 TexPageCommitmentMemKHR(). 1217 1218 Revision 1, 2016-08-05 (James Jones) 1219 - Initial draft. 1220