1Name 2 3 ARB_sync 4 5Name Strings 6 7 GL_ARB_sync 8 9Contributors 10 11 Barthold Lichtenbelt, NVIDIA 12 Bill Licea-Kane, ATI 13 Greg Roth, NVIDIA 14 Jeff Bolz, NVIDIA 15 Jeff Juliano, NVIDIA 16 Jeremy Sandmel, Apple 17 John Kessenich, Intel 18 Jon Leech, Khronos 19 Piers Daniell, NVIDIA 20 21Contact 22 23 Jon Leech (jon 'at' alumni.caltech.edu) 24 25Notice 26 27 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 28 http://www.khronos.org/registry/speccopyright.html 29 30Specification Update Policy 31 32 Khronos-approved extension specifications are updated in response to 33 issues and bugs prioritized by the Khronos OpenGL Working Group. For 34 extensions which have been promoted to a core Specification, fixes will 35 first appear in the latest version of that core Specification, and will 36 eventually be backported to the extension document. This policy is 37 described in more detail at 38 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 39 40IP Status 41 42 US patent #6025855 may bear on this extension (based on ARB 43 discussion in March, 2003). 44 45 The related NV_fence extension is marked "NVIDIA Proprietary". 46 47Status 48 49 Complete. Approved by the ARB on July 3, 2009. 50 51Version 52 53 September 18, 2009 (version 25) 54 55Number 56 57 ARB Extension #66 58 59Dependencies 60 61 OpenGL 3.1 is required. 62 63 The functionality of ARB_sync was added to the OpenGL 3.2 core. 64 65Overview 66 67 This extension introduces the concept of "sync objects". Sync 68 objects are a synchronization primitive - a representation of events 69 whose completion status can be tested or waited upon. One specific 70 type of sync object, the "fence sync object", is supported in this 71 extension, and additional types can easily be added in the future. 72 73 Fence sync objects have corresponding fences, which are inserted 74 into the OpenGL command stream at the time the sync object is 75 created. A sync object can be queried for a given condition. The 76 only condition supported for fence sync objects is completion of the 77 corresponding fence command. Fence completion allows applications to 78 request a partial Finish, wherein all commands prior to the fence 79 will be forced to complete before control is returned to the calling 80 process. 81 82 These new mechanisms allow for synchronization between the host CPU 83 and the GPU, which may be accessing the same resources (typically 84 memory), as well as between multiple GL contexts bound to multiple 85 threads in the host CPU. 86 87New Types 88 89 (Implementer's Note: GLint64 and GLuint64 are defined as appropriate 90 for an ISO C 99 compiler. Other language bindings, or non-ISO 91 compilers, may need to use a different approach). 92 93 #include <inttypes.h> 94 typedef int64_t GLint64; 95 typedef uint64_t GLuint64; 96 typedef struct __GLsync *GLsync; 97 98New Procedures and Functions 99 100 sync FenceSync(enum condition,bitfield flags) 101 boolean IsSync(sync sync) 102 void DeleteSync(sync sync) 103 104 enum ClientWaitSync(sync sync,bitfield flags,uint64 timeout) 105 void WaitSync(sync sync,bitfield flags,uint64 timeout) 106 107 void GetInteger64v(enum pname, int64 *params); 108 void GetSynciv(sync sync,enum pname,sizei bufSize,sizei *length, 109 int *values) 110 111New Tokens 112 113 Accepted as the <pname> parameter of GetInteger64v: 114 115 MAX_SERVER_WAIT_TIMEOUT 0x9111 116 117 Accepted as the <pname> parameter of GetSynciv: 118 119 OBJECT_TYPE 0x9112 120 SYNC_CONDITION 0x9113 121 SYNC_STATUS 0x9114 122 SYNC_FLAGS 0x9115 123 124 Returned in <values> for GetSynciv <pname> OBJECT_TYPE: 125 126 SYNC_FENCE 0x9116 127 128 Returned in <values> for GetSynciv <pname> SYNC_CONDITION: 129 130 SYNC_GPU_COMMANDS_COMPLETE 0x9117 131 132 Returned in <values> for GetSynciv <pname> SYNC_STATUS: 133 134 UNSIGNALED 0x9118 135 SIGNALED 0x9119 136 137 Accepted in the <flags> parameter of ClientWaitSync: 138 139 SYNC_FLUSH_COMMANDS_BIT 0x00000001 140 141 Accepted in the <timeout> parameter of WaitSync: 142 143 TIMEOUT_IGNORED 0xFFFFFFFFFFFFFFFFull 144 145 Returned by ClientWaitSync: 146 147 ALREADY_SIGNALED 0x911A 148 TIMEOUT_EXPIRED 0x911B 149 CONDITION_SATISFIED 0x911C 150 WAIT_FAILED 0x911D 151 152 153Additions to Chapter 2 of the OpenGL 3.1 Specification (OpenGL Operation) 154 155 Add to Table 2.2, GL data types: 156 157 "GL Type Minimum Description 158 Bit Width 159 ------- --------- ---------------------------------------------- 160 int64 64 Signed 2's complement binary long integer 161 uint64 64 Unsigned 2's complement binary long integer. 162 sync <ptrbits> Sync object handle (see section 5.2) 163 164 165Additions to Chapter 5 of the OpenGL 3.1 Specification (Special Functions) 166 167 Insert a new section following "Flush and Finish" (Section 5.1) 168 describing sync objects and fence operation. Renumber existing 169 section 5.2 "Hints" and all following 5.* sections. 170 171 "5.2 Sync Objects and Fences 172 --------------------------- 173 174 Sync objects act as a <synchronization primitive> - a representation 175 of events whose completion status can be tested or waited upon. Sync 176 objects may be used for synchronization with operations occurring in 177 the GL state machine or in the graphics pipeline, and for 178 synchronizing between multiple graphics contexts, among other 179 purposes. 180 181 Sync objects have a status value with two possible states: 182 <signaled> and <unsignaled>. Events are associated with a sync 183 object. When an sync object is created, its status is set to 184 unsignaled. When the associated event occurs, the sync object is 185 signaled (its status is set to signaled). Once a sync object has 186 been created, the GL may be asked to wait for a sync object to 187 become signaled. 188 189 Initially, only one specific type of sync object is defined: the 190 fence sync object, whose associated event is triggered by a fence 191 command placed in the GL command stream. Fence sync objects are used 192 to wait for partial completion of the GL command stream, as a more 193 flexible form of Finish. 194 195 The command 196 197 sync FenceSync(enum condition,bitfield flags) 198 199 creates a new fence sync object, inserts a fence command in the GL 200 command stream and associates it with that sync object, and returns 201 a non-zero name corresponding to the sync object. 202 203 When the specified <condition> of the sync object is satisfied by 204 the fence command, the sync object is signaled by the GL, causing 205 any ClientWaitSync or WaitSync commands (see below) blocking on 206 <sync> to <unblock>. No other state is affected by FenceSync or by 207 execution of the associated fence command. 208 209 <condition> must be SYNC_GPU_COMMANDS_COMPLETE. This condition is 210 satisfied by completion of the fence command corresponding to the 211 sync object and all preceding commands in the same command stream. 212 The sync object will not be signaled until all effects from these 213 commands on GL client and server state and the framebuffer are fully 214 realized. Note that completion of the fence command occurs once the 215 state of the corresponding sync object has been changed, but 216 commands waiting on that sync object may not be unblocked until 217 after the fence command completes. 218 219 <flags> must be 0[fn1]. 220 [fn1: <flags> is a placeholder for anticipated future extensions 221 of fence sync object capabilities.] 222 223 Each sync object contains a number of <properties> which determine 224 the state of the object and the behavior of any commands associated 225 with it. Each property has a <property name> and <property value>. 226 The initial property values for a sync object created by FenceSync 227 are shown in table 5.props: 228 229 Property Name Property Value 230 ------------- -------------- 231 OBJECT_TYPE SYNC_FENCE 232 SYNC_CONDITION <condition> 233 SYNC_STATUS UNSIGNALED 234 SYNC_FLAGS <flags> 235 -------------------------------------- 236 Table 5.props: Initial properties of a 237 sync object created with FenceSync(). 238 239 Properties of a sync object may be queried with GetSynciv (see 240 section 6.1.16). The SYNC_STATUS property will be changed to 241 SIGNALED when <condition> is satisfied. 242 243 If FenceSync fails to create a sync object, zero will be returned 244 and a GL error will be generated as described. An INVALID_ENUM error 245 is generated if <condition> is not SYNC_GPU_COMMANDS_COMPLETE. If 246 <flags> is not zero, an INVALID_VALUE error is generated. 247 248 A sync object can be deleted by passing its name to the command 249 250 void DeleteSync(sync sync) 251 252 If the fence command corresponding to the specified sync object has 253 completed, or if no ClientWaitSync or WaitSync commands are blocking 254 on <sync>, the object is deleted immediately. Otherwise, <sync> is 255 flagged for deletion and will be deleted when it is no longer 256 associated with any fence command and is no longer blocking any 257 ClientWaitSync or WaitSync command. In either case, after returning 258 from DeleteSync the <sync> name is invalid and can no longer be used 259 to refer to the sync object. 260 261 DeleteSync will silently ignore a <sync> value of zero. An 262 INVALID_VALUE error is generated if <sync> is neither zero nor the 263 name of a sync object. 264 265 266 5.2.1 Waiting for Sync Objects 267 ------------------------------ 268 269 The command 270 271 enum ClientWaitSync(sync sync,bitfield flags,uint64 timeout) 272 273 causes the GL to block, and will not return until the sync object 274 <sync> is signaled, or until the specified <timeout> period expires. 275 <timeout> is in units of nanoseconds. <timeout> is adjusted to the 276 closest value allowed by the implementation-dependent timeout 277 accuracy, which may be substantially longer than one nanosecond, and 278 may be longer than the requested period. 279 280 If <sync> is signaled at the time ClientWaitSync is called 281 then ClientWaitSync returns immediately. If <sync> is unsignaled at 282 the time ClientWaitSync is called then ClientWaitSync will block and 283 will wait up to <timeout> nanoseconds for <sync> to become signaled. 284 <flags> controls command flushing behavior, and may be 285 SYNC_FLUSH_COMMANDS_BIT, as discussed in section 5.2.2. 286 287 ClientWaitSync returns one of four status values. A return value of 288 ALREADY_SIGNALED indicates that <sync> was signaled at the time 289 ClientWaitSync was called. ALREADY_SIGNALED will always be returned 290 if <sync> was signaled, even if the value of <timeout> is zero. A 291 return value of TIMEOUT_EXPIRED indicates that the specified timeout 292 period expired before <sync> was signaled. A return value of 293 CONDITION_SATISFIED indicates that <sync> was signaled before the 294 timeout expired. Finally, if an error occurs, in addition to 295 generating a GL error as specified below, ClientWaitSync immediately 296 returns WAIT_FAILED without blocking. 297 298 If the value of <timeout> is zero, then ClientWaitSync does not 299 block, but simply tests the current state of <sync>. TIMEOUT_EXPIRED 300 will be returned in this case if <sync> is not signaled, even though 301 no actual wait was performed. 302 303 If <sync> is not the name of a sync object, an INVALID_VALUE error 304 is generated. If <flags> contains any bits other than 305 SYNC_FLUSH_COMMANDS_BIT, an INVALID_VALUE error is generated. 306 307 The command 308 309 void WaitSync(sync sync,bitfield flags,uint64 timeout) 310 311 is similar to ClientWaitSync, but instead of blocking and not 312 returning to the application until <sync> is signaled, WaitSync 313 returns immediately, instead causing the GL server [fn1] to block 314 until <sync> is signaled [fn2]. 315 [fn1 - the GL server may choose to wait either in the CPU 316 executing server-side code, or in the GPU hardware if it 317 supports this operation.] 318 [fn2 - WaitSync allows applications to continue to queue commands 319 from the client in anticipation of the sync being signaled, 320 increasing client-server parallelism. 321 322 <sync> has the same meaning as for ClientWaitSync. 323 324 <timeout> must currently be the special value TIMEOUT_IGNORED, and 325 is not used. Instead, WaitSync will always wait no longer than an 326 implementation-dependent timeout. The duration of this timeout in 327 nanoseconds may be queried by calling GetInteger64v with <value> 328 MAX_SERVER_WAIT_TIMEOUT. There is currently no way to determine 329 whether WaitSync unblocked because the timeout expired or because 330 the sync object being waited on was signaled. 331 332 <flags> must be 0. 333 334 If an error occurs, WaitSync generates a GL error as specified 335 below, and does not cause the GL server to block. 336 337 If <sync> is not the name of a sync object, an INVALID_VALUE error 338 is generated. If <timeout> is not TIMEOUT_IGNORED, or <flags> is not 339 zero, an INVALID_VALUE error is generated. 340 341 Multiple Waiters 342 ---------------- 343 344 It is possible for both the GL client to be blocked on a sync object 345 in a ClientWaitSync command, the GL server to be blocked as the 346 result of a previous WaitSync command, and for additional WaitSync 347 commands to be queued in the GL server, all for a single sync 348 object. When such a sync object is signaled in this situation, the 349 client will be unblocked, the server will be unblocked, and all such 350 queued WaitSync commands will continue immediately when they are 351 reached. 352 353 See section D.2 for more information about blocking on a sync 354 objects in multiple GL contexts. 355 356 5.2.2 Signaling 357 --------------- 358 359 A sync object can be in the signaled state only once the 360 corresponding fence command has completed and signaled the sync 361 object. 362 363 If the sync object being blocked upon will not be signaled in finite 364 time (for example, by an associated fence command issued previously, 365 but not yet flushed to the graphics pipeline), then ClientWaitSync 366 may hang forever. To help prevent this behavior [fn4], if the 367 SYNC_FLUSH_COMMANDS_BIT bit is set in <flags>, and <sync> is 368 unsignaled when ClientWaitSync is called, then the equivalent of 369 Flush will be performed before blocking on <sync>. 370 [fn4 - The simple flushing behavior defined by 371 SYNC_FLUSH_COMMANDS_BIT will not help when waiting for a fence 372 command issued in another context's command stream to complete. 373 Applications which block on a fence sync object must take 374 additional steps to assure that the context from which the 375 corresponding fence command was issued has flushed that command 376 to the graphics pipeline.] 377 378 If a sync object is marked for deletion while a client is blocking 379 on that object in a ClientWaitSync command, or a GL server is 380 blocking on that object as a result of a prior WaitSync command, 381 deletion is deferred until the sync object is signaled and all 382 blocked GL clients and servers are unblocked. 383 384 Additional constraints on the use of sync objects are discussed in 385 Appendix D. 386 387 State must be maintained to indicate which sync object names are 388 currently in use. The state require for each sync object in use is 389 an integer for the specific type, an integer for the condition, an 390 integer for the flags, and a bit indicating whether the object is 391 signaled or unsignaled. The initial values of sync object state are 392 defined as specified by FenceSync." 393 394Additions to Chapter 6 of the OpenGL 3.1 Specification (State and State Requests) 395 396 Add GetInteger64v to the first list of commands in section 6.1.1 397 "Simple Queries", and change the next sentence to mention the query: 398 399 "There are five commands for obtaining simple state variables: 400 401 ... 402 void GetInteger64v(enum value,int64 *data) 403 ... 404 405 The commands obtain boolean, integer, 64-bit integer, 406 floating-point..." 407 408 409 Modify the third sentence of section 6.1.2 "Data Conversions": 410 411 "If any of the other simple queries are called, a boolean value of 412 TRUE or FALSE is interpreted as 1 or 0, respectively. If GetIntegerv 413 or GetInteger64v are called, a floating-point value is rounded to 414 the nearest integer, unless the value is an RGBA color component..." 415 416 417 Insert a new subsection following "Asynchronous Queries" (subsection 418 6.1.6) describing sync object queries. Renumber existing subsection 419 6.1.7 "Buffer Object Queries" and all following 6.1.* subsections. 420 421 "6.1.7 Sync Object Queries 422 423 Properties of sync objects may be queried using the command 424 425 void GetSynciv(sync sync,enum pname,sizei bufSize,sizei *length, 426 int *values) 427 428 The value or values being queried are returned in the parameters 429 <length> and <values>. 430 431 On success, GetSynciv replaces up to <bufSize> integers in <values> 432 with the corresponding property values of the object being queried. 433 The actual number of integers replaced is returned in *<length>. If 434 <length> is NULL, no length is returned. 435 436 If <pname> is OBJECT_TYPE, a single value representing the specific 437 type of the sync object is placed in <values>. The only type 438 supported is SYNC_FENCE. 439 440 If <pname> is SYNC_STATUS, a single value representing the status of 441 the sync object (SIGNALED or UNSIGNALED) is placed in <values>. 442 443 If <pname> is SYNC_CONDITION, a single value representing the 444 condition of the sync object is placed in <values>. The only 445 condition supported is SYNC_GPU_COMMANDS_COMPLETE. 446 447 If <pname> is SYNC_FLAGS, a single value representing the flags with 448 which the sync object was created is placed in <values>. No flags 449 are currently supported. 450 451 If <sync> is not the name of a sync object, an INVALID_VALUE error 452 is generated. If <pname> is not one of the values described above, 453 an INVALID_ENUM error is generated. If an error occurs, 454 nothing will be written to <values> or <length>. 455 456 The command 457 458 boolean IsSync(sync sync) 459 460 returns TRUE if <sync> is the name of a sync object. If <sync> is 461 not the name of a sync object, or if an error condition occurs, 462 IsSync returns FALSE (note that zero is not the name of a sync 463 object). 464 465 Sync object names immediately become invalid after calling 466 DeleteSync, as discussed in sections 5.2 and D.2, but the underlying 467 sync object will not be deleted until it is no longer associated 468 with any fence command and no longer blocking any WaitSync command." 469 470 471Additions to Appendix D (Shared Objects and Multiple Contexts) 472 473 In the first paragraph of the appendix, add "sync objects" to the 474 list of shared state. 475 476 Replace the title and first sentence of section D.1 with: 477 478 "D.1 Object Deletion Behavior (other than sync objects) 479 ------------------------------------------------------ 480 481 After a shared object (other than sync objects, discussed in section 482 D.2) is deleted..." 483 484 485 Insert a new section following "Object Deletion Behavior" (section 486 D.1) describing sync object multicontext behavior. Renumber existing 487 section D.2 "Propagating State Changes..." and all following D.* 488 sections. 489 490 "D.2 Sync Objects and Multiple Contexts 491 -------------------------------------- 492 493 D.2.1 Sync Object Deletion Behavior 494 ----------------------------------- 495 496 Deleting sync objects is similar to other shared object types in 497 that the name of the deleted object immediately becomes invalid but 498 the underlying object will not be deleted until it is no longer in 499 use. Unlike other shared object types, a sync object is determined 500 to be in use if there is a corresponding fence command which has not 501 yet completed (signaling the sync object), or if there are any GL 502 clients and/or servers blocked on the sync object as a result of 503 ClientWaitSync or WaitSync commands. Once any corresponding fence 504 commands have completed, a sync object has been signaled, and all 505 clients and/or servers blocked on that sync object have been 506 unblocked, the object may then be deleted. 507 508 D.2.2 Multiple Waiters in Multiple Contexts 509 ------------------------------------------- 510 511 When multiple GL clients and/or servers are blocked on a single sync 512 object and that sync object is signaled, all such blocks are 513 released. The order in which blocks are released is 514 implementation-dependent." 515 516 517 Promote the fifth paragraph of section D.3 "Propagating State 518 Changes" (following the itemized list of changes to an object) to a 519 new subsection D.3.1. Renumber the existing subsection D.3.1 520 "Definitions" and all following D.3.* subsections. 521 522 "D.3.1 Determining Completion of Changes to an object 523 ---------------------------------------------------- 524 525 The object T is considered to have been changed once a command such 526 as described in section D.3 has completed. Completion of a 527 command[fn5] may be determined either by calling Finish, or by 528 calling FenceSync and executing a WaitSync command on the associated 529 sync object. The second method does not require a round trip to the 530 GL server and may be more efficient, particularly when changes to T 531 in one context must be known to have completed before executing 532 commands dependent on those changes in another context. 533 [fn5: The GL already specifies that a single context processes 534 commands in the order they are received. This means that a 535 change to an object in a context at time <t> must be 536 completed by the time a command issued in the same context 537 at time <t+1> uses the result of that change.]" 538 539 Change all references to "calling Finish" or "using Finish" in 540 section D.3.3 "Rules" to refer to section D.3.1. 541 542Additions to the GLX 1.4 Specification 543 544 Insert a new section after section 2.5, "Texture Objects": 545 546 "2.6 Sync Objects 547 548 Sync objects are shared by rendering contexts in the same fashion as 549 texture objects (see Appendix D, "Shared Objects and Multiple 550 Contexts", of the OpenGL 3.1 Specification). If a sync object is 551 blocked upon (glClientWaitSync or glWaitSync), signaled 552 (glSignalSync), or has events associated with it (glFence) from more 553 than one context, then it is up to the programmer to ensure that the 554 correct order of operations results, and that race conditions and 555 deadlocks are avoided. 556 557 All modifications to shared context state as a changing the status 558 of a sync object are atomic. Also, a sync object will not be deleted 559 until there are no longer any outstanding fence commands or blocks 560 associated with it." 561 562 Replace the third paragraph of section 3.3.7, "Rendering Contexts": 563 564 "If <share_list> is not NULL, then all shareable GL server state 565 (excluding texture objects named 0) will be shared by <share_list> 566 and the newly created rendering context. An arbitrary number of 567 GLXContexts can share server state. The server context state for all 568 sharing contexts must exist in a single address space or a BadMatch 569 error is generated." 570 571GLX Protocol 572 573 <TBD> 574 575Errors 576 577 INVALID_VALUE is generated if the <sync> parameter of 578 ClientWaitSync, SignalSync, WaitSync, or GetSynciv is not the name 579 of a sync object. 580 581 INVALID_VALUE is generated if the <sync> parameter of DeleteSync 582 is neither zero nor the name of a sync object. 583 584 INVALID_ENUM is generated if the <condition> parameter of FenceSync 585 is not SYNC_GPU_COMMANDS_COMPLETE. 586 587 INVALID_VALUE is generated if the <flags> parameter of 588 ClientWaitSync contains bits other than SYNC_FLUSH_COMMANDS_BIT, or 589 if the <flags> parameter of WaitSync is nonzero. 590 591 INVALID_ENUM is generated if the <mode> parameter of SignalSync is 592 not SIGNALED. 593 594 INVALID_ENUM is generated if the <pname> parameter of GetSynciv is 595 neither OBJECT_TYPE, SYNC_CONDITION, SYNC_FLAGS, nor SYNC_STATUS. 596 597New State 598 599Table 6.X. Sync Objects. 600 601Get value Type Get command Initial value Description Section 602------------------ ---- ----------- ---------------------------- --------------- ------- 603OBJECT_TYPE Z_1 GetSynciv SYNC_FENCE Type of sync object 5.2 604SYNC_STATUS Z_2 GetSynciv UNSIGNALED Sync object status 5.2 605SYNC_CONDITION Z_1 GetSynciv SYNC_GPU_COMMANDS_COMPLETE Sync object condition 5.2 606SYNC_FLAGS Z GetSynciv SYNC_FLAGS Sync object flags 5.2 607 608New Implementation Dependent State 609 610Table 40. Implementation Dependent Values (cont.) 611 612Get value Type Get command Minimum value Description Section 613------------------ ---- ------------- ---------------------------- --------------- ------- 614MAX_SERVER_WAIT_ Z^+ GetInteger64v 0 Maximum WaitSync 5.2 615 TIMEOUT timeout interval 616 617Sample Code 618 619 ... kick off a length GL operation 620 /* Place a fence and associate a fence sync object */ 621 GLsync sync = glFenceSync(GLSYNC_GPU_COMMANDS_COMPLETE, 0); 622 623 /* Elsewhere, wait for the sync to be signaled */ 624 625 /* To wait a specified amount of time (possibly clamped), do 626 * this to convert a time in seconds into nanoseconds: 627 */ 628 GLuint64 timeout = num_seconds * ((GLuint64)1000 * 1000 * 1000); 629 glWaitSync(sync, 0, timeout); 630 631 /* Or to determine the maximum possible wait interval and wait 632 * that long, do this instead: 633 */ 634 GLuint64 max_timeout; 635 glGetInteger64v(GL_MAX_SERVER_WAIT_TIMEOUT, &max_timeout); 636 glWaitSync(sync, 0, max_timeout); 637 638Issues 639 640 1) Are sync objects shareable between multiple contexts? 641 642 RESOLVED: YES. The sync object namespace is shared, and sync 643 objects themselves may be shared or not. Shared sync objects can 644 be blocked upon or deleted from any context they're shared with. 645 646 Enabling multi-context aware sync objects is a major change from 647 earlier versions of the specification. We believe this is now OK 648 because the rules defining sync object signaling behavior are 649 clear enough to make us comfortable with restoring full 650 multi-context awareness. 651 652 2) What specializations of sync objects are supported? 653 654 RESOLVED: Only fence sync objects (corresponding to synchronous 655 command stream fences). Additionally, fence sync objects are 656 constrained so that fence "stacking" is not allowed - the 657 initial status of a fence sync is unsignaled, and it may only be 658 signaled. 659 660 We expect to define a way to map sync objects into OpenCL events 661 to help performance of CL/GL sharing. 662 663 EGL sync objects (from the EGL_KHR_sync extension) should be 664 compatible with GL sync objects, although the sync object 665 namespace may require remapping between APIs. Also, EGL sync 666 objects do support fence stacking and unsignaling, possibly 667 imposing greater complexity and risk of hanging when used with 668 GL. 669 670 The sync object framework is intended to generalize to other 671 types of sync objects, such as mappings of OS-specific events 672 and semaphores, new specializations of sync objects such as 673 "pulsed" sync objects associated with video retrace, or other 674 command stream conditions, such as sync objects which would be 675 associated with completion of single or multiple asynchronous GL 676 commands. 677 678 3) What fence sync object conditions are supported? 679 680 RESOLVED: The conditions SYNC_GPU_COMMANDS_COMPLETE (equivalent 681 to ALL_COMPLETED_NV in NV_fence), meaning that a fence command 682 has completed in the GPU pipe. 683 684 In the future, we could define two additional conditions: 685 686 SYNC_SERVER_COMMANDS_COMPLETE would correspond to a command 687 completing "in the server"; the exact definition of "server" 688 would have to be nailed down, but generally meaning that the 689 command has been issued to the GPU by the driver. The primary 690 purpose of this condition would be to delay use of an object in 691 one context until after it has been created in another context, 692 so if it proves too difficult to define "server", the condition 693 could be restricted to simply meaning that all object creation 694 commands prior to the fence have realized their effect on server 695 state. 696 697 SYNC_CLIENT_COMMANDS_COMPLETE, would correspond to a command 698 being issued from the client to the server (although this can 699 effectively be done already, by explicitly signaling a sync 700 object in the client). 701 702 4) What state is associated with a sync object? Should state be 703 validated at creation time, or when events are associated with a 704 sync? This would express itself (for example) by passing a 705 <condition> parameter to Fence(), rather than to Sync(). 706 707 RESOLVED: sync object state includes specialization (type), 708 condition, flags, and status. Status is mutable data; condition 709 and flags are immutable properties defined defined at creation 710 time. 711 712 In the future, additional state and data may be introduced, such 713 as a timestamp when the sync object was last signaled, or a 714 swapbuffer / media stream count (SBC/MSC, in digital media 715 terminology), for a sync object triggered by display retrace. 716 717 5) What is the purpose of the flags argument to FenceSync? 718 719 RESOLVED: The flags argument is expected to be used by a vendor 720 extension to create sync objects in a broader sharing domain 721 than GLX/WGL share groups. In the future we may reintroduce the 722 generic property list mechanism if a generic sync object 723 creation call is defined for multiple types of sync objects, but 724 for fence sync objects alone, the flags parameter is sufficient 725 flexibility. 726 727 6) Can sync objects and NV_fence fences share enumerants and/or the 728 namespace of fences / sync objects? 729 730 RESOLVED: NO. The sync object namespace cannot be the same as 731 NV_fence since NV_fence does not put fence names on the share 732 list, while sync objects and their names are shared. We will 733 also not reuse enumerant values. The sync object interface is 734 quite a bit different from NV_fence even though the underlying 735 fence functionality is not. 736 737 7) Should we allow these commands to be compiled within display 738 lists? 739 740 RESOLVED: WaitSync and SignalSync are display listable. They 741 execute on the GL server or in the GL pipeline. 742 743 RESOLVED: ClientWaitSync and FenceSync are not display listable. 744 ClientWaitSync is defined to block the application, not the 745 server. FenceSync must return a value to the application. 746 747 (Note: this is not relevant to this draft of the extension, 748 which is written against core OpenGL 3.1. However, an 749 implementation supporting the ARB_compatibility extension should 750 behave as described. We may wish to add this qualified language 751 to the extension if it's to be shipped against such an 752 implementation). 753 754 8) What happens if you set a fence command for a sync object while a 755 previous fence command is still in flight? Are fences 756 "stackable"? (also see issue 21) 757 758 RESOLVED: Fences are not stackable at present. A single fence 759 command is associated with a fence sync object when it is 760 created. In the future we might reintroduce the separate sync 761 creation (Sync()) and fence-associated (Fence()) commands 762 present in prior drafts, with all the complexity of stacking 763 defined therein. 764 765 As with OS synchronization primitives, applications are 766 responsible for using sync objects and fences in ways that avoid 767 race conditions and hangs. Removing stackable fences may help 768 reduce the possibility of such errors. 769 770 We are still considering potential performance issues and 771 semantic difficulties of namespace sharing (e.g. when does a 772 name returned by FenceSync become valid in other contexts of the 773 share group) associated with this model. 774 775 9) What happens to *WaitSyncs blocking on a sync object, and to an 776 associated fence command still pending execution, when the sync 777 object is deleted? 778 779 RESOLVED: Following the OpenGL 3.0 shared object model, the sync 780 object name is immediately deleted, but the underlying sync 781 object is not deleted until all such outstanding references on 782 it are removed. 783 784 NOTE: This specifies behavior left intentionally unspecified by 785 earlier versions of this extension. 786 787 10) Is it possible to have multiple *WaitSyncs blocking on a single 788 sync object? 789 790 RESOLVED: YES, since we support multi-context aware sync 791 objects. *WaitSync might be issued from multiple contexts on the 792 same sync object. Additionally, multiple WaitSync commands may 793 be queued on a single GL server (although only one of them can 794 actually be blocking at any given time). 795 796 11) Can we determine completion time of a sync object? 797 798 RESOLVED: NO. 799 800 In the future, we may support variants of sync objects that 801 record their completion time in queriable object data. 802 803 12) Can we block on multiple sync objects? 804 805 RESOLVED: NO. 806 807 In the future, *WaitSyncs calls taking a list of sync object 808 names, a logical condition (any/all complete), and optionally 809 returning an index/name of a sync object triggering the 810 condition, like the GL2_async_object API, could be added. 811 812 13) Why don't the entry points/enums have ARB appended? 813 814 This functionality is going directly into the OpenGL 3.2 core 815 and also being defined as an extension for older platforms at 816 the same time, so it does not use ARB suffixes, like other such 817 new features going directly into the GL core. 818 819 14) Where can sync objects be waited on? 820 821 RESOLVED: In the client on the CPU, or in the GL server, either 822 in the CPU or GPU. 823 824 Rather than specifying where to wait in the server, the 825 implementation is allowed to choose. 826 827 15) Can the specialization of sync objects be changed, once created? 828 829 RESOLVED: NO. 830 831 This seems likely to cause errors and has little obvious use - 832 making sync objects persistent (being able to reset their status 833 and associate them with a new fence) should suffice to avoid 834 excessive creation/deletion of objects. 835 836 16) How can sync objects be used to facilitate asynchronous 837 operations, particularly large data transfer operations? 838 839 DISCUSSION: There are several methods. A more readily 840 supportable one uses multiple GL contexts and threads, with work 841 performed in one thread associated with a sync. Another thread 842 finishes, tests for completion, or waits on that sync, depending 843 on the exact semantic needed. 844 845 This method is implementable, but has the disadvantage of requiring 846 multiple contexts, drawing surfaces, and CPU threads. It also 847 requires some additional, possibly non-GL synchronization 848 between the threads (so that the work thread knows when the sync 849 created in the loader thread is valid - otherwise it can't be 850 tested without raising an error!) 851 852 It seems analogous to pbuffers in terms of overhead. That 853 suggests lighter-weight mechanisms may be preferable, in the 854 same fashion that framebuffer objects have become preferable to 855 pbuffers. 856 857 A more future-looking mechanism is to support multiple command 858 streams within a single context. Then the expensive asynchronous 859 operations can be kicked off without additional CPU threads, 860 rendering surfaces, or contexts. 861 862 This concept has not been implemented in GL yet, although the 863 original 3Dlabs white paper outlines an approach to it. The 864 desire for consistency / reproducibility means that retrofitting 865 multiple command streams onto the current API, defining when and 866 how resources changed in one stream affect another stream, may 867 require a great deal of spec work. Furthermore, most hardware 868 does not actually support multiple command streams, at least in 869 full generality. 870 871 If we do support multiple command streams, then at least at 872 first, there will probably be severe restrictions on what 873 commands could go in additional streams beyond the "main" or 874 "default" stream. 875 876 In either case, we will probably need to either define new 877 commands that are allowed to operate asynchronously (e.g. 878 TexImageAsync) with respect to surrounding commands, or to 879 overload existing commands to operate asynchronously when 880 some global state is set, like the old SGI_async extension. 881 882 Note that buffer objects allow the GL to implement data transfer 883 into, or out of, the buffer object to occur asynchronously. 884 However, once the transfer is completed, that data is in a buffer 885 object and not stored in memory that is under application control. 886 887 In defining these commands, we will probably need some way to 888 associate a sync object with them at the time they're issued, 889 not just place a fence following the async command. One reason 890 for this is wanting to know when the application data passed 891 into an asynchronous command has been consumed and can safely be 892 modified by the app. 893 894 17) Can the query object framework be used to support sync objects? 895 896 RESOLVED: NO. 897 898 It is straightforward to map the sync object API onto queries, 899 with the addition of a small number of entry points. However, 900 the query object namespace is defined not to be shared. This 901 makes it impossible to implement shared sync objects in the 902 query namespace without the possibility of breaking existing 903 code that uses the same query name in multiple contexts. 904 905 It is also possible to map occlusion queries into the sync 906 object API, again with the addition of a small number of entry 907 points. We might choose to do this in the future. 908 909 18) Do *WaitSync wait on an event, or on sync object status? What is 910 the meaning of sync object status? 911 912 RESOLVED: *WaitSync blocks until the status of the sync object 913 transitions to the signaled state. Sync object status is either 914 signaled or unsignaled. More detailed rules describing 915 signaling follow (these may need to be imbedded into the actual 916 spec language): 917 918 (Note: much of the following discussion is not relevant for the 919 constrained fence sync objects currently defined by this 920 extension, as such objects start in the unsignaled state and may 921 only transition to the signaled state, not the other way). 922 923 R1) A sync object has two possible status values: signaled or 924 unsignaled (corresponding to SYNC_STATUS values of SIGNALED 925 or UNSIGNALED, respectively). 926 927 R2) When created, the state of the sync object is signaled by 928 default, but may be explicitly set to unsignaled. 929 930 R3) A fence command is inserted into a command stream. A sync 931 object is not. 932 933 R4) When a fence command is inserted into a command stream using 934 Fence(), the status of the sync object associated with that 935 fence command is set to the unsignaled state. 936 937 R5) Multiple fence commands can be associated with the same sync 938 object. 939 940 R6) A fence command, once its condition has been met, will set 941 its associated sync object to the signaled state. The only 942 condition currently supported is SYNC_GPU_COMMANDS_COMPLETE. 943 944 R7) A wait function, such as ClientWaitSync or WaitSync, waits 945 on a sync object, not on a fence. 946 947 R8) A wait function called on a sync object in the unsignaled 948 state will block. It unblocks (note, not "returns to the 949 application") when the sync object transitions to the 950 signaled state. 951 952 Some of the behaviors resulting from these rules are: 953 954 B1) Calling ClientWaitSync with a timeout of 0 will return TRUE 955 if the sync object is in the signaled state. Note that 956 calling ClientWaitSync with a timeout of 0 in a loop can 957 miss state transitions. 958 B2) Stacking fences is allowed. Each fence, once its condition 959 has been met, will set its associated sync object to the 960 signaled state. If the sync object is already in the 961 signaled state, it stays in that state. 962 B3) ClientWaitSync could take a timeout parameter and return a 963 boolean. If the timeout period has expired, ClientWaitSync 964 will unblock and return FALSE to the caller. If 965 ClientWaitSync unblocks because the sync object it was 966 waiting on is in the signaled state, it will return TRUE. 967 B4) We could define a FinishMultipleSync() command that will 968 unblock once all (or any) of the sync objects passed to it 969 are in the signaled state (also see issue 12). 970 B5) We could define a set/resetSyncObject function to manually 971 set the sync object in the signaled or unsignaled state. 972 This makes it easy for apps to reuse a sync object in the 973 multi-context case, so the sync object can be blocked upon 974 before a fence command is associated with it in the command 975 stream. 976 B6) We could define an API to convert a sync object into an OS 977 specific synchronization primitive (Events on Windows, file 978 descriptors or X-events or semaphores on Unix?) 979 980 19) Which of the behaviors defined in issue 18 should be added? 981 982 RESOLVED: Add B1, B2, and B3 (timeout functionality). 983 984 We considered several possibilities including passing a <unit 985 duration,count> tuple, and adding a TIMEOUT_BIT to the flags to 986 representing "forever". The end result of discussion was to 987 introduce a new GL datatype, GLuint64. GLuint64 is a 64-bit 988 unsigned integer representing intervals in nanoseconds - the 989 same encoding as the Unadjusted System Time (UST) counter used 990 in OpenML and OpenKODE. All future uses of time in the GL should 991 use the GLuint64 datatype. 992 993 At present, the timeout duration passed to *WaitSync represents 994 a time relative to when the driver actually begins waiting. A 995 future extension could easily allow waiting until a specific UST 996 by adding a bit to the flags specifying that timeout is 997 absolute, not relative. 998 999 RESOLVED: Do not add B4 yet (easy to put in a future extension). 1000 1001 RESOLVED: Add B5 with a new glSignalSync call taking modes of 1002 SIGNALED or UNSIGNALED. Might add a PULSED mode in the future, 1003 but that's a bit weird - what if the sync object is already 1004 signaled? 1005 1006 RESOLVED: Add B6 via a WGL extension supporting only 1007 wglConvertSyncToEvent (no wglConvertEventToSync). Figure out the 1008 corresponding Unix/X functionality and define that as well - 1009 should it use pthreads? xsync objects? System V IPC semaphores? 1010 etc. 1011 1012 20) How can multi-context aware sync objects be used to synchronize 1013 two contexts? 1014 1015 NOTE: This example needs to be rewritten to accomodate changes 1016 to the API and asynchronous object creation. In particular, 1017 context B must wait for the shared sync object to be 1018 successfully created before waiting on it, which requires either 1019 platform-specific (non-OpenGL) code, or client-side cleverness 1020 suggested by Bill Licea-Kane. There should also be an example 1021 showing specifically how to use sync objects and server waiting 1022 to coordinate waiting on creation of another object. 1023 1024 Example of context B waiting on context A: 1025 1026 A: // Create a sync object in the unsignaled state 1027 int props[] = { 1028 OBJECT_SHARED, TRUE, 1029 SYNC_STATUS, UNSIGNALED }; 1030 1031 syncObjectA = Sync(SYNC_FENCE, 2, props); 1032 B: // Block, since syncObjectA is in the unsignaled state 1033 ClientWaitSync(syncObjectA); 1034 A: // Perform rendering that B should wait on 1035 render(); 1036 // Insert a fence into the command stream. syncObjectA 1037 // remains in the unsignaled state until completion 1038 Fence(syncObjectA); 1039 // To prevent deadlock, A must make forward progress 1040 Flush(); 1041 B: // Once the fence command issued above completes, the 1042 // ClientWaitSync issued above will unblock and allow B 1043 // to continue. 1044 1045 21) What is the stacking behavior of fence commands? 1046 1047 RESOLVED: Stacking is not allowed. 1048 1049 22) What should the blocking API be called? 1050 1051 RESOLVED: ClientWaitSync for blocking on the client side. 1052 WaitSync for blocking on the GL server (CPU or GPU). 1053 1054 Previously we used FinishSync by analogy with NV_fence's 1055 'glFinishFence'. However, the call may return before an event 1056 has actually signaled a sync, due to timeout. Also, other sync 1057 object specializations do not necessarily have anything to do 1058 with command streams (timers, retrace events, OS events, etc.) 1059 So 'Finish' is the wrong name. 1060 1061 23) How are sync objects implemented in terms of generic object 1062 interfaces? 1063 1064 RESOLVED: An object property name which could be generic is 1065 introduced here (OBJECT_TYPE), but no generic object 1066 manipulation commands are defined. 1067 1068 24) Do we need a default sync object that is always present? 1069 (Notionally the "sync object named zero")? 1070 1071 RESOLVED: NO. Fence sync objects cannot provide this 1072 functionality. Multiple contexts just have to be clever about 1073 use of (potentially client-created) sync object names. 1074 1075 DISCUSSION: The use case for a default sync object is in 1076 coordinating object creation across contexts (see the 1077 out-of-date example in issue 20 as well). Suppose we want to 1078 know in context B when context A has successfully created an 1079 object, so we can start using it. It's possible to do this by 1080 inserting a fence command after object creation in A and waiting 1081 on sync completion in B. But to do this, first we must have a 1082 sync object that is known to exist in both A and B, creating a 1083 circular dependency! 1084 1085 There are several possible approaches. 1086 1087 1) Create a sync object in context A before forking another 1088 thread that would create context B and use it. This wouldn't 1089 help in the indirect rendering / separate process model case. 1090 1091 2) Punt to platform-specific code: create a sync object in A, 1092 verify it was successfully created in A, then use 1093 platform-specific IPC to let other threads / processes know the 1094 sync is ready for use to coordinate object creation. This is 1095 highly inelegant. 1096 1097 3) Mandate that all contexts in a share group have a single, 1098 shared sync object defined, which is present from context 1099 creation time. When requesting this default object, the driver 1100 will either create it, if it doesn't already exist, or return a 1101 handle to the existing default object, if it does. The key point 1102 is that the handle can be obtained in two different contexts 1103 without either one needing to do non-portable or non-GL 1104 operations before knowing the handle is valid. 1105 1106 4) Clever client in context B. Bill has commented on this and 1107 people seem to agree this is doable and won't cause any coding 1108 issues, so we're assuming it's correct. 1109 1110 25) Do we need the ability to WaitSync in the GPU, as well 1111 as in the server? 1112 1113 RESOLVED: The implementation is allowed to choose. 1114 1115 26) How will sync objects be linked to OpenCL events? 1116 1117 NOTE: This is an issue for a future extension defining a new 1118 type of sync object. A suggestion for that extension is 1119 circulating on the OpenCL mailing list. This will likely be done 1120 as a new command taking a CL event handle and returning a GL 1121 sync object behaving like a fence sync, but with a different 1122 object type, and triggered by the CL event rather than a fence. 1123 1124 27) What is the relationship between EGL and OpenGL sync objects? 1125 1126 The goal is that an EGL-based implementation could support both 1127 APIs to a single underlying sync object implementation. It is 1128 unlikely that the namespaces of EGL and GL sync objects could be 1129 shared, however. 1130 1131 28) What is the deletion behavior of sync objects? 1132 1133 RESOLVED: DeleteSync immediately releases the name, but 1134 "bindings" of the underlying object, e.g. outstanding fences or 1135 blocking commands, will keep its underlying storage around until 1136 all such commands complete and unblock all such waiters. This is 1137 consistent with the OpenGL 3.0 shared object appendix, except 1138 references are formed by commands and blocks, rather than by the 1139 attachment hierarchy. 1140 1141 29) Should there be an implementation-dependent maximum timeout 1142 interval? 1143 1144 RESOLVED: Not for client waits, which may block "forever", but a 1145 MAX_SERVER_WAIT_TIMEOUT implementation-dependent value exists, 1146 together with a new GetInteger64v query (see issue 30). 1147 1148 In the Windsor F2F, we agreed to remove the value FOREVER. 1149 Because any timeout can be clamped, FOREVER didn't really mean 1150 "forever", so it was misleading (and inconsistent with the 1151 special treatment of FOREVER in the EGL_KHR_sync spec) to have 1152 it. Instead we have a sample code section which shows how to 1153 wait a long time. 1154 1155 30) What is the type of the timeout interval? 1156 1157 RESOLVED: GLuint64. We previously typedefed uint64_t (or 1158 equivalent) as 'GLtime', but now that max timeout intervals are 1159 queriable, a query function is required. A generic query for 1160 64-bit integer data is more useful than a GLtime-specific query. 1161 Consequently the type of <timeout> has been changed to 1162 'GLuint64' and a corresponding 'GetInteger64v' query taking 1163 'GLint64' added (by symmetry with GetInteger, where unsigned 1164 quantities are queries with a function taking a pointer to a 1165 signed integer - the pointer conversion is harmless). 1166 1167 The existing GLintptr argument is not guaranteed to be at least 1168 64 bits long, so is not appropriate here. 1169 1170 NOTE: We might choose a type tag for GLuint64 state other than 1171 the existing 'Z^+'. It is indeed a non-negative integer but the 1172 difference in size might be worth noting in the state tables. 1173 1174 31) Potential naming issues 1175 1176 Are SYNC_CONDITION and SYNC_STATUS too confusingly similar? We 1177 could refine these to SYNC_FENCE_CONDITION and 1178 SYNC_SIGNAL_STATUS at some wordiness cost, although the existing 1179 names match the EGL sync object extension and consistency may be 1180 a virtue. There's also a question of whether future types of 1181 sync objects would have a use for conditions having nothing to 1182 do with fences, e.g. a display sync might have conditions 1183 corresponding to different points in the draw / retrace interval 1184 cycle, which argues in favor of the existing name. 1185 1186 There's still time to change names prior to approval of EGL and 1187 GL sync objects, if anyone wants to make suggestions. 1188 1189 32) Do we need an explicit signaling API (SignalSync)? 1190 1191 RESOLVED: NO, not for fence sync objects. In the future other 1192 types of sync objects may choose to reintroduce this API. 1193 1194 33) What is the datatype of a sync object handle? 1195 1196 RESOLVED: GLsync, which is defined as an anonymous struct 1197 pointer in the C binding. This eases implementability on 64 bit 1198 environments by allowing server pointer representations to be 1199 used. 1200 1201Revision History 1202 1203 Version 1, 2006/02/08 - First writeup as spec language, based on 1204 NV_fence. 1205 1206 Version 2, 2006/02/10 - WaitSync can only wait on fence syncs. Sync 1207 types are immutable once created - FenceSync can be called on an 1208 existing sync of type fence to rebind it to a new fence command, but 1209 it cannot be called on a non-fence sync. Expanded list of errors. 1210 Numbered issues list and added issues 13-16. Noted future "multiple 1211 command stream" concept in issue 16. 1212 1213 Version 3, 2006/02/14 - Change FenceSync behavior to leave the sync 1214 state undefined if a previously issued fence command is still 1215 in-flight when a fence sync is reset. Add a flags parameter to 1216 FinishSync which can be used to produce flushing behavior like 1217 NV_fence in the single-context use case, and note that in the 1218 multiple-context case, applications must do more synchronization 1219 work between threads themselves to ensure that a fence command 1220 issues in one context will reach the hardware before blocking 1221 another context. 1222 1223 Version 4, 2006/02/22 - change sharing behavior so the sync 1224 namespace is shared, but sync objects can only be used from the 1225 context they were created in. Add subsection 2.2.1 and new Appendix 1226 C describing types of shared objects and how sharing affects sync 1227 commands (also as a placeholder for a future, more general 1228 discussion of shared object semantics). Remove WaitSync, since 1229 that's useful when syncs are shared. Add issue 18 discussing the 1230 distinction between waiting on events vs. waiting on changes in sync 1231 status, and issue 19 discussing stacking of fence commands. Split 1232 FenceSync into two parts to create the sync vs. issue the fence 1233 command. 1234 1235 Version 5, 2006/02/24 - Add a bit to FenceSync to control the 1236 initial status value of the sync. Note that TestSync is polling the 1237 status value, not the condition which causes that status value to 1238 change. Make FinishSync return immediately if the status of the sync 1239 being waited on is true at the time it's called, and otherwise wait 1240 for the event underlying the status to occur; change issue 18 1241 accordingly. 1242 1243 Version 6, 2006/02/24 - Added Contributors list. Marked explicitly 1244 RESOLVED all issues that have been closed, including issues 2, 3, 6 1245 (partly unresolved), 7, 8 (merged with 19), 9, 10, 15, 17, and 18. 1246 Allow stacking behavior for Fence and define FinishSync to wait on 1247 the most recently issued fence command at the time FinishSync was 1248 called. Note that DeleteSyncs() may be called while fence commands 1249 are outstanding for a sync (issue 9). 1250 1251 Version 7, 2006/03/07 - Modify DeleteSyncs behavior to allow 1252 deleting syncs from contexts other than the creator, to avoid 1253 orphaned & undeleteable syncs. 1254 1255 Version 8, 2006/03/09 - A terminology change from "sync types" to 1256 "sync specializations" affects wording of several issues. Full 1257 multi-context awareness has been restored, with the aid of a compact 1258 set of rules defining sync signaling behavior (see issue 18). This 1259 significantly changes the resolution and discussion of issues 1, 8 1260 (FinishSync blocks on the first outstanding fence command to 1261 complete, not the most recently issued one), 9 (sync destruction is 1262 delayed until all outstanding fence commands complete), 10, and 18 1263 (describe the rules), and in the corresponding spec language. Added 1264 issues 19-21 discussing additional ways to control sync signaling, 1265 and providing several examples of multi-context sync usage. Enum 1266 values will not be shared with NV_fence. 1267 1268 Version 9, 2006/03/13 - Inserting multiple outstanding fence 1269 commands on a sync from different contexts may not be supported. 1270 Delaying sync destruction until there are no outstanding commands 1271 may be too expensive to support. Note resolution of new features 1272 (support timeouts, form TBD; support SignalSync; support conversion 1273 of syncs to OS events, at least for WGL). Add SignalSync spec 1274 language. 1275 1276 Version 10, 2006/03/20 - major rewrite to replace fence-specific 1277 discussion in FinishSync with Barthold's more powerful and generic 1278 "signaled"/"unsignaled" terminology (also changed name of 1279 SYNC_UNTRIGGERED_STATUS_BIT to SYNC_UNSIGNALED_BIT). Added a timeout 1280 parameter to FinishSync and removed the now-redundant TestSync. 1281 Introduced the notion of UST time and the GLtime datatype to 1282 represent it. FinishSync now returns a condition code explaining why 1283 it completed. Corrected "GetFenceuiv" to "GetSyncuiv" in several 1284 places. Changed value of SYNC_FLUSH_COMMANDS_BIT to be exclusive 1285 with SYNC_UNSIGNALED_BIT, even though they are passed to separate 1286 <flag> arguments, since we don't know their future uses. 1287 1288 Version 11, 2006/03/23 - noted potential IP concern (first mentioned 1289 WRT GL2_async_core at the March 2003 ARB meeting). Updated 1290 description of sync deletion for consistency with the description of 1291 texture object deletion in the GLX 1.4 specification. Noted in issue 1292 8 and Appendix C that inserting fence commands on the same sync from 1293 multiple threads is allowed. New issue 22 for better naming of 1294 FinishSync. Noted that accuracy of GLtime is system-dependent. Fixed 1295 several typos and added a missing error condition for FinishSync. 1296 1297 Version 12, 2006/03/31 - Changed FinishSync to ClientWaitSync. Note 1298 that ClientWaitSync behavior is explicitly undefined (and note 1299 several of the possible consequences) when a sync object being 1300 blocked upon is deleted. Used shorthand "signaled" and "unsignaled" 1301 in many places rather than the wordier "placed into the signaled 1302 state". Changed sync status to SIGNALED/UNSIGNALED rather than 1303 TRUE/FALSE, and rewrote SignalSync language accordingly. Updated 1304 Appendix C description of multicontext behavior to explicitly 1305 describe full multi-context awareness. Use "sync object" 1306 consistently throughout and drop the "sync" shorthand. Use 1307 "unsignaled" everywhere, instead of "non-signaled". Clean up Errors 1308 section, but don't remove errors just because they're inferred from 1309 the core spec - many other extensions also try to be comprehensive 1310 in listing errors. 1311 1312 Version 13, 2006/04/03 - Add overview paragraph to start of section 1313 5.6. Replace "poll" terminology with "test". Disambiguate status 1314 value returned from ClientWaitSync when the sync was signaled at 1315 call time, but timeout was zero. Clarify that fence commands are not 1316 events, but their execution triggers events. 1317 1318 Version 14, 2008/06/08 - Merge changes from the Longs Peak object 1319 model version of sync objects back into the GL2 API version for use 1320 in OpenGL 3.0. Introduce generic object interfaces using GL2 names 1321 and explicit attribute lists instead of attribute objects and use 1322 those as the base of sync object manipulation. Move the object 1323 shared flag, condition, and status into the attribute list. Replace 1324 FenceSync creation flags with Sync using an explicit object 1325 type parameter together with an attribute list mechanism. Add 1326 WaitSync and rename SYNC_GPU_COMMANDS_COMPLETE to allow for possible 1327 future definition of server and client completion conditions as 1328 discussed in issue 3. Add issues 23 and 24 discussing generic object 1329 interfaces and the potential utility of a default sync object. 1330 1331 Version 15, 2009/04/23 - Merge changes from (abandoned) draft GL 3.0 1332 language back into this extension for consideration as a GL 3.2 / 1333 ARB extension feature. Minor API and terminology changes, including 1334 generating sync names at creation time instead of using Gen* 1335 functions changing DeleteSyncs to DeleteSync, and using 1336 sync-specific GetSynciv instead of GetObjectiv. Specify that 1337 multiple waiters on a sync object are all released when it's 1338 signaled. Added new issues 25-28 and moved the Issues list to the 1339 bottom of the document. 1340 1341 Version 16, 2009/05/03 - Change Fence -> FenceSync and merge sync 1342 creation into the command, removing Sync (until other sync types are 1343 supported), and also removing the ability to stack fences on a 1344 single fence sync object. Remove <where> parameter from WaitSync and 1345 allow it to wait in either the server or GPU. Make syncs always 1346 shared and remove OBJECT_SHARED property. Add issue 29 on whether 1347 implementation-dependent max timeout intervals should be defined. 1348 1349 Version 17, 2009/05/06 - Replace GLtime with GLuint64. Add 1350 implementation-dependent maximum timeout interval state in table 40. 1351 Modify *WaitSync to clamp requested timeout to the appropriate 1352 maximum interval. Add GetInteger64v query for these values and issue 1353 30 about the type signature of the query. Add clarification in 1354 FenceSync of what it means for a fence command to complete. Add 1355 issue 31 about possibly confusing token naming. Additional minor 1356 typos and wording changes from Greg. 1357 1358 Version 18, 2009/05/08 - Generate INVALID_VALUE instead of 1359 INVALID_OPERATION when passing <sync> parameters that are not the 1360 names of sync objects. Remove leftover language saying that a bit of 1361 state is needed to specify if the sync is shared or not. Add 1362 clarification that requested <timeout> intervals are adjusted to the 1363 closest value supported by the implementation, and a footnote that 1364 FOREVER is just shorthand for the longest representable timeout. 1365 Change parameter names and error handling for GetSynciv to be 1366 consistent with other variable-length queries such as 1367 GetActiveAttrib. 1368 1369 Version 19, 2009/05/14 - Remove FOREVER and add sample code showing 1370 how to wait in the server for a specified time, or for the 1371 implementation-dependent maximum possible time. Resolve issue 24 by 1372 saying we don't need a "default sync object". 1373 1374 Version 20, 2009/05/15 - Re-tag all issues still marked as 1375 unresolved - none of them affect sync functionality, they are more 1376 speculative for future uses of syncs, or details of spec writing. 1377 1378 Version 21, 2009/07/01 - "Sync" up with 3.2 core spec draft: 1379 * Use GLsync instead of GLuint for sync object handle type in all 1380 relevant commands, 1381 * Change type of FenceSync <condition> to GLenum. 1382 * Add <flags> argument to FenceSync and corresponding SYNC_FLAGS 1383 property. 1384 * Remove MAX_CLIENT_WAIT_TIMEOUT. 1385 * Clarify that the actual client wait time may be longer than the 1386 requested <timeout> and that TIMEOUT_EXPIRED may be 1387 returned even when ClientWaitSync is called with a 1388 <timeout> of zero. 1389 * Require the <timeout> parameter to WaitSync to be a no-op value. 1390 * Remove SignalSync, until a sync object type other than a fence 1391 sync is defined. 1392 * Change type of <flags> parameter to 1393 ClientWaitSync and WaitSync to GLbitfield. 1394 * Fix spelling of SYNC_FLUSH_COMMANDS_BIT 1395 * Add issues 31-33 describing some of the changes. 1396 1397 Version 22, 2009/07/01 - Add TIMEOUT_IGNORED and WAIT_FAILED to New 1398 Tokens list. 1399 1400 Version 23, 2009/07/20 (Apollo 11 commemorative edition) - Assign 1401 enum values. 1402 1403 Version 24, 2009/07/24 - Rename stray GetSyncuiv functions to 1404 GetSynciv. 1405 1406 Version 25, 2009/09/18 - Correct spelling of SYNC_FLUSH_COMMAND_BIT 1407 to SYNC_FLUSH_COMMANDS_BIT in several places. 1408