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
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
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.
image_slice_pitch is the size in bytes of each 2D slice in the 3D image. This be be 0 if host_ptr is
NULLand can be 0 or ≥ image_row_pitch × image_height if host_ptr is not
NULL. If host_ptr is not
NULLand 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_IMAGE3Dentry 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
Otherwise, it returns a
NULL value with one of the following error values
returned in errcode_ret:
CL_INVALID_CONTEXTif context is not a valid context.
CL_INVALID_VALUEif values specified in flags are not valid.
CL_INVALID_IMAGE_FORMAT_DESCRIPTORif values specified in image_format are not valid or if image_format is
CL_INVALID_IMAGE_SIZEif 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_DEPTHrespectively 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_PTRif host_ptr is
CL_MEM_COPY_HOST_PTRare set in flags or if host_ptr is not
CL_MEM_USE_HOST_PTRare not set in flags.
CL_IMAGE_FORMAT_NOT_SUPPORTEDif the image_format is not supported.
CL_MEM_OBJECT_ALLOCATION_FAILUREif there is a failure to allocate memory for image object.
CL_INVALID_OPERATIONif there are no devices in context that support images (i.e.
CL_DEVICE_IMAGE_SUPPORTspecified in the Device Queries table is
CL_OUT_OF_RESOURCESif there is a failure to allocate resources required by the OpenCL implementation on the device.
CL_OUT_OF_HOST_MEMORYif there is a failure to allocate resources required by the OpenCL implementation on the host.
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.