C Specification

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

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

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

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

Each channel component is a single precision floating-point value

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.

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, clCreateImage2D or clCreateImage3D will return a NULL memory object.

See Also

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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.