Description

The following built-in function calls to read images with a sampler are supported [1].

If the cl_khr_mipmap_image extension macro is supported, read functions which do not either

  • explicitly specify a level of detail lod, or

  • compute a level of detail from gradient parameters

read from mip level 0 if image is a mipmapped image.

Table 1. Built-in Image Read Functions
Function Description

float4 read_imagef(read_only image2d_t image, sampler_t sampler, int2 coord)
float4 read_imagef(read_only image2d_t image, sampler_t sampler, float2 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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(read_only image2d_t image, sampler_t sampler, int2 coord)
half4 read_imageh(read_only image2d_t image, sampler_t sampler, float2 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 CL_UNORM_INT8, or CL_UNORM_INT16.

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 CL_SNORM_INT8, or CL_SNORM_INT16.

read_imageh returns half-precision floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT.

The read_imageh calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 cl_khr_fp16 extension macro.

int4 read_imagei(read_only image2d_t image, sampler_t sampler, int2 coord)
int4 read_imagei(read_only image2d_t image, sampler_t sampler, float2 coord)
uint4 read_imageui(read_only image2d_t image, sampler_t sampler, int2 coord)
uint4 read_imageui(read_only image2d_t image, sampler_t sampler, float2 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.

The read_image{i|ui} 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.

float4 read_imagef(read_only image3d_t image, sampler_t sampler, int4 coord )
float4 read_imagef(read_only image3d_t image, sampler_t sampler, float4 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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

half4 read_imageh(read_only image3d_t image, sampler_t sampler, int4 coord )
half4 read_imageh(read_only image3d_t image, sampler_t sampler, float4 coord)

Use the coordinate (coord.x, coord.y, coord.z) to do an elementlookup 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 CL_UNORM_INT8, or CL_UNORM_INT16.

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 CL_SNORM_INT8, or CL_SNORM_INT16.

read_imageh returns half-precision floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT.

The read_imageh calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 cl_khr_fp16 extension macro.

int4 read_imagei(read_only image3d_t image, sampler_t sampler, int4 coord)
int4 read_imagei(read_only image3d_t image, sampler_t sampler, float4 coord)
uint4 read_imageui(read_only image3d_t image, sampler_t sampler, int4 coord)
uint4 read_imageui(read_only image3d_t image, sampler_t sampler, float4 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.

The read_image{i|ui} 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.

float4 read_imagef(read_only image2d_array_t image, sampler_t sampler, int4 coord)
float4 read_imagef(read_only image2d_array_t image, sampler_t sampler, float4 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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(read_only image2d_array_t image, sampler_t sampler, int4 coord)
half4 read_imageh(read_only image2d_array_t image, sampler_t sampler, float4 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 CL_UNORM_INT8, or CL_UNORM_INT16.

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 CL_SNORM_INT8, or CL_SNORM_INT16.

read_imageh returns half-precision floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT.

The read_imageh calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 cl_khr_fp16 extension macro.

int4 read_imagei(read_only image2d_array_t image, sampler_t sampler, int4 coord)
int4 read_imagei(read_only image2d_array_t image, sampler_t sampler, float4 coord)
uint4 read_imageui(read_only image2d_array_t image, sampler_t sampler, int4 coord)
uint4 read_imageui(read_only image2d_array_t image, sampler_t sampler, float4 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.

The read_image{i|ui} 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.

float4 read_imagef(read_only image1d_t image, sampler_t sampler, int coord)
float4 read_imagef(read_only image1d_t image, sampler_t sampler, float coord)

Use coord to do an element lookup in the 1D 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 1.2 or newer.

half4 read_imageh(read_only image1d_t image, sampler_t sampler, int coord)
half4 read_imageh(read_only image1d_t image, sampler_t sampler, float coord)

Use coord to do an element lookup in the 1D 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 CL_UNORM_INT8, or CL_UNORM_INT16.

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 CL_SNORM_INT8, or CL_SNORM_INT16.

read_imageh returns half-precision floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT.

The read_imageh calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 cl_khr_fp16 extension macro.

int4 read_imagei(read_only image1d_t image, sampler_t sampler, int coord)
int4 read_imagei(read_only image1d_t image, sampler_t sampler, float coord)
uint4 read_imageui(read_only image1d_t image, sampler_t sampler, int coord)
uint4 read_imageui(read_only image1d_t image, sampler_t sampler, float coord)

Use coord to do an element lookup in the 1D 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.

The read_image{i|ui} 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.

Requires support for OpenCL C 1.2 or newer.

float4 read_imagef(read_only image1d_array_t image, sampler_t sampler, int2 coord)
float4 read_imagef(read_only image1d_array_t image, sampler_t sampler, float2 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 1.2 or newer.

half4 read_imageh(read_only image1d_array_t image, sampler_t sampler, int2 coord)
half4 read_imageh(read_only image1d_array_t image, sampler_t sampler, float2 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_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 CL_UNORM_INT8, or CL_UNORM_INT16.

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 CL_SNORM_INT8, or CL_SNORM_INT16.

read_imageh returns half-precision floating-point values for image objects created with image_channel_data_type set to CL_HALF_FLOAT.

The read_imageh calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 cl_khr_fp16 extension macro.

int4 read_imagei(read_only image1d_array_t image, sampler_t sampler, int2 coord)
int4 read_imagei(read_only image1d_array_t image, sampler_t sampler, float2 coord)
uint4 read_imageui(read_only image1d_array_t image, sampler_t sampler, int2 coord)
uint4 read_imageui(read_only image1d_array_t image, sampler_t sampler, float2 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.

The read_image{i|ui} 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.

Requires support for OpenCL C 1.2 or newer.

float read_imagef(read_only image2d_depth_t image, sampler_t sampler, int2 coord)
float read_imagef(read_only image2d_depth_t image, sampler_t sampler, float2 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

Values returned by read_imagef for depth 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 cl_khr_depth_images extension macro.

float read_imagef(read_only image2d_array_depth_t image, sampler_t sampler, int4 coord)
float read_imagef(read_only image2d_array_depth_t image, sampler_t sampler, float4 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.

The read_imagef calls that take integer coordinates must use a sampler with filter mode set to CLK_FILTER_NEAREST, 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.

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 cl_khr_depth_images extension macro.

 
float4 read_imagef(
  read_only image2d_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

int4 read_imagei(
  read_only image2d_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

uint4 read_imageui(
  read_only image2d_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

float read_imagef(
  read_only image2d_depth_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

Use the coordinate coord.xy to do an element lookup in the mip level specified by lod in the 2D image object specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image2d_t image,
  sampler_t sampler,
  float2 coord,
  float2 gradient_x,
  float2 gradient_y)

int4 read_imagei(
  read_only image2d_t image,
  sampler_t sampler,
  float2 coord,
  float2 gradient_x,
  float2 gradient_y)

uint4 read_imageui(
  read_only image2d_t image,
  sampler_t sampler,
  float2 coord,
  float2 gradient_x,
  float2 gradient_y)

float read_imagef(
  read_only image2d_depth_t image,
  sampler_t sampler,
  float2 coord,
  float2 gradient_x,
  float2 gradient_y)

Use the gradients to compute the lod and coordinate coord.xy to do an element lookup in the mip level specified by the computed lod in the 2D image object specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image1d_t image,
  sampler_t sampler,
  float coord,
  float lod)

int4 read_imagei(
  read_only image1d_t image,
  sampler_t sampler,
  float coord,
  float lod)

uint4 read_imageui(
  read_only image1d_t image,
  sampler_t sampler,
  float coord,
  float lod)

Use the coordinate coord to do an element lookup in the mip level specified by lod in the 1D image object specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image1d_t image,
  sampler_t sampler,
  float coord,
  float gradient_x,
  float gradient_y)

int4 read_imagei(
  read_only image1d_t image,
  sampler_t sampler,
  float coord,
  float gradient_x,
  float gradient_y)

uint4 read_imageui(
  read_only image1d_t image,
  sampler_t sampler,
  float coord,
  float gradient_x,
  float gradient_y)

Use the gradients to compute the lod and coordinate coord to do an element lookup in the mip level specified by the computed lod in the 1D image object specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image3d_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

int4 read_imagei(
  read_only image3d_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

uint4 read_imageui(
  read_only image3d_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

Use the coordinate coord.xyz to do an element lookup in the mip level specified by lod in the 3D image object specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image3d_t image,
  sampler_t sampler,
  float4 coord,
  float4 gradient_x,
  float4 gradient_y)

int4 read_imagei(
  read_only image3d_t image,
  sampler_t sampler,
  float4 coord,
  float4 gradient_x,
  float4 gradient_y)

uint4 read_imageui(
  read_only image3d_t image,
  sampler_t sampler,
  float4 coord,
  float4 gradient_x,
  float4 gradient_y)

Use the gradients to compute the lod and coordinate coord.xyz to do an element lookup in the mip level specified by the computed lod in the 3D image object specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image1d_array_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

int4 read_imagei(
  read_only image1d_array_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

uint4 read_imageui(
  read_only image1d_array_t image,
  sampler_t sampler,
  float2 coord,
  float lod)

Use the coordinate coord.x to do an element lookup in the 1D image identified by coord.x and mip level specified by lod in the 1D image array specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image1d_array_t image,
  sampler_t sampler,
  float2 coord,
  float gradient_x,
  float gradient_y)

int4 read_imagei(
  read_only image1d_array_t image,
  sampler_t sampler,
  float2 coord,
  float gradient_x,
  float gradient_y)

uint4 read_imageui(
  read_only image1d_array_t image,
  sampler_t sampler,
  float2 coord,
  float gradient_x,
  float gradient_y)

Use the gradients to compute the lod and coordinate coord.x to do an element lookup in the mip level specified by the computed lod in the 1D image array specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image2d_array_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

int4 read_imagei(
  read_only image2d_array_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

uint4 read_imageui(
  read_only image2d_array_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

float read_imagef(
  read_only image2d_array_depth_t image,
  sampler_t sampler,
  float4 coord,
  float lod)

Use the coordinate coord.xy to do an element lookup in the 2D image identified by coord.z and mip level specified by lod in the 2D image array specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

 
float4 read_imagef(
  read_only image2d_array_t image,
  sampler_t sampler,
  float4 coord,
  float2 gradient_x,
  float2 gradient_y)

int4 read_imagei(
  read_only image2d_array_t image,
  sampler_t sampler,
  float4 coord,
  float2 gradient_x,
  float2 gradient_y)

uint4 read_imageui(
  read_only image2d_array_t image,
  sampler_t sampler,
  float4 coord,
  float2 gradient_x,
  float2 gradient_y)

float read_imagef(
  read_only image2d_array_depth_t image,
  sampler_t sampler,
  float4 coord,
  float2 gradient_x,
  float2 gradient_y)

Use the gradients to compute the lod coordinate and coord.xy to do an element lookup in the 2D image identified by coord.z and mip level specified by the computed lod in the 2D image array specified by image.

Requires support for the cl_khr_mipmap_image extension macro.

See Also

imageQueryFunctions, imageSamplerlessReadFunctions, imageWriteFunctions

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

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. Note that the built-in function calls to read images with a sampler are not supported for image1d_buffer_t image types.