# Supported Data Formats

# Supported Data Formats

Image data format is the internal memory representation of every image. Data formats are described by TImageFormat enumeration member of TImageData structure. Additional information about each of the data formats is stored in TImageFormatInfo structure.

## Functions related to data formats (low level interface)

Function name
Usage
GetImageFormatInfo
Returns additional information about the given data format
GetPixelsSize
Returns number of bytes occupied by Width x Height area of pixels in the given data format (works for all data formats)
GetFormatName
Returns symbolic name of the given data format
ConvertImage
Converts images between different data formats
NewImage
Creates new image with the given data format

Data Format Categories
Image data formats can be divided to these main categories:
- ARGB Formats
  Each pixel consists of several color channels and optional alpha transparency channel.
- Indexed Formats
  Each pixel is index to the array of colors called the palette.
- Grayscale Formats
  Pixels consist of intensity channel and optional alpha transparency channel.
- Floating-point ARGB Formats
  These formats are similar to ARGB formats but color values are stored as floating-point numbers.
- Special Formats
  Each special format requires special and unique conversion procedures. Compressed formats like DXTC belong to this category.
Meaning of Data Format Symbolic Names
Each data format has its symbolic name. These names are formed in the way which tells something about its internal structure. Symbolic names look like this:
if[(channel1)(channel1sizebits)]..[(channeln)(channelnsizebits)][modifier1]..[modifiern]
For example ifA8R8G8B8 shows that each image pixel contains four 8 bit sized channels. ifR32F format contains one 32 bit channel and F modifier indicates that this is floating-point format. All channels in the symbolic names are listed from left to right, most significant bit (MSB) to least significant bit (LSB). For example, ifA8R8G8B8 is ordered from the MSB channel A (alpha), to the LSB channel B (blue). When traversing image data on little endian machines, the data is stored in memory from LSB to MSB, which means that the channel order in memory is from LSB (blue) to MSB (alpha).

Special data format names do not follow this naming convention. Their symbolic names refer for example to compression technology used (ifDXT5 is data format of image compressed with DXT5).

Symbolic Name Fragment | Info
--- | ---
X | Unused memory space
R | Red color channel
G | Green color channel
B | Blue color channel
A | Alpha transparency channel
Index | Index to palette
Gray | Grayscale intensity channel
F | Indicates that this format stores channel values as floating point numbers

ARGB Formats
The following table lists all ARGB formats supported in the current version of Imaging library. Channel values are stored as unsigned integers.

Symbolic Name | Info
--- | ---
ifX5R1G1B1 | 8 bit format with one bit for each color channel. 5 bits are unused.
ifR3G3B2 | 8 bit format with 3 bits for read and green and 2 bits for blue channel.
ifR5G6B5 | 16 bit format with 5 bits for read and blue and 6 bits for green channel.
ifA1R5G5B5 | 16 bit format with 5 bits for each color and one bit for alpha.
ifA4R4G4B4 | 16 bit format with 4 bits for each color and alpha.
ifX1R5G5B5 | 16 bit format with 5 bits for each color and one unused bit.
ifX4R4G4B4 | 16 bit format with 4 bits for each color and 4 unused bits.
ifR8G8B8 | 24 bit format with 8 bits for each color.
ifA8R8G8B8 | 32 bit format with 8 bits for each color and alpha.
ifX8R8G8B8 | 32 bit format with 8 bits for each color and 8 unused bits.
ifR16G16B16 | 48 bit format with 16 bits for each color.
ifA16R16G16B16 | 64 bit format with 16 bits for each color and alpha.
ifB16G16R16 | 48 bit BGR format with 16 bits for each color.
ifA16B16G16R16 | 64 bit BGR format with 16 bits for each color and alpha.

Indexed Formats
The following table lists all indexed formats supported in the current version of Imaging library. Indexes are stored as unsigned integers. Palette is PPalette32 member of TImageData structure. It is a pointer to array of 32 bit ARGB values in ifA8R8G8B8 format.

Symbolic Name | Info
--- | ---
ifIndex8 | 8 bit format with 8 bits for index.

Grayscale Formats
The following table lists all grayscale formats supported in the current version of Imaging library. Channels values are stored as unsigned integers.

Symbolic Name | Info
--- | ---
ifGray8 | 8 bit format with 8 bits for grayscale intensity.
ifA8Gray8 | 16 bit format with 8 bits for alpha transparency and 8 bits for grayscale intensity.
ifGray16 | 16 bit format with 16 bits for grayscale intensity.
ifGray32 | 32 bit format with 32 bits for grayscale intensity.
ifGray64 | 64 bit format with 64 bits for grayscale intensity.
ifA16Gray16 | 32 bit format with 16 bits for alpha transparency and 16 bits for grayscale intensity.

Floating-point ARGB Formats
The following table lists all floating-point formats supported in the current version of Imaging library. Channels values are stored as signed floating-point numbers.

Symbolic Name | Info
--- | ---
ifR32F | 32 bit format with one red 32 bit IEEE-754 channel.
ifA32R32G32B32F | 128 bit format with 32 bit IEEE-754 channel for each color and alpha.
ifA32B32G32R32F | 128 bit BGR format with 32 bit IEEE-754 channel for each color and alpha.
ifR16F | 16 bit format with one red 16 bit half-float (s1e5m10) channel.
ifA16R16G16B16F | 64 bit format with 16 bit half-float (s1e5m10) channel for each color and alpha.
ifA16B16G16R16F | 64 bit BGR format with 16 bit half-float (s1e5m10) channel for each color and alpha.

Special Formats
The following table lists all special formats supported in the current version of Imaging library.

Symbolic Name | Info
--- | ---
ifDXT1 | Image in this format is compressed with DXT1 compression (15/16 bit interpolated color, zero or one bit alpha).
ifDXT3 | Image in this format is compressed with DXT3 compression (16 bit interpolated color, 4 bit explicit alpha).
ifDXT5 | Image in this format is compressed with DXT5 compression (16 bit interpolated color, 8 bit interpolated alpha).
ifBTC | Image in this format is compressed with BTC compression (block truncation coding, grayscale, 2bits per pixel).
ifATI1N | Image in this format is compressed using 3Dc+ compression (one channel, 4bits per pixel).
ifATI2N | Image in this format is compressed using original 3Dc compression (two channels, 8bits per pixel).

There maybe some legal issues when using DXTC/S3TC compression (3Dc probably too as it is "subset" of DXT5) as S3 holds patent to this.