Name ANDROID_native_fence_sync Name Strings EGL_ANDROID_native_fence_sync Contributors Jamie Gennis Contact Jamie Gennis, Google Inc. (jgennis 'at' google.com) Status Complete Version Version 3, September 4, 2012 Number EGL Extension #50 Dependencies Requires EGL 1.1 This extension is written against the wording of the EGL 1.2 Specification EGL_KHR_fence_sync is required. Overview This extension enables the creation of EGL fence sync objects that are associated with a native synchronization fence object that is referenced using a file descriptor. These EGL fence sync objects have nearly identical semantics to those defined by the KHR_fence_sync extension, except that they have an additional attribute storing the file descriptor referring to the native fence object. This extension assumes the existence of a native fence synchronization object that behaves similarly to an EGL fence sync object. These native objects must have a signal status like that of an EGLSyncKHR object that indicates whether the fence has ever been signaled. Once signaled the native object's signal status may not change again. New Types None. New Procedures and Functions EGLint eglDupNativeFenceFDANDROID( EGLDisplay dpy, EGLSyncKHR); New Tokens Accepted by the parameter of eglCreateSyncKHR, and returned in when eglGetSyncAttribKHR is called with EGL_SYNC_TYPE_KHR: EGL_SYNC_NATIVE_FENCE_ANDROID 0x3144 Accepted by the parameter of eglCreateSyncKHR: EGL_SYNC_NATIVE_FENCE_FD_ANDROID 0x3145 Accepted by the parameter of eglCreateSyncKHR, and returned by eglDupNativeFenceFDANDROID in the event of an error: EGL_NO_NATIVE_FENCE_FD_ANDROID -1 Returned in when eglGetSyncAttribKHR is called with EGL_SYNC_CONDITION_KHR: EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID 0x3146 Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) Add the following after the sixth paragraph of Section 3.8.1 (Sync Objects), added by KHR_fence_sync "If is EGL_SYNC_NATIVE_FENCE_ANDROID, an EGL native fence sync object is created. In this case the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute may optionally be specified. If this attribute is specified, it must be set to either a file descriptor that refers to a native fence object or to the value EGL_NO_NATIVE_FENCE_FD_ANDROID. The default values for the EGL native fence sync object attributes are as follows: Attribute Name Initial Attribute Value(s) --------------- -------------------------- EGL_SYNC_TYPE_KHR EGL_SYNC_NATIVE_FENCE_ANDROID EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR EGL_SYNC_NATIVE_FENCE_FD_ANDROID EGL_NO_NATIVE_FENCE_FD_ANDROID If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is set to EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR attribute is set to reflect the signal status of the native fence object. Additionally, the EGL implementation assumes ownership of the file descriptor, so the caller must not use it after calling eglCreateSyncKHR." Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at the seventh paragraph "When a fence sync object is created or when an EGL native fence sync object is created with the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute set to EGL_NO_NATIVE_FENCE_FD_ANDROID, 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. After associating the fence command with an EGL native fence sync object, the next Flush() operation performed by the current client API causes a new native fence object to be created, and the EGL_SYNC_NATIVE_FENCE_ANDROID attribute of the EGL native fence object is set to a file descriptor that refers to the new native fence object. This new native fence object is signaled when the EGL native fence sync object is signaled. 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 to unblock. If the sync object is an EGL native fence sync object then the native fence object is also signaled when the condition is satisfied. The EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition 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. The EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID condition is satisfied by the signaling of the native fence object referred to by the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute. When this happens any eglClientWaitSyncKHR commands blocking on unblock." Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects), added by KHR_fence_sync "Errors ------ * If is not the name of a valid, initialized EGLDisplay, EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is generated. * If is EGL_SYNC_FENCE_KHR and is neither NULL nor empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is generated. * If is EGL_SYNC_NATIVE_FENCE_ANDROID and contains an attribute other than EGL_SYNC_NATIVE_FENCE_FD_ANDROID, EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is generated. * If is not a supported type of sync object, EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is generated. * If is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID 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 is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 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 is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID 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." Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync " 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 and EGL_SYNC_NATIVE_FENCE_ANDROID only " Modify the second paragraph description of eglDestroySyncKHR in Section 3.8.1 (Sync Objects), added by KHR_fence_sync "If no errors are generated, EGL_TRUE is returned, and will no longer be the handle of a valid sync object. Additionally, if is an EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then that file descriptor is closed." Add the following after the last paragraph of Section 3.8.1 (Sync Objects), added by KHR_fence_sync The command EGLint eglDupNativeFenceFDANDROID( EGLDisplay dpy, EGLSyncKHR sync); duplicates the file descriptor stored in the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync object and returns the new file descriptor. Errors ------ * If is not a valid sync object for , EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER error is generated. * If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of is EGL_NO_NATIVE_FENCE_FD_ANDROID, EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER error is generated. * If does not match the display passed to eglCreateSyncKHR when was created, the behaviour is undefined." Issues 1. Should EGLSyncKHR objects that wrap native fence objects use the EGL_SYNC_FENCE_KHR type? RESOLVED: A new sync object type will be added. We don't want to require all EGL fence sync objects to wrap native fence objects, so we need some way to tell the EGL implementation at sync object creation whether the sync object should support querying the native fence FD attribute. We could do this with either a new sync object type or with a boolean attribute. It might be nice to pick up future signaling conditions that might be added for fence sync objects, but there may be things that get added that don't make sense in the context of native fence objects. 2. Who is responsible for dup'ing the native fence file descriptors? RESOLVED: Whenever a file descriptor is passed into or returned from an EGL call in this extension, ownership of that file descriptor is transfered. The recipient of the file descriptor must close it when it is no longer needed, and the provider of the file descriptor must dup it before providing it if they require continued use of the native fence. 3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried? RESOLVED: No. Returning the file descriptor owned by the EGL implementation would violate the file descriptor ownership rule described in issue #2. Having eglGetSyncAttribKHR return a different (dup'd) file descriptor each time it's called seems wrong, so a new function was added to explicitly dup the file descriptor. That said, the attribute is useful both as a way to pass an existing file descriptor to eglCreateSyncKHR and as a way to describe the subsequent behavior of EGL native fence sync objects, so it is left as an attribute for which the value cannot be queried. Revision History #3 (Jamie Gennis, September 4, 2012) - Reworded the extension to refer to "native fence" objects rather than "Android fence" objects. - Added a paragraph to the overview that describes assumptions about the native fence sync objects. #2 (Jamie Gennis, July 23, 2012) - Changed the file descriptor ownership transferring behavior. - Added the eglDupAndroidFenceFDANDROID function. - Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable attributes. - Added language specifying that a native Android fence is created at the flush following the creation of an EGL Android fence sync object that is not passed an existing native fence. #1 (Jamie Gennis, May 29, 2012) - Initial draft.