|Home > Using OpenCL extensions > Inter-operation with EGL > EGL images|
EGL_KHR_image_base EGL extension provides the basic mechanism for sharing EGL images.
EGL_KHR_image_base EGL extension defines two entry points for creating and destroying EGL images:
EGLImageKHR eglCreateImageKHR( EGLDisplay dpy, EGLContext ctx, EGLenum target, EGLClientBuffer buffer, const EGLint *attrib_list) EGLBoolean eglDestroyImageKHR( EGLDisplay dpy, EGLImageKHR image)
eglCreateImageKHR call returns an opaque handle that the Khronos APIs use for referencing EGL images. Nothing in the extension specification precludes an EGL image from being the storage for the content that is to be shared, but the actual role of EGL images in the DDK is to serve only as references to memory allocations made by a low level API. There are two low level APIs for memory allocation that the DDK actively supports:
dma_bufon Linux, covered in
The availability of the memory allocation methods depends on the platform, the
EGL_KHR_image_base extension relies on additional extensions to define platform-specific values for the
buffer parameters on the
EGL_KHR_image_base extension only states that the
target parameter is a unique number identifying the content source. The
buffer parameter is an extension-specific handle that is cast to
EGLClientBuffer, a void pointer on the official Khronos EGL headers.
Applications needing the EGL image contents to be preserved must set
EGL_TRUE rather than relying on the default value.
The only attribute defined by the
EGL_KHR_image_base extension is
EGL_IMAGE_PRESERVED_KHR, which is a boolean defining whether the image contents are undefined after the
eglCreateImageKHR call returns. The default value for
EGL_FALSE, meaning that undefined contents are acceptable unless the application explicitly sets the value to
Failing to set
EGL_TRUE can lead to applications relying on undefined behavior, that is subject to change between Mali™ DDK releases.
There are two OpenCL mechanisms for supporting data sharing with other APIs from the Khronos ecosystem.
The two OpenCL mechanisms for supporting data sharing with other APIs from the Khronos ecosystem are:
Because customers can implement all their relevant use cases with the
cl_khr_egl_image path, cl_khr_gl_sharing extension is unsupported on the Mali DDK since the r6p0-01rel0 release.
cl_khr_egl_image OpenCL extension defines an entry point for creating
cl_mem objects out of EGL images:
cl_mem clCreateFromEGLImageKHR ( cl_context context, CLeglDisplayKHR display, CLeglImageKHR image, cl_mem_flags flags, const cl_egl_image_properties_khr * properties, cl_int * errcode_ret)
image parameter is an EGL image handle that is returned by
eglCreateImageKHR. The flags are a subset of the flags that are accepted by
clCreateBuffer, where the accepted flags are only
CL_MEM_READ_WRITE. The list of
properties is present on the extension for allowing future additions, but no such properties currently exist.
Applications are responsible for flushing the work when one Khronos API consumes the output from another.
For example, if an application produces an OpenGL ES render that OpenCL has to consume, then it is the responsibility of the application to issue a
glFinish before the OpenCL access happens.
The same application responsibility is also required when OpenCL outputs data that OpenGL is going to use. For example, an OpenGL ES rendering application that consumes some OpenCL output needs to ensure that it calls
clWaitForEvents to guarantee that the data is available for consumption before using OpenGL ES to access it.
In addition to flushing, there are GPU architectures that require the EGL images that are consumed or produced by OpenCL to be transferred between different device memories. That kind of architecture is common on discrete graphics cards for desktop PCs. The Mali implementations, on the other hand, uses the same main memory as the application processor, rather than a dedicated memory. Therefore there is no requirement to transfer data between the application processor and any dedicated GPU memory.
The OpenCL API delegates to the applications to choose the times at which the transfers happen by explicitly signaling when the accesses start and end.
The start and end of the EGL image accesses by OpenCL applications must be signaled by enqueuing
clEnqueueReleaseEGLObjectsKHR commands on an OpenCL command queue before and after a kernel accesses the EGL image data. An OpenCL kernel that uses an EGL image that it has not previously acquired gets an error at kernel enqueue time, for ensuring portability and compliance with the OpenCL standard, even on Mali implementations.
It is not possible to query an EGL image for its format or dimensions through the EGL API. The Mali™ OpenCL driver, on the other hand, allows querying for the format and dimensions of an OpenCL image created out of an EGL image.
However, the reported OpenCL format is only meaningful for formats that have a mapping between the EGL image source format and a format defined in the OpenCL specification.
A second limitation is that OpenCL images created out of EGL images cannot be memory mapped by means of
clEnqueueUnmapMemObject. The Khronos specifications do not explicitly say whether the memory mapping must be supported for this kind of OpenCL images. The DDK does not support memory mapping.