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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
|
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreateSync">
<info>
<copyright>
<year>2018</year>
<holder>The Khronos Group Inc.</holder>
</copyright>
</info>
<refmeta>
<refentrytitle>eglCreateSync</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>eglCreateSync</refname>
<refpurpose>
create a new <acronym>EGL</acronym> sync object
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>EGLSync <function>eglCreateSync</function></funcdef>
<paramdef>EGLDisplay <parameter>display</parameter></paramdef>
<paramdef>EGLEnum <parameter>type</parameter></paramdef>
<paramdef>EGLAttrib const * <parameter>attrib_list</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>display</parameter></term>
<listitem><para>
Specifies the <acronym>EGL</acronym> display connection.
</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem><para>
Specifies the type of sync object to create.
</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>attrib_list</parameter></term>
<listitem><para>
Specifies attributes and attribute values for the sync
object being created.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="description"><title>Description</title>
<para>
<firstterm>sync objects</firstterm> 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.
</para>
<para>
Sync objects have a status with two possible states:
<firstterm>signaled</firstterm> and
<firstterm>unsignaled</firstterm>. 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.
</para>
<para>
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.
</para>
<para>
<function>eglCreateSync</function> creates a sync object of the specified
<parameter>type</parameter> associated with the specified display
<parameter>display</parameter>, and returns a handle to the new object.
<parameter>attrib_list</parameter> is an attribute-value list specifying
other attributes of the sync object, terminated by an attribute entry
<constant>EGL_NONE</constant>. Attributes not specified in the list will be
assigned their default values.
</para>
<para>
Once the <firstterm>condition</firstterm> of the sync object is satisfied,
the sync is signaled, causing any <function>eglClientWaitSync</function> or
<function>eglWaitSync</function> commands blocking on
<parameter>sync</parameter> to unblock.
</para>
</refsect1>
<refsect1 xml:id="fencesync"><title>Creating Fence Sync Objects</title>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant>, a fence sync object is
created. In this case <parameter>attrib_list</parameter> must be
<constant>NULL</constant> or empty (containing only
<constant>EGL_NONE</constant>). Attributes of the fence sync
object, and their initial values, are:
</para>
<variablelist>
<varlistentry>
<term><constant>EGL_SYNC_TYPE</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_FENCE</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_STATUS</constant></term>
<listitem>
<para>
<constant>EGL_UNSIGNALED</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_CONDITION</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_PRIOR_COMMANDS_COMPLETE</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
When a fence sync object is created, <function>eglCreateSync</function> also inserts a
fence command into the command stream of the bound client API's current
context (i.e., the context returned by <function>eglGetCurrentContext</function>), and
associates it with the newly created sync object.
</para>
<para>
The only condition supported for fence sync objects is
<constant>EGL_SYNC_PRIOR_COMMANDS_COMPLETE</constant>, 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.
</para>
<para>
Creation of fence sync objects requires support from the bound
client API, and will not succeed unless the client API satisfies
one of the following properties. Note that
<function>eglWaitSync</function> also requires satisfying these
conditions.
</para>
<para>
<itemizedlist>
<listitem>
<para>
client API is OpenGL, and either the OpenGL version is
3.2 or greater, or the <constant>GL_ARB_sync</constant>
extension is supported.
</para>
</listitem>
<listitem>
<para>
client API is OpenGL ES, and either the OpenGL ES
version is 3.0 or greater, or the
<constant>GL_OES_EGL_sync</constant> extension is
supported.
</para>
</listitem>
<listitem>
<para>
client API is OpenVG, and the
<constant>VG_KHR_EGL_sync</constant> extension is
supported.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 xml:id="openclsync"><title>Creating OpenCL Event Sync Objects</title>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_CL_EVENT</constant>, an OpenCL event sync
object is created. In this case
<parameter>attrib_list</parameter> must contain the attribute
<constant>EGL_CL_EVENT_HANDLE</constant>, set to a valid OpenCL
event handle returned by a call to
<function>clEnqueueReleaseGLObjects</function> or
<function>clEnqueueReleaseEGLObjects</function>; other types of
OpenCL event handles are not supported. Note that
<constant>EGL_CL_EVENT_HANDLE</constant> is not a queriable
property of a sync object. Attributes of the OpenCL event sync
object, and their initial values, are:
</para>
<variablelist>
<varlistentry>
<term><constant>EGL_SYNC_TYPE</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_CL_EVENT</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_STATUS</constant></term>
<listitem>
<para>
Depends on status of <parameter>event</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_CONDITION</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_CL_EVENT_COMPLETE</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The status of such a sync object depends on
<parameter>event</parameter>. When the status of
<parameter>event</parameter> is <constant>CL_QUEUED</constant>,
<constant>CL_SUBMITTED</constant>, or
<constant>CL_RUNNING</constant>, the status of the linked sync
object will be <constant>EGL_UNSIGNALED</constant>. When the
status of <parameter>event</parameter> changes to
<constant>CL_COMPLETE</constant>, the status of the linked sync
object will become <constant>EGL_SIGNALED</constant>.
</para>
<para>
The only condition supported for OpenCL event sync objects is
<constant>EGL_SYNC_CL_EVENT_COMPLETE</constant>, which is
satisfied when the status of the OpenCL event associated with
the sync object changes to <constant>CL_COMPLETE</constant>.
</para>
<para>
Creating a linked sync object places a reference on the linked
OpenCL event object. When the sync object is deleted, the
reference will be removed from the event object.
</para>
<para>
However, implementations are not required to validate the OpenCL
event, and passing an invalid event handle in
<parameter>attrib_list</parameter> may result in undefined
behavior up to and including program termination.
</para>
</refsect1>
<refsect1 xml:id="notes"><title>Notes</title>
<para>
<function>eglCreateSync</function> is supported only if the EGL
version is 1.5 or greater.
</para>
</refsect1>
<refsect1 xml:id="errors"><title>Errors</title>
<para>
<function>eglCreateSync</function> returns
<constant>EGL_NO_SYNC</constant> on failure.
</para>
<para>
If <parameter>display</parameter> is not the name of a valid,
initialized <type>EGLDisplay</type>, an
<constant>EGL_BAD_DISPLAY</constant> error is generated.
</para>
<para>
If <parameter>attrib_list</parameter> contains an attribute name
not defined for the type of sync object being created, an
<constant>EGL_BAD_ATTRIBUTE</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is not a supported type of sync
object, an <constant>EGL_BAD_PARAMETER</constant> error is
generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant> and no context is current
for the bound API (i.e.,
<function>eglGetCurrentContext</function> returns
<constant>EGL_NO_CONTEXT</constant>), an
<constant>EGL_BAD_MATCH</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant> and
<parameter>display</parameter> does not match the
<type>EGLDisplay</type> of the currently bound context for the
currently bound client API (the <type>EGLDisplay</type> returned
by <function>eglGetCurrentDisplay</function>), an
<constant>EGL_BAD_MATCH</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant> and the current context for
the currently bound client API does not support fence commands,
an <constant>EGL_BAD_MATCH</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_CL_EVENT</constant> and
<constant>EGL_CL_EVENT_HANDLE</constant> is not specified in
<parameter>attrib_list</parameter>, or its attribute value is
not a valid OpenCL event handle as described above, then an
<constant>EGL_BAD_ATTRIBUTE</constant> error is generated.
</para>
</refsect1>
<refsect1 xml:id="seealso"><title>See Also</title>
<para>
<function>clEnqueueReleaseGLObjects</function>,
<function>clEnqueueReleaseEGLObjects</function>,
<citerefentry><refentrytitle>eglClientWaitSync</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglCreateSync</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglGetCurrentContext</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglGetCurrentDisplay</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglWaitSync</refentrytitle></citerefentry>
</para>
</refsect1>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/>
</refentry>
|
