| Name |
| |
| KHR_reusable_sync |
| |
| Name Strings |
| |
| EGL_KHR_reusable_sync |
| |
| Contributors |
| |
| Acorn Pooley |
| Gary King |
| Gregory Prisament |
| Jon Leech |
| Robert Palmer |
| |
| Contacts |
| |
| Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com) |
| Gary King, NVIDIA Corporation (gking 'at' nvidia.com) |
| Gregory Prisament, NVIDIA Corporation (gprisament 'at' nvidia.com) |
| Jon Leech (jon 'at' alumni.caltech.edu) |
| Robert Palmer (robert.palmer 'at' nokia.com) |
| |
| Notice |
| |
| Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Status |
| |
| Complete. |
| Approved by the Khronos Board of Promoters on August 28, 2009. |
| |
| Version |
| |
| Version 22, January 31, 2014 |
| |
| Number |
| |
| EGL Extension #6 |
| |
| Dependencies |
| |
| Requires EGL 1.1 |
| |
| This extension is written against the wording of the EGL 1.2 |
| Specification. |
| |
| Overview |
| |
| This extension introduces the concept of "sync objects" into EGL. |
| Sync objects are a synchronization primitive, representing events |
| whose completion can be tested or waited upon. This extension |
| borrows from the GL_ARB_sync extension but introduces a type of sync |
| object known as "reusable sync object" comparable to an OS |
| semaphore. The specification is designed to allow additional types of |
| sync objects to be easily introduced in later extensions. |
| |
| Reusable sync objects may be used to synchronize activity between |
| threads or between client APIs. Synchronization is accomplished by |
| explicitly changing the status of a reusable object using EGL API |
| commands. |
| |
| New Types |
| |
| /* |
| * EGLSyncKHR is an opaque handle to an EGL sync object |
| */ |
| typedef void* EGLSyncKHR; |
| |
| /* |
| * EGLTimeKHR is a 64-bit unsigned integer representing intervals |
| * in nanoseconds. |
| */ |
| #include <khrplatform.h> |
| typedef khronos_utime_nanoseconds_t EGLTimeKHR; |
| |
| |
| New Procedures and Functions |
| |
| EGLSyncKHR eglCreateSyncKHR( |
| EGLDisplay dpy, |
| EGLenum type, |
| const EGLint *attrib_list); |
| |
| EGLBoolean eglDestroySyncKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync); |
| |
| EGLint eglClientWaitSyncKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync, |
| EGLint flags, |
| EGLTimeKHR timeout); |
| |
| EGLBoolean eglSignalSyncKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync, |
| EGLenum mode); |
| |
| EGLBoolean eglGetSyncAttribKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync, |
| EGLint attribute, |
| EGLint *value); |
| |
| |
| New Tokens |
| |
| Accepted by the <type> parameter of eglCreateSyncKHR, and returned |
| in <value> when eglGetSyncAttribKHR is called with <attribute> |
| EGL_SYNC_TYPE_KHR: |
| |
| EGL_SYNC_REUSABLE_KHR 0x30FA |
| |
| Accepted by the <attribute> parameter of eglGetSyncAttribKHR: |
| |
| EGL_SYNC_TYPE_KHR 0x30F7 |
| EGL_SYNC_STATUS_KHR 0x30F1 |
| |
| Accepted by the <mode> parameter of eglSignalSyncKHR and returned in |
| <value> when eglGetSyncAttribKHR is called with <attribute> |
| EGL_SYNC_STATUS_KHR: |
| |
| EGL_SIGNALED_KHR 0x30F2 |
| EGL_UNSIGNALED_KHR 0x30F3 |
| |
| Accepted in the <flags> parameter of eglClientWaitSyncKHR: |
| |
| EGL_SYNC_FLUSH_COMMANDS_BIT_KHR 0x0001 |
| |
| Accepted in the <timeout> parameter of eglClientWaitSyncKHR: |
| |
| EGL_FOREVER_KHR 0xFFFFFFFFFFFFFFFFull |
| |
| Returned by eglClientWaitSyncKHR: |
| |
| EGL_TIMEOUT_EXPIRED_KHR 0x30F5 |
| EGL_CONDITION_SATISFIED_KHR 0x30F6 |
| |
| Returned by eglCreateSyncKHR in the event of an error: |
| |
| EGL_NO_SYNC_KHR ((EGLSyncKHR)0) |
| |
| Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) |
| |
| Add a new subsection at the end of Section 3.8, page 43 |
| (Synchronization Primitives) |
| |
| "3.8.1 Sync Objects |
| |
| In addition to the aforementioned synchronization functions, which |
| provide an efficient means of serializing client and native API |
| operations within a thread, <sync objects> are provided to enable |
| synchronization of client API operations between threads and/or |
| between API contexts. Sync objects may be tested or waited upon by |
| application threads. |
| |
| Sync objects have a status with two possible states: <signaled> and |
| <unsignaled>. Initially, sync objects are unsignaled. EGL may be |
| asked to wait for a sync object to become signaled, or a sync |
| object's status may be queried. |
| |
| Depending on the type of a sync object, its status may be changed |
| either by an external event, or by explicitly signaling and |
| unsignaling the sync. |
| |
| Sync objects are associated with an EGLDisplay when they are |
| created, and have <attributes> defining additional aspects of the |
| sync object. All sync objects include attributes for their type and |
| their status. Additional attributes are discussed below |
| for different types of sync objects. |
| |
| <Reusable sync objects> are created in the unsignaled state, and may |
| be signaled and/or unsignaled repeatedly. Every transition of a |
| reusable sync object's status from unsignaled to signaled will |
| release any threads waiting on that sync object. |
| |
| The command |
| |
| EGLSyncKHR eglCreateSyncKHR( |
| EGLDisplay dpy, |
| EGLenum type, |
| const EGLint *attrib_list); |
| |
| creates a sync object of the specified <type> associated with the |
| specified display <dpy>, and returns a handle to the new object. |
| <attrib_list> is an attribute-value list specifying other attributes |
| of the sync object, terminated by an attribute entry EGL_NONE. |
| Attributes not specified in the list will be assigned their default |
| values. |
| |
| If <type> is EGL_SYNC_REUSABLE_KHR, a reusable sync object is |
| created. In this case <attrib_list> must be NULL or empty |
| (containing only EGL_NONE). Attributes of the reusable sync object |
| are set as follows: |
| |
| Attribute Name Initial Attribute Value(s) |
| --------------- -------------------------- |
| EGL_SYNC_TYPE_KHR EGL_SYNC_REUSABLE_KHR |
| EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR |
| |
| Errors |
| ------ |
| |
| * If <dpy> is not the name of a valid, initialized EGLDisplay, |
| EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is |
| generated. |
| * If <attrib_list> is neither NULL nor empty (containing only |
| EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE |
| error is generated. |
| * If <type> is not a supported type of sync object, |
| EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is |
| generated. |
| |
| The command |
| |
| EGLint eglClientWaitSyncKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync, |
| EGLint flags, |
| EGLTimeKHR timeout); |
| |
| blocks the calling thread until the specified sync object <sync> is |
| signaled, or until <timeout> nanoseconds have passed. |
| |
| More than one eglClientWaitSyncKHR may be outstanding on the same |
| <sync> at any given time. When there are multiple threads blocked on |
| the same <sync> and the sync object is signaled, all such threads |
| are released, but the order in which they are released is not |
| defined. |
| |
| If the value of <timeout> is zero, then eglClientWaitSyncKHR simply |
| tests the current status of <sync>. If the value of <timeout> is the |
| special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not |
| time out. For all other values, <timeout> is adjusted to the closest |
| value allowed by the implementation-dependent timeout accuracy, |
| which may be substantially longer than one nanosecond. |
| |
| eglClientWaitSyncKHR returns one of three status values describing |
| the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR |
| indicates that the specified timeout period expired before <sync> |
| was signaled, or if <timeout> is zero, indicates that <sync> is |
| not signaled. A return value of EGL_CONDITION_SATISFIED_KHR |
| indicates that <sync> was signaled before the timeout expired, which |
| includes the case when <sync> was already signaled when |
| eglClientWaitSyncKHR was called. If an error occurs then an error is |
| generated and EGL_FALSE is returned. |
| |
| If the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is set in |
| <flags>, and <sync> is unsignaled when eglClientWaitSyncKHR is |
| called, then the equivalent of Flush() will be performed for the |
| current API context (i.e., the context returned by |
| eglGetCurrentContext()) before blocking on <sync>. If no context is |
| current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit |
| is ignored. |
| |
| If a sync object is destroyed while an eglClientWaitSyncKHR is |
| blocking on that object, eglClientWaitSyncKHR will unblock and |
| return immediately, just as if the sync object had been signaled |
| prior to being destroyed. |
| |
| Errors |
| ------ |
| |
| * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is |
| returned and an EGL_BAD_PARAMETER error is generated. |
| * If <dpy> does not match the EGLDisplay passed to |
| eglCreateSyncKHR when <sync> was created, the behaviour is |
| undefined. |
| |
| |
| The command |
| |
| EGLBoolean eglSignalSyncKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync, |
| EGLenum mode); |
| |
| signals or unsignals the reusable sync object <sync> by changing its |
| status to <mode>, which must be one of the values in table 3.bb. If |
| as a result of calling eglSignalSyncKHR the status of <sync> |
| transitions from unsignaled to signaled, any eglClientWaitSyncKHR |
| commands blocking on <sync> will unblock. |
| |
| Assuming no errors are generated, EGL_TRUE is returned. |
| |
| Mode Effect |
| ------------------ ------------- |
| EGL_SIGNALED_KHR Set the status of <sync> to signaled |
| EGL_UNSIGNALED_KHR Set the status of <sync> to unsignaled |
| |
| Table 3.bb Modes Accepted by eglSignalSyncKHR Command |
| |
| Errors |
| ------ |
| |
| * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is |
| returned and an EGL_BAD_PARAMETER error is generated. |
| * If the type of <sync> is not EGL_SYNC_REUSABLE_KHR, EGL_FALSE is |
| returned and an EGL_BAD_MATCH error is generated. |
| * If <dpy> does not match the EGLDisplay passed to |
| eglCreateSyncKHR when <sync> was created, the behaviour is |
| undefined. |
| |
| |
| The command |
| |
| EGLBoolean eglGetSyncAttribKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync, |
| EGLint attribute, |
| EGLint *value); |
| |
| is used to query attributes of the sync object <sync>. Legal values |
| for <attribute> depend on the type of sync object, as shown in table |
| 3.cc. Assuming no errors are generated, EGL_TRUE is returned and the |
| value of the queried attribute is returned in <value>. |
| |
| Attribute Description Supported Sync Objects |
| ----------------- ----------------------- ---------------------- |
| EGL_SYNC_TYPE_KHR Type of the sync object All |
| EGL_SYNC_STATUS_KHR Status of the sync object All |
| |
| Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command |
| |
| Errors |
| ------ |
| |
| * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is |
| returned and an EGL_BAD_PARAMETER error is generated. |
| * If <dpy> does not match the display passed to eglCreateSyncKHR |
| when <sync> was created, the behaviour is undefined. |
| * If <attribute> is not one of the attributes in table 3.cc, |
| EGL_FALSE is returned and an EGL_BAD_ATTRIBUTE error is |
| generated. |
| * If <attribute> is not supported for the type of sync object |
| passed in <sync>, EGL_FALSE is returned and an EGL_BAD_MATCH |
| error is generated. |
| |
| If any error occurs, <*value> is not modified. |
| |
| The command |
| |
| EGLBoolean eglDestroySyncKHR( |
| EGLDisplay dpy, |
| EGLSyncKHR sync); |
| |
| is used to destroy an existing sync object. If any |
| eglClientWaitSyncKHR commands are blocking on <sync> when |
| eglDestroySyncKHR is called, they will be woken up, as if <sync> |
| were signaled. |
| |
| If no errors are generated, EGL_TRUE is returned, and <sync> will no |
| longer be the handle of a valid sync object. |
| |
| Errors |
| ------ |
| |
| * If <sync> is not a valid sync object for <dpy>, EGL_FALSE is |
| returned and an EGL_BAD_PARAMETER error is generated. |
| * If <dpy> does not match the display passed to eglCreateSyncKHR |
| when <sync> was created, the behaviour is undefined." |
| |
| Issues |
| |
| Note about the Issues |
| --------------------- |
| The wording for this extension was originally written as a single |
| extension defining two types of sync object; a "reusable sync |
| object" and a "fence sync object". That extension was split to |
| produce standalone extensions for each type of sync object, and |
| references to the other type removed from the specification |
| language. This issues list has been simplied to remove references to |
| fence sync objects but is otherwise very similar to the |
| EGL_KHR_fence_sync extension issues list. |
| |
| 1. Explain the key choices made in this extension. |
| |
| RESPONSE: This extension has been written to enable adoption to be |
| as wide as possible, and to behave as similarly as possible to |
| synchronization primitives available in desktop OpenGL (e.g., |
| NV_fence, ARB_sync). |
| |
| In the interest of enabling widespread adoption, this extension |
| (following the ARB_sync model) has foregone the inclusion of |
| synchronization primitives and synchronization tests which may be |
| performed entirely inside client API command streams, instead |
| performing synchronization tests (eglClientWaitSyncKHR) inside the |
| application & host CPU. |
| |
| In the interest of maintaining similarity with previous |
| synchronization primitives, this extension attempts to copy the |
| ARB_sync specification wherever possible (both functionally and |
| stylistically), only making changes where needed to operate inside |
| EGL (rather than a client API context) and match EGL naming |
| conventions. |
| |
| 2. Why place this behavior in EGL, rather than in the client APIs? |
| |
| RESPONSE: Ultimately, synchronization between multiple asynchronous |
| client API contexts (potentially executing in different threads) is |
| a problem which affects or will affect all EGL client APIs. Rather |
| than creating separate synchronization primitives in each of the |
| client APIs (and then wrapping them in an EGL container), in the |
| interest of developer simplicity & consistency this behavior is |
| being placed inside EGL. |
| |
| 3. What does this extension provide that can not be accomplished |
| with the existing, more efficient eglWaitClient and eglWaitNative |
| API functions? |
| |
| RESPONSE: eglWaitClient and eglWaitNative may be implemented in |
| extremely lightweight manners, in some cases not blocking the |
| calling thread at all; however, they can not be used to synchronize |
| between client API contexts and native APIs executing in separate |
| threads (or simply between client API contexts executing in separate |
| threads), such as between a thread with an active OpenGL context and |
| a second thread performing video decode. |
| |
| 4. [REMOVED - found in the fence_sync extension.] |
| |
| 5. Should integration with native platform synchronization objects |
| be included in this extension, or reserved for future |
| (platform-specific) extensions? |
| |
| RESOLVED: Integration with native platform synchronization objects |
| should not be part of this extension, but can be added as future |
| layered extensions if needed. These layered extensions can be |
| platform-specific, or perhaps OpenKODE based. |
| |
| Originally, this extension included the ability to create native |
| platform synchronization objects from EGLSync objects. This feature |
| was removed for a few reasons: |
| |
| i) The proposed mechanism suggested mapping EGLSync objects to |
| pthread conditional variables on platforms with pthread support. |
| However, pthread conditional variables require an associated |
| mutex and there was no mechanism to relay this associated mutex |
| to the application. |
| |
| ii) On certain platforms support for converting to native |
| platform synchronization objects adds great complexity to the |
| implementation. |
| |
| iii) Now that OpenKODE is more mature, it would be better to |
| allow conversion from EGLSyncKHR objects to OpenKODE |
| synchronization primitives rather than platform-specific ones. |
| We suggest that this functionality, if needed, be added as a |
| layered extension instead of being included here. This way, |
| EGL_KHR_sync remains minimal and easy to implement on a variety |
| of platforms. |
| |
| 6. Please provide a more detailed description of how |
| eglClientWaitSyncKHR behaves. |
| |
| RESOLVED: eglClientWaitSyncKHR blocks until the status of the sync |
| object transitions to the signaled state. Sync object status is |
| either signaled or unsignaled. More detailed rules describing |
| signalling follow (these may need to be imbedded into the actual |
| spec language): |
| |
| * A reusable sync object has two possible status values: signaled |
| or unsignaled. |
| * When created, the status of the sync object is unsignaled by |
| default. |
| * A reusable sync can be set to signaled or unsignaled |
| status using eglSignalSyncKHR. |
| * A wait function called on a sync object in the unsignaled state |
| will block. It unblocks (note, not "returns to the application") |
| when the sync object transitions to the signaled state. |
| * A wait function called on a sync object in the signaled state |
| will return immediately. |
| |
| 7. Should the 'flags' argument to eglClientWaitSyncKHR be |
| EGLint or EGLuint? |
| |
| RESOLVED: EGLint, setting a precedent for explicit bitmask types |
| in EGL going forward. We don't have an EGLuint type and it is |
| overkill for this purposes when other bitmasks (surface type |
| and api type) are already using EGLint attribute fields. |
| |
| 8. Can multiple WaitSyncs be placed on the same sync object? |
| |
| RESOLVED: Yes. This has been allowed all along but we now state it |
| more clearly in the spec language. However, there is some concern |
| that this is hard to implement and of limited use, and we might |
| remove this capability before approving the extension. |
| |
| One way to do this while allowing multiple waiters at some future |
| point is to expose it through the API to developers as either a sync |
| attribute allowing multiple waits (default not allowing it), or a |
| parameter to WaitSync, which initially must be something like |
| EGL_SINGLE_WAIT_ONLY. |
| |
| 9. Should eglDestroySyncKHR release all WaitSyncs placed on a |
| reusable sync object? |
| |
| RESOLVED: Yes. It is safest to release all threads waiting on a |
| reusable object when the sync object is deleted so that waiting |
| threads do not wait forever. |
| |
| Revision History |
| |
| #22 (Jon Leech, January 31, 2014) |
| - Clarify return value of ClientWaitSyncKHR when called with <timeout> |
| of zero for an unsignaled <sync> (Bug 11576). |
| #21 (Jon Leech, April 23, 2013) |
| - Simplify issues list to remove issues specific to fence sync |
| objects. |
| #20 (Jon Leech, September 8, 2009) |
| - Change status to complete and note approval by the Promoters. |
| Minor formatting changes. |
| #19 (Robert Palmer, July 14, 2009) |
| - Branch wording from draft KHR_sync specification. Remove ability |
| to create "fence sync objects and all tokens/wording specific to |
| them. |
| #18 (Robert Palmer, July 8, 2009) |
| - Issues 8 and 9 declared resolved in EGL meeting 2009-07-08 |
| #17 (Robert Palmer, July 8, 2009) |
| - Update eglDestroySyncKHR to special-case deletion of fence sync |
| objects. This is explained in issue 9. |
| - Corrected EGL_REUSABLE_SYNC_KHR -> EGL_SYNC_REUSABLE_KHR |
| - Define value for EGL_SYNC_REUSABLE_KHR |
| - Fix typo and whitespace |
| #16 (Jon Leech, July 7, 2009) |
| - Update description of new tokens to match changes to the |
| eglCreateSyncKHR entry point in revision 15. |
| #15 (Jon Leech, June 16, 2009) |
| - Define separate one-time fence sync and reusable sync extensions |
| and corresponding extension strings. Remove AUTO_RESET and |
| eglFenceKHR. Rename eglCreateFenceSyncKHR to eglCreateSyncKHR and |
| change initial status of reusable syncs to unsignaled. Clarify |
| which functions apply to which types of sync objects. Update |
| issues list. |
| #14 (Jon Leech, April 29, 2009) |
| - Clarify that all waiters are woken up on signalling a sync. |
| Remove tabs to cleanup some formatting issues. |
| #13 (Acorn Pooley, April 2, 2009) |
| - Renamed |
| GL_OES_egl_sync -> GL_OES_EGL_sync |
| VG_KHR_egl_sync -> VG_KHR_EGL_sync |
| #12 (Jon Leech, April 1, 2009) |
| - Changed sync flags type from EGLuint to EGLint and add issue 7. |
| #11 (Acorn Pooley, February 4, 2009) |
| - add error case to eglGetSyncAttribKHR. |
| - fix year on rev 8-10 (2008->2009) |
| #10 (Acorn Pooley, February 4, 2009) |
| - clarify some error message descriptions |
| #9 (Greg Prisament, January 15, 2009) |
| - Destroy now wakes up all waits (eglClientWaitSyncKHR) |
| - Add EGLDisplay <dpy> as first parameter to all commands |
| - Split into 3 extension strings, EGL_KHR_sync, GL_OES_egl_sync, |
| VG_KHR_egl_sync, all described in this document. |
| - Add attribute AUTO_RESET_KHR |
| - Time type uses the type from khrplatform.h |
| - Remove EGL_ALREADY_SIGNALLED |
| #8 (Jon Leech, November 11, 2009) |
| - Assign enum values |
| #7 (Acorn Pooley, October 30, 2008) |
| - Fix typos |
| - remove obsolete wording about Native sync objects (see issue 5) |
| - formatting: remove tabs, 80 columns |
| #6 (Acorn Pooley, October 27, 2008) |
| - Corrected 'enum' to 'EGLenum' in prototypes. |
| #5 (Jon Leech, September 9, 2008) |
| - Removed native sync support (eglCreateNativeSyncKHR and |
| EGL_SYNC_NATIVE_SYNC_KHR), and re-flowed spec to fit in 80 columns. |
| #4 (Jon Leech, November 20, 2007) |
| - Corrected 'enum' to 'EGLenum' in prototypes. |
| #3 (Jon Leech, April 5, 2007) |
| - Added draft Status and TBD Number |
| #2 (November 27, 2006) |
| - Changed OES token to KHR |
