Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

SDL_PixelFormat (3)

Name

SDL_PixelFormat - Stores surface format information

Synopsis

Please see following description for synopsis

Description

SDL_PixelFormat(3)             SDL API Reference            SDL_PixelFormat(3)



NAME
       SDL_PixelFormat - Stores surface format information

STRUCTURE DEFINITION
       typedef struct SDL_PixelFormat {
         SDL_Palette *palette;
         Uint8  BitsPerPixel;
         Uint8  BytesPerPixel;
         Uint8  Rloss, Gloss, Bloss, Aloss;
         Uint8  Rshift, Gshift, Bshift, Ashift;
         Uint32 Rmask, Gmask, Bmask, Amask;
         Uint32 colorkey;
         Uint8  alpha;
       } SDL_PixelFormat;

STRUCTURE DATA
       palette             Pointer  to  the  palette,  or NULL if the BitsPer-
                           Pixel>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  val-
                           ues

       [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

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

       If  you  wish to do pixel level modifications on a surface, then under-
       standing 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  SDL_Color  structure  from  surface->format->pal-
       ette->colors. Like so:

       SDL_Surface *surface;
       SDL_PixelFormat *fmt;
       SDL_Color *color;
       Uint8 index;

       .
       .

       /* Create surface */
       .
       .
       fmt=surface->format;

       /* Check the bitdepth of the surface */
       if(fmt->BitsPerPixel!=8){
         fprintf(stderr, "Not an 8-bit surface.
       ");
         return(-1);
       }

       /* Lock the surface */
       SDL_LockSurface(surface);

       /* Get the topleft pixel */
       index=*(Uint8 *)surface->pixels;
       color=fmt->palette->colors[index];

       /* Unlock the surface */
       SDL_UnlockSurface(surface);
       printf("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 */
       SDL_PixelFormat *fmt;
       SDL_Surface *surface;
       Uint32 temp, pixel;
       Uint8 red, green, blue, alpha;
       .
       .
       .
       fmt=surface->format;
       SDL_LockSurface(surface);
       pixel=*((Uint32*)surface->pixels);
       SDL_UnlockSurface(surface);

       /* Get Red component */
       temp=pixel&fmt->Rmask; /* Isolate red component */
       temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */
       temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */
       red=(Uint8)temp;

       /* Get Green component */
       temp=pixel&fmt->Gmask; /* Isolate green component */
       temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */
       temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */
       green=(Uint8)temp;

       /* Get Blue component */
       temp=pixel&fmt->Bmask; /* Isolate blue component */
       temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */
       temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */
       blue=(Uint8)temp;

       /* Get Alpha component */
       temp=pixel&fmt->Amask; /* Isolate alpha component */
       temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */
       temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */
       alpha=(Uint8)temp;

       printf("Pixel Color -> R: %d,  G: %d,  B: %d,  A: %d
       ", red, green, blue, alpha);
       .
       .
       .

ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/sdl      |
       +---------------+------------------+
       |Stability      | Volatile         |
       +---------------+------------------+
SEE ALSO
       SDL_Surface, SDL_MapRGB



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source        was        downloaded        from        https://www.lib-
       sdl.org/release/SDL-1.2.15.tar.gz

       Further information about this software can be found on the open source
       community website at https://www.libsdl.org/.



SDL                         Tue 11 Sep 2001, 23:01          SDL_PixelFormat(3)