blob: 953487ce0e7c47f129878a31ca0ed0473b03ab3f [file] [log] [blame]
Name Strings
Jon Leech, Khronos
Alon Or-bach, Samsung Electronics
Tom Cooksey, ARM
Jon Leech (jon 'at'
IP Status
No known claims.
Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
Approved by the EGL Working Group on December 4, 2013.
Version 5, December 4, 2013
EGL Extension #65
EGL 1.4 and the EGL_KHR_fence_sync extension are required.
This extension is written against the language added to EGL 1.2 by
the EGL_KHR_fence_sync extension.
An OpenCL implementation supporting sharing OpenCL event objects
with EGL is required.
Khronos recommends obsoleting and replacing implementations of
EGL_KHR_cl_event with this extension as soon as possible.
This extension allows creating an EGL sync object linked to an OpenCL
event object, potentially improving efficiency of sharing images between
the two APIs. The companion cl_khr_egl_event extension provides the
complementary functionality of creating an OpenCL event object from an
EGL sync object.
This extension is functionally identical to EGL_KHR_cl_event, but is
intended to replace that extension. It exists only to address an
implementation issue on 64-bit platforms where passing OpenCL event
handles in an EGLint attribute list value is impossible, because the
implementations use a 32-bit type for EGLint.
This extension also incorporates some required functionality from the
EGL_KHR_fence_sync extension, similarly modified for 64-bit platforms.
New Types
* EGLAttribKHR is a integer type used to pass arrays of attribute
* name/value pairs which may include pointer and handle attribute
* values.
#include <khrplatform.h>
typedef intptr_t EGLAttribKHR;
Event handles of type cl_event, defined in the OpenCL header files, may
be included in the attribute list passed to eglCreateSync64KHR.
New Procedures and Functions
EGLSyncKHR eglCreateSync64KHR(
EGLDisplay dpy,
EGLenum type,
const EGLAttribKHR *attrib_list);
New Tokens
Accepted as attribute names in the <attrib_list> argument
of eglCreateSync64KHR:
Returned in <values> for eglGetSyncAttribKHR <attribute>
Returned in <values> for eglGetSyncAttribKHR <attribute>
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Modify the language in section 3.8.1 (Sync Objects) starting at the
sixth paragraph, describing commands to create sync objects:
"The commands
EGLSyncKHR eglCreateSync64KHR(
EGLDisplay dpy,
EGLenum type,
const EGLAttribKHR *attrib_list);
EGLSyncKHR eglCreateSyncKHR(
EGLDisplay dpy,
EGLenum type,
const EGLint *attrib_list);
create a sync object ...
... When a fence sync object is created, eglCreateSyncKHR and
eglCreateSync64KHR also insert a fence command into... "
Add following the eigth paragraph (the paragraph beginning "<Fence sync
objects> are created..."):
"A <CL event sync object> reflects the status of a corresponding OpenCL
event object to which the sync object is linked. This provides another
method of coordinating sharing of images between EGL and OpenCL (see
Chapter 9 of the OpenCL 1.0 Specification and the cl_khr_egl_sharing
extension). Waiting on such a sync object is equivalent to waiting for
completion of the linked CL event object.
CL event sync objects may only be created using the command
eglCreateSync64KHR, because they require an attribute which may not be
representable in the attrib_list argument of eglCreateSyncKHR."
Add following the description of fence sync objects (prior to the
"Errors" section for eglCreateSyncKHR):
"If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is
created. In this case <attrib_list> must contain the attribute
EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that
EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync
object. Attributes of the CL event sync objects are set as follows:
Attribute Name Initial Attribute Value(s)
------------- --------------------------
EGL_SYNC_STATUS_KHR Depends on status of <event>
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_KHR. When the status
of <event> changes to CL_COMPLETE, the status of the linked sync
object will become EGL_SIGNALED_KHR.
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
The command eglCreateSync64KHR must be used to create a CL event sync
[fn1] If the implementation also supports the older EGL_KHR_cl_event
extension, then eglCreateSyncKHR may also be used to create a CL
event sync object. However, this use is not recommended because it
is not portable to platforms where OpenCL event handles are larger
than 32 bits."
Modify the ninth and tenth paragraphs, starting "When the condition":
"When the condition of the sync object is satisfied, the sync is
signaled by the associated client API context, causing any
eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock.
The only condition supported for fence sync objects is
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, 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.
Each client API which supports fence commands indicates this support
in the form of a client API extension. If the GL_OES_EGL_sync
extension is supported by OpenGL ES (either version 1.x or 2.0), a
fence sync object may be created when the currently bound API is
OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG,
a fence sync object may be created when the currently bound API is
The only condition supported for CL event sync objects is
EGL_SYNC_CL_EVENT_COMPLETE_KHR, which is satisfied when the status of
the OpenCL event associated with the sync object changes to CL_COMPLETE."
Add to the "Errors" section for eglCreateSyncKHR and eglCreateSync64KHR:
"* If <type> is EGL_SYNC_CL_EVENT_KHR then
** If eglCreateSyncKHR was called, then EGL_NO_SYNC_KHR is returned and
an EGL_BAD_ATTRIBUTE error is generated.
** If eglCreateSync64KHR was called and EGL_CL_EVENT_HANDLE_KHR is not
specified in <attrib_list>, or its attribute value is not a valid
OpenCL event handle returned by a call to clEnqueueReleaseGLObjects
or clEnqueueReleaseEGLObjects, then EGL_NO_SYNC_KHR is returned and
an EGL_BAD_ATTRIBUTE error is generated."
Replace the EGL_SYNC_CONDITION_KHR row of table with:
"Attribute Description Supported Sync Objects
----------------- ----------------------- ----------------------
Table Attributes Accepted by eglGetSyncAttribKHR Command"
Replace the second paragraph describing eglDestroySync with:
"If any eglClientWaitSyncKHR commands are blocking on <sync> when
eglDestroySyncKHR is called, <sync> is flagged for deletion and will
be deleted when the associated fence command or CL event object has
completed, and <sync> is no longer blocking any eglClientWaitSyncKHR
command. Otherwise, the sync object is destroyed immediately."
Sample Code
Conformance Tests
None yet
Note that some issues from the EGL_KHR_cl_event and EGL_KHR_fence_sync
extensions also apply to this extension, which incorporates
functionality from both of those extensions while making it usable on a
64-bit architecture. Issues specific to this extension are below.
1) Why does this extension exist?
The existence of this extension is an unfortunate necessity. Khronos did
not define EGLint as a 64-bit type in the version of <khrplatform.h> we
provided, assuming that vendors on those platforms would do so. By the
time we discovered that not all vendors had done this, it was too late
to fix, because ABI considerations made it impossible for those vendors
to change to a 64-bit EGLint type. Our only option was to define new
extensions and commands using a new attribute type, EGLAttribKHR, which
is explicitly large enough to hold a pointer or handle.
2) What is the relationship of this extension to EGL_KHR_cl_event?
RESOLVED: The only functional difference is that the new
eglCreateSync64KHR command must be used to create CL event sync objects.
This is necessary because some 64-bit platforms define EGLint as a
32-bit type, making it impossible to pass an arbitrary OpenCL event
handle in the EGLint *attrib_list passed to eglCreateSyncKHR.
3) How are pointer- and handle-sized attributes represented?
RESOLVED: Using the new type EGLAttribKHR, which is explicitly defined
as an integer type large enough to hold a pointer.
EGLAttribKHR is defined as an alias of the ISO C intptr_t type, rather
than using one of the explicitly-sized types from khrplatform.h.
Requiring this means that khrplatform.h must make sure to include the
appropriate header file (probably <stdint.h>) and that a C compiler
supporting intptr_t must be used. In the past we were concerned about
older C/C++ compilers, but this seems an acceptable choice in 2013.
We could choose to use intptr_t as the base type of attribute lists,
instead of the EGLAttribKHR alias. As Ian Romanick has pointed out
passionately in ARB discussions, modern C compilers are required to
support a well-defined set of scalar types. There is no requirement to
use API-specific scalar types when explicitly defining a C API.
However, there is some value in semantically tagging parameters with EGL
types. Also, using 'intptr_t *attrib_list' would be cosmetically
objectionable due to mixing EGL* and C native scalar types in EGL APIs.
We probably want to wait until there's an EGL API compatibility break -
a hypothetical "EGL 2.0" - before moving to native ISO C types in our
4) Why is the new fence sync creation function defined here, instead of
in a separate EGL_KHR_fence_sync2 extension?
RESOLVED: eglCreateSync64KHR is defined here because this is the only
functionality requiring it, and we expect this extension to be a stopgap
for 64-bit platforms until the time that EGL 1.5 is defined. The EGL 1.5
core will presumably include only the EGLAttribKHR-based version of this
If there are any new extensions using handle or pointer attributes in
the meantime, they should copy the EGLAttribKHR and eglCreateSync64KHR
language here as required. There is no harm in defining the same type or
command in multiple extensions, so long as the definitions are
5) Why is the new command called eglCreateSync64KHR?
UNRESOLVED: For consistency with OpenGL, which has '64'-suffixed
commands for representing 64-bit integers and arbitrary offsets into GPU
memory. If we ever support EGL on 128-bit platforms this would be a
silly naming convention, but that time is probably many decades away and
by then EGL 1.5 should be defined and widely supported. The name
eglCreateSync2KHR was originally suggested.
6) Why is there no command for querying EGLAttribKHR attributes from
sync objects?
RESOLVED: Because the only sync attribute which requires the extra bits
in an EGLAttribKHR type is EGL_CL_EVENT_HANDLE_KHR, which is not
queryable. Sync attributes which are queryable will all fit into the
EGLint returned by eglGetSyncAttribKHR.
NOTE: It's unfortunate that this name is used, since it uses the
"AttribKHR" name for command returning EGLints. In EGL 1.5 we should use
a different name for the query.
7) Does this extension replace EGL_KHR_fence_sync and EGL_KHR_cl_event?
RESOLVED: It does not replace EGL_KHR_fence_sync, but extends it to
support creation of a new type of sync object, the CL event sync object.
RESOLVED: It is intended to replace EGL_KHR_cl_event; this extension
must be used for OpenCL interop on 64-bit platforms, and we hope all
vendors will implement it even on 32-bit platforms, for maximum code
Revision History
Version 5, 20130/12/04 (Jon Leech) - minor cleanup for public release.
Version 4, 20130/10/16 (Jon Leech) - add Dependencies and Overview text
noting that this extension obsoletes and should replace
Version 3, 20130/10/15 (Jon Leech) - change type of EGLAttribKHR from
uintptr to intptr (Bug 11027).
Version 2, 20130/10/12 (Jon Leech) - merge EGL_KHR_fence_sync2 with this
extension, change the naming scheme, define EGLAttribKHR as uintptr_t,
and add a new issues list.
Version 1, 2010/10/02 (Tom Cooksey) - initial version based on
EGL_KHR_cl_event and adding 64-bit EGLAttrKHR variants.