Description
| Sampler-less image read functions require support for OpenCL C 1.2 or newer, with some functions requiring support for newer versions of OpenCL C as noted in the table below. |
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 sampler-less read functions this may be read_only or read_write.
| 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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. |
half4 read_imageh(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_imageh returns half-precision 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 read_imageh returns half-precision floating-point values in the
range [-1.0, 1.0] for image objects created with
image_channel_data_type set to read_imageh returns half-precision floating-point values for image
objects created with image_channel_data_type set to Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the |
int4 read_imagei(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: 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: 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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description are undefined. |
half4 read_imageh(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_imageh returns half-precision 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 read_imageh returns half-precision floating-point values in the
range [-1.0, 1.0] for image objects created with
image_channel_data_type set to read_imageh returns half-precision floating-point values for image
objects created with image_channel_data_type set to Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description are undefined. Requires support for the |
int4 read_imagei(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: 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: 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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. |
half4 read_imageh(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_imageh returns half-precision 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 read_imageh returns half-precision floating-point values in the
range [-1.0, 1.0] for image objects created with
image_channel_data_type set to read_imageh returns half-precision floating-point values for image
objects created with image_channel_data_type set to Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the |
int4 read_imagei(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: 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: 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) |
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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. |
half4 read_imageh(aQual image1d_t image, int coord) |
Use coord to do an element lookup in the 1D image or 1D image buffer object specified by image. read_imageh returns half-precision 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 read_imageh returns half-precision floating-point values in the
range [-1.0, 1.0] for image objects created with
image_channel_data_type set to read_imageh returns half-precision floating-point values for image
objects created with image_channel_data_type set to Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the |
int4 read_imagei(aQual image1d_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: 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: 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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. |
half4 read_imageh(aQual image1d_array_t image, int2 coord) |
Use coord.x to do an element lookup in the 2D image identified by coord.y in the 2D image array specified by image. read_imageh returns half-precision 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 read_imageh returns half-precision floating-point values in the
range [-1.0, 1.0] for image objects created with
image_channel_data_type set to read_imageh returns half-precision floating-point values for image
objects created with image_channel_data_type set to Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the |
int4 read_imagei(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: 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: 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
read_imagef returns a floating-point value for depth image objects
created with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for OpenCL C 2.0 or newer, or for
the |
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
read_imagef returns a floating-point value for depth image objects
created with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for OpenCL C 2.0 or newer, or for
the |
|
Use the coordinate (coord.x, coord.y) and sample 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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the
|
|
Use the coordinate (coord.x, coord.y) and sample 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: 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: If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. Requires support for the
|
|
Use coord.xy and sample 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 read_imagef returns floating-point values in the range [-1.0, 1.0]
for image objects created with image_channel_data_type set to
read_imagef returns floating-point values for image objects created
with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the
|
|
Use coord.xy and sample 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: 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: If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. Requires support for the
|
|
Use the coordinate (coord.x, coord.y) and sample 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
read_imagef returns a floating-point value for depth image objects
created with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. Requires support for the
|
|
Use coord.xy and sample 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
read_imagef returns a floating-point value for depth image objects
created with image_channel_data_type set to Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. Note: When a multisample image is accessed in a kernel, the access takes one vector of integers describing which pixel to fetch and an integer corresponding to the sample numbers describing which sample within the pixel to fetch. sample identifies the sample position in the multi-sample image. For best performance, we recommend that sample be a literal value so it is known at compile time and the OpenCL compiler can perform appropriate optimizations for multi-sample reads on the device. No standard sampling instructions are allowed on the multisample image. Accessing a coordinate outside the image and/or a sample that is outside the number of samples associated with each pixel in the image is undefined Requires support for the
|
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.