Parameters

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:

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.

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:

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

Copyright © 2003-2014 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.