Name KHR_fence_sync Name Strings EGL_KHR_fence_sync GL_OES_EGL_sync VG_KHR_EGL_sync Contributors Acorn Pooley Gary King Gregory Prisament Jon Leech 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) Notice Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Complete. Approved by the EGL Working Group on March 3, 2010. Approved by the Khronos Board of Promoters on April 30, 2010. Version Version 24, January 31, 2014 Number EGL Extension #20 OpenGL ES Extension #75 OpenVG Extension #7 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 heavily from the GL_ARB_sync extension and introduces a type of sync object known as a "fence sync object" comparable to the OpenGL fence sync object. The specification is designed to allow additional types of sync objects to be easily introduced in later extensions. Fence sync objects have corresponding fence commands, which are inserted into a client API command stream at the time the fence sync is created. A fence sync object is used to wait for completion of the corresponding fence command. This allows applications to request a partial Finish of an API command stream, wherein all commands issued in a particular client API context will be forced to complete before control is returned to the calling thread. This document describes three different extension strings collectively. The "EGL_KHR_fence_sync" string indicates that fence syncs and the corresponding interfaces (to create and place a fence, destroy, query, and wait on) are supported. The remaining extensions list valid client APIs for fence syncs. The "GL_OES_EGL_sync" string indicates that a fence sync object can be created in association with a fence command placed in the command stream of a bound OpenGL ES context. The "VG_KHR_EGL_sync" string indicates the same thing for a bound OpenVG context. 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 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_FENCE_KHR 0x30F9 Accepted by the <attribute> parameter of eglGetSyncAttribKHR: EGL_SYNC_TYPE_KHR 0x30F7 EGL_SYNC_STATUS_KHR 0x30F1 EGL_SYNC_CONDITION_KHR 0x30F8 Returned in <value> when eglGetSyncAttribKHR is called with <attribute> EGL_SYNC_STATUS_KHR: EGL_SIGNALED_KHR 0x30F2 EGL_UNSIGNALED_KHR 0x30F3 Returned in <value> when eglGetSyncAttribKHR is called with <attribute> EGL_SYNC_CONDITION_KHR: EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR 0x30F0 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. <Fence sync objects> are created in association with a <fence command> in a client API. When the client API executes the fence command, an event is generated which signals the corresponding fence sync object. Fence sync objects may not be explicitly signaled, and may only change their status once, from the initial unsignaled status to signaled. Fence sync objects may be used to wait for partial completion of a client API command stream, as a more flexible form of glFinish / vgFinish. 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_FENCE_KHR, a fence sync object is created. In this case <attrib_list> must be NULL or empty (containing only EGL_NONE). Attributes of the fence sync object are set as follows: Attribute Name Initial Attribute Value(s) --------------- -------------------------- EGL_SYNC_TYPE_KHR EGL_SYNC_FENCE_KHR EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR When a fence sync object is created, eglCreateSyncKHR also inserts a fence command into the command stream of the bound client API's current context (i.e., the context returned by eglGetCurrentContext), and associates it with the newly created sync object. When the condition of the sync object is satisfied by the fence command, the sync is signaled by the associated client API context, causing any eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. The only condition currently supported is EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by completion of the fence command corresponding to the sync object, and all preceding commands in the associated client API context's command stream. The sync object will not be signaled until all effects from these commands on the client API's internal and framebuffer state are fully realized. No other state is affected by execution of the fence command. Each client API which supports fence commands indicates this support in the form of a client API extension. If the GL_OES_EGL_sync extension is supported by OpenGL ES (either version 1.x or 2.0), a fence sync object may be created when the currently bound API is OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG, a fence sync object may be created when the currently bound API is OpenVG. 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. * If <type> is EGL_SYNC_FENCE_KHR and no context is current for the bound API (i.e., eglGetCurrentContext returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an EGL_BAD_MATCH error is generated. * If <type> is EGL_SYNC_FENCE_KHR and <dpy> does not match the EGLDisplay of the currently bound context for the currently bound client API (the EGLDisplay returned by eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an EGL_BAD_MATCH error is generated. * If <type> is EGL_SYNC_FENCE_KHR and the currently bound client API does not support the client API extension indicating it can place fence commands, then EGL_NO_SYNC_KHR is returned and an EGL_BAD_MATCH 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 sync object being blocked upon will not be signaled in finite time (for example, by an associated fence command issued previously, but not yet flushed to the graphics pipeline), then eglClientWaitSyncKHR may wait forever. To help prevent this behavior (footnote1), 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. [footnote 1: The simple Flush behavior defined by EGL_SYNC_FLUSH_COMMANDS_BIT_KHR will not help when waiting for a fence command issued in a different context's command stream. Applications which block on a fence sync object must take additional steps to ensure that the context from which the associated fence command was issued has flushed that command to the graphics pipeline.] 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 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 EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR only 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, <sync> is flagged for deletion and will be deleted when it is no longer associated with any fence command and is no longer blocking any eglClientWaitSyncKHR command. 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 reusable sync objects but is otherwise very similar to the EGL_KHR_reusable_sync extension issues list. 1. [REMOVED - found in the reusable_sync extension.] 2. [REMOVED - found in the reusable_sync extension.] 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. What does this extension provide that could not be accomplished with native platform synchronization primitives and the existing client API Finish commands? RESPONSE: This extension provides a lighter-weight mechanism for synchronizing an application with client API command streams than the all-or-nothing Finish commands, enabling applications to block until a subset of issued client API commands have completed. 5. [REMOVED - found in the reusable_sync extension.] 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 fence sync object has two possible status values: signaled or unsignaled. * When created, the status of the sync object is unsignaled. * A fence command is inserted into a command stream. A fence sync object is not. * A fence command, once its condition has been met, will set its associated sync object to the signaled state. The only condition currently supported is EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR. * A wait function, such as ClientWaitSyncKHR, waits on a fence sync object, not on a fence command. * 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. [REMOVED - found in the reusable_sync extension.] 8. [REMOVED - found in the reusable_sync extension.] 9. Should eglDestroySyncKHR release all WaitSyncs placed on a fence sync object? RESOLVED: No. (note that this behavior differs from reusable syncs.) Fence sync objects are intended to be signalled by the graphics driver within a short period of time (typically less than 1 second after creation) and so should not cause waiting threads to hang forever. To reduce implementation complexity, fence sync objects are defined to not release waiting threads; waiting threads are released normally when their condition is satisfied or their timeout expires. The handle to a fence sync object immediately becomes invalid following a call to eglDestroySyncKHR. Revision History #24 (Jon Leech, January 31, 2014) - Clarify return value of ClientWaitSyncKHR when called with <timeout> of zero for an unsignaled <sync> (Bug 11576). #23 (Jon Leech, April 23, 2013) - Simplify issues list to remove issues specific to reusable sync objects and general sync object design issues. #22 (Jon Leech, June 15, 2010) - Correct minor typos in GL/VG extension names. #21 (Jon Leech, May 5, 2010) - Correct minor typos, assign extension numbers for EGL, OpenGL ES, and OpenVG, and publish in the registry, #20 (Robert Palmer, July 14, 2009) - Branch wording from draft KHR_sync specification. Remove ability to create "reusable sync objects and all tokens/wording specific to them. #19 (Robert Palmer, July 22, 2009) - Replace specific eglCreateSyncKHR error cases for bad <type> argument with extensible catch-all case. #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