SDL_PixelFormat(3)

1SDL_PixelFormat(3)             SDL API Reference            SDL_PixelFormat(3)
2
3
4

NAME

6       SDL_PixelFormat - Stores surface format information
7

STRUCTURE DEFINITION

9       typedef struct SDL_PixelFormat {
10         SDL_Palette *palette;
11         Uint8  BitsPerPixel;
12         Uint8  BytesPerPixel;
13         Uint8  Rloss, Gloss, Bloss, Aloss;
14         Uint8  Rshift, Gshift, Bshift, Ashift;
15         Uint32 Rmask, Gmask, Bmask, Amask;
16         Uint32 colorkey;
17         Uint8  alpha;
18       } SDL_PixelFormat;
19

STRUCTURE DATA

21       palette             Pointer  to  the  palette,  or NULL if the BitsPer‐
22                           Pixel>8
23
24       BitsPerPixel        The number of bits used to represent each pixel  in
25                           a surface. Usually 8, 16, 24 or 32.
26
27       BytesPerPixel       The number of bytes used to represent each pixel in
28                           a surface. Usually one to four.
29
30       [RGBA]mask          Binary mask used to retrieve individual color  val‐
31                           ues
32
33       [RGBA]loss          Precision    loss    of    each   color   component
34                           (2^[RGBA]loss)
35
36       [RGBA]shift         Binary left shift of each color  component  in  the
37                           pixel value
38
39       colorkey            Pixel value of transparent pixels
40
41       alpha               Overall surface alpha value
42

DESCRIPTION

44       A  SDL_PixelFormat describes the format of the pixel data stored at the
45       pixels field of a SDL_Surface. Every surface stores  a  SDL_PixelFormat
46       in the format field.
47
48       If  you  wish to do pixel level modifications on a surface, then under‐
49       standing how SDL stores its color information is essential.
50
51       8-bit pixel formats are the easiest to understand. Since its  an  8-bit
52       format, we have 8 BitsPerPixel and 1 BytesPerPixel. Since BytesPerPixel
53       is 1, all pixels are represented by a Uint8  which  contains  an  index
54       into  palette->colors. So, to determine the color of a pixel in a 8-bit
55       surface: we read the color index from surface->pixels and we  use  that
56       index  to  read  the  SDL_Color  structure  from  surface->format->pal‐
57       ette->colors. Like so:
58
59       SDL_Surface *surface;
60       SDL_PixelFormat *fmt;
61       SDL_Color *color;
62       Uint8 index;
63
64       .
65       .
66
67       /* Create surface */
68       .
69       .
70       fmt=surface->format;
71
72       /* Check the bitdepth of the surface */
73       if(fmt->BitsPerPixel!=8){
74         fprintf(stderr, "Not an 8-bit surface.
75       ");
76         return(-1);
77       }
78
79       /* Lock the surface */
80       SDL_LockSurface(surface);
81
82       /* Get the topleft pixel */
83       index=*(Uint8 *)surface->pixels;
84       color=fmt->palette->colors[index];
85
86       /* Unlock the surface */
87       SDL_UnlockSurface(surface);
88       printf("Pixel Color-> Red: %d, Green: %d, Blue: %d. Index: %d
89       ",
90                 color->r, color->g, color->b, index);
91       .
92       .
93
94       Pixel formats above 8-bit are an entirely  different  experience.  They
95       are  considered  to be "TrueColor" formats and the color information is
96       stored in the pixels themselves, not in a palette. The mask, shift  and
97       loss  fields  tell  us  how  the color information is encoded. The mask
98       fields allow us to isolate each color component, the shift fields  tell
99       us the number of bits to the right of each component in the pixel value
100       and the loss fields tell us the number of bits lost from each component
101       when packing 8-bit color component in a pixel.
102
103       /* Extracting color components from a 32-bit color value */
104       SDL_PixelFormat *fmt;
105       SDL_Surface *surface;
106       Uint32 temp, pixel;
107       Uint8 red, green, blue, alpha;
108       .
109       .
110       .
111       fmt=surface->format;
112       SDL_LockSurface(surface);
113       pixel=*((Uint32*)surface->pixels);
114       SDL_UnlockSurface(surface);
115
116       /* Get Red component */
117       temp=pixel&fmt->Rmask; /* Isolate red component */
118       temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */
119       temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */
120       red=(Uint8)temp;
121
122       /* Get Green component */
123       temp=pixel&fmt->Gmask; /* Isolate green component */
124       temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */
125       temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */
126       green=(Uint8)temp;
127
128       /* Get Blue component */
129       temp=pixel&fmt->Bmask; /* Isolate blue component */
130       temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */
131       temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */
132       blue=(Uint8)temp;
133
134       /* Get Alpha component */
135       temp=pixel&fmt->Amask; /* Isolate alpha component */
136       temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */
137       temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */
138       alpha=(Uint8)temp;
139
140       printf("Pixel Color -> R: %d,  G: %d,  B: %d,  A: %d
141       ", red, green, blue, alpha);
142       .
143       .
144       .
145

NAME

STRUCTURE DEFINITION

STRUCTURE DATA

DESCRIPTION

SEE ALSO