1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreateSync"> 2 <info> 3 <copyright> 4 <year>2018</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglCreateSync</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglCreateSync</refname> 14 <refpurpose> 15 create a new <acronym>EGL</acronym> sync object 16 </refpurpose> 17 </refnamediv> 18 <refsynopsisdiv> 19 <title>C Specification</title> 20 <funcsynopsis> 21 <funcprototype> 22 <funcdef>EGLSync <function>eglCreateSync</function></funcdef> 23 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 24 <paramdef>EGLEnum <parameter>type</parameter></paramdef> 25 <paramdef>EGLAttrib const * <parameter>attrib_list</parameter></paramdef> 26 </funcprototype> 27 </funcsynopsis> 28 </refsynopsisdiv> 29 <refsect1 xml:id="parameters"><title>Parameters</title> 30 <variablelist> 31 <varlistentry> 32 <term><parameter>display</parameter></term> 33 <listitem><para> 34 Specifies the <acronym>EGL</acronym> display connection. 35 </para></listitem> 36 </varlistentry> 37 <varlistentry> 38 <term><parameter>type</parameter></term> 39 <listitem><para> 40 Specifies the type of sync object to create. 41 </para></listitem> 42 </varlistentry> 43 <varlistentry> 44 <term><parameter>attrib_list</parameter></term> 45 <listitem><para> 46 Specifies attributes and attribute values for the sync 47 object being created. 48 </para></listitem> 49 </varlistentry> 50 </variablelist> 51 </refsect1> 52 <refsect1 xml:id="description"><title>Description</title> 53 <para> 54 <firstterm>sync objects</firstterm> are provided to enable 55 synchronization of client API operations between threads and/or 56 between API contexts. Sync objects may be tested or waited upon 57 by application threads. 58 </para> 59 <para> 60 Sync objects have a status with two possible states: 61 <firstterm>signaled</firstterm> and 62 <firstterm>unsignaled</firstterm>. Initially, sync objects are 63 unsignaled. EGL may be asked to wait for a sync object to become 64 signaled, or a sync object's status may be queried. 65 </para> 66 <para> 67 Depending on the type of a sync object, its status may be 68 changed either by an external event, or by explicitly signaling 69 and unsignaling the sync. 70 </para> 71 <para> 72 <function>eglCreateSync</function> creates a sync object of the specified 73 <parameter>type</parameter> associated with the specified display 74 <parameter>display</parameter>, and returns a handle to the new object. 75 <parameter>attrib_list</parameter> is an attribute-value list specifying 76 other attributes of the sync object, terminated by an attribute entry 77 <constant>EGL_NONE</constant>. Attributes not specified in the list will be 78 assigned their default values. 79 </para> 80 <para> 81 Once the <firstterm>condition</firstterm> of the sync object is satisfied, 82 the sync is signaled, causing any <function>eglClientWaitSync</function> or 83 <function>eglWaitSync</function> commands blocking on 84 <parameter>sync</parameter> to unblock. 85 </para> 86 </refsect1> 87 <refsect1 xml:id="fencesync"><title>Creating Fence Sync Objects</title> 88 <para> 89 If <parameter>type</parameter> is 90 <constant>EGL_SYNC_FENCE</constant>, a fence sync object is 91 created. In this case <parameter>attrib_list</parameter> must be 92 <constant>NULL</constant> or empty (containing only 93 <constant>EGL_NONE</constant>). Attributes of the fence sync 94 object, and their initial values, are: 95 </para> 96 <variablelist> 97 <varlistentry> 98 <term><constant>EGL_SYNC_TYPE</constant></term> 99 <listitem> 100 <para> 101 <constant>EGL_SYNC_FENCE</constant> 102 </para> 103 </listitem> 104 </varlistentry> 105 <varlistentry> 106 <term><constant>EGL_SYNC_STATUS</constant></term> 107 <listitem> 108 <para> 109 <constant>EGL_UNSIGNALED</constant> 110 </para> 111 </listitem> 112 </varlistentry> 113 <varlistentry> 114 <term><constant>EGL_SYNC_CONDITION</constant></term> 115 <listitem> 116 <para> 117 <constant>EGL_SYNC_PRIOR_COMMANDS_COMPLETE</constant> 118 </para> 119 </listitem> 120 </varlistentry> 121 </variablelist> 122 <para> 123 When a fence sync object is created, <function>eglCreateSync</function> also inserts a 124 fence command into the command stream of the bound client API's current 125 context (i.e., the context returned by <function>eglGetCurrentContext</function>), and 126 associates it with the newly created sync object. 127 </para> 128 <para> 129 The only condition supported for fence sync objects is 130 <constant>EGL_SYNC_PRIOR_COMMANDS_COMPLETE</constant>, which is satisfied by completion of 131 the fence command corresponding to the sync object, and all preceding 132 commands in the associated client API context's command stream. The sync 133 object will not be signaled until all effects from these commands on the 134 client API's internal and framebuffer state are fully realized. No other 135 state is affected by execution of the fence command. 136 </para> 137 <para> 138 Creation of fence sync objects requires support from the bound 139 client API, and will not succeed unless the client API satisfies 140 one of the following properties. Note that 141 <function>eglWaitSync</function> also requires satisfying these 142 conditions. 143 </para> 144 <para> 145 <itemizedlist> 146 <listitem> 147 <para> 148 client API is OpenGL, and either the OpenGL version is 149 3.2 or greater, or the <constant>GL_ARB_sync</constant> 150 extension is supported. 151 </para> 152 </listitem> 153 <listitem> 154 <para> 155 client API is OpenGL ES, and either the OpenGL ES 156 version is 3.0 or greater, or the 157 <constant>GL_OES_EGL_sync</constant> extension is 158 supported. 159 </para> 160 </listitem> 161 <listitem> 162 <para> 163 client API is OpenVG, and the 164 <constant>VG_KHR_EGL_sync</constant> extension is 165 supported. 166 </para> 167 </listitem> 168 </itemizedlist> 169 </para> 170 </refsect1> 171 <refsect1 xml:id="openclsync"><title>Creating OpenCL Event Sync Objects</title> 172 <para> 173 If <parameter>type</parameter> is 174 <constant>EGL_SYNC_CL_EVENT</constant>, an OpenCL event sync 175 object is created. In this case 176 <parameter>attrib_list</parameter> must contain the attribute 177 <constant>EGL_CL_EVENT_HANDLE</constant>, set to a valid OpenCL 178 event handle returned by a call to 179 <function>clEnqueueReleaseGLObjects</function> or 180 <function>clEnqueueReleaseEGLObjects</function>; other types of 181 OpenCL event handles are not supported. Note that 182 <constant>EGL_CL_EVENT_HANDLE</constant> is not a queriable 183 property of a sync object. Attributes of the OpenCL event sync 184 object, and their initial values, are: 185 </para> 186 <variablelist> 187 <varlistentry> 188 <term><constant>EGL_SYNC_TYPE</constant></term> 189 <listitem> 190 <para> 191 <constant>EGL_SYNC_CL_EVENT</constant> 192 </para> 193 </listitem> 194 </varlistentry> 195 <varlistentry> 196 <term><constant>EGL_SYNC_STATUS</constant></term> 197 <listitem> 198 <para> 199 Depends on status of <parameter>event</parameter> 200 </para> 201 </listitem> 202 </varlistentry> 203 <varlistentry> 204 <term><constant>EGL_SYNC_CONDITION</constant></term> 205 <listitem> 206 <para> 207 <constant>EGL_SYNC_CL_EVENT_COMPLETE</constant> 208 </para> 209 </listitem> 210 </varlistentry> 211 </variablelist> 212 <para> 213 The status of such a sync object depends on 214 <parameter>event</parameter>. When the status of 215 <parameter>event</parameter> is <constant>CL_QUEUED</constant>, 216 <constant>CL_SUBMITTED</constant>, or 217 <constant>CL_RUNNING</constant>, the status of the linked sync 218 object will be <constant>EGL_UNSIGNALED</constant>. When the 219 status of <parameter>event</parameter> changes to 220 <constant>CL_COMPLETE</constant>, the status of the linked sync 221 object will become <constant>EGL_SIGNALED</constant>. 222 </para> 223 <para> 224 The only condition supported for OpenCL event sync objects is 225 <constant>EGL_SYNC_CL_EVENT_COMPLETE</constant>, which is 226 satisfied when the status of the OpenCL event associated with 227 the sync object changes to <constant>CL_COMPLETE</constant>. 228 </para> 229 <para> 230 Creating a linked sync object places a reference on the linked 231 OpenCL event object. When the sync object is deleted, the 232 reference will be removed from the event object. 233 </para> 234 <para> 235 However, implementations are not required to validate the OpenCL 236 event, and passing an invalid event handle in 237 <parameter>attrib_list</parameter> may result in undefined 238 behavior up to and including program termination. 239 </para> 240 </refsect1> 241 <refsect1 xml:id="notes"><title>Notes</title> 242 <para> 243 <function>eglCreateSync</function> is supported only if the EGL 244 version is 1.5 or greater. 245 </para> 246 </refsect1> 247 <refsect1 xml:id="errors"><title>Errors</title> 248 <para> 249 <function>eglCreateSync</function> returns 250 <constant>EGL_NO_SYNC</constant> on failure. 251 </para> 252 <para> 253 If <parameter>display</parameter> is not the name of a valid, 254 initialized <type>EGLDisplay</type>, an 255 <constant>EGL_BAD_DISPLAY</constant> error is generated. 256 </para> 257 <para> 258 If <parameter>attrib_list</parameter> contains an attribute name 259 not defined for the type of sync object being created, an 260 <constant>EGL_BAD_ATTRIBUTE</constant> error is generated. 261 </para> 262 <para> 263 If <parameter>type</parameter> is not a supported type of sync 264 object, an <constant>EGL_BAD_PARAMETER</constant> error is 265 generated. 266 </para> 267 <para> 268 If <parameter>type</parameter> is 269 <constant>EGL_SYNC_FENCE</constant> and no context is current 270 for the bound API (i.e., 271 <function>eglGetCurrentContext</function> returns 272 <constant>EGL_NO_CONTEXT</constant>), an 273 <constant>EGL_BAD_MATCH</constant> error is generated. 274 </para> 275 <para> 276 If <parameter>type</parameter> is 277 <constant>EGL_SYNC_FENCE</constant> and 278 <parameter>display</parameter> does not match the 279 <type>EGLDisplay</type> of the currently bound context for the 280 currently bound client API (the <type>EGLDisplay</type> returned 281 by <function>eglGetCurrentDisplay</function>), an 282 <constant>EGL_BAD_MATCH</constant> error is generated. 283 </para> 284 <para> 285 If <parameter>type</parameter> is 286 <constant>EGL_SYNC_FENCE</constant> and the current context for 287 the currently bound client API does not support fence commands, 288 an <constant>EGL_BAD_MATCH</constant> error is generated. 289 </para> 290 <para> 291 If <parameter>type</parameter> is 292 <constant>EGL_SYNC_CL_EVENT</constant> and 293 <constant>EGL_CL_EVENT_HANDLE</constant> is not specified in 294 <parameter>attrib_list</parameter>, or its attribute value is 295 not a valid OpenCL event handle as described above, then an 296 <constant>EGL_BAD_ATTRIBUTE</constant> error is generated. 297 </para> 298 </refsect1> 299 <refsect1 xml:id="seealso"><title>See Also</title> 300 <para> 301 <function>clEnqueueReleaseGLObjects</function>, 302 <function>clEnqueueReleaseEGLObjects</function>, 303 <citerefentry><refentrytitle>eglClientWaitSync</refentrytitle></citerefentry>, 304 <citerefentry><refentrytitle>eglCreateSync</refentrytitle></citerefentry>, 305 <citerefentry><refentrytitle>eglGetCurrentContext</refentrytitle></citerefentry>, 306 <citerefentry><refentrytitle>eglGetCurrentDisplay</refentrytitle></citerefentry>, 307 <citerefentry><refentrytitle>eglWaitSync</refentrytitle></citerefentry> 308 </para> 309 </refsect1> 310 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 311</refentry> 312