C Specification

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

// Provided by CL_VERSION_1_0
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);
clCreateImage2D is deprecated by version 1.2.

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

If CL_MEM_IMMUTABLE_EXT is set in flags, the image created is an immutable memory object that cannot be modified by the implementation after creation, and CL_MEM_COPY_HOST_PTR or CL_MEM_USE_HOST_PTR must be set in flags.

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 there are no devices in context that support image_format.

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

  • CL_INVALID_VALUE if CL_MEM_IMMUTABLE_EXT is set in flags and neither CL_MEM_COPY_HOST_PTR nor CL_MEM_USE_HOST_PTR is set in flags.

See Also

CL_VERSION_1_0, cl_context, cl_image_format, cl_int, cl_mem_flags

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

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0