TSDL_PixelFormat

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)
  end;

Structure Data

Description

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: 

var 
  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 
begin
  WriteLn( 'Not an 8-bit surface.' );
  return(-1);
end;

// 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