eglCreateSync — create a new EGL sync object
EGLSync eglCreateSync(
|
EGLDisplay display, |
EGLEnum type, | |
EGLAttrib const * attrib_list) ; |
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.
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.
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.
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.
eglCreateSync
is supported only if the EGL
version is 1.5 or greater.
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.
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.