C Specification

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

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


  • 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_depth is the depth of the image in pixels. This must be a value > 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.

  • image_slice_pitch is the size in bytes of each 2D slice in the 3D image. This be be 0 if host_ptr is NULL and can be 0 or ≥ image_row_pitch × image_height if host_ptr is not NULL. If host_ptr is not NULL and image_slice_pitch is 0, image_slice_pitch is calculated as image_row_pitch × image_height. If image_slice_pitch is not 0, it must be a multiple of the image_row_pitch.

  • 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 clCreateImage3D. Refer to the CL_​MEM_​OBJECT_​IMAGE3D 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 2D slices. 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.


clCreateImage3D 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 image_depth ≤ 1 or if they exceed the maximum values specified in CL_​DEVICE_​IMAGE3D_​MAX_​WIDTH, CL_​DEVICE_​IMAGE3D_​MAX_​HEIGHT or CL_​DEVICE_​IMAGE3D_​MAX_​DEPTH respectively for all devices in context or if values specified by image_row_pitch and image_slice_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.