6.15.15. Image Read and Write Functions
6.15.15. 图像读写函数
The built-in functions defined in this section can only be used with image memory objects. An image memory object can be accessed by specific function calls that read from and/or write to specific locations in the image.
本节中定义的内置函数只能用于图像内存对象。可以通过从图像中的特定位置读取或向其写入的特定函数调用来访问图像存储对象。
Support for the image built-in functions is optional. If a device supports images then the value of the CL_DEVICE_IMAGE_SUPPORT device query) is CL_TRUE and the OpenCL C compiler for that device must define the __IMAGE_SUPPORT__ macro. A compiler for OpenCL C 3.0 or newer for that device must also support the __opencl_c_images feature.
对图像内置函数的支持是可选的。如果设备支持图像，则CL_DEVICE_IMAGE_SUPPORT设备查询的值）为CL_TRUE，并且该设备的OpenCL C编译器必须定义__IMAGE_SUPPORT__宏。该设备的OpenCL C 3.0或更高版本的编译器还必须支持__opencl_c_images功能。
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 supported. Image memory objects that are being read and written by a kernel should be declared with the read_write qualifier.
内核正在读取的图像内存对象应使用read_only限定符声明。对用只读限定符声明的图像内存对象的write_image调用将生成编译错误。内核正在写入的图像内存对象应使用write_only限定符声明。对用write_only限定符声明的图像内存对象的readimage调用将生成编译错误。支持对内核中同一图像内存对象的read_image和write_image调用。内核正在读写的图像内存对象应使用read_write限定符声明。
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.
read_image调用返回一个四分量浮点、整数或无符号整数颜色值。read_image返回的颜色值被标识为x、y、z、w，其中x表示红色分量，y表示绿色分量，z表示蓝色分量，w表示阿尔法分量。
6.15.15.1. Samplers
6.15.15.1. 采样器
The image read functions take a sampler argument. The sampler can be passed as an argument to the kernel using clSetKernelArg, or can be declared in the outermost scope of kernel functions, or it can be a constant variable of type sampler_t declared in the program source.
图像读取函数接受采样器参数。采样器可以使用clSetKernelArg作为参数传递给内核，也可以在内核函数的最外层作用域中声明，也可以是程序源中声明的sampler_t类型的常量变量。
Sampler variables in a program are declared to be of type sampler_t. A variable of sampler_t type declared in the program source must be initialized with a 32-bit unsigned integer constant, which is interpreted as a bit-field specifying the following properties:
程序中的采样器变量被声明为sampler_t类型。程序源中声明的sampler_t型变量必须用32位无符号整数常量初始化，该常量被解释为指定以下属性的位字段：
-
Addressing Mode
-
寻址模式
-
Filter Mode
-
过滤模式
-
Normalized Coordinates
-
归一化坐标
These properties control how elements of an image object are read by read_image{f|i|ui}.
这些属性控制read_image{f|i|ui}如何读取图像对象的元素。
Samplers can also be declared as global constants in the program source using the following syntax.
采样器也可以使用以下语法在程序源代码中声明为全局常量。
const sampler_t <sampler name> = <value>or
constant sampler_t <sampler name> = <value>or
__constant sampler_t <sampler_name> = <value>Note that samplers declared using the constant qualifier are not counted towards the maximum number of arguments pointing to the constant address space or the maximum size of the constant address space allowed per device (i.e. the value of the CL_DEVICE_MAX_CONSTANT_ARGS and CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE device queries).
请注意，使用constant限定符声明的采样器不会计入指向constant地址空间的最大参数数或每个设备允许的常量地址空间最大大小（即CL_DEVICE_MAX_CONSTANT_ARGS和CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE设备查询的值）。
The sampler fields are described in the following table.
采样器字段如下表所示。
| Sampler State 采样器状态 | Description 描述 |
|---|---|
|
| Specifies whether the x, y and z coordinates are passed in as normalized or unnormalized values. This must be a literal value and can be one of the following predefined enums: 指定x、y和z坐标是作为归一化值还是非归一化值传入。这必须是一个文本值，可以是以下预定义枚举之一：
The samplers used with an image in multiple calls to read_image{f|i|ui} declared in a kernel must use the same value for <normalized coords>. 在内核中声明的多次调用read_image{f|i|ui}时，与图像一起使用的采样器必须对<normalized coords>使用相同的值。 |
|
| Specifies the image addressing mode, i.e. how out-of-range image coordinates are handled. This must be a literal value and can be one of the following predefined enums: 指定图像寻址模式，即如何处理超出范围的图像坐标。这必须是一个文本值，可以是以下预定义枚举之一：
For 1D and 2D image arrays, the addressing mode applies only to the x and (x, y) coordinates. The addressing mode for the coordinate which specifies the array index is always 对于1D和2D图像阵列，寻址模式仅适用于x和（x，y）坐标。指定数组索引的坐标的寻址模式始终是CLK_ADDRESS_CLAMP_TO_EDGE。 |
|
| Specifies the filter mode to use. This must be a literal value and can be one of the following predefined enums: 指定要使用的筛选模式。这必须是一个文本值，可以是以下预定义的枚举之一： Refer to the detailed description of these filter modes. 请参阅这些过滤模式的详细说明。 |
Examples:
示例：
const sampler_t samplerA = CLK_NORMALIZED_COORDS_TRUE |
CLK_ADDRESS_REPEAT |
CLK_FILTER_NEAREST;samplerA specifies a sampler that uses normalized coordinates, the repeat addressing mode and a nearest filter.
samplerA指定了一个使用归一化坐标、重复寻址模式和最近滤波器的采样器。
The maximum number of samplers that can be declared in a kernel can be queried using the CL_DEVICE_MAX_SAMPLERS token in clGetDeviceInfo.
可以使用clGetDeviceInfo中的CL_DEVICE_MAX_SAMPLERS令牌查询内核中可以声明的最大采样器数量。
6.15.15.1.1. Determining the Border Color or Value
6.15.15.1.1. 确定边框颜色或值
If <addressing mode> in sampler is CLK_ADDRESS_CLAMP, then out-of-range image coordinates return the border color. The border color selected depends on the image channel order and can be one of the following values:
如果采样器中的<寻址模式>为CLK_ADDRESS_CLAMP，则超出范围的图像坐标将返回边框颜色。所选的边框颜色取决于图像通道顺序，可以是以下值之一：
-
If the image channel order is
CL_A,CL_INTENSITY,CL_Rx,CL_RA,CL_RGx,CL_RGBx,CL_sRGBx,CL_ARGB,CL_BGRA,CL_ABGR,CL_RGBA,CL_sRGBAorCL_sBGRA, the border color is(0.0f, 0.0f, 0.0f, 0.0f). -
如果图像通道顺序为 CL_A、CL_INTENSITY、CL_Rx、CL_RA、CL_RGx、CL_RGBx、CL_sRGBx、CL_ARGB、CL_BGRA、CL_ABGR、CL_RGBA、CL_sRGBA 或 CL_sBGRA，则边框颜色为 (0.0f、0.0f、0.0f、0.0f)。
-
If the image channel order is
CL_R,CL_RG,CL_RGB, orCL_LUMINANCE, the border color is(0.0f, 0.0f, 0.0f, 1.0f). -
如果图像通道顺序为CL_R、CL_RG、CL_RGB或CL_LUMINANCE，则边框颜色为（0.0f、0.0f、0.07f、1.0f）。
-
If the image channel order is
CL_DEPTH, the border value is0.0f. -
如果图像通道顺序为CL_DEPTH，则边框值为0.0f。
6.15.15.1.2. sRGB Images
6.15.15.1.2. sRGB图像
The built-in image read functions will perform sRGB to linear RGB conversions if the image is an sRGB image. Likewise, the built-in image write functions perform the linear to sRGB conversion if the image is an sRGB image.
如果图像是sRGB图像，内置的图像读取函数将执行sRGB到线性RGB的转换。同样，如果图像是sRGB图像，内置的图像写入函数会执行线性到sRGB的转换。
Only the R, G and B components are converted from linear to sRGB and vice-versa. The alpha component is returned as is.
只有R、G和B分量从线性转换为sRGB，反之亦然。alpha组件按原样返回。
6.15.15.2. Built-in Image Read Functions
6.15.15.2. 内置图像读取函数
The following built-in function calls to read images with a sampler are supported [80].
支持以下使用采样器读取图像的内置函数调用[80]。
If the cl_khr_mipmap_image extension macro is supported, read functions which do not either
如果支持cl_khr_mipmap_image扩展宏，请读取既不支持也不支持的函数
-
explicitly specify a level of detail lod, or
-
明确指定详细程度的lod，或
-
compute a level of detail from gradient parameters
-
根据gradient参数计算细节级别
read from mip level 0 if image is a mipmapped image.
如果image是mipmapped图像，则从mip级别0读取。
| Function 函数 | Description 描述 |
|---|---|
| float4 read_imagef(read_only image2d_t image, sampler_t sampler, int2 coord) | Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D image object specified by image. 使用坐标（coord.x，coord.y）在image指定的2D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 The read_imagef calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imagef调用必须使用过滤器模式设置为 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| half4 read_imageh(read_only image2d_t image, sampler_t sampler, int2 coord) | Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D image object specified by image. 使用坐标（coord.x，coord.y）在image指定的2D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 The read_imageh calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imageh调用必须使用一个采样器，其过滤模式设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| int4 read_imagei(read_only image2d_t image, sampler_t sampler, int2 coord) | Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D image object specified by image. 使用坐标（coord.x，coord.y）在image指定的2D图像对象中进行元素查找。 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和read_imageui分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 The read_image{i|ui} calls support a nearest filter only. The filter_mode specified in sampler must be set to read_image{i|ui}调用仅支持最近的过滤器。采样器中指定的filter_mode必须设置为 Furthermore, the read_image{i|ui} calls that take integer coordinates must use a sampler with normalized coordinates set to 此外，取整数坐标的read_image{i|ui}调用必须使用归一化坐标设置为 |
| float4 read_imagef(read_only image3d_t image, sampler_t sampler, 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. 使用坐标（coord.x、coord.y、coord.z）在image指定的3D图像对象中进行元素查找。coord.w被忽略。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 The read_imagef calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imagef调用必须使用过滤器模式设置为 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description are undefined. read_imagef为描述中未指定image_channel_data_type值的图像对象返回的值未定义。 |
| half4 read_imageh(read_only image3d_t image, sampler_t sampler, int4 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. 使用坐标（coord.x、coord.y、coord.z）在image指定的3D图像对象中进行元素查找。coord.w被忽略。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 The read_imageh calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imageh调用必须使用一个采样器，其过滤模式设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description are undefined. read_imageh为描述中未指定image_channel_data_type值的图像对象返回的值未定义。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| int4 read_imagei(read_only image3d_t image, sampler_t sampler, 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. 使用坐标（coord.x、coord.y、coord.z）在image指定的3D图像对象中进行元素查找。coord.w被忽略。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 The read_image{i|ui} calls support a nearest filter only. The filter_mode specified in sampler must be set to read_image{i|ui}调用仅支持最近的过滤器。采样器中指定的filter_mode必须设置为 Furthermore, the read_image{i|ui} calls that take integer coordinates must use a sampler with normalized coordinates set to 此外，取整数坐标的read_image{i|ui}调用必须使用归一化坐标设置为 |
| float4 read_imagef(read_only image2d_array_t image, sampler_t sampler, 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. 使用coord.xy在由image指定的2D图像数组中的coord.z标识的2D图像中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 The read_imagef calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imagef调用必须使用过滤器模式设置为 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| half4 read_imageh(read_only image2d_array_t image, sampler_t sampler, 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. 使用coord.xy在由image指定的2D图像数组中的coord.z标识的2D图像中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 The read_imageh calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imageh调用必须使用一个采样器，其过滤模式设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| int4 read_imagei(read_only image2d_array_t image, sampler_t sampler, 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. 使用coord.xy在由image指定的2D图像数组中的coord.z标识的2D图像中进行元素查找。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 The read_image{i|ui} calls support a nearest filter only. The filter_mode specified in sampler must be set to read_image{i|ui}调用仅支持最近的过滤器。采样器中指定的filter_mode必须设置为 Furthermore, the read_image{i|ui} calls that take integer coordinates must use a sampler with normalized coordinates set to 此外，取整数坐标的read_image{i|ui}调用必须使用归一化坐标设置为 |
| float4 read_imagef(read_only image1d_t image, sampler_t sampler, int coord) | Use coord to do an element lookup in the 1D image object specified by image. 使用coord在image指定的1D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 The read_imagef calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imagef调用必须使用过滤器模式设置为 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for OpenCL C 1.2 or newer. 需要支持OpenCL C 1.2或更高版本。 |
| half4 read_imageh(read_only image1d_t image, sampler_t sampler, int coord) | Use coord to do an element lookup in the 1D image object specified by image. 使用coord在image指定的1D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 The read_imageh calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imageh调用必须使用一个采样器，其过滤模式设置为 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 read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| int4 read_imagei(read_only image1d_t image, sampler_t sampler, int coord) | Use coord to do an element lookup in the 1D image object specified by image. 使用coord在image指定的1D图像对象中进行元素查找。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 The read_image{i|ui} calls support a nearest filter only. The filter_mode specified in sampler must be set to read_image{i|ui}调用仅支持最近的过滤器。采样器中指定的filter_mode必须设置为 Furthermore, the read_image{i|ui} calls that take integer coordinates must use a sampler with normalized coordinates set to 此外，取整数坐标的read_image{i|ui}调用必须使用归一化坐标设置为 Requires support for OpenCL C 1.2 or newer. 需要支持OpenCL C 1.2或更高版本。 |
| float4 read_imagef(read_only image1d_array_t image, sampler_t sampler, 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. 使用coord.x在由image指定的1D图像数组中由coord.y标识的1D图像中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 The read_imagef calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imagef调用必须使用过滤器模式设置为 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for OpenCL C 1.2 or newer. 需要支持OpenCL C 1.2或更高版本。 |
| half4 read_imageh(read_only image1d_array_t image, sampler_t sampler, 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. 使用coord.x在由image指定的1D图像数组中由coord.y标识的1D图像中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 The read_imageh calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imageh调用必须使用一个采样器，其过滤模式设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| int4 read_imagei(read_only image1d_array_t image, sampler_t sampler, 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. 使用coord.x在由image指定的1D图像数组中由coord.y标识的1D图像中进行元素查找。 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和read_imageui分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 The read_image{i|ui} calls support a nearest filter only. The filter_mode specified in sampler must be set to read_image{i|ui}调用仅支持最近的过滤器。采样器中指定的filter_mode必须设置为 Furthermore, the read_image{i|ui} calls that take integer coordinates must use a sampler with normalized coordinates set to 此外，取整数坐标的read_image{i|ui}调用必须使用归一化坐标设置为 Requires support for OpenCL C 1.2 or newer. 需要支持OpenCL C 1.2或更高版本。 |
| float read_imagef(read_only image2d_depth_t image, sampler_t sampler, int2 coord) | Use the coordinate (coord.x, coord.y) to do an element lookup in the 2D depth image object specified by image. 使用坐标（coord.x，coord.y）在图像指定的2D深度图像对象中进行元素查找。 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为image_channel_data_type设置为 read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to read_imagef为使用设置为CL_FLOAT的image_channel_data_type创建的深度图像对象返回浮点值。 The read_imagef calls that take integer coordinates must use a sampler with filter mode set to 采用整数坐标的read_imagef调用必须使用过滤器模式设置为 Values returned by read_imagef for depth image objects with image_channel_data_type values not specified in the description above are undefined. 上述描述中未指定image_channel_data_type值的深度图像对象的read_imagef返回的值是未定义的。 Requires support for OpenCL C 2.0 or newer, or for the 需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。 |
| float read_imagef(read_only image2d_array_depth_t image, sampler_t sampler, 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. 使用coord.xy在image指定的2D深度图像数组中的coord.z标识的2D图像中进行元素查找。 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为image_channel_data_type设置为 read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to The read_imagef calls that take integer coordinates must use a sampler with filter mode set to read_imagef为使用设置为CL_FLOAT的image_channel_data_type创建的深度图像对象返回浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for OpenCL C 2.0 or newer, or for the 需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。 |
| 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. 使用坐标coord.xy在image指定的2D图像对象中的lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用梯度计算lod，坐标coord.xy在image指定的2D图像对象中，在由计算的lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| Use the coordinate coord to do an element lookup in the mip level specified by lod in the 1D image object specified by image. 使用坐标coord在由image指定的1D图像对象中，在由lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用梯度计算lod和坐标coord，在图像指定的1D图像对象中，在由计算的lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用坐标coord.xyz在image指定的3D图像对象中的lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用梯度计算lod，坐标coord.xyz在image指定的3D图像对象中计算lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用坐标coord.x在由coord.x标识的1D图像中进行元素查找，并在由image指定的1D图像数组中使用由lod指定的mip级别。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用梯度计算lod，坐标coord.x在image指定的1D图像数组中，在由计算的lod指定的mip级别中进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用坐标coord.xy在由coord.z标识的2D图像中进行元素查找，并在由image指定的2D图像数组中使用由lod指定的mip级别。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| 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. 使用梯度计算lod坐标，使用coord.xy在由coord.z标识的2D图像中进行元素查找，并在由图像指定的2D图像数组中使用由计算的lod指定的mip级别进行元素查找。 Requires support for the 需要支持cl_khr_mipmap_image扩展宏。 |
| If the 如果支持cl_khr_mipmap_image扩展宏，则 |
6.15.15.3. Built-in Image Sampler-less Read Functions
6.15.15.3. 内置无图像采样器读取功能
| 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. 无采样器图像读取函数需要支持OpenCL C 1.2或更高版本，如下表所示，一些函数需要支持较新版本的OpenCL C。 |
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.
无采样器图像读取函数的行为与相应的内置图像读取函数完全相同，该函数采用整数坐标，采样器的滤波器模式设置为CLK_FILTER_NEAREST，归一化坐标设置为CLK_NORMALIZED_COORDS_FALSE，寻址模式设置为CLK_ADDRESS_NONE。当image_channel_data_type是浮点类型（如CL_FLOAT）时，有一个例外。在这种特殊情况下，当信道数据值被非规范化时，无采样器图像读取函数可能会返回非规范化数据，而具有采样器参数的图像读取函数则可能会将非规范化信道数据值刷新为零。
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.
下表中的aQual是指其中一个访问限定符。对于无采样器的读取函数，这可能是read_only或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. 使用坐标（coord.x，coord.y）在image指定的2D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| 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. 使用坐标（coord.x，coord.y）在image指定的2D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| 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. 使用坐标（coord.x，coord.y）在image指定的2D图像对象中进行元素查找。 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和read_imageui分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 |
| 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. 使用坐标（coord.x、coord.y、coord.z）在image指定的3D图像对象中进行元素查找。coord.w被忽略。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description are undefined. read_imagef为描述中未指定image_channel_data_type值的图像对象返回的值未定义。 |
| 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. 使用坐标（coord.x、coord.y、coord.z）在图像指定的3D图像对象中进行元素查找。coord.w被忽略。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description are undefined. read_imageh为描述中未指定image_channel_data_type值的图像对象返回的值未定义。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| 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. 使用坐标（coord.x、coord.y、coord.z）在image指定的3D图像对象中进行元素查找。coord.w被忽略。 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和read_imageui分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 |
| 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. 使用coord.xy在由image指定的2D图像数组中的coord.z标识的2D图像中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| 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. 使用coord.xy在由image指定的2D图像数组中的coord.z标识的2D图像中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| 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. 使用coord.xy在由image指定的2D图像数组中的coord.z标识的2D图像中进行元素查找。 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和read_imageui分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 |
| 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. 使用coord在image指定的1D图像或1D图像缓冲区对象中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| 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. 使用coord在image指定的1D图像或1D图像缓冲区对象中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| 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. 使用coord在image指定的1D图像或1D图像缓冲区对象中进行元素查找。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 |
| 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. 使用coord.x在由image指定的1D图像数组中由coord.y标识的1D图像中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 |
| 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. 使用coord.x在由image指定的2D图像数组中的coord.y标识的2D图像中进行元素查找。 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返回范围[0.0，1.0]内的半精度浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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 read_imageh为image_channel_data_type设置为 Values returned by read_imageh for image objects with image_channel_data_type values not specified in the description above are undefined. read_imageh为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_fp16扩展宏。 |
| 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. 使用coord.x在由image指定的1D图像数组中由coord.y标识的1D图像中进行元素查找。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 |
| 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. 使用坐标（coord.x，coord.y）在image指定的2D深度图像对象中进行元素查找。 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为image_channel_data_type设置为 read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to read_imagef为使用设置为CL_FLOAT的image_channel_data_type创建的深度图像对象返回浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for OpenCL C 2.0 or newer, or for the 需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。 |
| 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. 使用coord.xy在image指定的2D深度图像数组中的coord.z标识的2D图像中进行元素查找。 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为image_channel_data_type设置为 read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to read_imagef为使用设置为CL_FLOAT的image_channel_data_type创建的深度图像对象返回浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for OpenCL C 2.0 or newer, or for the 需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。 |
| Use the coordinate (coord.x, coord.y) and sample to do an element lookup in the 2D image object specified by image. 使用坐标（coord.x，coord.y）和样本在image指定的2D图像对象中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_gl_msaa_sharing扩展宏。 |
| Use the coordinate (coord.x, coord.y) and sample to do an element lookup in the 2D image object specified by image. 使用坐标（coord.x，coord.y）和样本在image指定的2D图像对象中进行元素查找。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象： * If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象： * If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 Requires support for the 需要支持cl_khr_gl_msaa_sharing扩展宏。 |
| 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. 使用coord.xy和sample在由image指定的2D图像数组中由coord.z标识的2D图像中进行元素查找。 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返回范围[0.0，1.0]内的浮点值，用于将image_channel_data_type设置为预定义打包格式之一或 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返回范围[-1.0，1.0]内的浮点值，用于将image_channel_data_type设置为 read_imagef returns floating-point values for image objects created with image_channel_data_type set to read_imagef返回使用设置为CL_HALF_FLOAT或CL_FLOAT的image_channel_data_type创建的图像对象的浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_gl_msaa_sharing扩展宏。 |
| 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. 使用coord.xy和sample在由image指定的2D图像数组中由coord.z标识的2D图像中进行元素查找。 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 和read_imageui 分别返回非标准化的有符号整数值和无符号整数值。每个通道将存储在32位整数中。 read_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: read_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象： * If the image_channel_data_type is not one of the above values, the values returned by read_imagei are undefined. 如果image_channel_data_type不是上述值之一，则read_imagei返回的值未定义。 read_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: read_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象： * If the image_channel_data_type is not one of the above values, the values returned by read_imageui are undefined. 如果image_channel_data_type不是上述值之一，则read_imageui返回的值未定义。 Requires support for the 需要支持cl_khr_gl_msaa_sharing扩展宏。 |
| Use the coordinate (coord.x, coord.y) and sample to do an element lookup in the 2D depth image object specified by image. 使用坐标（coord.x，coord.y）和样本在image指定的2D深度图像对象中进行元素查找。 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为image_channel_data_type设置为 read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to read_imagef为使用设置为CL_FLOAT的image_channel_data_type创建的深度图像对象返回浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 Requires support for the 需要支持cl_khr_gl_msaa_sharing扩展宏。 |
| 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. 使用coord.xy和sample在由image指定的2D深度图像数组中由coord.z标识的2D图像中进行元素查找。 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为image_channel_data_type设置为 read_imagef returns a floating-point value for depth image objects created with image_channel_data_type set to read_imagef为使用设置为CL_FLOAT的image_channel_data_type创建的深度图像对象返回浮点值。 Values returned by read_imagef for image objects with image_channel_data_type values not specified in the description above are undefined. read_imagef为具有上述描述中未指定的image_channel_data_type值的图像对象返回的值是未定义的。 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. 为了获得最佳性能，我们建议sample是一个文本值，以便在编译时已知，OpenCL编译器可以对设备上的多样本读取进行适当的优化。 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 需要支持cl_khr_gl_msaa_sharing扩展宏。 |
6.15.15.4. Built-in Image Write Functions
6.15.15.4. 内置图像写入函数
The following built-in function calls to write images are supported.
支持以下用于写入图像的内置函数调用。
aQual in the following table refers to one of the access qualifiers. For write functions this may be write_only or read_write.
下表中的aQual是指其中一个访问限定符。对于写函数，这可以是write_only或read_write。
If the cl_khr_mipmap_image_writes extension macro is supported, write functions which do not explicitly specify a level of detail lod write to mip level 0 if image is a mipmapped image. mipwidth, mipheight, and mipdepth in the table refer to the width, height, and depth of the image mip level specified by lod respectively; miplayers refers to the number of layers in image; and miplevels refers to the number of mip levels in image.
如果支持cl_khr_mipmap_image_writes扩展宏，则如果图像是mipmap图像，则将不显式指定细节级别的函数写入到mip级别0。表中的mipwidth、mipheight和mipdest分别指lod指定的图像mip级别的宽度、高度和深度；miplevels 是指图像中的层数；mip级别是指图像中mip级别的数量。
If the cl_khr_srgb_image_writes extension macro is supported, the write_imagef functions described below may write to sRGB images. Linear to sRGB conversion is performed by the function. Only the R, G, and B components are converted from linear to sRGB; the A component is written as-is.
如果支持cl_khr_sgb_image_writes扩展宏，则下面描述的write_imagef函数可能会写入sRGB图像。线性到sRGB的转换由该函数执行。只有R、G和B分量从线性转换为sRGB；A组件按原样编写。
| Function 函数 | Description 描述 |
|---|---|
| void write_imagef( | Write color value to location specified by coord.xy in the 2D image object specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. coord.x and coord.y are considered to be unnormalized coordinates, and must be in the range [0, image width-1] and [0, image height-1] respectively. 将color值写入image指定的2D图像对象中coord.xy指定的位置。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。coord.x和coord.y被认为是非标准化坐标，并且必须分别在[0，图像宽度-1]和[0，图高-1]范围内。 write_imagef and write_imageh can only be used with image objects created with image_channel_data_type set to one of the pre-defined packed formats or set to write_imagef和write_imageh只能用于使用image_channel_data_type创建的图像对象，该image_channel _data_type设置为预定义的打包格式之一，或设置为 write_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: write_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
write_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: write_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
The behavior of write_imagef, write_imageh, write_imagei and write_imageui for image objects created with image_channel_data_type values not specified in the description above or with x and y coordinate values that are not in the range [0, image width-1] and [0, image height-1], respectively, is undefined. 对于使用上述描述中未指定的image_channel_data_type值或分别不在[0，image width-1]和[0，imageheight-1]范围内的x和y坐标值创建的图像对象，write_imagef、write_imageh、write_imagei和write_imageui的行为未定义。 write_imageh requires support for the write_imageh需要对cl_khr_fp16扩展宏的支持。 |
| void write_imagef( | Write color value to location specified by coord.xy in the 2D image identified by coord.z in the 2D image array specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. coord.x, coord.y and coord.z are considered to be unnormalized coordinates, and must be in the range [0, image width-1] and [0, image height-1], and [0, image number of layers-1], respectively. 将color值写入由coord.xy指定的位置，该位置在由image指定的2D图像数组中由coord.z标识的2D图像中。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。coord.x、coord.y和coord.z被认为是非标准化坐标，并且必须分别在[0，图像宽度-1]和[0，图高-1]以及[0，图层数-1]的范围内。 write_imagef and write_imageh can only be used with image objects created with image_channel_data_type set to one of the pre-defined packed formats or set to write_imagef和write_imageh只能用于使用image_channel_data_type创建的图像对象，该image_channel _data_type设置为预定义的打包格式之一，或设置为 write_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: write_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
write_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: write_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
The behavior of write_imagef, write_imageh, write_imagei and write_imageui for image objects created with image_channel_data_type values not specified in the description above or with (x, y, z) coordinate values that are not in the range [0, image width-1], [0, image height-1], and [0, image number of layers-1], respectively, is undefined. 对于使用上述描述中未指定的image_channel_data_type值或分别不在[0，image width-1]，[0，imageheight-1]和[0，图像层数-1]范围内的（x，y，z）坐标值创建的图像对象，write_imagef、write_imageh、write_imagei和write_imageui的行为未定义。 write_imageh requires support for the write_imageh需要对cl_khr_fp16扩展宏的支持。 |
| void write_imagef( | Write color value to location specified by coord in the 1D image or 1D image buffer object specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. coord is considered to be an unnormalized coordinate, and must be in the range [0, image width-1]. 将color值写入1D图像或image指定的1D图像缓冲对象中由coord指定的位置。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。coord被认为是一个非标准化坐标，必须在[0，图像宽度-1]范围内。 write_imagef and write_imageh can only be used with image objects created with image_channel_data_type set to one of the pre-defined packed formats or set to write_imagef和write_imageh只能用于使用image_channel_data_type创建的图像对象，该image_channel _data_type设置为预定义的打包格式之一，或设置为 write_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: write_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
write_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: write_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
The behavior of write_imagef, write_imageh, write_imagei and write_imageui for image objects created with image_channel_data_type values not specified in the description above, or with a coordinate value that is not in the range [0, image width-1], is undefined. 对于使用上述描述中未指定的image_channel_data_type值或不在[0，image width-1]范围内的坐标值创建的图像对象，write_imagef、write_imageh、write_imagei和write_imageui的行为未定义。 Requires support for OpenCL C 1.2 or newer. 需要支持OpenCL C 1.2或更高版本。 write_imageh requires support for the write_imageh需要对cl_khr_fp16扩展宏的支持。 |
| void write_imagef( | Write color value to location specified by coord.x in the 1D image identified by coord.y in the 1D image array specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. coord.x and coord.y are considered to be unnormalized coordinates and must be in the range [0, image width-1] and [0, image number of layers-1], respectively. 将color值写入由coord.x指定的位置，该位置位于由coord.y标识的1D图像中，位于由image指定的1D图像数组中。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。coord.x和coord.y被认为是非标准化坐标，必须分别在[0，图像宽度-1]和[0，层图像数量-1]的范围内。 write_imagef and write_imageh can only be used with image objects created with image_channel_data_type set to one of the pre-defined packed formats or set to write_imagef和write_imageh只能用于使用image_channel_data_type创建的图像对象，该image_channel _data_type设置为预定义的打包格式之一，或设置为 write_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: write_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
write_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: write_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
The behavior of write_imagef, write_imageh, write_imagei and write_imageui for image objects created with image_channel_data_type values not specified in the description above or with (x, y) coordinate values that are not in the range [0, image width-1] and [0, image number of layers-1], respectively, is undefined. 对于使用上述描述中未指定的image_channel_data_type值或分别不在[0，image width-1]和[0，imagenumber of layers-1]范围内的（x，y）坐标值创建的图像对象，write_imagef、write_imageh、write_imagei和write_imageui的行为是未定义的。 Requires support for OpenCL C 1.2 or newer. 需要支持OpenCL C 1.2或更高版本。 |
| void write_imagef( | Write depth value to location specified by coord.xy in the 2D depth image object specified by image. Appropriate data format conversion to the specified image format is done before writing the depth value. coord.x and coord.y are considered to be unnormalized coordinates, and must be in the range [0, image width-1], and [0, image height-1], respectively. 将depth值写入image指定的2D深度图像对象中coord.xy指定的位置。在写入深度值之前，将适当的数据格式转换为指定的图像格式。coord.x和coord.y被认为是非标准化坐标，并且必须分别在[0，图像宽度-1]和[0，图高-1]范围内。 write_imagef can only be used with image objects created with image_channel_data_type set to write_imagef只能用于将image_channel_data_type设置为 The behavior of write_imagef, write_imagei and write_imageui for image objects created with image_channel_data_type values not specified in the description above or with (x, y) coordinate values that are not in the range [0, image width-1] and [0, image height-1], respectively, is undefined. 对于使用上述描述中未指定的image_channel_data_type值或分别不在[0，image width-1]和[0，imageheight-1]范围内的（x，y）坐标值创建的图像对象，write_imagef、write_imagei和write_imageui的行为是未定义的。 Requires support for OpenCL C 2.0 or newer, or for the 需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。 |
| void write_imagef( | Write depth value to location specified by coord.xy in the 2D image identified by coord.z in the 2D depth image array specified by image. Appropriate data format conversion to the specified image format is done before writing the depth value. coord.x, coord.y and coord.z are considered to be unnormalized coordinates, and must be in the range [0, image width-1], [0, image height-1], and [0, image number of layers-1], respectively. 将depth值写入由coord.xy指定的位置，该位置位于由image指定的2D深度图像数组中由coord.z标识的2D图像中。在写入深度值之前，将适当的数据格式转换为指定的图像格式。coord.x、coord.y和coord.z被认为是非标准化坐标，并且必须分别在[0，图像宽度-1]、[0，图片高度-1]和[0，图层数-1]的范围内。 write_imagef can only be used with image objects created with image_channel_data_type set to write_imagef只能用于将image_channel_data_type设置为 The behavior of write_imagef, write_imagei and write_imageui for image objects created with image_channel_data_type values not specified in the description above or with (x, y, z) coordinate values that are not in the range [0, image width-1], [0, image height-1], [0, image number of layers-1], respectively, is undefined. 对于使用上述描述中未指定的image_channel_data_type值或分别不在[0，image width-1]，[0，image height-1]，[0]，image number of layers-1]范围内的（x，y，z）坐标值创建的图像对象，write_imagef、write_imagei和write_imageui的行为未定义。 Requires support for OpenCL C 2.0 or newer, or for the 需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。 |
| void write_imagef( | Write color value to the location specified by coord.xyz in the 3D image object specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. coord.x, coord.y and coord.z are considered to be unnormalized coordinates, and must be in the range [0, image width-1], [0, image height-1], and [0, image depth-1], respectively. 将color值写入image指定的3D图像对象中coord.xyz指定的位置。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。coord.x、coord.y和coord.z被认为是非标准化坐标，并且必须分别在[0，图像宽度-1]、[0，图高-1]和[0，像深-1]的范围内。 write_imagef and write_imageh can only be used with image objects created with image_channel_data_type set to one of the pre-defined packed formats or set to write_imagef和write_imageh只能用于使用image_channel_data_type创建的图像对象，该image_channel _data_type设置为预定义的打包格式之一，或设置为 write_imagei can only be used with image objects created with image_channel_data_type set to one of the following values: write_imagei只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
write_imageui can only be used with image objects created with image_channel_data_type set to one of the following values: write_imageui只能用于使用image_channel_data_type设置为以下值之一创建的图像对象：
The behavior of write_imagef, write_imageh, write_imagei and write_imageui for image objects with image_channel_data_type values not specified in the description above or with (x, y, z) coordinate values that are not in the range [0, image width-1], [0, image height-1], and [0, image depth-1], respectively, is undefined. 对于具有上述描述中未指定的image_channel_data_type值或（x，y，z）坐标值分别不在[0，image width-1]、[0，imageheight-1]和[0，Imagedepth-1]范围内的图像对象，write_imagef、write_imageh、write_imagei和write_imageui的行为是未定义的。 Requires support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the 需要支持OpenCL C 2.0、OpenCL C 3.0或更高版本以及 write_imageh requires support for the write_imageh需要对cl_khr_fp16扩展宏的支持。 |
| Write color value to location specified by coord.xy in the mip level specified by lod in the 2D image object specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. 将color值写入由image指定的2D图像对象中由lod指定的mip级别中由coord.xy指定的位置。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。 lod must be in the range [0, miplevels-1]. coord.x and coord.y are considered to be unnormalized coordinates and must be in the range [0, mipwidth-1] and [0, mipheight-1] respectively. Behavior is undefined if lod, coord.x, or coord.y is not in range. lod必须在[0，miplease-1]范围内。coord.x和coord.y被认为是非标准化坐标，必须分别在[0，mipwidth-1]和[0，mipheight-1]范围内。如果lod、coord.x或coord.y不在范围内，则行为未定义。 Requires support for the 需要支持cl_khr_mipmap_image_writes扩展宏。 |
| Write color value to location specified by coord in the mip level specified by lod in the 1D image object specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. 将color 值写入由image指定的1D图像对象中由lod指定的mip级别中由coord指定的位置。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。 lod must be in the range [0, miplevels-1]. coord is considered to be an unnormalized coordinate and must be in the range [0, mipwidth-1]. Behavior is undefined if lod or coord is not in range. lod必须在[0，miplease-1]范围内。coord被认为是一个非标准化坐标，必须在[0，mipwidth-1]范围内。如果lod或coord不在范围内，则行为未定义。 Requires support for the 需要支持cl_khr_mipmap_image_writes扩展宏。 |
| Write color value to location specified by coord.x in the 1D image identified by coord.y and mip level lod in the 1D image array specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. 将color值写入由coord.y标识的1D图像中由coord.x指定的位置，并将mip-level lod写入由image指定的1D图像数组中。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。 lod must be in the range [0, miplevels-1]. coord.x and coord.y are considered to be unnormalized coordinates and must be in the range [0, mipwidth-1] and [0, miplayers -1] respectively. Behavior is undefined if lod, coord.x, or coord.y is not in range. lod必须在[0，miplease-1]范围内。coord.x和coord.y被认为是非标准化坐标，必须分别在[0，mipwidth-1]和[0，miplayers-1]范围内。如果lod、coord.x或coord.y不在范围内，则行为未定义。 Requires support for the 需要支持cl_khr_mipmap_image_writes扩展宏。 |
| Write color value to location specified by coord.xy in the 2D image identified by coord.z and mip level lod in the 2D image array specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. 将color值写入由coord.z标识的2D图像中由coord.xy指定的位置，并将mip-level lod写入由image指定的2D图像数组中。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。 lod must be in the range [0, miplevels-1]. coord.x, coord.y and coord.z are considered to be unnormalized coordinates and must be in the range [0, mipwidth-1], [0, mipheight-1], and [0, miplayers-1] respectively. Behavior is undefined if lod, coord.x, coord.y, or coord.z is not in range. lod必须在[0，miplease-1]范围内。coord.x、coord.y和coord.z被认为是非标准化坐标，并且必须分别在[0，mipwidth-1]、[0，mipheight-1]和[0，MIP layers-1]的范围内。如果lod、coord.x、coord.y或coord.z不在范围内，则行为未定义。 Requires support for the 需要支持cl_khr_mipmap_image_writes扩展宏。 |
| Write color value to location specified by coord.xyz and mip level lod in the 3D image object specified by image. Appropriate data format conversion to the specified image format is done before writing the color value. 将color值写入image指定的3D图像对象中由coord.xyz和mip-level lod指定的位置。在写入颜色值之前，将适当的数据格式转换为指定的图像格式。 lod must be in the range [0, miplevels-1]. coord.x, coord.y and coord.z are considered to be unnormalized coordinates and must be in the range [0, mipwidth-1], [0, mipheight-1] and [0, mipdepth-1] respectively. Behavior is undefined if lod, coord.x, coord.y, or coord.z is not in range. lod必须在[0，miplease-1]范围内。coord.x、coord.y和coord.z被视为非标准化坐标，必须分别在[0，mipwidth-1]、[0，mipheight-1]和[0，MIP depth-1]范围内。如果lod、coord.x、coord.y或coord.z不在范围内，则行为未定义。 Requires support for the 需要支持cl_khr_mipmap_image_writes扩展宏。 |
6.15.15.5. Built-in Image Query Functions
6.15.15.5. 内置图像查询函数
The following built-in function calls to query image information are supported.
支持以下查询图像信息的内置函数调用。
aQual in the following table refers to one of the access qualifiers. For query functions this may be read_only, write_only or read_write.
下表中的aQual是指其中一个访问限定符。对于查询函数，这可能是read_only、write_only或read_write。
| Function 函数 | Description 描述 |
|---|---|
| int get_image_width(aQual image2d_t image) For OpenCL C 1.2 or newer: int get_image_width(aQual image1d_t image) For OpenCL C 2.0 or newer, or if the int get_image_width(aQual image2d_depth_t image) If the int get_image_width(aQual image2d_msaa_t image) | Return the image width in pixels. 返回图像宽度（像素）。 |
| int get_image_height(aQual image2d_t image) For OpenCL C 1.2 or newer: int get_image_height(aQual image2d_array_t image) For OpenCL C 2.0 or newer, or if the int get_image_height(aQual image2d_depth_t image) If the int get_image_height(aQual image2d_msaa_t image) | Return the image height in pixels. 返回图像高度（像素）。 |
| int get_image_depth(image3d_t image) | Return the image depth in pixels. 返回图像深度（像素）。 |
| int get_image_channel_data_type(aQual image2d_t image) For OpenCL C 1.2 or newer: int get_image_channel_data_type(aQual image1d_t image) For OpenCL C 2.0 or newer, or if the int get_image_channel_data_type(aQual image2d_depth_t image) If the int get_image_channel_data_type(aQual image2d_msaa_t image) | Return the channel data type. Valid values are: 返回通道数据类型。有效值为：
Additionally, for OpenCL C 3.0 or newer: 此外，对于OpenCL C 3.0或更高版本：
|
| int get_image_channel_order(aQual image2d_t image) For OpenCL C 1.2 or newer: int get_image_channel_order(aQual image1d_t image) For OpenCL C 2.0 or newer, or if the int get_image_channel_order(aQual image2d_depth_t image) If the int get_image_channel_order(aQual image2d_msaa_t image) | Return the image channel order. Valid values are: 返回图像通道顺序。有效值为：
Additionally, for OpenCL C 1.1 or newer: 此外，对于OpenCL C 1.1或更高版本：
Additionally, for OpenCL C 2.0 or newer: 此外，对于OpenCL C 2.0或更高版本：
|
| int2 get_image_dim(aQual image2d_t image) For OpenCL C 1.2 or newer: int2 get_image_dim(aQual image2d_array_t image) For OpenCL C 2.0 or newer, or if the int2 get_image_dim(aQual image2d_depth_t image) If the int2 get_image_dim(aQual image2d_msaa_t image) | Return the 2D image width and height as an 以int2类型返回2D图像的宽度和高度。宽度在x分量中返回，高度在y分量中返回。 |
| int4 get_image_dim(aQual image3d_t image) | Return the 3D image width, height, and depth as an 以int4类型返回3D图像的宽度、高度和深度。x分量返回宽度，y分量返回高度，z分量返回深度，w分量返回0。 |
| For OpenCL C 1.2 or newer: size_t get_image_array_size(aQual image2d_array_t image) For OpenCL C 2.0 or newer, or if the size_t get_image_array_size(aQual image2d_array_depth_t image) If the size_t get_image_array_size(aQual image2d_array_msaa_depth_t image) | Return the number of images in the 2D image array. 返回二维图像数组中的图像数量。 |
| For OpenCL C 1.2 or newer: size_t get_image_array_size(aQual image1d_array_t image) | Return the number of images in the 1D image array. 返回1D图像数组中的图像数量。 |
| If the int get_image_num_samples(aQual image2d_msaa_t image) | Return the number of samples in the 2D MSAA image 返回二维MSAA图像中的样本数 |
| If the int get_image_num_mip_levels(aQual image1d_t image) | Return the number of mip levels in image. 返回image中的mip级别数。 |
The values returned by get_image_channel_data_type and get_image_channel_order as specified in Built-in Image Query Functions with the CLK_ prefixes correspond to the CL_ prefixes used to describe the image channel order and data type in the OpenCL Specification. For example, both CL_UNORM_INT8 and CLK_UNORM_INT8 refer to an image channel data type that is an unnormalized unsigned 8-bit integer.
具有CLK_前缀的内置图像查询函数中指定的get_image_channel_data_type和get_image_channel_order返回的值对应于OpenCL规范中用于描述图像通道顺序和数据类型的CL_前缀。例如，CL_UNORM_INT8 和CLK_UNORM_INT8 都指一种图像通道数据类型，该数据类型是一个非标准化的无符号8位整数。
6.15.15.6. Reading and Writing to the Same Image in a Kernel
6.15.15.6. 在内核中读写同一图像
The atomic_work_item_fence(CLK_IMAGE_MEM_FENCE) built-in function can be used to make sure that sampler-less writes are visible to later reads by the same work-item. Only a scope of memory_scope_work_item and an order of memory_order_acq_rel is valid for atomic_work_item_fence when passed the CLK_IMAGE_MEM_FENCE flag. If multiple work-items are writing to and reading from multiple locations in an image, the work_group_barrier(CLK_IMAGE_MEM_FENCE) should be used.
atomic_work_item_fence(CLK_IMAGE_MEM_FENCE) 内置函数可用于确保无采样器写入对同一工作项的后续读取可见。当传递CLK_IMAGE_MEM_FENCE 标志时，只有memory_scope_work_item的作用域和memory_order_acq_rel的顺序对atomic_work_item_fence有效。如果多个工作项正在对图像中的多个位置进行写入和读取，则应使用work_group_barrier(CLK_IMAGE_MEM_FENCE) 。
Consider the following example:
考虑以下示例：
kernel void
foo(read_write image2d_t img, ... )
{
int2 coord;
coord.x = (int)get_global_id(0);
coord.y = (int)get_global_id(1);
float4 clr = read_imagef(img, coord);
...
write_imagef(img, coord, clr);
// required to ensure that following read from image at
// location coord returns the latest color value.
atomic_work_item_fence(
CLK_IMAGE_MEM_FENCE,
memory_order_acq_rel,
memory_scope_work_item);
float4 clr_new = read_imagef(img, coord);
...
}6.15.15.7. Mapping Image Channels to Color Values Returned by read_image and Color Values Passed to write_image to Image Channels
6.15.15.7. 将图像通道映射到read_Image返回的颜色值，并将传递给write_Image的颜色值映射到图像通道
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.
下表描述了图像元素的通道数量与float4、int4或uint4矢量数据类型中由read_image{f|i|ui}返回或提供给write_image{f |i|ui}的颜色值的适当分量的映射。对于红色、绿色和蓝色通道，未映射的组件将设置为0.0，对于阿尔法通道，将设置为1.0。
| Channel Order 通道顺序 |
通道数据的float4、int4或uint4分量 |
|---|---|
|
| (r, 0.0, 0.0, 1.0) |
|
| (0.0, 0.0, 0.0, a) |
|
| (r, g, 0.0, 1.0) |
|
| (r, 0.0, 0.0, a) |
|
| (r, g, b, 1.0) |
|
| (r, g, b, a) |
|
| (I, I, I, I) |
|
| (L, L, L, 1.0) |
For CL_DEPTH images, a scalar value is returned by read_imagef or supplied to write_imagef. Requires support for OpenCL C 2.0 or newer, or for the cl_khr_depth_images extension macro.
对于CL_DEPTH图像，read_imagef返回标量值或将其提供给write_imagef。需要支持OpenCL C 2.0或更高版本，或cl_khr_depth_images扩展宏。
| A kernel that uses a sampler with the 使用具有多个图像的CL_ADDRESS_CLAMP寻址模式的采样器的内核可能会导致实现在内部使用额外的采样器。如果同一采样器用于通过read_image{f|i|ui}调用的多个图像，则实现可能需要分配额外的采样器来处理根据所使用的图像格式可能需要的不同边框颜色值。这些实现分配的采样器将计入设备支持的 |
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
