Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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);
       .
       .
       .

SEE ALSO
       SDL_Surface, SDL_MapRGB

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

NAME | STRUCTURE DEFINITION | STRUCTURE DATA | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SDL_PixelFormat&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help