clCreateFromEGLImageKHR

Creates an EGLImage target from an EGLImage source.

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)

Parameters

context

display

Should be of type EGLDisplay, cast into the type CLeglDisplayKHR.

image

Should be of type EGLImageKHR, cast into the type CLeglImageKHR. Assuming no errors are generated in this function, the resulting image object will be an EGLImage target of the specified EGLImage image. The resulting cl_mem is an image object which may be used normally by all OpenCL operations. This maps to an image2d_t type in OpenCL kernel code.

flags

A bit-field that is used to specify usage information about the memory object being created. The possible values for flags are: CL_MEM_FLAGS_READ_ONLY, CL_MEM_FLAGS_WRITE_ONLY and CL_MEM_FLAGS_READ_WRITE.

For OpenCL 1.2 flags also accepts: CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY or CL_MEM_HOST_NO_ACCESS.

This extension only requires support for CL_MEM_FLAGS_READ_ONLY, and for OpenCL 1.2 CL_MEM_HOST_NO_ACCESS. For OpenCL 1.1, a CL_INVALID_OPERATION will be returned for images which do not support host mapping.

If the value passed in flags is not supported by the OpenCL implementation it will return CL_INVALID_VALUE. The accepted flags may be dependent upon the texture format used.

properties

Specifies a list of property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. No properties are currently supported with this version of the extension. properties can be NULL.

errcode_ret

Description

clCreateFromEGLImageKHR creates an EGLImage target of type cl_mem from the EGLImage source provided as image.

Lifetime of Shared Objects

An OpenCL memory object created from an EGL image remains valid according to the lifetime behaviour as described in EGL_KHR_image_base.

"Any EGLImage siblings exist in any client API context"

For OpenCL this means that while the application retains a reference on the cl_mem (EGL sibling) the image remains valid.

Synchronizing OpenCL and EGL Access to Shared Objects

In order to ensure data integrity, the application is responsible for synchronizing access to shared CL/EGL objects by their respective APIs. Failure to provide such synchronization may result in race conditions and other undefined behavior including non-portability between implementations.

Prior to calling clEnqueueAcquireEGLObjectsKHR, the application must ensure that any pending operations which access the objects specified in mem_objects have completed. This may be accomplished in a portable way by ceasing all client operations on the resource, and issuing and waiting for completion of a glFinish command on all GL contexts with pending references to these objects. Implementations may offer more efficient synchronization methods, such as synchronisation primitives or fence operations.

Similarly, after calling clEnqueueReleaseEGLImageObjects, the application is responsible for ensuring that any pending OpenCL operations which access the objects specified in mem_objects have completed prior to executing subsequent commands in other APIs which reference these objects. This may be accomplished in a portable way by calling clWaitForEvents with the event object returned by clEnqueueReleaseGLObjects , or by calling clFinish. As above, some implementations may offer more efficient methods.

Attempting to access the data store of an EGLImage object after it has been acquired by OpenCL and before it has been released will result in undefined behavior. Similarly, attempting to access a shared EGLImage object from OpenCL before it has been acquired by the OpenCL command queue or after it has been released, will result in undefined behavior.

Errors

  • CL_INVALID_CONTEXT if context is not a valid OpenCL context.
  • CL_INVALID_VALUE if properties contains invalid values, if display is not a valid display object or if flags are not in the set defined above.
  • CL_INVALID_EGL_OBJECT_KHR if image is not a valid EGLImage object.
  • CL_IMAGE_FORMAT_NOT_SUPPORTED if the OpenCL implementation is not able to create a cl_mem compatible with the provided CLeglImageKHR for an implementation-dependent reason (this could be caused by, but not limited to, reasons such as unsupported texture formats, etc).
  • CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in table 4.3 (see clGetDeviceInfo) is CL_FALSE) or if the flags passed are not supported for that image type.
  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.
  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

Specification

OpenCL Specification

Also see

cl_khr_egl_image, cl_khr_egl_event

Copyright © 2007-2013 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.