Description

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.

Table 1. Built-in Image Write Functions

Function

Description

void write_imagef(aQual image2d_t image, int2 coord, float4 color)
void write_imagei(aQual image2d_t image, int2 coord, int4 color)
void write_imageui(aQual image2d_t image, int2 coord, uint4 color)

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.

write_imagef 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 CL_SNORM_INT8, CL_UNORM_INT8, CL_SNORM_INT16, CL_UNORM_INT16, CL_HALF_FLOAT or CL_FLOAT. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored.

write_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.

write_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.

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 and y coordinate values that are not in the range [0, image width-1] and [0, image height-1], respectively, is undefined.

void write_imagef(aQual image2d_array_t image, int4 coord, float4 color)
void write_imagei(aQual image2d_array_t image, int4 coord, int4 color)
void write_imageui(aQual image2d_array_t image, int4 coord, uint4 color)

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.

write_imagef 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 CL_SNORM_INT8, CL_UNORM_INT8, CL_SNORM_INT16, CL_UNORM_INT16, CL_HALF_FLOAT or CL_FLOAT. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored.

write_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.

write_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.

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], and [0, image number of layers-1], respectively, is undefined.

void write_imagef(aQual image1d_t image, int coord, float4 color)
void write_imagei(aQual image1d_t image, int coord, int4 color)
void write_imageui(aQual image1d_t image, int coord, uint4 color)
void write_imagef(aQual image1d_buffer_t image, int coord, float4 color)
void write_imagei(aQual image1d_buffer_t image, int coord, int4 color)
void write_imageui(aQual image1d_buffer_t image, int coord, uint4 color)

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].

write_imagef 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 CL_SNORM_INT8, CL_UNORM_INT8, CL_SNORM_INT16, CL_UNORM_INT16, CL_HALF_FLOAT or CL_FLOAT. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored.

write_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.

write_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.

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 a coordinate value that is not in the range [0, image width-1], is undefined.

void write_imagef(aQual image1d_array_t image, int2 coord, float4 color)
void write_imagei(aQual image1d_array_t image, int2 coord, int4 color)
void write_imageui(aQual image1d_array_t image, int2 coord, uint4 color)

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.

write_imagef 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 CL_SNORM_INT8, CL_UNORM_INT8, CL_SNORM_INT16, CL_UNORM_INT16, CL_HALF_FLOAT or CL_FLOAT. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored.

write_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.

write_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.

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 number of layers-1], respectively, is undefined.

void write_imagef(aQual image2d_depth_t image, int2 coord, float depth)

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.

write_imagef can only be used with image objects created with image_channel_data_type set to CL_UNORM_INT16, CL_UNORM_INT24 or CL_FLOAT. Appropriate data format conversion will be done to convert depth valye from a floating-point value to actual data format associated with the image.

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.

void write_imagef(aQual image2d_array_depth_t image, int4 coord, float depth)

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.

write_imagef can only be used with image objects created with image_channel_data_type set to CL_UNORM_INT16, CL_UNORM_INT24 or CL_FLOAT. Appropriate data format conversion will be done to convert depth valye from a floating-point value to actual data format associated with the image.

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.

void write_imagef(aQual image3d_t image, int4 coord, float4 color)
void write_imagei(aQual image3d_t image, int4 coord, int4 color)
void write_imageui(aQual image3d_t image, int4 coord, uint4 color)

Write color value to 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.

write_imagef 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 CL_SNORM_INT8, CL_UNORM_INT8, CL_SNORM_INT16, CL_UNORM_INT16, CL_HALF_FLOAT or CL_FLOAT. Appropriate data format conversion will be done to convert channel data from a floating-point value to actual data format in which the channels are stored.

write_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.

write_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.

The behavior of write_imagef, 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.

See Also

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.