blob: 551d2a4c8f553e21a033cf45a6e6b5a3c135eec3 [file] [log] [blame] [edit]
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreateSync">
<info>
<copyright>
<year>2018</year>
<holder>The Khronos Group Inc.</holder>
</copyright>
</info>
<refmeta>
<refentrytitle>eglCreateSync</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>eglCreateSync</refname>
<refpurpose>
create a new <acronym>EGL</acronym> sync object
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>EGLSync <function>eglCreateSync</function></funcdef>
<paramdef>EGLDisplay <parameter>display</parameter></paramdef>
<paramdef>EGLEnum <parameter>type</parameter></paramdef>
<paramdef>EGLAttrib const * <parameter>attrib_list</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>display</parameter></term>
<listitem><para>
Specifies the <acronym>EGL</acronym> display connection.
</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem><para>
Specifies the type of sync object to create.
</para></listitem>
</varlistentry>
<varlistentry>
<term><parameter>attrib_list</parameter></term>
<listitem><para>
Specifies attributes and attribute values for the sync
object being created.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="description"><title>Description</title>
<para>
<firstterm>sync objects</firstterm> 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.
</para>
<para>
Sync objects have a status with two possible states:
<firstterm>signaled</firstterm> and
<firstterm>unsignaled</firstterm>. 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.
</para>
<para>
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.
</para>
<para>
<function>eglCreateSync</function> creates a sync object of the specified
<parameter>type</parameter> associated with the specified display
<parameter>display</parameter>, and returns a handle to the new object.
<parameter>attrib_list</parameter> is an attribute-value list specifying
other attributes of the sync object, terminated by an attribute entry
<constant>EGL_NONE</constant>. Attributes not specified in the list will be
assigned their default values.
</para>
<para>
Once the <firstterm>condition</firstterm> of the sync object is satisfied,
the sync is signaled, causing any <function>eglClientWaitSync</function> or
<function>eglWaitSync</function> commands blocking on
<parameter>sync</parameter> to unblock.
</para>
</refsect1>
<refsect1 xml:id="fencesync"><title>Creating Fence Sync Objects</title>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant>, a fence sync object is
created. In this case <parameter>attrib_list</parameter> must be
<constant>NULL</constant> or empty (containing only
<constant>EGL_NONE</constant>). Attributes of the fence sync
object, and their initial values, are:
</para>
<variablelist>
<varlistentry>
<term><constant>EGL_SYNC_TYPE</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_FENCE</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_STATUS</constant></term>
<listitem>
<para>
<constant>EGL_UNSIGNALED</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_CONDITION</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_PRIOR_COMMANDS_COMPLETE</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
When a fence sync object is created, <function>eglCreateSync</function> also inserts a
fence command into the command stream of the bound client API's current
context (i.e., the context returned by <function>eglGetCurrentContext</function>), and
associates it with the newly created sync object.
</para>
<para>
The only condition supported for fence sync objects is
<constant>EGL_SYNC_PRIOR_COMMANDS_COMPLETE</constant>, 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.
</para>
<para>
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
<function>eglWaitSync</function> also requires satisfying these
conditions.
</para>
<para>
<itemizedlist>
<listitem>
<para>
client API is OpenGL, and either the OpenGL version is
3.2 or greater, or the <constant>GL_ARB_sync</constant>
extension is supported.
</para>
</listitem>
<listitem>
<para>
client API is OpenGL ES, and either the OpenGL ES
version is 3.0 or greater, or the
<constant>GL_OES_EGL_sync</constant> extension is
supported.
</para>
</listitem>
<listitem>
<para>
client API is OpenVG, and the
<constant>VG_KHR_EGL_sync</constant> extension is
supported.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
<refsect1 xml:id="openclsync"><title>Creating OpenCL Event Sync Objects</title>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_CL_EVENT</constant>, an OpenCL event sync
object is created. In this case
<parameter>attrib_list</parameter> must contain the attribute
<constant>EGL_CL_EVENT_HANDLE</constant>, set to a valid OpenCL
event handle returned by a call to
<function>clEnqueueReleaseGLObjects</function> or
<function>clEnqueueReleaseEGLObjects</function>; other types of
OpenCL event handles are not supported. Note that
<constant>EGL_CL_EVENT_HANDLE</constant> is not a queriable
property of a sync object. Attributes of the OpenCL event sync
object, and their initial values, are:
</para>
<variablelist>
<varlistentry>
<term><constant>EGL_SYNC_TYPE</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_CL_EVENT</constant>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_STATUS</constant></term>
<listitem>
<para>
Depends on status of <parameter>event</parameter>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>EGL_SYNC_CONDITION</constant></term>
<listitem>
<para>
<constant>EGL_SYNC_CL_EVENT_COMPLETE</constant>
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The status of such a sync object depends on
<parameter>event</parameter>. When the status of
<parameter>event</parameter> is <constant>CL_QUEUED</constant>,
<constant>CL_SUBMITTED</constant>, or
<constant>CL_RUNNING</constant>, the status of the linked sync
object will be <constant>EGL_UNSIGNALED</constant>. When the
status of <parameter>event</parameter> changes to
<constant>CL_COMPLETE</constant>, the status of the linked sync
object will become <constant>EGL_SIGNALED</constant>.
</para>
<para>
The only condition supported for OpenCL event sync objects is
<constant>EGL_SYNC_CL_EVENT_COMPLETE</constant>, which is
satisfied when the status of the OpenCL event associated with
the sync object changes to <constant>CL_COMPLETE</constant>.
</para>
<para>
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.
</para>
<para>
However, implementations are not required to validate the OpenCL
event, and passing an invalid event handle in
<parameter>attrib_list</parameter> may result in undefined
behavior up to and including program termination.
</para>
</refsect1>
<refsect1 xml:id="notes"><title>Notes</title>
<para>
<function>eglCreateSync</function> is supported only if the EGL
version is 1.5 or greater.
</para>
</refsect1>
<refsect1 xml:id="errors"><title>Errors</title>
<para>
<function>eglCreateSync</function> returns
<constant>EGL_NO_SYNC</constant> on failure.
</para>
<para>
If <parameter>display</parameter> is not the name of a valid,
initialized <type>EGLDisplay</type>, an
<constant>EGL_BAD_DISPLAY</constant> error is generated.
</para>
<para>
If <parameter>attrib_list</parameter> contains an attribute name
not defined for the type of sync object being created, an
<constant>EGL_BAD_ATTRIBUTE</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is not a supported type of sync
object, an <constant>EGL_BAD_PARAMETER</constant> error is
generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant> and no context is current
for the bound API (i.e.,
<function>eglGetCurrentContext</function> returns
<constant>EGL_NO_CONTEXT</constant>), an
<constant>EGL_BAD_MATCH</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant> and
<parameter>display</parameter> does not match the
<type>EGLDisplay</type> of the currently bound context for the
currently bound client API (the <type>EGLDisplay</type> returned
by <function>eglGetCurrentDisplay</function>), an
<constant>EGL_BAD_MATCH</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_FENCE</constant> and the current context for
the currently bound client API does not support fence commands,
an <constant>EGL_BAD_MATCH</constant> error is generated.
</para>
<para>
If <parameter>type</parameter> is
<constant>EGL_SYNC_CL_EVENT</constant> and
<constant>EGL_CL_EVENT_HANDLE</constant> is not specified in
<parameter>attrib_list</parameter>, or its attribute value is
not a valid OpenCL event handle as described above, then an
<constant>EGL_BAD_ATTRIBUTE</constant> error is generated.
</para>
</refsect1>
<refsect1 xml:id="seealso"><title>See Also</title>
<para>
<function>clEnqueueReleaseGLObjects</function>,
<function>clEnqueueReleaseEGLObjects</function>,
<citerefentry><refentrytitle>eglClientWaitSync</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglCreateSync</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglGetCurrentContext</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglGetCurrentDisplay</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>eglWaitSync</refentrytitle></citerefentry>
</para>
</refsect1>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/>
</refentry>