A 2D image object can be created using the following function
const cl_image_format* image_format,
|clCreateImage2D is deprecated by version 1.2.
context is a valid OpenCL context on which the image object is to be created.
flags is a bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the supported memory flag values table. If the value specified for flags is 0, the default is used which is
image_format is a pointer to a structure that describes format properties of the image to be allocated. Refer to the Image Format Descriptor section for a detailed description of the image format descriptor.
image_width and image_height are the width and height of the image in pixels. These must be values greater than or equal to 1.
image_row_pitch is the scan-line pitch in bytes. This must be 0 if host_ptr is
NULLand can be either 0 or ≥ image_width × size of element in bytes if host_ptr is not
NULL. If host_ptr is not
NULLand image_row_pitch is 0, image_row_pitch is calculated as image_width × size of element in bytes. If image_row_pitch is not 0, it must be a multiple of the image element size in bytes.
host_ptr is a pointer to the image data that may already be allocated by the application. Refer to the
CL_MEM_entry in the required host_ptr buffer size table for a description of how large the buffer that host_ptr points to must be. The image data specified by host_ptr is stored as a linear sequence of adjacent scanlines. Each scanline is a linear sequence of image elements. Image elements are stored according to their image format as described in the Image Format Descriptor section.
errcode_ret will return an appropriate error code. If errcode_ret is
NULL, no error code is returned.
clCreateImage2D returns a valid non-zero image object created and the
errcode_ret is set to
CL_SUCCESS if the image object is created
Otherwise, it returns a
NULL value with one of the following error values
returned in errcode_ret:
CL_INVALID_if context is not a valid context.
CL_INVALID_if values specified in flags are not valid.
CL_INVALID_if values specified in image_format are not valid or if image_format is
IMAGE_ FORMAT_ DESCRIPTOR
CL_INVALID_if image_width or image_height are 0 or if they exceed the maximum values specified in
IMAGE2D_ MAX_ WIDTH
CL_DEVICE_respectively for all devices in context or if values specified by image_row_pitch do not follow rules described in the argument description above.
IMAGE2D_ MAX_ HEIGHT
CL_INVALID_if host_ptr is
USE_ HOST_ PTR
CL_MEM_are set in flags or if host_ptr is not
COPY_ HOST_ PTR
COPY_ HOST_ PTR
CL_MEM_are not set in flags.
USE_ HOST_ PTR
CL_IMAGE_if there are no devices in context that support image_format.
FORMAT_ NOT_ SUPPORTED
CL_MEM_if there is a failure to allocate memory for image object.
OBJECT_ ALLOCATION_ FAILURE
CL_INVALID_if there are no devices in context that support images (i.e.
CL_DEVICE_specified in the Device Queries table is
CL_OUT_if there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_if there is a failure to allocate resources required by the OpenCL implementation on the host.
OF_ HOST_ MEMORY
For more information, see the OpenCL Specification
This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.