The image descriptor structure describes the type and dimensions of the image or image array and is defined as:
typedef struct _cl_image_desc { cl_mem_object_type image_type; size_t image_width; size_t image_height; size_t image_depth; size_t image_array_size; size_t image_row_pitch; size_t image_slice_pitch; cl_uint num_mip_levels; cl_uint num_samples; cl_mem buffer; } cl_image_desc; |
Describes the image type and must be either
CL_MEM_OBJECT_IMAGE1D
,
CL_MEM_OBJECT_IMAGE1D_BUFFER
,
CL_MEM_OBJECT_IMAGE1D_ARRAY
,
CL_MEM_OBJECT_IMAGE2D
,
CL_MEM_OBJECT_IMAGE2D_ARRAY
, or
CL_MEM_OBJECT_IMAGE3D
.
The width of the image in pixels. For a 2D
image and image array, the image width must be ≤
CL_DEVICE_IMAGE2D_MAX_WIDTH
. For a 3D image, the image
width must be ≤ CL_DEVICE_IMAGE3D_MAX_WIDTH
. For
a 1D image buffer, the image width must be ≤
CL_DEVICE_IMAGE_MAX_BUFFER_SIZE
. For
a 1D image and 1D image array, the image width must be ≤
CL_DEVICE_IMAGE2D_MAX_WIDTH
.
The height of the image in pixels. This is only used if the image is a 2D, 3D
or 2D image array. For a 2D image or image array, the image height must be
≤ CL_DEVICE_IMAGE2D_MAX_HEIGHT
. For a 3D image, the
image height must be ≤ CL_DEVICE_IMAGE3D_MAX_HEIGHT
.
The depth of the image in pixels. This is only used if the
image is a 3D image and must be a value ≥ 1 and ≤
CL_DEVICE_IMAGE3D_MAX_DEPTH
.
The number of images in the image array. This is only
used if the image is a 1D or 2D image array. The values for
image_array_size
, if specified, must be a value ≥
1 and ≤ CL_DEVICE_IMAGE_MAX_ARRAY_SIZE
.
Note that reading and writing 2D image arrays from a kernel with
image_array_size
= 1 may be lower performance than
2D images.
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
=
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.
The size in bytes of each 2D slice in the 3D image or the size in
bytes of each image in a 1D or 2D image array. This must be 0 if
host_ptr
is NULL. If host_ptr
is not NULL, image_slice_pitch
can
be either 0 or ≥ image_row_pitch
*
image_height
for a 2D image array or 3D image
and can be either 0 or ≥ image_row_pitch
for a 1D image array. If host_ptr
is not NULL and image_slice_pitch
=
0, image_slice_pitch
is calculated as
image_row_pitch
* image_height
for a 2D image array or 3D image and image_row_pitch
for a 1D image array. If image_slice_pitch
is not 0,
it must be a multiple of the image_row_pitch
.
Must be 0.
Refers to a valid buffer memory object if image_type
is CL_MEM_OBJECT_IMAGE1D_BUFFER
. Otherwise it must
be NULL. For a 1D image buffer object, the image pixels are taken from
the buffer object's data store. When the contents of a buffer object's
data store are modified, those changes are reflected in the contents of
the 1D image buffer object and vice-versa at corresponding sychronization
points. The image_width
* size of element in bytes
must be ≤ size of buffer object data store.
Concurrent reading from, writing to and copying between both a buffer object and 1D image buffer object associated with the buffer object is undefined. Only reading from both a buffer object and 1D image buffer object associated with the buffer object is defined.