C Specification

The cl_image_format image format descriptor structure describes an image format, and is defined as:

// Provided by CL_VERSION_1_0
typedef struct cl_image_format {
    cl_channel_order    image_channel_order;
    cl_channel_type     image_channel_data_type;
} cl_image_format;

Members

  • image_channel_order specifies the number of channels and the channel layout i.e. the memory layout in which channels are stored in the image. Valid values are described in the Image Channel Order table.

  • image_channel_data_type describes the size of the channel data type. The list of supported values is described in the Image Channel Data Types table. The number of bits per element determined by the image_channel_data_type and image_channel_order must be a power of two.

Description

Table 1. List of supported Image Channel Order Values
Image Channel Order Description

CL_R, CL_A,

Single channel image formats where the single channel represents a RED or ALPHA component.

CL_DEPTH

missing before version 2.0.

Also supported if the cl_khr_depth_images extension is supported.

A single channel image format where the single channel represents a DEPTH component.

CL_LUMINANCE

A single channel image format where the single channel represents a LUMINANCE value. The LUMINANCE value is replicated into the RED, GREEN, and BLUE components.

CL_INTENSITY,

A single channel image format where the single channel represents an INTENSITY value. The INTENSITY value is replicated into the RED, GREEN, BLUE, and ALPHA components.

CL_RG, CL_RA

Two channel image formats. The first channel always represents a RED component. The second channel represents a GREEN component or an ALPHA component.

CL_Rx

missing before version 1.1.

A two channel image format, where the first channel represents a RED component and the second channel is ignored.

CL_DEPTH_STENCIL

provided by the cl_khr_gl_depth_images extension.

A two channel image format, where the first channel represents a DEPTH component and the second channel represents a stencil component. This format can only be used if the image channel data type is CL_UNORM_INT24 or CL_FLOAT.

See Restrictions on Depth/Stencil Images.

CL_RGB

A three channel image format, where the three channels represent RED, GREEN, and BLUE components.

CL_RGx

missing before version 1.1.

A three channel image format, where the first two channels represent RED and GREEN components and the third channel is ignored.

CL_RGBA, CL_ARGB, CL_BGRA, CL_ABGR

CL_ABGR is missing before version 2.0.

Four channel image formats, where the four channels represent RED, GREEN, BLUE, and ALPHA components.

CL_RGBx

missing before version 1.1.

A four channel image format, where the first three channels represent RED, GREEN, and BLUE components and the fourth channel is ignored.

CL_sRGB

missing before version 2.0.

A three channel image format, where the three channels represent RED, GREEN, and BLUE components in the sRGB color space.

CL_sRGBA, CL_sBGRA

missing before version 2.0.

Four channel image formats, where the first three channels represent RED, GREEN, and BLUE components in the sRGB color space. The fourth channel represents an ALPHA component.

CL_sRGBx

missing before version 2.0.

A four channel image format, where the three channels represent RED, GREEN, and BLUE components in the sRGB color space. The fourth channel is ignored.
Table 2. List of supported Image Channel Data Types
Image Channel Data Type Description

CL_SNORM_INT8

Each channel component is a normalized signed 8-bit integer value

CL_SNORM_INT16

Each channel component is a normalized signed 16-bit integer value

CL_UNORM_INT8

Each channel component is a normalized unsigned 8-bit integer value

CL_UNORM_INT16

Also supported if the cl_khr_depth_images extension is supported.

Each channel component is a normalized unsigned 16-bit integer value

CL_UNORM_SHORT_565

Represents a normalized 5-6-5 3-channel RGB image. The channel order must be CL_RGB or CL_RGBx.

CL_UNORM_SHORT_555

Represents a normalized x-5-5-5 4-channel xRGB image. The channel order must be CL_RGB or CL_RGBx.

CL_UNORM_INT_101010

Represents a normalized x-10-10-10 4-channel xRGB image. The channel order must be CL_RGB or CL_RGBx.

CL_UNORM_INT_101010_2

missing before version 2.1.

Represents a normalized 10-10-10-2 four-channel RGBA image. The channel order must be CL_RGBA.

CL_SIGNED_INT8

Each channel component is an unnormalized signed 8-bit integer value

CL_UNORM_INT_2_101010_EXT

provided by the cl_ext_image_unorm_int_2_101010 extension.

Represents a normalized 2-10-10-10 four-channel ABGR image. The channel order must be CL_ABGR.

CL_SIGNED_INT16

Each channel component is an unnormalized signed 16-bit integer value

CL_SIGNED_INT32

Each channel component is an unnormalized signed 32-bit integer value

CL_UNSIGNED_INT8

