1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
Name
ANDROID_fence_sync
Name Strings
EGL_ANDROID_fence_sync
Contributors
Jamie Gennis
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Draft.
Version
Version 1, May 29, 2012
Number
EGL Extension #XXX
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 an Android Sync HAL fence object. 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 Android fence object.
New Types
None.
New Procedures and Functions
None.
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_ANDROID_FENCE_ANDROID 0x3144
Accepted by the <attribute> parameter of eglGetSyncAttribKHR:
EGL_SYNC_FENCE_FD_ANDROID 0x3145
Returned in <value> when eglGetSyncAttribKHR is called with <attribute>
EGL_SYNC_CONDITION_KHR:
EGL_SYNC_ANDROID_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 <type> is EGL_SYNC_ANDROID_FENCE_ANDROID, an EGL Android fence sync
object is created. In this case the EGL_SYNC_FENCE_FD_ANDROID attribute may
optionally be specified. If this attribute is specified, it must be set to
a file descriptor that refers to a native Android fence object.
The default values for the EGL Android fence sync object attributes are as
follows:
Attribute Name Initial Attribute Value(s)
--------------- --------------------------
EGL_SYNC_TYPE_KHR EGL_SYNC_ANDROID_FENCE_ANDROID
EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR
EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR
Upon creation of an EGL Android fence sync object, the
EGL_SYNC_FENCE_FD_ANDROID attribute is set to a newly generated file
descriptor that refers to a native Android fence object. If the
EGL_SYNC_FENCE_FD_ANDROID attribute is specified in the eglCreateSyncKHR
call then the generated file descriptor refers to the same native Android
fence object as the file descriptor passed to eglCreateSyncKHR. Note,
however, that the value of the sync object attribute is *not* the same file
descriptor as the one passed to eglCreateSyncKHR - it simply refers to the
same underlying native Android fence object. Additionally, if the
EGL_SYNC_FENCE_FD_ANDROID attribute is specified then the
EGL_SYNC_CONDITION_KHR attribute is set to
EGL_SYNC_ANDROID_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR
attribute is set to reflect the signal status of the native Android fence
object."
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 Android fence sync
object is created without specifying the EGL_SYNC_FENCE_FD_ANDROID
attribute, 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. If
the sync object is an EGL Android fence sync object then the native Android
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_ANDROID_FENCE_SIGNALED_ANDROID condition is satisfied by the
signaling of the native Android fence object. When this happens any
eglClientWaitSyncKHR commands blocking on <sync> unblock."
Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects),
added by KHR_fence_sync
"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 <type> is EGL_SYNC_FENCE_KHR and <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 EGL_SYNC_ANDROID_FENCE_ANDROID and <attrib_list> contains
an attribute other than EGL_SYNC_FENCE_FD_ANDROID, 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 or EGL_SYNC_ANDROID_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 <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_ANDROID_FENCE_ANDROID 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 or EGL_SYNC_ANDROID_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_ANDROID_FENCE_ANDROID only
EGL_SYNC_FENCE_FD_ANDROID Native Android fence EGL_SYNC_ANDROID_FENCE_ANDROID only
object file descriptor
"
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 <sync> will no
longer be the handle of a valid sync object. Additionally, if <sync> is an
EGL Android fence sync object then the file descriptor stored in the
EGL_SYNC_FENCE_FD_ANDROID attribute is closed and is no longer a valid file
descriptor."
Issues
1. Should EGLSyncKHR objects that wrap Android 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 Android fence
objects, so we need some way to tell the EGL implementation at sync object
creation whether the sync object should support querying the Android 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 Android fence objects.
2. Who is responsible for dup'ing the Android fence file descriptors?
RESOLVED: The recipient of a file descriptor is responsible for dup'ing it
if it wishes to maintain a reference to the Android fence object.
This means that when eglCreateSyncKHR is called with an existing file
descriptor, the EGL implementation must dup it. On the other hand, when
eglGetSyncAttribKHR is called to query the file descriptor, it is the
responsibility of the caller to dup the file descriptor if it wishes to
maintain a reference that will outlast the EGLSyncKHR object.
Revision History
#1 (Jamie Gennis, May 29, 2012)
- Initial draft.
|
