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