Description

The sampler-less image read functions behave exactly as the corresponding built-in image read functions that take integer coordinates and a sampler with filter mode set to CLK_FILTER_NEAREST, normalized coordinates set to CLK_NORMALIZED_COORDS_FALSE and addressing mode to CLK_ADDRESS_NONE. There is one exception when the image_channel_data_type is a floating point type (such as CL_FLOAT). In this exceptional case, when channel data values are denormalized, the sampler-less image read function may return the denormalized data, while the image read function with a sampler argument may flush the denormalized channel data values to zero.

aQual in the following table refers to one of the access qualifiers. For samplerless read functions this may be read_only or read_write.

Table 1. Built-in Image Sampler-less Read Functions

Function

Description

float4 read_imagef(aQual image2d_t image, int2 coord)

Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D image object specified by image.

read_imagef returns floating-point values in the range [0.0, 1.0] for image objects created with image_channel_data_type set to one of the pre-defined packed formats or CL_UNORM_INT8, or CL_UNORM_INT16.

read_imagef returns floating-point values in the range [-1.0, 1.0] for image objects created with image_channel_data_type set to CL_SNORM_INT8, or CL_SNORM_INT16.

read_imagef returns floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT or CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined.

int4 read_imagei(aQual image2d_t image, int2 coord)
uint4 read_imageui(aQual image2d_t image, int2 coord)

Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D image object specified by image.

read_imagei and read_imageui 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 and
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.

float4 read_imagef(aQual image3d_t image, int4 coord )

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_imagef returns floating-point values in the range [0.0, 1.0] for image objects created with image_channel_data_type set to one of the pre-defined packed formats or CL_UNORM_INT8, or CL_UNORM_INT16.

read_imagef returns floating-point values in the range [-1.0, 1.0] for image objects created with image_channel_data_type set to CL_SNORM_INT8, or CL_SNORM_INT16.

read_imagef returns floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT or CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description are undefined.

int4 read_imagei(aQual image3d_t image, int4 coord)
uint4 read_imageui(aQual image3d_t image, int4 coord)

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

float4 read_imagef(aQual image2d_array_t image, int4 coord)

Use coord.xy to do an element lookup in the 2D image identified by coord.z in the 2D image array specified by image.

read_imagef returns floating-point values in the range [0.0, 1.0] for image objects created with image_channel_data_type set to one of the pre-defined packed formats or CL_UNORM_INT8, or CL_UNORM_INT16.

read_imagef returns floating-point values in the range [-1.0, 1.0] for image objects created with image_channel_data_type set to CL_SNORM_INT8, or CL_SNORM_INT16.

read_imagef returns floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT or CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined.

int4 read_imagei(aQual image2d_array_t image, int4 coord)
uint4 read_imageui(aQual image2d_array_t image, int4 coord)

Use coord.xy to do an element lookup in the 2D image identified by coord.z in the 2D image array specified by image.

read_imagei and read_imageui 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 and
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.

float4 read_imagef(aQual image1d_t image, int coord)
float4 read_imagef(aQual image1d_buffer_t image, int coord)

Use coord to do an element lookup in the 1D image or 1D image buffer object specified by image.

read_imagef returns floating-point values in the range [0.0, 1.0] for image objects created with image_channel_data_type set to one of the pre-defined packed formats or CL_UNORM_INT8, or CL_UNORM_INT16.

read_imagef returns floating-point values in the range [-1.0, 1.0] for image objects created with image_channel_data_type set to CL_SNORM_INT8, or CL_SNORM_INT16.

read_imagef returns floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT or CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined.

int4 read_imagei(aQual image1d_t image, int coord)
uint4 read_imageui(aQual image1d_t image, int coord)
int4 read_imagei(aQual image1d_buffer_t image, int coord)
uint4 read_imageui(aQual image1d_buffer_t image, int coord)

Use coord to do an element lookup in the 1D image or 1D image buffer object specified by image.

read_imagei and read_imageui 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 and
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.

float4 read_imagef(aQual image1d_array_t image, int2 coord)

Use coord.x to do an element lookup in the 1D image identified by coord.y in the 1D image array specified by image.

read_imagef returns floating-point values in the range [0.0, 1.0] for image objects created with image_channel_data_type set to one of the pre-defined packed formats or CL_UNORM_INT8, or CL_UNORM_INT16.

read_imagef returns floating-point values in the range [-1.0, 1.0] for image objects created with image_channel_data_type set to CL_SNORM_INT8, or CL_SNORM_INT16.

read_imagef returns floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT or CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined.

int4 read_imagei(aQual image1d_array_t image, int2 coord)
uint4 read_imageui(aQual image1d_array_t image, int2 coord)

Use coord.x to do an element lookup in the 1D image identified by coord.y in the 1D image array specified by image.

read_imagei and read_imageui 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 and
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.

float read_imagef(aQual image2d_depth_t image, int2 coord)

Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D depth image object specified by image.

read_imagef returns a floating-point value in the range [0.0, 1.0] for depth image objects created with image_channel_data_type set to CL_UNORM_INT16 or CL_UNORM_INT24.

read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined.

float read_imagef(aQual image2d_array_depth_t image, int4 coord)

Use coord.xy to do an element lookup in the 2D image identified by coord.z in the 2D depth image array specified by image.

read_imagef returns a floating-point value in the range [0.0, 1.0] for depth image objects created with image_channel_data_type set to CL_UNORM_INT16 or CL_UNORM_INT24.

read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to CL_FLOAT.

Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined.

See Also

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C 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.