1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreateSync - EGL Reference Pages</title> 5 <link rel="stylesheet" type="text/css" href="khronos-man.css"/> 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/> 7 </head> 8 <body> 9 <header/> 10 <div class="refentry" id="eglCreateSync"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglCreateSync — 15 create a new <abbr class="acronym">EGL</abbr> sync object 16 </p> 17 </div> 18 <div class="refsynopsisdiv"> 19 <h2>C Specification</h2> 20 <div class="funcsynopsis"> 21 <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> 22 <tr> 23 <td> 24 <code class="funcdef">EGLSync <strong class="fsfunc">eglCreateSync</strong>(</code> 25 </td> 26 <td>EGLDisplay <var class="pdparam">display</var>, </td> 27 </tr> 28 <tr> 29 <td> </td> 30 <td>EGLEnum <var class="pdparam">type</var>, </td> 31 </tr> 32 <tr> 33 <td> </td> 34 <td>EGLAttrib const * <var class="pdparam">attrib_list</var><code>)</code>;</td> 35 </tr> 36 </table> 37 <div class="funcprototype-spacer"> </div> 38 </div> 39 </div> 40 <div class="refsect1" id="parameters"> 41 <h2>Parameters</h2> 42 <div class="variablelist"> 43 <dl class="variablelist"> 44 <dt> 45 <span class="term"> 46 <em class="parameter"> 47 <code>display</code> 48 </em> 49 </span> 50 </dt> 51 <dd> 52 <p> 53 Specifies the <abbr class="acronym">EGL</abbr> display connection. 54 </p> 55 </dd> 56 <dt> 57 <span class="term"> 58 <em class="parameter"> 59 <code>type</code> 60 </em> 61 </span> 62 </dt> 63 <dd> 64 <p> 65 Specifies the type of sync object to create. 66 </p> 67 </dd> 68 <dt> 69 <span class="term"> 70 <em class="parameter"> 71 <code>attrib_list</code> 72 </em> 73 </span> 74 </dt> 75 <dd> 76 <p> 77 Specifies attributes and attribute values for the sync 78 object being created. 79 </p> 80 </dd> 81 </dl> 82 </div> 83 </div> 84 <div class="refsect1" id="description"> 85 <h2>Description</h2> 86 <p> 87 <em class="firstterm">sync objects</em> are provided to enable 88 synchronization of client API operations between threads and/or 89 between API contexts. Sync objects may be tested or waited upon 90 by application threads. 91 </p> 92 <p> 93 Sync objects have a status with two possible states: 94 <em class="firstterm">signaled</em> and 95 <em class="firstterm">unsignaled</em>. Initially, sync objects are 96 unsignaled. EGL may be asked to wait for a sync object to become 97 signaled, or a sync object's status may be queried. 98 </p> 99 <p> 100 Depending on the type of a sync object, its status may be 101 changed either by an external event, or by explicitly signaling 102 and unsignaling the sync. 103 </p> 104 <p> 105 <code class="function">eglCreateSync</code> creates a sync object of the specified 106 <em class="parameter"><code>type</code></em> associated with the specified display 107 <em class="parameter"><code>display</code></em>, and returns a handle to the new object. 108 <em class="parameter"><code>attrib_list</code></em> is an attribute-value list specifying 109 other attributes of the sync object, terminated by an attribute entry 110 <code class="constant">EGL_NONE</code>. Attributes not specified in the list will be 111 assigned their default values. 112 </p> 113 <p> 114 Once the <em class="firstterm">condition</em> of the sync object is satisfied, 115 the sync is signaled, causing any <code class="function">eglClientWaitSync</code> or 116 <code class="function">eglWaitSync</code> commands blocking on 117 <em class="parameter"><code>sync</code></em> to unblock. 118 </p> 119 </div> 120 <div class="refsect1" id="fencesync"> 121 <h2>Creating Fence Sync Objects</h2> 122 <p> 123 If <em class="parameter"><code>type</code></em> is 124 <code class="constant">EGL_SYNC_FENCE</code>, a fence sync object is 125 created. In this case <em class="parameter"><code>attrib_list</code></em> must be 126 <code class="constant">NULL</code> or empty (containing only 127 <code class="constant">EGL_NONE</code>). Attributes of the fence sync 128 object, and their initial values, are: 129 </p> 130 <div class="variablelist"> 131 <dl class="variablelist"> 132 <dt> 133 <span class="term"> 134 <code class="constant">EGL_SYNC_TYPE</code> 135 </span> 136 </dt> 137 <dd> 138 <p> 139 <code class="constant">EGL_SYNC_FENCE</code> 140 </p> 141 </dd> 142 <dt> 143 <span class="term"> 144 <code class="constant">EGL_SYNC_STATUS</code> 145 </span> 146 </dt> 147 <dd> 148 <p> 149 <code class="constant">EGL_UNSIGNALED</code> 150 </p> 151 </dd> 152 <dt> 153 <span class="term"> 154 <code class="constant">EGL_SYNC_CONDITION</code> 155 </span> 156 </dt> 157 <dd> 158 <p> 159 <code class="constant">EGL_SYNC_PRIOR_COMMANDS_COMPLETE</code> 160 </p> 161 </dd> 162 </dl> 163 </div> 164 <p> 165 When a fence sync object is created, <code class="function">eglCreateSync</code> also inserts a 166 fence command into the command stream of the bound client API's current 167 context (i.e., the context returned by <code class="function">eglGetCurrentContext</code>), and 168 associates it with the newly created sync object. 169 </p> 170 <p> 171 The only condition supported for fence sync objects is 172 <code class="constant">EGL_SYNC_PRIOR_COMMANDS_COMPLETE</code>, which is satisfied by completion of 173 the fence command corresponding to the sync object, and all preceding 174 commands in the associated client API context's command stream. The sync 175 object will not be signaled until all effects from these commands on the 176 client API's internal and framebuffer state are fully realized. No other 177 state is affected by execution of the fence command. 178 </p> 179 <p> 180 Creation of fence sync objects requires support from the bound 181 client API, and will not succeed unless the client API satisfies 182 one of the following properties. Note that 183 <code class="function">eglWaitSync</code> also requires satisfying these 184 conditions. 185 </p> 186 <p> 187 </p> 188 <div class="itemizedlist"> 189 <ul class="itemizedlist" style="list-style-type: disc; "> 190 <li class="listitem"> 191 <p> 192 client API is OpenGL, and either the OpenGL version is 193 3.2 or greater, or the <code class="constant">GL_ARB_sync</code> 194 extension is supported. 195 </p> 196 </li> 197 <li class="listitem"> 198 <p> 199 client API is OpenGL ES, and either the OpenGL ES 200 version is 3.0 or greater, or the 201 <code class="constant">GL_OES_EGL_sync</code> extension is 202 supported. 203 </p> 204 </li> 205 <li class="listitem"> 206 <p> 207 client API is OpenVG, and the 208 <code class="constant">VG_KHR_EGL_sync</code> extension is 209 supported. 210 </p> 211 </li> 212 </ul> 213 </div> 214 <p> 215 </p> 216 </div> 217 <div class="refsect1" id="openclsync"> 218 <h2>Creating OpenCL Event Sync Objects</h2> 219 <p> 220 If <em class="parameter"><code>type</code></em> is 221 <code class="constant">EGL_SYNC_CL_EVENT</code>, an OpenCL event sync 222 object is created. In this case 223 <em class="parameter"><code>attrib_list</code></em> must contain the attribute 224 <code class="constant">EGL_CL_EVENT_HANDLE</code>, set to a valid OpenCL 225 event handle returned by a call to 226 <code class="function">clEnqueueReleaseGLObjects</code> or 227 <code class="function">clEnqueueReleaseEGLObjects</code>; other types of 228 OpenCL event handles are not supported. Note that 229 <code class="constant">EGL_CL_EVENT_HANDLE</code> is not a queriable 230 property of a sync object. Attributes of the OpenCL event sync 231 object, and their initial values, are: 232 </p> 233 <div class="variablelist"> 234 <dl class="variablelist"> 235 <dt> 236 <span class="term"> 237 <code class="constant">EGL_SYNC_TYPE</code> 238 </span> 239 </dt> 240 <dd> 241 <p> 242 <code class="constant">EGL_SYNC_CL_EVENT</code> 243 </p> 244 </dd> 245 <dt> 246 <span class="term"> 247 <code class="constant">EGL_SYNC_STATUS</code> 248 </span> 249 </dt> 250 <dd> 251 <p> 252 Depends on status of <em class="parameter"><code>event</code></em> 253 </p> 254 </dd> 255 <dt> 256 <span class="term"> 257 <code class="constant">EGL_SYNC_CONDITION</code> 258 </span> 259 </dt> 260 <dd> 261 <p> 262 <code class="constant">EGL_SYNC_CL_EVENT_COMPLETE</code> 263 </p> 264 </dd> 265 </dl> 266 </div> 267 <p> 268 The status of such a sync object depends on 269 <em class="parameter"><code>event</code></em>. When the status of 270 <em class="parameter"><code>event</code></em> is <code class="constant">CL_QUEUED</code>, 271 <code class="constant">CL_SUBMITTED</code>, or 272 <code class="constant">CL_RUNNING</code>, the status of the linked sync 273 object will be <code class="constant">EGL_UNSIGNALED</code>. When the 274 status of <em class="parameter"><code>event</code></em> changes to 275 <code class="constant">CL_COMPLETE</code>, the status of the linked sync 276 object will become <code class="constant">EGL_SIGNALED</code>. 277 </p> 278 <p> 279 The only condition supported for OpenCL event sync objects is 280 <code class="constant">EGL_SYNC_CL_EVENT_COMPLETE</code>, which is 281 satisfied when the status of the OpenCL event associated with 282 the sync object changes to <code class="constant">CL_COMPLETE</code>. 283 </p> 284 <p> 285 Creating a linked sync object places a reference on the linked 286 OpenCL event object. When the sync object is deleted, the 287 reference will be removed from the event object. 288 </p> 289 <p> 290 However, implementations are not required to validate the OpenCL 291 event, and passing an invalid event handle in 292 <em class="parameter"><code>attrib_list</code></em> may result in undefined 293 behavior up to and including program termination. 294 </p> 295 </div> 296 <div class="refsect1" id="notes"> 297 <h2>Notes</h2> 298 <p> 299 <code class="function">eglCreateSync</code> is supported only if the EGL 300 version is 1.5 or greater. 301 </p> 302 </div> 303 <div class="refsect1" id="errors"> 304 <h2>Errors</h2> 305 <p> 306 <code class="function">eglCreateSync</code> returns 307 <code class="constant">EGL_NO_SYNC</code> on failure. 308 </p> 309 <p> 310 If <em class="parameter"><code>display</code></em> is not the name of a valid, 311 initialized <span class="type">EGLDisplay</span>, an 312 <code class="constant">EGL_BAD_DISPLAY</code> error is generated. 313 </p> 314 <p> 315 If <em class="parameter"><code>attrib_list</code></em> contains an attribute name 316 not defined for the type of sync object being created, an 317 <code class="constant">EGL_BAD_ATTRIBUTE</code> error is generated. 318 </p> 319 <p> 320 If <em class="parameter"><code>type</code></em> is not a supported type of sync 321 object, an <code class="constant">EGL_BAD_PARAMETER</code> error is 322 generated. 323 </p> 324 <p> 325 If <em class="parameter"><code>type</code></em> is 326 <code class="constant">EGL_SYNC_FENCE</code> and no context is current 327 for the bound API (i.e., 328 <code class="function">eglGetCurrentContext</code> returns 329 <code class="constant">EGL_NO_CONTEXT</code>), an 330 <code class="constant">EGL_BAD_MATCH</code> error is generated. 331 </p> 332 <p> 333 If <em class="parameter"><code>type</code></em> is 334 <code class="constant">EGL_SYNC_FENCE</code> and 335 <em class="parameter"><code>display</code></em> does not match the 336 <span class="type">EGLDisplay</span> of the currently bound context for the 337 currently bound client API (the <span class="type">EGLDisplay</span> returned 338 by <code class="function">eglGetCurrentDisplay</code>), an 339 <code class="constant">EGL_BAD_MATCH</code> error is generated. 340 </p> 341 <p> 342 If <em class="parameter"><code>type</code></em> is 343 <code class="constant">EGL_SYNC_FENCE</code> and the current context for 344 the currently bound client API does not support fence commands, 345 an <code class="constant">EGL_BAD_MATCH</code> error is generated. 346 </p> 347 <p> 348 If <em class="parameter"><code>type</code></em> is 349 <code class="constant">EGL_SYNC_CL_EVENT</code> and 350 <code class="constant">EGL_CL_EVENT_HANDLE</code> is not specified in 351 <em class="parameter"><code>attrib_list</code></em>, or its attribute value is 352 not a valid OpenCL event handle as described above, then an 353 <code class="constant">EGL_BAD_ATTRIBUTE</code> error is generated. 354 </p> 355 </div> 356 <div class="refsect1" id="seealso"> 357 <h2>See Also</h2> 358 <p> 359 <code class="function">clEnqueueReleaseGLObjects</code>, 360 <code class="function">clEnqueueReleaseEGLObjects</code>, 361 <a class="citerefentry" href="eglClientWaitSync.xhtml"><span class="citerefentry"><span class="refentrytitle">eglClientWaitSync</span></span></a>, 362 <a class="citerefentry" href="eglCreateSync.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreateSync</span></span></a>, 363 <a class="citerefentry" href="eglGetCurrentContext.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentContext</span></span></a>, 364 <a class="citerefentry" href="eglGetCurrentDisplay.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetCurrentDisplay</span></span></a>, 365 <a class="citerefentry" href="eglWaitSync.xhtml"><span class="citerefentry"><span class="refentrytitle">eglWaitSync</span></span></a> 366 </p> 367 </div> 368 <p> 369 </p> 370 <div class="refsect3" id="copyright"> 371 <img src="KhronosLogo.jpg"/> 372 <p> 373 Copyright © 2003-2014 The Khronos Group Inc. 374 Permission is hereby granted, free of charge, to any person obtaining a 375 copy of this software and/or associated documentation files (the 376 "Materials"), to deal in the Materials without restriction, including 377 without limitation the rights to use, copy, modify, merge, publish, 378 distribute, sublicense, and/or sell copies of the Materials, and to 379 permit persons to whom the Materials are furnished to do so, subject to 380 the condition that this copyright notice and permission notice shall be included 381 in all copies or substantial portions of the Materials. 382 </p> 383 </div> 384 <p> 385</p> 386 </div> 387 <footer/> 388 </body> 389</html> 390
