TSDL_PixelFormat -- Stores surface format information

Structure Definition

  TSDL_PixelFormat = record
palette: PSDL_Palette;
BitsPerPixel: UInt8;
BytesPerPixel: UInt8;
Rloss: UInt8;
Gloss: UInt8;
Bloss: UInt8;
Aloss: UInt8;
Rshift: UInt8;
Gshift: UInt8;
Bshift: UInt8;
Ashift: UInt8;
Rmask: UInt32;
Gmask: UInt32;
Bmask: UInt32;
Amask: UInt32;
colorkey: Uint32; // RGB color key information
alpha: Uint8; // Alpha value information (per-surface alpha)

Structure Data

palette Pointer to the palette, or nil if the BitsPerPixel>8
BitsPerPixel The number of bits used to represent each pixel in a surface. Usually 8, 16, 24 or 32.
BytesPerPixel The number of bytes used to represent each pixel in a surface. Usually one to four.
[RGBA]mask Binary mask used to retrieve individual color values
[RGBA]loss Precision loss of each color component (2[RGBA]loss)
[RGBA]shift Binary left shift of each color component in the pixel value
colorkey Pixel value of transparent pixels
alpha Overall surface alpha value


A SDL_PixelFormat describes the format  of the pixel data stored at the pixels    field of a TSDL_Surface   . Every surface stores a SDL_PixelFormat   in the format field.

If you wish to do pixel level modifications on a surface, then understanding how SDL stores its color information is essential.

8-bit pixel formats are the easiest to understand. Since its an 8-bit format, we have 8 BitsPerPixel and 1 BytesPerPixel. Since   BytesPerPixel   is 1, all pixels are represented by a Uint8 which contains an index into palette.colors . So, to determine the color of a pixel in a 8-bit surface:  we read the color index from surface.pixels and we use that index to read the TSDL_Color structure from surface. format.palette.colors. Like so: 

surface : PSDL_Surface;
fmt : PSDL_PixelFormat;
color : PSDL_Color;
index : UInt8;


// Create surface
fmt := surface.format;

// Check the bitdepth of the surface
if ( fmt.BitsPerPixel <> 8 ) then
WriteLn( 'Not an 8-bit surface.' );

// Lock the surface
SDL_LockSurface( surface );

// Get the topleft pixel
index := PUint8( surface.pixels )^;
color := fmt.palette.colors[ index ];

// Unlock the surface
SDL_UnlockSurface( surface );
WriteLn( Format( 'Pixel Color-> Red: %d, Green: %d, Blue: %d. Index: %d', [ color.r, color.g, color.b, index ] ) );

Pixel formats above 8-bit are an entirely different experience. They are considered to be "TrueColor" formats and the color information is stored in the pixels themselves, not in a palette. The mask, shift and loss fields tell us how the color information is encoded. The mask fields allow us to isolate each color component, the shift fields tell us the number of bits to the right of each component in the pixel value and the loss fields tell us the number of bits lost from each component when packing 8-bit color component in a pixel.

// Extracting color components from a 32-bit color value */
fmt : PSDL_PixelFormat;
surface : PSDL_Surface;
temp, pixel : UInt32;
red, green, blue, alpha : UInt8;
fmt := surface->format;
SDL_LockSurface( surface );
pixel := PUint32( surface.pixels )^;
SDL_UnlockSurface( surface );

// Get Red component
temp := pixel and fmt.RMask; // Isolate red component
temp := temp shr fmt.RShift; // Shift it down to 8-bit
temp := temp shl fmt.RLoss; // Expand to a full 8-bit number
red := UInt8( temp );

// Get Green component
temp := pixel and fmt.GMask; // Isolate green component
temp := temp shr fmt.GShift; // Shift it down to 8-bit
temp := temp shl fmt.GLoss; // Expand to a full 8-bit number
green := UInt8( temp );

// Get Blue component
temp := pixel and fmt.BMask; // Isolate blue component
temp := temp shr fmt.BShift; // Shift it down to 8-bit
temp := temp shl fmt.BLoss; // Expand to a full 8-bit number
blue := UInt8( temp );

// Get Alpha component
temp := pixel and fmt.AMask; // Isolate alpha component
temp := temp shr fmt.AShift; // Shift it down to 8-bit
temp := temp shl fmt.ALoss; // Expand to a full 8-bit number
alpha := UInt8( temp );

WriteLn( Format( 'Pixel Color -> R: %d, G: %d, B: %d, A: %d', [ red, green, blue, alpha ] ) );

See Also

TSDL_Surface   , SDL_MapRGB