Each channel component is an unnormalized unsigned 8-bit integer value

CL_UNSIGNED_INT16

Each channel component is an unnormalized unsigned 16-bit integer value

CL_UNORM_INT24

provided by the cl_khr_gl_depth_images extension.

Each channel component is a normalized unsigned 24-bit integer value

CL_UNSIGNED_INT32

Each channel component is an unnormalized unsigned 32-bit integer value

CL_HALF_FLOAT

Each channel component is a 16-bit half-float value

CL_FLOAT

Also supported if the cl_khr_depth_images extension is supported.

Each channel component is a single precision floating-point value

CL_UNSIGNED_INT10X6_EXT

provided by the cl_ext_image_unsigned_10x6_12x4_14x2 extension.

Each channel component is an unnormalized unsigned 10-bit integer value stored in bits 15:6 of a 16-bit location. The channel order must be CL_R, CL_RG, or CL_RGBA.

CL_UNSIGNED_INT12X4_EXT

provided by the cl_ext_image_unsigned_10x6_12x4_14x2 extension.

Each channel component is an unnormalized unsigned 12-bit integer value stored in bits 15:4 of a 16-bit location. The channel order must be CL_R, CL_RG, or CL_RGBA.

CL_UNSIGNED_INT14X2_EXT

provided by the cl_ext_image_unsigned_10x6_12x4_14x2 extension.

Each channel component is an unnormalized unsigned 14-bit integer value stored in bits 15:2 of a 16-bit location. The channel order must be CL_R, CL_RG, or CL_RGBA.

CL_UNORM_INT10X6_EXT

provided by the cl_ext_image_unsigned_10x6_12x4_14x2 extension.

Each channel component is a normalized unsigned 10-bit integer value stored in bits 15:6 of a 16-bit location. The channel order must be CL_R, CL_RG, or CL_RGBA.

CL_UNORM_INT12X4_EXT

provided by the cl_ext_image_unsigned_10x6_12x4_14x2 extension.

Each channel component is a normalized unsigned 12-bit integer value stored in bits 15:4 of a 16-bit location. The channel order must be CL_R, CL_RG, or CL_RGBA.

CL_UNORM_INT14X2_EXT

provided by the cl_ext_image_unsigned_10x6_12x4_14x2 extension.

Each channel component is a normalized unsigned 14-bit integer value stored in bits 15:2 of a 16-bit location. The channel order must be CL_R, CL_RG, or CL_RGBA.

For example, to specify a normalized unsigned 8-bit / channel RGBA image, image_channel_order = CL_RGBA, and image_channel_data_type = CL_UNORM_INT8. The memory layout of this image format is described below:

R

G

B

A

…​

with the corresponding byte offsets

0

1

2

3

…​

Similar, if image_channel_order = CL_RGBA and image_channel_data_type = CL_SIGNED_INT16, the memory layout of this image format is described below:

R

G

B

A

…​

with the corresponding byte offsets

0

2

4

6

…​

image_channel_data_type values of CL_UNORM_SHORT_565, CL_UNORM_SHORT_555, CL_UNORM_INT_101010, and CL_UNORM_INT_101010_2 are special cases of packed image formats where the channels of each element are packed into a single unsigned short or unsigned int. For these special packed image formats, the channels are normally packed with the first channel in the most significant bits of the bitfield, and successive channels occupying progressively less significant locations. For CL_UNORM_SHORT_565, R is in bits 15:11, G is in bits 10:5 and B is in bits 4:0. For CL_UNORM_SHORT_555, bit 15 is undefined, R is in bits 14:10, G in bits 9:5 and B in bits 4:0. For CL_UNORM_INT_101010, bits 31:30 are undefined, R is in bits 29:20, G in bits 19:10 and B in bits 9:0. For CL_UNORM_INT_101010_2, R is in bits 31:22, G in bits 21:12, B in bits 11:2 and A in bits 1:0. For CL_UNORM_INT_2_101010_EXT, A is in bits 31:30, B in bits 29:20, G in bits 19:10 and R in bits 9:0.

OpenCL implementations must maintain the minimum precision specified by the number of bits in image_channel_data_type. If the image format specified by image_channel_order, and image_channel_data_type cannot be supported by the OpenCL implementation, then the call to clCreateImage, clCreateImageWithProperties, clCreateImage2D, or clCreateImage3D will return a NULL memory object.

See Also

CL_VERSION_1_0, clCreateImage, clCreateImage2D, clCreateImage3D, clCreateImageWithProperties, clGetImageRequirementsInfoEXT, clGetSupportedImageFormats, cl_channel_order, cl_channel_type

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL 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