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 XXX. 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.3. 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. 536 537 Prior to signaling the semaphore, memory used by the specified 538 buffer objects and textures will be made visible, and textures 539 can be transitioned to a specified internal layout to allow 540 applications to access the textures using a consistent layout in 541 an external API or process. Possible layouts are specified in 542 table 4.3, along with their corresponding layout in the Vulkan 543 API. 544 545Add a new Chapter, "Memory Objects", between Chapter 5 (Shared Objects 546and Multiple Contexts) and Chapter 6 (Buffer Objects) 547 548 Memory objects reference a fixed-size allocation of abstract server 549 memory. The memory may not be accessed directly, but may be bound 550 to other objects that require a data store in server memory. The 551 memory itself is allocated outside the scope of the GL, and is 552 merely referenced by a memory object. 553 554 The command 555 556 void CreateMemoryObjectsEXT(sizei n, uint *memoryObjects); 557 558 returns <n> previously unused memory object names in <memoryObjects>. 559 The memory objects named contain default state, but initially have no 560 external memory associated with them. 561 562 Memory objects are deleted by calling 563 564 void DeleteMemoryObjectsEXT(sizei n, const uint *memoryObjects); 565 566 <memoryObjects> contains <n> names of memory objects to be deleted. 567 After a memory object is deleted, it references no server memory, 568 and its name is again unused. 569 570 Unused names in <memoryObjects> are silently ignored, as is the 571 value zero. 572 573 The command 574 575 boolean IsMemoryObjectEXT(uint memoryObject); 576 577 returns TRUE if <memoryObject> is the name of a memory object. If 578 <memoryObject> is zero, or if <memoryObject> is a non-zero value 579 that is not the name of a memory object, IsMemoryObjectEXT returns 580 FALSE. 581 582 6.1 Importing Abstract Memory into a Memory Object 583 584 A memory object is associated with external memory by importing an 585 externally-allocated abstract memory region via a reference to an 586 associated external handle. The supported set of external handle types 587 and their corresponding import functions are listed in table 6.1. 588 589 Table 6.1: Commands for importing external memory handles. 590 591 | Handle Type | Import command | 592 +-------------+----------------+ 593 +-------------+----------------+ 594 595 Applications must only import external memory handles exported 596 from the same device or set of devices used by the current context. 597 Refer to section 4.2.1 for methods to determine which devices are 598 used by the current context. 599 600 External handles are often defined using platform-specific types. 601 Therefore, the base GL specification defines no methods to import an 602 external handle. 603 604 6.2 Memory object parameters 605 606 Memory object parameters are set using the command 607 608 void MemoryObjectParameterivEXT(uint memoryObject, 609 enum pname, 610 const int *params); 611 612 <memoryObject> is the name of the memory object on which the parameter 613 <pname> will be set to the value(s) in <params>. The possible values for 614 <pname> are specified in table 6.2. 615 616 Table 6.2: Memory Object Parameters. 617 618 | Name | Legal Values | 619 +-----------------------------+--------------+ 620 | DEDICATED_MEMORY_OBJECT_EXT | FALSE, TRUE | 621 | PROTECTED_MEMORY_OBJECT_EXT | FALSE, TRUE | 622 +-----------------------------+--------------+ 623 624 The parameter DEDICATED_MEMORY_OBJECT_EXT must be set to TRUE when the 625 external memory handle from which the object's memory will be imported 626 was created as a dedicated allocation. 627 628 The parameter PROTECTED_MEMORY_OBJECT_EXT must be set to TRUE when the 629 external memory handle from which the object's memory will be imported 630 refers to a protected resource. The definition of a protected resource 631 is outside the scope of this extension. 632 633 Memory object parameters become immutable once the object is associated 634 with external memory by an import operation. An INVALID_OPERATION error 635 is generated if <memoryObject> is immutable. 636 637 The parameters of a memory object may be queried with the command: 638 639 void GetMemoryObjectParameterivEXT(uint memoryObject 640 enum pname, 641 int *params); 642 643 The value(s) of the parameter <pname> from the memory object 644 <memoryObject> are returned in <params>. 645 646Additions to Chapter 6 of the OpenGL 4.5 Specification (Buffer Objects) 647 648 Modify the list of commands described in 6.2 "Creating and Modifying 649 Buffer Object Data Stores" to add the following: 650 651 void BufferStorageMemEXT(enum target, 652 sizeiptr size, 653 uint memory, 654 uint64 offset); 655 656 void NamedBufferStorageMemEXT(uint buffer, 657 sizeiptr size, 658 uint memory, 659 uint64 offset); 660 661 Replace the two paragraphs after the above list of commands with the 662 following: 663 664 "For BufferStorage and BufferStorageMemEXT, the buffer object is 665 that bound to <target>, which must be one of the values listed 666 in table 6.1. For NamedBufferStorage and 667 NamedBufferStorageMemEXT, <buffer> is the name of the buffer 668 object. For all the above commands, <size> is the size of the 669 data store in basic machine units. For BufferStorageMemEXT and 670 NamedBufferStorageMemEXT, <memory> and <offset> define a region 671 of abstract memory that will be used as the data store for 672 <buffer>. The implementation may restrict which values of 673 <offset> are valid for a given memory object and buffer 674 parameter combination. These restrictions are outside the scope 675 of this extension and must be determined by querying the API or 676 mechanism which created the resource which <memory> refers to. 677 If an invalid offset is specified an INVALID_VALUE error is 678 generated. 679 680 "The data store of the buffer object is allocated or referenced 681 as a result of these commands, and cannot be de-allocated or 682 unreferenced until the buffer is deleted with a call to 683 DeleteBuffers." 684 685 Replace the paragraph that beings "BufferStorage and 686 NamedBufferStorage delete..." with the following: 687 688 "BufferStorage, BufferStorageMemEXT, NamedBufferStorage, and 689 NamedBufferStorageMemEXT delete any existing data store, and set 690 the values of the buffer object's state variables as shown in 691 table 6.3." 692 693 Add the following to the list of errors for the BufferStorage 694 functions" 695 696 "An INVALID_VALUE error is generated by BufferStorageMemEXT and 697 NamedBufferStorageMemEXT if <memory> is 0, or if <offset> + 698 <size> is greater than the size of the specified 699 memory object. 700 701 "An INVALID_VALUE error is generated if <offset> is not a valid 702 value for <memory> or the texture." 703 704 "An INVALID_OPERATION error is generated if <memory> names a valid 705 memory object which has no associated memory." 706 707 Modify the header for the third column in table 6.2 to read 708 "Value for *BufferStorage*", and update the table description to 709 include the new memory object buffer storage commands. 710 711 Modify the first sentence of section 6.3, "Mapping and Unmapping 712 Buffer Data", to read as follows: 713 714 "If the data store for a buffer object is not a reference to a 715 memory object, all or part of the data store may be mapped into 716 the client's address space with the commands:" 717 718 Add the following to the list of errors for the MapBufferRange and 719 MapNamedBufferRange commands: 720 721 An INVALID_OPERATION error is generated by Map*BufferRange if 722 the specified buffer is referencing a memory object as its data 723 store. 724 725Additions to Chapter 8 of the OpenGL 4.5 Specification (Textures and 726Samplers) 727 728 For each list of TexStorage* commands in the 1D, 2D, 3D, 729 2DMultisample, and 3DMultisample families, add the following 730 variants: 731 732 void TexStorageMem*EXT(<existing parameters>, 733 uint memory, 734 uint64 offset); 735 736 void TextureStorageMem*EXT(<existing parameters>, 737 uint memory, 738 uint64 offset); 739 740 For each family of TexStorage* commands, add appropriate language to 741 the description based on the following template: 742 743 "Calling TexStorageMem*EXT or TextureStorageMem*EXT is 744 equivalent to calling TexStorage* or TextureStorage* 745 except that rather than allocating new memory for the texture's 746 image data, the memory at <offset> in the memory object 747 specified by <memory> will be used. The implementation may 748 restrict which values of <offset> are valid for a given memory 749 object and texture parameter combination. These restrictions are 750 outside the scope of this extension and must be determined by 751 querying the API or mechanism which created the resource which 752 <memory> refers to. If an invalid offset is specified an 753 INVALID_VALUE error is generated." 754 755 Add errors based on the following template for each family of 756 TexStorage* commands: 757 758 "An INVALID_VALUE error is generated if <memory> is 0, or if 759 the memory object is not large enough to contain the specified 760 texture's image data." 761 762 "An INVALID_VALUE error is generated if <offset> is not a valid 763 value for <memory> or the texture." 764 765 "An INVALID_OPERATION error is generated if <memory> names a valid 766 memory object which has no associated memory." 767 768 "An INVALID_OPERATION error is generated if <memory> is a protected 769 memory object and the texture parameter TEXTURE_PROTECTED_EXT is not 770 TRUE." 771 772 Insert the following before Table 8.17: 773 774 "If <pname> is TEXTURE_TILING_EXT then the state is stored in the 775 texture, but only takes effect the next time storage is allocated 776 from a memory object for the texture object using TexStorageMem*EXT 777 or TextureStorageMem*EXT. If the value of TEXTURE_IMMUTABLE_FORMAT 778 is TRUE, then TEXTURE_TILING_EXT cannot be changed and an 779 INVALID_OPERATION error is generated." 780 781 Add the following to table 8.17: Texture parameters and their values. 782 783 | Name | Type | Legal values | 784 +--------------------+---------+---------------------------------------+ 785 | TEXTURE_TILING_EXT | enum | OPTIMAL_TILING_EXT, LINEAR_TILING_EXT | 786 +--------------------+---------+---------------------------------------+ 787 788Additions to Chapter 22 of the OpenGL 4.5 Specification (Context state 789Queries) 790 791 Add the following to the end of the first list of functions in section 792 22.1, Simple Queries: 793 794 void GetUnsignedBytevEXT(enum pname, 795 ubyte *data); 796 797 Replace the sentence following that list with: 798 799 The commands obtain boolean, integer, 64-bit integer, floating- 800 point, double-precision, or unsigned byte state variables. 801 802 Add the following to the end of the list of indexed simple state query 803 commands: 804 805 void GetUnsignedBytei_vEXT(enum target, 806 uint index, 807 ubyte *data); 808 809 810 811 Add the following to section 22.3.2, Other Internal Format Queries: 812 813 NUM_TILING_TYPES_EXT: The number of tiling types that would be 814 returned by querying TILING_TYPES_EXT is returned in <params>. 815 816 TILING_TYPES_EXT: The tiling type supported when using memory 817 objects to create textures with <internalFormat> and <target> 818 are written to <params>, in the order in which they occur in 819 table 22.3. Possible values are those listed in table 22.3. 820 821 Table 22.3: Possible tiling types supported by textures using 822 memory objects. 823 824 | Tiling Type | 825 +--------------------+ 826 | OPTIMAL_TILING_EXT | 827 | LINEAR_TILING_EXT | 828 +--------------------+ 829 830Errors 831 832New State 833 834Issues 835 836 1) Should only DSA-style texture and buffer object binding 837 functions be added to keep the number of new functions 838 to a minimum? 839 840 RESOLVED: No. Both DSA and traditional entry points will be added. 841 842 2) Should the type of the memory <size> and <offset> parameters be 843 GLsizeiptr, GLintptr, GLint64, or GLuint64? 844 845 RESOLVED: GLuint64. This matches the VkDeviceSize semantics. 846 847 3) Should there be a way to allocate memory within OpenGL in 848 addition to importing it? 849 850 RESOLVED: No. This could be covered in a separate extension, but 851 this would involve building up all the memory property 852 infrastructure Vulkan already has. Applications wishing to use 853 memory objects in OpenGL will need to leverage the allocation and 854 memory capability querying mechanisms present in Vulkan to perform 855 the actual allocations, and then map the capabilities to GL 856 equivalents when using them. 857 858 4) How are sparse textures handled? 859 860 RESOLVED: Sparse texture support is deferred to a later extension. 861 Late in the development of this specification, it was discovered 862 that naively extending TexPageCommitmentARB to accept an offset 863 and memory object parameter results in a subtly awkward interface 864 when used to build GL sparse textures equivalent to those of Vulkan 865 sparse images, due to the lack of a defined memory layout ordering 866 for array textures. Developing a better interface would have 867 further delayed release of the basic functionality defined here, 868 which is in higher demand. 869 870 5) Do memory objects created as dedicated allocations need special 871 handling? 872 873 RESOLVED: No. Like other memory regions, these allocations must be 874 bound to GL objects compatible with those they are bound to in 875 Vulkan to avoid aliasing issues, but otherwise no special handling 876 is required. 877 878 6) Should the BufferStorage functions still take a flags parameter? 879 880 RESOLVED: No. The flags are not relevant when the memory has 881 already been allocated externally. 882 883 7) Should the Buffer commands be called BufferStorage or BufferData? 884 885 RESOLVED: BufferStorage. GL has both commands, while GL ES has only 886 BufferData. The difference between the two GL commands is 887 immutability. The naming of the BufferStorage seems more consistent 888 with the usage, since data is not specified with these commands, but 889 a backing store is, and immutability for Vulkan memory-backed buffer 890 objects seems desirable. However, if GLES implementations can not 891 support immutable buffers, BufferData() support can be added in a 892 future extension with some added driver complexity. 893 894 8) Can semaphore commands be issued inside of Begin/End, or be 895 included in display lists? 896 897 RESOLVED: No. 898 899 9) Do ownership transfer and memory barrier commands need to be 900 included in the semaphore operations? 901 902 RESOLVED: Yes, these are needed for proper synchronization on some 903 implementations. Presumably only the source side of the barriers 904 needs to be specified when transitioning from external to GL usage, 905 and only the destination side needs to be specified when 906 transitioning from GL to external usage. That should give the 907 OpenGL driver sufficient knowledge to perform any needed automatic 908 transitions based on subsequent usage within the GL API. 909 910 Still, it is unclear how much of the Vulkan pipeline barrier API 911 should be explicitly exposed in the GL API: 912 913 * Should queue ownership be included? There is no equivalent 914 idiom to define this on top of in GL. However, since the 915 external side is the only portion specified by the 916 application, it could be described in Vulkan terms. 917 918 * Should image layout be included? Similar to the above, there 919 is no GL concept of this, but Vulkan terms could be leveraged. 920 921 * Should access type be included? This maps relatively well to 922 OpenGL memory barrier bits, but there is not a 1-1 923 correspondence. 924 925 * Should the pipeline stage be included? This could be mapped 926 to stages defined in the GL state machine, but such explicit 927 references to the stages are not thus far included in GL 928 language or tokens. 929 930 Another option is to require the Vulkan driver to put images, 931 buffers, and their memory in a particular state before sharing 932 them with OpenGL. For example, require applications to 933 transition to the GENERAL image layout, dstStageMask of 934 TOP_OF_PIPE or ALL_COMMANDS, dstAccessMask will include 935 MEMORY_WRITE_BIT | MEMORY_READ_BIT or some new "more external" 936 version of these, and the dstQueueFamilyIndex must be IGNORED 937 while srcQueueFamilyIndex must be a valid queue family (a 938 currently illegal situation). 939 940 10) Should the barrier functionality be included in the semaphore 941 operation commands? 942 943 RESOLVED: Yes. The only time such barriers are required in GL is 944 when synchronizing with external memory accesses, which is also the 945 only time semaphores should be used. For internal synchronization, 946 existing GL and EGL commands should be used. Since the use cases 947 align, it makes sense to make them a single command to cut down on 948 the potential for misuse and keep the API footprint as small as 949 possible. 950 951 11) Must both Gen[MemoryObjects,Semaphores]EXT commands and 952 Create[MemoryObjects,Semaphores]EXT commands be defined, or is 953 one or the other sufficient? 954 955 RESOLVED: One variant is sufficient for each object type. 956 957 12) Should buffer objects backed by memory objects be mappable? 958 959 RESOLVED: No. This would complicate the API as interactions between 960 GL and Vulkan cache flushing semantics would need to be defined. 961 962 13) Does the usage information provided when creating Vulkan images 963 need to be specified when creating textures on memory objects? 964 If so, how is it specified? 965 966 RESOLVED: There are a few options for specifying the usage in 967 OpenGL: 968 969 * Have some sort of GLX/EGL-like attrib list that allows users 970 to specify an arbitrary set of usage parameters. 971 972 * Allow applications to re-use the Vulkan usage flags directly 973 in GL. 974 975 * Re-define all the Vulkan image usage flags in GL, and update 976 the list via new GL interop extensions as new Vulkan usage 977 flags are added by Vulkan extensions. 978 979 None of these are very compelling. They all complicate the OpenGL 980 API significantly and have a high spec maintenance burden as new 981 extensions are added. 982 983 Other options for resolving the overall issue of GL knowing the 984 usage include: 985 986 * Disallow Vulkan implementations from utilizing the usage 987 information as input when determining the internal parameters of a 988 Vulkan image used with eternal memory. 989 990 * Only allow Vulkan implementations to utilize the usage information 991 when using the dedicated allocation path where it can be stored as 992 a form of metadata along with the memory. 993 994 * Require applications to specify all supported usage flags at image 995 creation time on the Vulkan side for images that are intended to 996 alias with OpenGL textures. 997 998 The first two options have the downside of potentially limiting the 999 ability of implementations to fully optimize external images 1000 regardless of their use case. The last option constrains the 1001 limitations to the case of interoperation with OpenGL, making it a 1002 less onerous requirement for implementations while still keeping the 1003 OpenGL side of the API relatively simple compared to the options 1004 involving re-specification of image usage on the OpenGL side. 1005 1006 The agreed resolution is to use the final option: Require all 1007 supported usage flags be specified by the application on the Vulkan 1008 side if the image is intended to alias with an OpenGL texture. 1009 1010 14) Are memory barriers for textures and buffer objects needed with 1011 semaphore signal/wait operations, or should a blanket availability/ 1012 visibility rule be applied like in Vulkan<->Vulkan semaphore 1013 synchronization? 1014 1015 RESOLVED: Perhaps extra availability/visibility operations need to 1016 be performed to enable external accesses, so it is safest to require 1017 explicit specification of the resources that need to be made 1018 available and visible as part of a semaphore synchronization 1019 operation. 1020 1021 15) Are OpenGL equivalents of the Vulkan image creation flags related to 1022 sparse properties needed? 1023 1024 RESOLVED: Sparse support is not included in this extension. 1025 1026 Prior to this resolution, the proposed resolution was as follows: 1027 1028 No. For the purposes of OpenGL, the functionality of all the Vulkan 1029 sparse image creation flags is contained in the existing 1030 TEXTURE_SPARSE texture parameter. Because OpenGL does not have the 1031 same sparse feature granularity as Vulkan, applications wishing to 1032 create a sparse image that will alias with an OpenGL sparse texture 1033 will be required to set all of the sparse bits. Images not intended 1034 to alias with an OpenGL texture without the TEXTURE_SPARSE flag set 1035 must have none of the Vulkan sparse bits set. 1036 1037 16) How do Vulkan sparse block sizes and OpenGL virtual page sizes 1038 interact? 1039 1040 RESOLVED: Sparse support is not included in this extension. 1041 1042 Prior to this resolution, the proposed resolution was as follows: 1043 1044 The application must use an OpenGL virtual page size with dimensions 1045 matching those of the Vulkan sparse block size for any Vulkan images 1046 aliasing OpenGL sparse textures. If no such virtual page size exists, 1047 such aliasing is not supported. 1048 1049 17) Is an OpenGL equivalent of the mutable format Vulkan image creation 1050 parameter needed? 1051 1052 RESOLVED: No. However, Vulkan applications will be required to set 1053 the mutable format bit when creating an image that will alias with 1054 an OpenGL texture on an OpenGL implementation that supports 1055 ARB_texture_view, OES_texture_view, EXT_texture_view, or OpenGL 4.3 1056 and above. 1057 1058 18) Is an OpenGL equivalent of the tiling Vulkan image creation 1059 parameter needed? 1060 1061 RESOLVED: Yes. Further, OpenGL implementations may not support 1062 creating textures from Vulkan images using certain tiling types, so 1063 a query is needed to determine the types supported. 1064 1065 19) Is a way to specify dedicated allocation semantics needed? 1066 1067 RESOLVED: Yes. Importing dedicated allocation-style memory may 1068 require the driver to use different paths than importing purely 1069 abstract memory. Additionally, textures and buffer objects may need to derive meta-data from their associated memory object if 1070 it is a dedicated allocation. Therefore, a dedicated allocation 1071 parameter should be added to the memory objects. Additional 1072 parameters for textures and buffer objects are not required because 1073 unlike Vulkan, OpenGL exposes no application-visible texture or 1074 buffer state that would vary depending on whether a dedicated 1075 allocation will be used for their storage. Therefore, they can 1076 inherit the state from the memory object associated with them at 1077 storage specification time. Note that allowing parameters to be 1078 specified on a memory object prior to the import operation requires 1079 separate memory import from memory object instantiation commands. 1080 1081 20) How should devices be correlated between OpenGL Vulkan, and other 1082 APIs? 1083 1084 RESOLVED: Device UUID, LUID, and node mask queries are introduced, 1085 corresponding to those added to the Vulkan API for external memory/ 1086 semaphore purposes. Because contexts may be associated with 1087 multiple physical GPUs in some cases, multiple values are returned 1088 for device UUIDs and multiple bits are set in the device node masks. 1089 It is not expected that a single context will be associated with 1090 multiple DXGI adapters, so only one LUID is returned. 1091 1092 When sharing with Vulkan device groups, the device UUIDs used by the 1093 context must match those of the Vulkan physical devices in the 1094 Vulkan device group. Future extensions could relax this 1095 requirement. 1096 1097 21) How do applications determine valid values for the <offset> 1098 parameter of the new storage allocation/binding functions? 1099 1100 RESOLVED: This is outside the scope of this extension. The API or 1101 mechanism which allocated the memory must provide this information. 1102 However, the GL will generate an error if an invalid offset is used. 1103 1104 22) Are there any interactions with the EXT_protected_textures 1105 extension? 1106 1107 RESOLVED: Yes. Memory objects can be marked as protected or not 1108 protected before import. This state must match that of the 1109 imported resource. For all textures bound to a given memory object, 1110 the value of the TEXTURE_PROTECTED_EXT parameter of the textures 1111 must match the PROTECTED_MEMORY_OBJECT_EXT parameter of the memory 1112 object. 1113 1114 23) How do applications detect when the new texture layouts 1115 corresponding to the image layouts in VK_KHR_maintenance2 are 1116 supported in OpenGL? 1117 1118 RESOLVED: OpenGL contexts that report the GL_EXT_semaphore extension 1119 string and have a DRIVER_UUID_EXT and DEVICE_UUID_EXT corresponding 1120 to a Vulkan driver that supports VK_KHR_maintenance2 must support 1121 the new OpenGL texture layouts. 1122 1123Revision History 1124 1125 Revision 14, 2018-07-18 (James Jones) 1126 - Fixed a typo: Replace NamedBufferStroage with NamedBufferStorage 1127 1128 Revision 13, 2017-09-26 (James Jones) 1129 - Added new image layouts corresponding to those from 1130 VK_KHR_maintenance2. 1131 - Added issue 23 and resolution. 1132 1133 Revision 12, 2017-06-08 (Andres Rodriguez) 1134 - Fixed parameter name in MemoryObjectParameterivEXT's description. 1135 - Fixed missing EXT suffix in some mentions of GetUnsignedByte* 1136 1137 Revision 11, 2017-06-02 (James Jones) 1138 - Added extension numbers. 1139 - Fixed the name of GetSemaphoreParameterui64vEXT. 1140 - Clarified which extensions each command and token belongs to. 1141 - Marked complete. 1142 1143 Revision 10, 2017-05-24 (James Jones) 1144 - Added issue 21 and resolution. 1145 - Added issue 22 and resolution. 1146 - Removed sparse texture support. 1147 - Filled in real token values 1148 - Further documented the new LAYOUT tokens. 1149 1150 Revision 9, 2017-04-05 (James Jones) 1151 - Added context device UUID queries. 1152 1153 Revision 8, 2017-04-04 (James Jones) 1154 - Clarified semaphore semantics 1155 1156 Revision 7, 2017-03-28 (James Jones) 1157 - Fixed various typos. 1158 1159 Revision 6, 2017-03-17 (James Jones) 1160 - Renamed from KHR to EXT. 1161 - Added texture tiling parameters. 1162 - Added semaphore parameter manipulation functions. 1163 - Replaced GenMemoryObjectsEXT with CreateMemoryObjectsEXT 1164 - Added memory object parameter manipulation functions. 1165 - Updated issue 13 with a proposed resolution. 1166 - Added issues 15-19 and proposed resolutions. 1167 1168 Revision 5, 2016-10-22 (James Jones) 1169 - Added proposed memory barrier semantics to the semaphore commands. 1170 - Added issue 14. 1171 - Added some clarifications to issue 13 1172 1173 Revision 4, 2016-09-28 (James Jones) 1174 - Merged in GL_KHR_semaphore to reduce number of specs. 1175 - Added spec body describing the new commands. 1176 - Added issues 9-13. 1177 1178 Revision 3, 2016-08-15 (James Jones and Jeff Juliano) 1179 - Clarified overview text. 1180 1181 Revision 2, 2016-08-07 (James Jones) 1182 - Added non-contiguous sparse binding support via 1183 TexPageCommitmentMemKHR(). 1184 1185 Revision 1, 2016-08-05 (James Jones) 1186 - Initial draft. 1187