C Specification

A 2D image object can be created using the following function

cl_mem clCreateImage2D(
    cl_context context,
    cl_mem_flags flags,
    const cl_image_format* image_format,
    size_t image_width,
    size_t image_height,
    size_t image_row_pitch,
    void* host_ptr,
    cl_int* errcode_ret);

Parameters

  • 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 CL_​MEM_​READ_​WRITE.

  • 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 NULL and can be either 0 or ≥ image_width × size of element in bytes if host_ptr is not NULL. If host_ptr is not NULL and 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. It is only used to initialize the image, and can be freed after the call to clCreateImage2D. Refer to the CL_​MEM_​OBJECT_​IMAGE2D 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.

Description

clCreateImage2D returns a valid non-zero image object created and the errcode_ret is set to CL_​SUCCESS if the image object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

  • CL_​INVALID_​CONTEXT if context is not a valid context.

  • CL_​INVALID_​VALUE if values specified in flags are not valid.

  • CL_​INVALID_​IMAGE_​FORMAT_​DESCRIPTOR if values specified in image_format are not valid or if image_format is NULL.

  • CL_​INVALID_​IMAGE_​SIZE if image_width or image_height are 0 or if they exceed the maximum values specified in CL_​DEVICE_​IMAGE2D_​MAX_​WIDTH or CL_​DEVICE_​IMAGE2D_​MAX_​HEIGHT respectively for all devices in context or if values specified by image_row_pitch do not follow rules described in the argument description above.

  • CL_​INVALID_​HOST_​PTR if host_ptr is NULL and CL_​MEM_​USE_​HOST_​PTR or CL_​MEM_​COPY_​HOST_​PTR are set in flags or if host_ptr is not NULL but CL_​MEM_​COPY_​HOST_​PTR or CL_​MEM_​USE_​HOST_​PTR are not set in flags.

  • CL_​IMAGE_​FORMAT_​NOT_​SUPPORTED if the image_format is not supported.

  • CL_​MEM_​OBJECT_​ALLOCATION_​FAILURE if there is a failure to allocate memory for image object.

  • CL_​INVALID_​OPERATION if there are no devices in context that support images (i.e. CL_​DEVICE_​IMAGE_​SUPPORT specified in the Device Queries table is CL_​FALSE).

  • 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.

See Also

Document Notes

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.

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.