1Name 2 3 KHR_fence_sync 4 5Name Strings 6 7 EGL_KHR_fence_sync 8 GL_OES_EGL_sync 9 VG_KHR_EGL_sync 10 11Contributors 12 13 Acorn Pooley 14 Gary King 15 Gregory Prisament 16 Jon Leech 17 18Contacts 19 20 Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) 21 Gary King, NVIDIA Corporation (gking 'at' nvidia.com) 22 Gregory Prisament, NVIDIA Corporation (gprisament 'at' nvidia.com) 23 Jon Leech (jon 'at' alumni.caltech.edu) 24 25Notice 26 27 Copyright (c) 2006-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 40Status 41 42 Complete. Approved by the EGL Working Group on March 3, 2010. 43 Approved by the Khronos Board of Promoters on April 30, 2010. 44 45Version 46 47 Version 24, January 31, 2014 48 49Number 50 51 EGL Extension #20 52 OpenGL ES Extension #75 53 OpenVG Extension #7 54 55Dependencies 56 57 Requires EGL 1.1 58 59 This extension is written against the wording of the EGL 1.2 60 Specification. 61 62Overview 63 64 This extension introduces the concept of "sync objects" into EGL. 65 Sync objects are a synchronization primitive, representing events 66 whose completion can be tested or waited upon. This extension 67 borrows heavily from the GL_ARB_sync extension and introduces a type 68 of sync object known as a "fence sync object" comparable to the 69 OpenGL fence sync object. The specification is designed to allow 70 additional types of sync objects to be easily introduced in later 71 extensions. 72 73 Fence sync objects have corresponding fence commands, which are 74 inserted into a client API command stream at the time the fence sync 75 is created. A fence sync object is used to wait for completion of 76 the corresponding fence command. This allows applications to request 77 a partial Finish of an API command stream, wherein all commands 78 issued in a particular client API context will be forced to complete 79 before control is returned to the calling thread. 80 81 This document describes three different extension strings 82 collectively. The "EGL_KHR_fence_sync" string indicates that fence 83 syncs and the corresponding interfaces (to create and place a fence, 84 destroy, query, and wait on) are supported. 85 86 The remaining extensions list valid client APIs for fence syncs. The 87 "GL_OES_EGL_sync" string indicates that a fence sync object can be 88 created in association with a fence command placed in the command 89 stream of a bound OpenGL ES context. The "VG_KHR_EGL_sync" string 90 indicates the same thing for a bound OpenVG context. 91 92New Types 93 94 /* 95 * EGLSyncKHR is an opaque handle to an EGL sync object 96 */ 97 typedef void* EGLSyncKHR; 98 99 /* 100 * EGLTimeKHR is a 64-bit unsigned integer representing intervals 101 * in nanoseconds. 102 */ 103 #include <khrplatform.h> 104 typedef khronos_utime_nanoseconds_t EGLTimeKHR; 105 106 107New Procedures and Functions 108 109 EGLSyncKHR eglCreateSyncKHR( 110 EGLDisplay dpy, 111 EGLenum type, 112 const EGLint *attrib_list); 113 114 EGLBoolean eglDestroySyncKHR( 115 EGLDisplay dpy, 116 EGLSyncKHR sync); 117 118 EGLint eglClientWaitSyncKHR( 119 EGLDisplay dpy, 120 EGLSyncKHR sync, 121 EGLint flags, 122 EGLTimeKHR timeout); 123 124 EGLBoolean eglGetSyncAttribKHR( 125 EGLDisplay dpy, 126 EGLSyncKHR sync, 127 EGLint attribute, 128 EGLint *value); 129 130 131New Tokens 132 133 Accepted by the <type> parameter of eglCreateSyncKHR, and returned 134 in <value> when eglGetSyncAttribKHR is called with <attribute> 135 EGL_SYNC_TYPE_KHR: 136 137 EGL_SYNC_FENCE_KHR 0x30F9 138 139 Accepted by the <attribute> parameter of eglGetSyncAttribKHR: 140 141 EGL_SYNC_TYPE_KHR 0x30F7 142 EGL_SYNC_STATUS_KHR 0x30F1 143 EGL_SYNC_CONDITION_KHR 0x30F8 144 145 Returned in <value> when eglGetSyncAttribKHR is called with 146 <attribute> EGL_SYNC_STATUS_KHR: 147 148 EGL_SIGNALED_KHR 0x30F2 149 EGL_UNSIGNALED_KHR 0x30F3 150 151 Returned in <value> when eglGetSyncAttribKHR is called with 152 <attribute> EGL_SYNC_CONDITION_KHR: 153 154 EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR 0x30F0 155 156 Accepted in the <flags> parameter of eglClientWaitSyncKHR: 157 158 EGL_SYNC_FLUSH_COMMANDS_BIT_KHR 0x0001 159 160 Accepted in the <timeout> parameter of eglClientWaitSyncKHR: 161 162 EGL_FOREVER_KHR 0xFFFFFFFFFFFFFFFFull 163 164 Returned by eglClientWaitSyncKHR: 165 166 EGL_TIMEOUT_EXPIRED_KHR 0x30F5 167 EGL_CONDITION_SATISFIED_KHR 0x30F6 168 169 Returned by eglCreateSyncKHR in the event of an error: 170 171 EGL_NO_SYNC_KHR ((EGLSyncKHR)0) 172 173Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) 174 175 Add a new subsection at the end of Section 3.8, page 43 176 (Synchronization Primitives) 177 178 "3.8.1 Sync Objects 179 180 In addition to the aforementioned synchronization functions, which 181 provide an efficient means of serializing client and native API 182 operations within a thread, <sync objects> are provided to enable 183 synchronization of client API operations between threads and/or 184 between API contexts. Sync objects may be tested or waited upon by 185 application threads. 186 187 Sync objects have a status with two possible states: <signaled> and 188 <unsignaled>. Initially, sync objects are unsignaled. EGL may be 189 asked to wait for a sync object to become signaled, or a sync 190 object's status may be queried. 191 192 Depending on the type of a sync object, its status may be changed 193 either by an external event, or by explicitly signaling and 194 unsignaling the sync. 195 196 Sync objects are associated with an EGLDisplay when they are 197 created, and have <attributes> defining additional aspects of the 198 sync object. All sync objects include attributes for their type and 199 their status. Additional attributes are discussed below 200 for different types of sync objects. 201 202 <Fence sync objects> are created in association with a <fence 203 command> in a client API. When the client API executes the fence 204 command, an event is generated which signals the corresponding fence 205 sync object. Fence sync objects may not be explicitly signaled, and 206 may only change their status once, from the initial unsignaled 207 status to signaled. Fence sync objects may be used to wait for 208 partial completion of a client API command stream, as a more 209 flexible form of glFinish / vgFinish. 210 211 The command 212 213 EGLSyncKHR eglCreateSyncKHR( 214 EGLDisplay dpy, 215 EGLenum type, 216 const EGLint *attrib_list); 217 218 creates a sync object of the specified <type> associated with the 219 specified display <dpy>, and returns a handle to the new object. 220 <attrib_list> is an attribute-value list specifying other attributes 221 of the sync object, terminated by an attribute entry EGL_NONE. 222 Attributes not specified in the list will be assigned their default 223 values. 224 225 If <type> is EGL_SYNC_FENCE_KHR, a fence sync object is created. In 226 this case <attrib_list> must be NULL or empty (containing only 227 EGL_NONE). Attributes of the fence sync object are 228 set as follows: 229 230 Attribute Name Initial Attribute Value(s) 231 --------------- -------------------------- 232 EGL_SYNC_TYPE_KHR EGL_SYNC_FENCE_KHR 233 EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR 234 EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR 235 236 When a fence sync object is created, eglCreateSyncKHR also inserts a 237 fence command into the command stream of the bound client API's 238 current context (i.e., the context returned by 239 eglGetCurrentContext), and associates it with the newly created sync 240 object. 241 242 When the condition of the sync object is satisfied by the fence 243 command, the sync is signaled by the associated client API context, 244 causing any eglClientWaitSyncKHR commands (see below) blocking on 245 <sync> to unblock. The only condition currently supported is 246 EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by 247 completion of the fence command corresponding to the sync object, 248 and all preceding commands in the associated client API context's 249 command stream. The sync object will not be signaled until all 250 effects from these commands on the client API's internal and 251 framebuffer state are fully realized. No other state is affected by 252 execution of the fence command. 253 254 Each client API which supports fence commands indicates this support 255 in the form of a client API extension. If the GL_OES_EGL_sync 256 extension is supported by OpenGL ES (either version 1.x or 2.0), a 257 fence sync object may be created when the currently bound API is 258 OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG, 259 a fence sync object may be created when the currently bound API is 260 OpenVG. 261 262 Errors 263 ------ 264 265 * If <dpy> is not the name of a valid, initialized EGLDisplay, 266 EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is 267 generated. 268 * If <attrib_list> is neither NULL nor empty (containing only 269 EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE 270 error is generated. 271 * If <type> is not a supported type of sync object, 272 EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is 273 generated. 274 * If <type> is EGL_SYNC_FENCE_KHR and no context is current for 275 the bound API (i.e., eglGetCurrentContext returns 276 EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an 277 EGL_BAD_MATCH error is generated. 278 * If <type> is EGL_SYNC_FENCE_KHR and <dpy> does not match the 279 EGLDisplay of the currently bound context for the currently 280 bound client API (the EGLDisplay returned by 281 eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an 282 EGL_BAD_MATCH error is generated. 283 * If <type> is EGL_SYNC_FENCE_KHR and the currently bound client 284 API does not support the client API extension indicating it can 285 place fence commands, then EGL_NO_SYNC_KHR is returned and an 286 EGL_BAD_MATCH error is generated. 287 288 The command 289 290 EGLint eglClientWaitSyncKHR( 291 EGLDisplay dpy, 292 EGLSyncKHR sync, 293 EGLint flags, 294 EGLTimeKHR timeout); 295 296 blocks the calling thread until the specified sync object <sync> is 297 signaled, or until <timeout> nanoseconds have passed. 298 299 More than one eglClientWaitSyncKHR may be outstanding on the same 300 <sync> at any given time. When there are multiple threads blocked on 301 the same <sync> and the sync object is signaled, all such threads 302 are released, but the order in which they are released is not 303 defined. 304 305 If the value of <timeout> is zero, then eglClientWaitSyncKHR simply 306 tests the current status of <sync>. If the value of <timeout> is the 307 special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not 308 time out. For all other values, <timeout> is adjusted to the closest 309 value allowed by the implementation-dependent timeout accuracy, 310 which may be substantially longer than one nanosecond. 311 312 eglClientWaitSyncKHR returns one of three status values describing 313 the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR 314 indicates that the specified timeout period expired before <sync> 315 was signaled, or if <timeout> is zero, indicates that <sync> is 316 not signaled. A return value of EGL_CONDITION_SATISFIED_KHR 317 indicates that <sync> was signaled before the timeout expired, which 318 includes the case when <sync> was already signaled when 319 eglClientWaitSyncKHR was called. If an error occurs then an error is 320 generated and EGL_FALSE is returned. 321 322 If the sync object being blocked upon will not be signaled in finite 323 time (for example, by an associated fence command issued previously, 324 but not yet flushed to the graphics pipeline), then 325 eglClientWaitSyncKHR may wait forever. To help prevent this behavior 326 (footnote1), if the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is set in 327 <flags>, and <sync> is unsignaled when eglClientWaitSyncKHR is 328 called, then the equivalent of Flush() will be performed for the 329 current API context (i.e., the context returned by 330 eglGetCurrentContext()) before blocking on <sync>. If no context is 331 current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit 332 is ignored. 333 334 [footnote 1: The simple Flush behavior defined by 335 EGL_SYNC_FLUSH_COMMANDS_BIT_KHR will not help when waiting for a 336 fence command issued in a different context's command stream. 337 Applications which block on a fence sync object must take 338 additional steps to ensure that the context from which the 339 associated fence command was issued has flushed that command to 340 the graphics pipeline.] 341 342 Errors 343 ------ 344 345 * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is 346 returned and an EGL_BAD_PARAMETER error is generated. 347 * If <dpy> does not match the EGLDisplay passed to 348 eglCreateSyncKHR when <sync> was created, the behaviour is 349 undefined. 350 351 352 The command 353 354 EGLBoolean eglGetSyncAttribKHR( 355 EGLDisplay dpy, 356 EGLSyncKHR sync, 357 EGLint attribute, 358 EGLint *value); 359 360 is used to query attributes of the sync object <sync>. Legal values 361 for <attribute> depend on the type of sync object, as shown in table 362 3.cc. Assuming no errors are generated, EGL_TRUE is returned and the 363 value of the queried attribute is returned in <value>. 364 365 Attribute Description Supported Sync Objects 366 ----------------- ----------------------- ---------------------- 367 EGL_SYNC_TYPE_KHR Type of the sync object All 368 EGL_SYNC_STATUS_KHR Status of the sync object All 369 EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR only 370 371 Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command 372 373 Errors 374 ------ 375 376 * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is 377 returned and an EGL_BAD_PARAMETER error is generated. 378 * If <dpy> does not match the display passed to eglCreateSyncKHR 379 when <sync> was created, the behaviour is undefined. 380 * If <attribute> is not one of the attributes in table 3.cc, 381 EGL_FALSE is returned and an EGL_BAD_ATTRIBUTE error is 382 generated. 383 * If <attribute> is not supported for the type of sync object 384 passed in <sync>, EGL_FALSE is returned and an EGL_BAD_MATCH 385 error is generated. 386 387 If any error occurs, <*value> is not modified. 388 389 The command 390 391 EGLBoolean eglDestroySyncKHR( 392 EGLDisplay dpy, 393 EGLSyncKHR sync); 394 395 is used to destroy an existing sync object. 396 397 If any eglClientWaitSyncKHR commands are blocking on <sync> when 398 eglDestroySyncKHR is called, <sync> is flagged for deletion and will 399 be deleted when it is no longer associated with any fence command 400 and is no longer blocking any eglClientWaitSyncKHR command. 401 402 If no errors are generated, EGL_TRUE is returned, and <sync> will no 403 longer be the handle of a valid sync object. 404 405 Errors 406 ------ 407 408 * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is 409 returned and an EGL_BAD_PARAMETER error is generated. 410 * If <dpy> does not match the display passed to eglCreateSyncKHR 411 when <sync> was created, the behaviour is undefined. 412 413Issues 414 415 Note about the Issues 416 --------------------- 417 The wording for this extension was originally written as a single 418 extension defining two types of sync object; a "reusable sync 419 object" and a "fence sync object". That extension was split to 420 produce standalone extensions for each type of sync object, and 421 references to the other type removed from the specification 422 language. This issues list has been simplied to remove references to 423 reusable sync objects but is otherwise very similar to the 424 EGL_KHR_reusable_sync extension issues list. 425 426 1. [REMOVED - found in the reusable_sync extension.] 427 428 2. [REMOVED - found in the reusable_sync extension.] 429 430 3. What does this extension provide that can not be accomplished 431 with the existing, more efficient eglWaitClient and eglWaitNative 432 API functions? 433 434 RESPONSE: eglWaitClient and eglWaitNative may be implemented in 435 extremely lightweight manners, in some cases not blocking the 436 calling thread at all; however, they can not be used to synchronize 437 between client API contexts and native APIs executing in separate 438 threads (or simply between client API contexts executing in separate 439 threads), such as between a thread with an active OpenGL context and 440 a second thread performing video decode. 441 442 4. What does this extension provide that could not be accomplished 443 with native platform synchronization primitives and the existing 444 client API Finish commands? 445 446 RESPONSE: This extension provides a lighter-weight mechanism for 447 synchronizing an application with client API command streams than 448 the all-or-nothing Finish commands, enabling applications to block 449 until a subset of issued client API commands have completed. 450 451 5. [REMOVED - found in the reusable_sync extension.] 452 453 6. Please provide a more detailed description of how 454 eglClientWaitSyncKHR behaves. 455 456 RESOLVED: eglClientWaitSyncKHR blocks until the status of the sync 457 object transitions to the signaled state. Sync object status is 458 either signaled or unsignaled. More detailed rules describing 459 signalling follow (these may need to be imbedded into the actual 460 spec language): 461 462 * A fence sync object has two possible status values: signaled or 463 unsignaled. 464 * When created, the status of the sync object is unsignaled. 465 * A fence command is inserted into a command stream. A fence sync 466 object is not. 467 * A fence command, once its condition has been met, will set its 468 associated sync object to the signaled state. The only condition 469 currently supported is EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR. 470 * A wait function, such as ClientWaitSyncKHR, waits on a fence 471 sync object, not on a fence command. 472 * A wait function called on a sync object in the unsignaled state 473 will block. It unblocks (note, not "returns to the application") 474 when the sync object transitions to the signaled state. 475 * A wait function called on a sync object in the signaled state 476 will return immediately. 477 478 7. [REMOVED - found in the reusable_sync extension.] 479 480 8. [REMOVED - found in the reusable_sync extension.] 481 482 9. Should eglDestroySyncKHR release all WaitSyncs placed on a fence 483 sync object? 484 485 RESOLVED: No. (note that this behavior differs from reusable syncs.) 486 487 Fence sync objects are intended to be signalled by the graphics 488 driver within a short period of time (typically less than 1 second 489 after creation) and so should not cause waiting threads to hang 490 forever. To reduce implementation complexity, fence sync objects are 491 defined to not release waiting threads; waiting threads are released 492 normally when their condition is satisfied or their timeout expires. 493 The handle to a fence sync object immediately becomes invalid 494 following a call to eglDestroySyncKHR. 495 496Revision History 497 498#24 (Jon Leech, January 31, 2014) 499 - Clarify return value of ClientWaitSyncKHR when called with <timeout> 500 of zero for an unsignaled <sync> (Bug 11576). 501#23 (Jon Leech, April 23, 2013) 502 - Simplify issues list to remove issues specific to reusable sync 503 objects and general sync object design issues. 504#22 (Jon Leech, June 15, 2010) 505 - Correct minor typos in GL/VG extension names. 506#21 (Jon Leech, May 5, 2010) 507 - Correct minor typos, assign extension numbers for EGL, OpenGL ES, 508 and OpenVG, and publish in the registry, 509#20 (Robert Palmer, July 14, 2009) 510 - Branch wording from draft KHR_sync specification. Remove ability 511 to create "reusable sync objects and all tokens/wording specific 512 to them. 513#19 (Robert Palmer, July 22, 2009) 514 - Replace specific eglCreateSyncKHR error cases for bad <type> 515 argument with extensible catch-all case. 516#18 (Robert Palmer, July 8, 2009) 517 - Issues 8 and 9 declared resolved in EGL meeting 2009-07-08 518#17 (Robert Palmer, July 8, 2009) 519 - Update eglDestroySyncKHR to special-case deletion of fence sync 520 objects. This is explained in issue 9. 521 - Corrected EGL_REUSABLE_SYNC_KHR -> EGL_SYNC_REUSABLE_KHR 522 - Define value for EGL_SYNC_REUSABLE_KHR 523 - Fix typo and whitespace 524#16 (Jon Leech, July 7, 2009) 525 - Update description of new tokens to match changes to the 526 eglCreateSyncKHR entry point in revision 15. 527#15 (Jon Leech, June 16, 2009) 528 - Define separate one-time fence sync and reusable sync extensions 529 and corresponding extension strings. Remove AUTO_RESET and 530 eglFenceKHR. Rename eglCreateFenceSyncKHR to eglCreateSyncKHR and 531 change initial status of reusable syncs to unsignaled. Clarify 532 which functions apply to which types of sync objects. Update 533 issues list. 534#14 (Jon Leech, April 29, 2009) 535 - Clarify that all waiters are woken up on signalling a sync. 536 Remove tabs to cleanup some formatting issues. 537#13 (Acorn Pooley, April 2, 2009) 538 - Renamed 539 GL_OES_egl_sync -> GL_OES_EGL_sync 540 VG_KHR_egl_sync -> VG_KHR_EGL_sync 541#12 (Jon Leech, April 1, 2009) 542 - Changed sync flags type from EGLuint to EGLint and add issue 7. 543#11 (Acorn Pooley, February 4, 2009) 544 - add error case to eglGetSyncAttribKHR. 545 - fix year on rev 8-10 (2008->2009) 546#10 (Acorn Pooley, February 4, 2009) 547 - clarify some error message descriptions 548#9 (Greg Prisament, January 15, 2009) 549 - Destroy now wakes up all waits (eglClientWaitSyncKHR) 550 - Add EGLDisplay <dpy> as first parameter to all commands 551 - Split into 3 extension strings, EGL_KHR_sync, GL_OES_egl_sync, 552 VG_KHR_egl_sync, all described in this document. 553 - Add attribute AUTO_RESET_KHR 554 - Time type uses the type from khrplatform.h 555 - Remove EGL_ALREADY_SIGNALLED 556#8 (Jon Leech, November 11, 2009) 557 - Assign enum values 558#7 (Acorn Pooley, October 30, 2008) 559 - Fix typos 560 - remove obsolete wording about Native sync objects (see issue 5) 561 - formatting: remove tabs, 80 columns 562#6 (Acorn Pooley, October 27, 2008) 563 - Corrected 'enum' to 'EGLenum' in prototypes. 564#5 (Jon Leech, September 9, 2008) 565 - Removed native sync support (eglCreateNativeSyncKHR and 566 EGL_SYNC_NATIVE_SYNC_KHR), and re-flowed spec to fit in 80 columns. 567#4 (Jon Leech, November 20, 2007) 568 - Corrected 'enum' to 'EGLenum' in prototypes. 569#3 (Jon Leech, April 5, 2007) 570 - Added draft Status and TBD Number 571#2 (November 27, 2006) 572 - Changed OES token to KHR 573