2018 The Khronos Group Inc.
eglCreateSync 3G
eglCreateSync create a new EGL sync object

## C Specification

EGLSync `eglCreateSync` EGLDisplay display EGLEnum type EGLAttrib const * attrib_list

## Parameters

display

  Specifies the EGL display connection.

type

  Specifies the type of sync object to create.

attrib_list

  Specifies attributes and attribute values for the sync object being created.

## Description

sync objects 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.

Sync objects have a status with two possible states: signaled and unsignaled. 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.

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.

`eglCreateSync` creates a sync object of the specified type associated with the specified display display, and returns a handle to the new object. attrib_list is an attribute-value list specifying other attributes of the sync object, terminated by an attribute entry `EGL_NONE`. Attributes not specified in the list will be assigned their default values.

Once the condition of the sync object is satisfied, the sync is signaled, causing any `eglClientWaitSync` or `eglWaitSync` commands blocking on sync to unblock.

## Creating Fence Sync Objects

If type is `EGL_SYNC_FENCE`, a fence sync object is created. In this case attrib_list must be `NULL` or empty (containing only `EGL_NONE`). Attributes of the fence sync object, and their initial values, are:

`EGL_SYNC_TYPE`

  `EGL_SYNC_FENCE`

`EGL_SYNC_STATUS`

  `EGL_UNSIGNALED`

`EGL_SYNC_CONDITION`

  `EGL_SYNC_PRIOR_COMMANDS_COMPLETE`

When a fence sync object is created, `eglCreateSync` 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.

The only condition supported for fence sync objects is `EGL_SYNC_PRIOR_COMMANDS_COMPLETE`, 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.

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 `eglWaitSync` also requires satisfying these conditions.

- client API is OpenGL, and either the OpenGL version is 3.2 or greater, or the `GL_ARB_sync` extension is supported.

- client API is OpenGL ES, and either the OpenGL ES version is 3.0 or greater, or the `GL_OES_EGL_sync` extension is supported.

- client API is OpenVG, and the `VG_KHR_EGL_sync` extension is supported.

## Creating OpenCL Event Sync Objects

If type is `EGL_SYNC_CL_EVENT`, an OpenCL event sync object is created. In this case attrib_list must contain the attribute `EGL_CL_EVENT_HANDLE`, set to a valid OpenCL event handle returned by a call to `clEnqueueReleaseGLObjects` or `clEnqueueReleaseEGLObjects`; other types of OpenCL event handles are not supported. Note that `EGL_CL_EVENT_HANDLE` is not a queriable property of a sync object. Attributes of the OpenCL event sync object, and their initial values, are:

`EGL_SYNC_TYPE`

  `EGL_SYNC_CL_EVENT`

`EGL_SYNC_STATUS`

  Depends on status of event

`EGL_SYNC_CONDITION`

  `EGL_SYNC_CL_EVENT_COMPLETE`

The status of such a sync object depends on event. When the status of event is `CL_QUEUED`, `CL_SUBMITTED`, or `CL_RUNNING`, the status of the linked sync object will be `EGL_UNSIGNALED`. When the status of event changes to `CL_COMPLETE`, the status of the linked sync object will become `EGL_SIGNALED`.

The only condition supported for OpenCL event sync objects is `EGL_SYNC_CL_EVENT_COMPLETE`, which is satisfied when the status of the OpenCL event associated with the sync object changes to `CL_COMPLETE`.

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.

However, implementations are not required to validate the OpenCL event, and passing an invalid event handle in attrib_list may result in undefined behavior up to and including program termination.

## Notes

`eglCreateSync` is supported only if the EGL version is 1.5 or greater.

## Errors

`eglCreateSync` returns `EGL_NO_SYNC` on failure.

If display is not the name of a valid, initialized EGLDisplay, an `EGL_BAD_DISPLAY` error is generated.

If attrib_list contains an attribute name not defined for the type of sync object being created, an `EGL_BAD_ATTRIBUTE` error is generated.

If type is not a supported type of sync object, an `EGL_BAD_PARAMETER` error is generated.

If type is `EGL_SYNC_FENCE` and no context is current for the bound API (i.e., `eglGetCurrentContext` returns `EGL_NO_CONTEXT`), an `EGL_BAD_MATCH` error is generated.

If type is `EGL_SYNC_FENCE` and display does not match the EGLDisplay of the currently bound context for the currently bound client API (the EGLDisplay returned by `eglGetCurrentDisplay`), an `EGL_BAD_MATCH` error is generated.

If type is `EGL_SYNC_FENCE` and the current context for the currently bound client API does not support fence commands, an `EGL_BAD_MATCH` error is generated.

If type is `EGL_SYNC_CL_EVENT` and `EGL_CL_EVENT_HANDLE` is not specified in attrib_list, or its attribute value is not a valid OpenCL event handle as described above, then an `EGL_BAD_ATTRIBUTE` error is generated.

## See Also

`clEnqueueReleaseGLObjects`, `clEnqueueReleaseEGLObjects`, eglClientWaitSync, eglCreateSync, eglGetCurrentContext, eglGetCurrentDisplay, eglWaitSync