Description

Use the coordinate (coord.x, coord.y, coord.z)) to do an element lookup in the 3D image object specified by image. coord.w is ignored.

read_imagei and read_imageu{i|ui} return unnormalized signed integer and unsigned integer values respectively. Each channel will be stored in a 32-bit integer.

read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: CL_SIGNED_INT8, CL_SIGNED_INT16, or
CL_SIGNED_INT32. If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined.

read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: CL_UNSIGNED_INT8, CL_UNSIGNED_INT16, and CL_UNSIGNED_INT32. If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined.

The read_imageui calls support a nearest filter only. The filter_mode specified in sampler must be set to CLK_FILTER_NEAREST; otherwise the values returned are undefined.

Furthermore, the read_image{i|ui} calls that take integer coordinates must use a sampler with normalized coordinates set to CLK_NORMALIZED_COORDS_FALSE and addressing mode set to CLK_ADDRESS_CLAMP_TO_EDGE, CLK_ADDRESS_CLAMP or CLK_ADDRESS_NONE; otherwise the values returned are undefined.

Notes

The built-in functions defined in this section can only be used with image memory objects
created with clCreateImage2D, or clCreateImage3D. An image memory object can be
accessed by specific function calls that read from and/or write to specific locations in the image.

Image memory objects that are being read by a kernel should be declared with the
__read_only qualifier. write_image calls to image memory objects declared with the
__read_only qualifier will generate a compilation error. Image memory objects that are
being written to by a kernel should be declared with the __write_only qualifier.
read_image calls to image memory objects declared with the __write_only qualifier will
generate a compilation error. read_image
and write_image calls to the same image memory
object in a kernel are not supported.

The read_image calls returns a four component floating-point, integer or unsigned integer color
value. The color values returned by read_image are identified as x, y, z, w where x refers to
the red component, y refers to the green component, z refers to the blue component and w refers to the alpha component.

The image read functions take a sampler argument. The sampler can be passed as an argument
to the kernel using clSetKernelArg, or it can be a constant variable of type sampler_t declared in the program source.

The following table describes the mapping of the number of channels of an image element to the appropriate components in the float4, int4 or uint4 vector data type for the color values returned by read_image{f|i|ui} or supplied to write_image{f|i|ui}. The unmapped components will be set to 0.0 for red, green and blue channels and will be set to 1.0 for the alpha channel.

Channel Order

float4, int4 or unsigned int4 components of channel data

CL_R, CL_Rx

(r, 0.0, 0.0, 1.0)

CL_A

(0.0, 0.0, 0.0, a)

CL_RG, CL_RGx

(r, g, 0.0, 1.0)

CL_RA

(r, 0.0, 0.0, a)

CL_RGB, CL_RGBx

(r, g, b, 1.0)

CL_RGBA, CL_BGRA, CL_ARGB

(r, g, b, a)

CL_INTENSITY

(I, I, I, I)

CL_LUMINANCE

(L, L, L, 1.0)

A kernel that uses a sampler with the CL_ADDRESS_CLAMP addressing mode with
multiple images may result in additional samplers being used internally by an implementation. If
the same sampler is used with multiple images called via read_image{f | i | ui}, then it is
possible that an implementation may need to allocate an additional sampler to handle the
different border color values that may be needed depending on the image formats being used.
These implementation allocated samplers will count against the maximum sampler values
supported by the device and given by CL_DEVICE_MAX_SAMPLERS. Enqueuing a kernel that
requires more samplers than the implementation can support will result in a
CL_OUT_OF_RESOURCES error being returned.