Name KHR_cl_event2 Name Strings EGL_KHR_cl_event2 Contributors Jon Leech, Khronos Alon Or-bach, Samsung Electronics Tom Cooksey, ARM Contact Jon Leech (jon 'at' alumni.caltech.edu) IP Status No known claims. Notice Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Complete. Approved by the EGL Working Group on December 4, 2013. Version Version 5, December 4, 2013 Number EGL Extension #65 Dependencies 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. Overview 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 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 argument of eglCreateSync64KHR: EGL_CL_EVENT_HANDLE_KHR 0x309C Returned in for eglGetSyncAttribKHR EGL_SYNC_TYPE_KHR: EGL_SYNC_CL_EVENT_KHR 0x30FE Returned in for eglGetSyncAttribKHR EGL_SYNC_CONDITION_KHR: EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF 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); and 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 " are created..."): "A 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 is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is created. In this case 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_TYPE_KHR EGL_SYNC_CL_EVENT_KHR EGL_SYNC_STATUS_KHR Depends on status of EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR The status of such a sync object depends on . When the status of is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of the linked sync object will be EGL_UNSIGNALED_KHR. When the status of 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 may result in undefined behavior up to and including program termination." The command eglCreateSync64KHR must be used to create a CL event sync object[fn1]. [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 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 OpenVG. 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 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 , 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 3.cc with: "Attribute Description Supported Sync Objects ----------------- ----------------------- ---------------------- EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or EGL_SYNC_CL_EVENT_KHR Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command" Replace the second paragraph describing eglDestroySync with: "If any eglClientWaitSyncKHR commands are blocking on when eglDestroySyncKHR is called, is flagged for deletion and will be deleted when the associated fence command or CL event object has completed, and is no longer blocking any eglClientWaitSyncKHR command. Otherwise, the sync object is destroyed immediately." Sample Code None Conformance Tests None yet Issues 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 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 ) 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 interfaces. 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 command. 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 compatible. 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 portability. 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 EGL_KHR_cl_event. 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.