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.

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.

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.

Table 1. Built-in Image Write Functions
Function Description

void write_imagef(
aQual image2d_t image,
int2 coord,
float4 color)
void write_imageh(
aQual image2d_t image,
int2 coord,
half4 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 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 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_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.

write_imageh requires support for the cl_khr_fp16 extension macro.

void write_imagef(
aQual image2d_array_t image,
int4 coord,
float4 color)
void write_imageh(
aQual image2d_array_t image,
int4 coord,
half4 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 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 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_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.

write_imageh requires support for the cl_khr_fp16 extension macro.

void write_imagef(
aQual image1d_t image,
int coord,
float4 color)
void write_imageh(
aQual image1d_t image,
int coord,
half4 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_imageh(
aQual image1d_buffer_t image,
int coord,
half4 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 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 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_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.

Requires support for OpenCL C 1.2 or newer.

write_imageh requires support for the cl_khr_fp16 extension macro.

void write_imagef(
aQual image1d_array_t image,
int2 coord,
float4 color)
void write_imageh(
aQual image1d_array_t image,
int2 coord,
half4 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 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 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_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.

Requires support for OpenCL C 1.2 or newer.

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.

Requires support for OpenCL C 2.0 or newer, or for the cl_khr_depth_images extension macro.

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.

Requires support for OpenCL C 2.0 or newer, or for the cl_khr_depth_images extension macro.

void write_imagef(
aQual image3d_t image,
int4 coord,
float4 color)
void write_imageh(
aQual image3d_t image,
int4 coord,
half4 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 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.

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

Requires support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the __opencl_c_3d_image_writes feature, or the cl_khr_3d_image_writes extension.

write_imageh requires support for the cl_khr_fp16 extension macro.

 
void write_imagef(
  write_only image2d_t image,
  int2 coord,
  int lod,
  float4 color)

void write_imagei(
  write_only image2d_t image,
  int2 coord,
  int lod,
  int4 color)

void write_imageui(
  write_only image2d_t image,
  int2 coord,
  int lod,
  uint4 color)

void write_imagef(
  write_only image2d_depth_t image,
  int2 coord,
  int lod,
  float depth)

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.

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.

Requires support for the cl_khr_mipmap_image_writes extension macro.

 
void write_imagef(
  write_only image1d_t image,
  int coord,
  int lod,
  float4 color)

void write_imagei(
  write_only image1d_t image,
  int coord,
  int lod,
  int4 color)

void write_imageui(
  write_only image1d_t image,
  int coord,
  int lod,
  uint4 color)

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.

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.

Requires support for the cl_khr_mipmap_image_writes extension macro.

 
void write_imagef(
  write_only image1d_array_t image,
  int2 coord,
  int lod,
  float4 color)

void write_imagei(
  write_only image1d_array_t image,
  int2 coord,
  int lod,
  int4 color)

void write_imageui(
  write_only image1d_array_t image,
  int2 coord,
  int lod,
  uint4 color)

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.

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.

Requires support for the cl_khr_mipmap_image_writes extension macro.

 
void write_imagef(
  write_only image2d_array_t image,
  int4 coord,
  int lod,
  float4 color)

void write_imagei(
  write_only image2d_array_t image,
  int4 coord,
  int lod,
  int4 color)

void write_imageui(
  write_only image2d_array_t image,
  int4 coord,
  int lod,
  uint4 color)

void write_imagef(
  write_only image2d_array_depth_t image,
  int4 coord,
  int lod,
  float depth)

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.

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.

Requires support for the cl_khr_mipmap_image_writes extension macro.

 
void write_imagef(
  write_only image3d_t image,
  int4 coord,
  int lod,
  float4 color)

void write_imagei(
  write_only image3d_t image,
  int4 coord,
  int lod,
  int4 color)

void write_imageui(
  write_only image3d_t image,
  int4 coord,
  int lod,
  uint4 color)

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.

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.

Requires support for the cl_khr_mipmap_image_writes extension macro.

See Also

imageQueryFunctions, imageReadFunctions, imageSamplerlessReadFunctions

Document Notes

For more information, see the OpenCL C Specification

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

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0