1Name
2
3    ANDROID_native_fence_sync
4
5Name Strings
6
7    EGL_ANDROID_native_fence_sync
8
9Contributors
10
11    Jamie Gennis
12
13Contact
14
15    Jamie Gennis, Google Inc. (jgennis 'at' google.com)
16
17Status
18
19    Complete
20
21Version
22
23    Version 3, September 4, 2012
24
25Number
26
27    EGL Extension #50
28
29Dependencies
30
31    Requires EGL 1.1
32
33    This extension is written against the wording of the EGL 1.2 Specification
34
35    EGL_KHR_fence_sync is required.
36
37Overview
38
39    This extension enables the creation of EGL fence sync objects that are
40    associated with a native synchronization fence object that is referenced
41    using a file descriptor.  These EGL fence sync objects have nearly
42    identical semantics to those defined by the KHR_fence_sync extension,
43    except that they have an additional attribute storing the file descriptor
44    referring to the native fence object.
45
46    This extension assumes the existence of a native fence synchronization
47    object that behaves similarly to an EGL fence sync object.  These native
48    objects must have a signal status like that of an EGLSyncKHR object that
49    indicates whether the fence has ever been signaled.  Once signaled the
50    native object's signal status may not change again.
51
52New Types
53
54    None.
55
56New Procedures and Functions
57
58    EGLint eglDupNativeFenceFDANDROID(
59                        EGLDisplay dpy,
60                        EGLSyncKHR);
61
62New Tokens
63
64    Accepted by the <type> parameter of eglCreateSyncKHR, and returned
65    in <value> when eglGetSyncAttribKHR is called with <attribute>
66    EGL_SYNC_TYPE_KHR:
67
68    EGL_SYNC_NATIVE_FENCE_ANDROID          0x3144
69
70    Accepted by the <attrib_list> parameter of eglCreateSyncKHR:
71
72    EGL_SYNC_NATIVE_FENCE_FD_ANDROID       0x3145
73
74    Accepted by the <attrib_list> parameter of eglCreateSyncKHR, and returned
75    by eglDupNativeFenceFDANDROID in the event of an error:
76
77    EGL_NO_NATIVE_FENCE_FD_ANDROID         -1
78
79    Returned in <value> when eglGetSyncAttribKHR is called with <attribute>
80    EGL_SYNC_CONDITION_KHR:
81
82    EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID 0x3146
83
84Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
85
86    Add the following after the sixth paragraph of Section 3.8.1 (Sync
87    Objects), added by KHR_fence_sync
88
89    "If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID, an EGL native fence sync
90    object is created. In this case the EGL_SYNC_NATIVE_FENCE_FD_ANDROID
91    attribute may optionally be specified. If this attribute is specified, it
92    must be set to either a file descriptor that refers to a native fence
93    object or to the value EGL_NO_NATIVE_FENCE_FD_ANDROID.
94
95    The default values for the EGL native fence sync object attributes are as
96    follows:
97
98      Attribute Name                     Initial Attribute Value(s)
99      ---------------                    --------------------------
100      EGL_SYNC_TYPE_KHR                  EGL_SYNC_NATIVE_FENCE_ANDROID
101      EGL_SYNC_STATUS_KHR                EGL_UNSIGNALED_KHR
102      EGL_SYNC_CONDITION_KHR             EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR
103      EGL_SYNC_NATIVE_FENCE_FD_ANDROID   EGL_NO_NATIVE_FENCE_FD_ANDROID
104
105    If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not
106    EGL_NO_NATIVE_FENCE_FD_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is
107    set to EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR
108    attribute is set to reflect the signal status of the native fence object.
109    Additionally, the EGL implementation assumes ownership of the file
110    descriptor, so the caller must not use it after calling eglCreateSyncKHR."
111
112    Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at
113    the seventh paragraph
114
115    "When a fence sync object is created or when an EGL native fence sync
116    object is created with the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute set
117    to EGL_NO_NATIVE_FENCE_FD_ANDROID, eglCreateSyncKHR also inserts a fence
118    command into the command stream of the bound client API's current context
119    (i.e., the context returned by eglGetCurrentContext), and associates it
120    with the newly created sync object.
121
122    After associating the fence command with an EGL native fence sync object,
123    the next Flush() operation performed by the current client API causes a
124    new native fence object to be created, and the
125    EGL_SYNC_NATIVE_FENCE_ANDROID attribute of the EGL native fence object is
126    set to a file descriptor that refers to the new native fence object. This
127    new native fence object is signaled when the EGL native fence sync object
128    is signaled.
129
130    When the condition of the sync object is satisfied by the fence command,
131    the sync is signaled by the associated client API context, causing any
132    eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock.
133    If the sync object is an EGL native fence sync object then the native
134    fence object is also signaled when the condition is satisfied. The
135    EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition is satisfied by completion
136    of the fence command corresponding to the sync object and all preceding
137    commands in the associated client API context's command stream. The sync
138    object will not be signaled until all effects from these commands on the
139    client API's internal and framebuffer state are fully realized. No other
140    state is affected by execution of the fence command.
141
142    The EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID condition is satisfied by the
143    signaling of the native fence object referred to by the
144    EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute. When this happens any
145    eglClientWaitSyncKHR commands blocking on <sync> unblock."
146
147    Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects),
148    added by KHR_fence_sync
149
150    "Errors
151    ------
152
153      * If <dpy> is not the name of a valid, initialized EGLDisplay,
154        EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
155        generated.
156      * If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> is neither NULL nor
157        empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an
158        EGL_BAD_ATTRIBUTE error is generated.
159      * If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID and <attrib_list> contains
160        an attribute other than EGL_SYNC_NATIVE_FENCE_FD_ANDROID,
161        EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
162        generated.
163      * If <type> is not a supported type of sync object,
164        EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
165        generated.
166      * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
167        no context is current for the bound API (i.e., eglGetCurrentContext
168        returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an
169        EGL_BAD_MATCH error is generated.
170      * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
171        <dpy> does not match the EGLDisplay of the currently bound context for
172        the currently bound client API (the EGLDisplay returned by
173        eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an
174        EGL_BAD_MATCH error is generated.
175      * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
176        the currently bound client API does not support the client API
177        extension indicating it can place fence commands, then EGL_NO_SYNC_KHR
178        is returned and an EGL_BAD_MATCH error is generated."
179
180    Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync
181
182    "
183    Attribute                          Description                Supported Sync Objects
184    -----------------                  -----------------------    ----------------------
185    EGL_SYNC_TYPE_KHR                  Type of the sync object    All
186    EGL_SYNC_STATUS_KHR                Status of the sync object  All
187    EGL_SYNC_CONDITION_KHR             Signaling condition        EGL_SYNC_FENCE_KHR and
188                                                                  EGL_SYNC_NATIVE_FENCE_ANDROID only
189    "
190
191    Modify the second paragraph description of eglDestroySyncKHR in Section
192    3.8.1 (Sync Objects), added by KHR_fence_sync
193
194    "If no errors are generated, EGL_TRUE is returned, and <sync> will no
195    longer be the handle of a valid sync object.  Additionally, if <sync> is an
196    EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID
197    attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then that file descriptor
198    is closed."
199
200    Add the following after the last paragraph of Section 3.8.1 (Sync
201    Objects), added by KHR_fence_sync
202
203    The command
204
205        EGLint eglDupNativeFenceFDANDROID(
206                            EGLDisplay dpy,
207                            EGLSyncKHR sync);
208
209    duplicates the file descriptor stored in the
210    EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync
211    object and returns the new file descriptor.
212
213    Errors
214    ------
215
216      * If <sync> is not a valid sync object for <dpy>,
217        EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER
218        error is generated.
219      * If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of <sync> is
220        EGL_NO_NATIVE_FENCE_FD_ANDROID, EGL_NO_NATIVE_FENCE_FD_ANDROID is
221        returned and an EGL_BAD_PARAMETER error is generated.
222      * If <dpy> does not match the display passed to eglCreateSyncKHR
223        when <sync> was created, the behaviour is undefined."
224
225Issues
226
227    1. Should EGLSyncKHR objects that wrap native fence objects use the
228    EGL_SYNC_FENCE_KHR type?
229
230    RESOLVED: A new sync object type will be added.
231
232    We don't want to require all EGL fence sync objects to wrap native fence
233    objects, so we need some way to tell the EGL implementation at sync object
234    creation whether the sync object should support querying the native fence
235    FD attribute. We could do this with either a new sync object type or with a
236    boolean attribute. It might be nice to pick up future signaling conditions
237    that might be added for fence sync objects, but there may be things that
238    get added that don't make sense in the context of native fence objects.
239
240    2. Who is responsible for dup'ing the native fence file descriptors?
241
242    RESOLVED: Whenever a file descriptor is passed into or returned from an
243    EGL call in this extension, ownership of that file descriptor is
244    transfered. The recipient of the file descriptor must close it when it is
245    no longer needed, and the provider of the file descriptor must dup it
246    before providing it if they require continued use of the native fence.
247
248    3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried?
249
250    RESOLVED: No.
251
252    Returning the file descriptor owned by the EGL implementation would
253    violate the file descriptor ownership rule described in issue #2. Having
254    eglGetSyncAttribKHR return a different (dup'd) file descriptor each time
255    it's called seems wrong, so a new function was added to explicitly dup the
256    file descriptor.
257
258    That said, the attribute is useful both as a way to pass an existing file
259    descriptor to eglCreateSyncKHR and as a way to describe the subsequent
260    behavior of EGL native fence sync objects, so it is left as an attribute
261    for which the value cannot be queried.
262
263Revision History
264
265#3 (Jamie Gennis, September 4, 2012)
266    - Reworded the extension to refer to "native fence" objects rather than
267    "Android fence" objects.
268    - Added a paragraph to the overview that describes assumptions about the
269    native fence sync objects.
270
271#2 (Jamie Gennis, July 23, 2012)
272    - Changed the file descriptor ownership transferring behavior.
273    - Added the eglDupAndroidFenceFDANDROID function.
274    - Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable
275    attributes.
276    - Added language specifying that a native Android fence is created at the
277    flush following the creation of an EGL Android fence sync object that is
278    not passed an existing native fence.
279
280#1 (Jamie Gennis, May 29, 2012)
281    - Initial draft.
282