e14743d1 |
1 | <HTML |
2 | ><HEAD |
3 | ><TITLE |
4 | >SDL_PixelFormat</TITLE |
5 | ><META |
6 | NAME="GENERATOR" |
7 | CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ |
8 | "><LINK |
9 | REL="HOME" |
10 | TITLE="SDL Library Documentation" |
11 | HREF="index.html"><LINK |
12 | REL="UP" |
13 | TITLE="Video" |
14 | HREF="video.html"><LINK |
15 | REL="PREVIOUS" |
16 | TITLE="SDL_Palette" |
17 | HREF="sdlpalette.html"><LINK |
18 | REL="NEXT" |
19 | TITLE="SDL_Surface" |
20 | HREF="sdlsurface.html"></HEAD |
21 | ><BODY |
22 | CLASS="REFENTRY" |
23 | BGCOLOR="#FFF8DC" |
24 | TEXT="#000000" |
25 | LINK="#0000ee" |
26 | VLINK="#551a8b" |
27 | ALINK="#ff0000" |
28 | ><DIV |
29 | CLASS="NAVHEADER" |
30 | ><TABLE |
31 | SUMMARY="Header navigation table" |
32 | WIDTH="100%" |
33 | BORDER="0" |
34 | CELLPADDING="0" |
35 | CELLSPACING="0" |
36 | ><TR |
37 | ><TH |
38 | COLSPAN="3" |
39 | ALIGN="center" |
40 | >SDL Library Documentation</TH |
41 | ></TR |
42 | ><TR |
43 | ><TD |
44 | WIDTH="10%" |
45 | ALIGN="left" |
46 | VALIGN="bottom" |
47 | ><A |
48 | HREF="sdlpalette.html" |
49 | ACCESSKEY="P" |
50 | >Prev</A |
51 | ></TD |
52 | ><TD |
53 | WIDTH="80%" |
54 | ALIGN="center" |
55 | VALIGN="bottom" |
56 | ></TD |
57 | ><TD |
58 | WIDTH="10%" |
59 | ALIGN="right" |
60 | VALIGN="bottom" |
61 | ><A |
62 | HREF="sdlsurface.html" |
63 | ACCESSKEY="N" |
64 | >Next</A |
65 | ></TD |
66 | ></TR |
67 | ></TABLE |
68 | ><HR |
69 | ALIGN="LEFT" |
70 | WIDTH="100%"></DIV |
71 | ><H1 |
72 | ><A |
73 | NAME="SDLPIXELFORMAT" |
74 | ></A |
75 | >SDL_PixelFormat</H1 |
76 | ><DIV |
77 | CLASS="REFNAMEDIV" |
78 | ><A |
79 | NAME="AEN3178" |
80 | ></A |
81 | ><H2 |
82 | >Name</H2 |
83 | >SDL_PixelFormat -- Stores surface format information</DIV |
84 | ><DIV |
85 | CLASS="REFSECT1" |
86 | ><A |
87 | NAME="AEN3181" |
88 | ></A |
89 | ><H2 |
90 | >Structure Definition</H2 |
91 | ><PRE |
92 | CLASS="PROGRAMLISTING" |
93 | >typedef struct SDL_PixelFormat { |
94 | SDL_Palette *palette; |
95 | Uint8 BitsPerPixel; |
96 | Uint8 BytesPerPixel; |
97 | Uint8 Rloss, Gloss, Bloss, Aloss; |
98 | Uint8 Rshift, Gshift, Bshift, Ashift; |
99 | Uint32 Rmask, Gmask, Bmask, Amask; |
100 | Uint32 colorkey; |
101 | Uint8 alpha; |
102 | } SDL_PixelFormat;</PRE |
103 | ></DIV |
104 | ><DIV |
105 | CLASS="REFSECT1" |
106 | ><A |
107 | NAME="AEN3184" |
108 | ></A |
109 | ><H2 |
110 | >Structure Data</H2 |
111 | ><DIV |
112 | CLASS="INFORMALTABLE" |
113 | ><A |
114 | NAME="AEN3186" |
115 | ></A |
116 | ><P |
117 | ></P |
118 | ><TABLE |
119 | BORDER="0" |
120 | CLASS="CALSTABLE" |
121 | ><TBODY |
122 | ><TR |
123 | ><TD |
124 | ALIGN="LEFT" |
125 | VALIGN="TOP" |
126 | ><TT |
127 | CLASS="STRUCTFIELD" |
128 | ><I |
129 | >palette</I |
130 | ></TT |
131 | ></TD |
132 | ><TD |
133 | ALIGN="LEFT" |
134 | VALIGN="TOP" |
135 | >Pointer to the <A |
136 | HREF="sdlpalette.html" |
137 | >palette</A |
138 | >, or <TT |
139 | CLASS="LITERAL" |
140 | >NULL</TT |
141 | > if the <TT |
142 | CLASS="STRUCTFIELD" |
143 | ><I |
144 | >BitsPerPixel</I |
145 | ></TT |
146 | >>8</TD |
147 | ></TR |
148 | ><TR |
149 | ><TD |
150 | ALIGN="LEFT" |
151 | VALIGN="TOP" |
152 | ><TT |
153 | CLASS="STRUCTFIELD" |
154 | ><I |
155 | >BitsPerPixel</I |
156 | ></TT |
157 | ></TD |
158 | ><TD |
159 | ALIGN="LEFT" |
160 | VALIGN="TOP" |
161 | >The number of bits used to represent each pixel in a surface. Usually 8, 16, 24 or 32.</TD |
162 | ></TR |
163 | ><TR |
164 | ><TD |
165 | ALIGN="LEFT" |
166 | VALIGN="TOP" |
167 | ><TT |
168 | CLASS="STRUCTFIELD" |
169 | ><I |
170 | >BytesPerPixel</I |
171 | ></TT |
172 | ></TD |
173 | ><TD |
174 | ALIGN="LEFT" |
175 | VALIGN="TOP" |
176 | >The number of bytes used to represent each pixel in a surface. Usually one to four.</TD |
177 | ></TR |
178 | ><TR |
179 | ><TD |
180 | ALIGN="LEFT" |
181 | VALIGN="TOP" |
182 | ><TT |
183 | CLASS="STRUCTFIELD" |
184 | ><I |
185 | >[RGBA]mask</I |
186 | ></TT |
187 | ></TD |
188 | ><TD |
189 | ALIGN="LEFT" |
190 | VALIGN="TOP" |
191 | >Binary mask used to retrieve individual color values</TD |
192 | ></TR |
193 | ><TR |
194 | ><TD |
195 | ALIGN="LEFT" |
196 | VALIGN="TOP" |
197 | ><TT |
198 | CLASS="STRUCTFIELD" |
199 | ><I |
200 | >[RGBA]loss</I |
201 | ></TT |
202 | ></TD |
203 | ><TD |
204 | ALIGN="LEFT" |
205 | VALIGN="TOP" |
206 | >Precision loss of each color component (2<SUP |
207 | >[RGBA]loss</SUP |
208 | >)</TD |
209 | ></TR |
210 | ><TR |
211 | ><TD |
212 | ALIGN="LEFT" |
213 | VALIGN="TOP" |
214 | ><TT |
215 | CLASS="STRUCTFIELD" |
216 | ><I |
217 | >[RGBA]shift</I |
218 | ></TT |
219 | ></TD |
220 | ><TD |
221 | ALIGN="LEFT" |
222 | VALIGN="TOP" |
223 | >Binary left shift of each color component in the pixel value</TD |
224 | ></TR |
225 | ><TR |
226 | ><TD |
227 | ALIGN="LEFT" |
228 | VALIGN="TOP" |
229 | ><TT |
230 | CLASS="STRUCTFIELD" |
231 | ><I |
232 | >colorkey</I |
233 | ></TT |
234 | ></TD |
235 | ><TD |
236 | ALIGN="LEFT" |
237 | VALIGN="TOP" |
238 | >Pixel value of transparent pixels</TD |
239 | ></TR |
240 | ><TR |
241 | ><TD |
242 | ALIGN="LEFT" |
243 | VALIGN="TOP" |
244 | ><TT |
245 | CLASS="STRUCTFIELD" |
246 | ><I |
247 | >alpha</I |
248 | ></TT |
249 | ></TD |
250 | ><TD |
251 | ALIGN="LEFT" |
252 | VALIGN="TOP" |
253 | >Overall surface alpha value</TD |
254 | ></TR |
255 | ></TBODY |
256 | ></TABLE |
257 | ><P |
258 | ></P |
259 | ></DIV |
260 | ></DIV |
261 | ><DIV |
262 | CLASS="REFSECT1" |
263 | ><A |
264 | NAME="AEN3225" |
265 | ></A |
266 | ><H2 |
267 | >Description</H2 |
268 | ><P |
269 | >A <SPAN |
270 | CLASS="STRUCTNAME" |
271 | >SDL_PixelFormat</SPAN |
272 | > describes the format of the pixel data stored at the <TT |
273 | CLASS="STRUCTFIELD" |
274 | ><I |
275 | >pixels</I |
276 | ></TT |
277 | > field of a <A |
278 | HREF="sdlsurface.html" |
279 | ><SPAN |
280 | CLASS="STRUCTNAME" |
281 | >SDL_Surface</SPAN |
282 | ></A |
283 | >. Every surface stores a <SPAN |
284 | CLASS="STRUCTNAME" |
285 | >SDL_PixelFormat</SPAN |
286 | > in the <TT |
287 | CLASS="STRUCTFIELD" |
288 | ><I |
289 | >format</I |
290 | ></TT |
291 | > field.</P |
292 | ><P |
293 | >If you wish to do pixel level modifications on a surface, then understanding how SDL stores its color information is essential.</P |
294 | ><P |
295 | >8-bit pixel formats are the easiest to understand. Since its an 8-bit format, we have 8 <TT |
296 | CLASS="STRUCTFIELD" |
297 | ><I |
298 | >BitsPerPixel</I |
299 | ></TT |
300 | > and 1 <TT |
301 | CLASS="STRUCTFIELD" |
302 | ><I |
303 | >BytesPerPixel</I |
304 | ></TT |
305 | >. Since <TT |
306 | CLASS="STRUCTFIELD" |
307 | ><I |
308 | >BytesPerPixel</I |
309 | ></TT |
310 | > is 1, all pixels are represented by a Uint8 which contains an index into <TT |
311 | CLASS="STRUCTFIELD" |
312 | ><I |
313 | >palette</I |
314 | ></TT |
315 | >-><TT |
316 | CLASS="STRUCTFIELD" |
317 | ><I |
318 | >colors</I |
319 | ></TT |
320 | >. So, to determine the color of a pixel in a 8-bit surface: we read the color index from <SPAN |
321 | CLASS="STRUCTNAME" |
322 | >surface</SPAN |
323 | >-><TT |
324 | CLASS="STRUCTFIELD" |
325 | ><I |
326 | >pixels</I |
327 | ></TT |
328 | > and we use that index to read the <A |
329 | HREF="sdlcolor.html" |
330 | ><SPAN |
331 | CLASS="STRUCTNAME" |
332 | >SDL_Color</SPAN |
333 | ></A |
334 | > structure from <SPAN |
335 | CLASS="STRUCTNAME" |
336 | >surface</SPAN |
337 | >-><TT |
338 | CLASS="STRUCTFIELD" |
339 | ><I |
340 | >format</I |
341 | ></TT |
342 | >-><TT |
343 | CLASS="STRUCTFIELD" |
344 | ><I |
345 | >palette</I |
346 | ></TT |
347 | >-><TT |
348 | CLASS="STRUCTFIELD" |
349 | ><I |
350 | >colors</I |
351 | ></TT |
352 | >. Like so: |
353 | <PRE |
354 | CLASS="PROGRAMLISTING" |
355 | >SDL_Surface *surface; |
356 | SDL_PixelFormat *fmt; |
357 | SDL_Color *color; |
358 | Uint8 index; |
359 | |
360 | . |
361 | . |
362 | |
363 | /* Create surface */ |
364 | . |
365 | . |
366 | fmt=surface->format; |
367 | |
368 | /* Check the bitdepth of the surface */ |
369 | if(fmt->BitsPerPixel!=8){ |
370 | fprintf(stderr, "Not an 8-bit surface.\n"); |
371 | return(-1); |
372 | } |
373 | |
374 | /* Lock the surface */ |
375 | SDL_LockSurface(surface); |
376 | |
377 | /* Get the topleft pixel */ |
378 | index=*(Uint8 *)surface->pixels; |
379 | color=fmt->palette->colors[index]; |
380 | |
381 | /* Unlock the surface */ |
382 | SDL_UnlockSurface(surface); |
383 | printf("Pixel Color-> Red: %d, Green: %d, Blue: %d. Index: %d\n", |
384 | color->r, color->g, color->b, index); |
385 | . |
386 | .</PRE |
387 | ></P |
388 | ><P |
389 | >Pixel formats above 8-bit are an entirely different experience. They are |
390 | considered to be "TrueColor" formats and the color information is stored in the |
391 | pixels themselves, not in a palette. The mask, shift and loss fields tell us |
392 | how the color information is encoded. The mask fields allow us to isolate each |
393 | color component, the shift fields tell us the number of bits to the right of |
394 | each component in the pixel value and the loss fields tell us the number of |
395 | bits lost from each component when packing 8-bit color component in a pixel. |
396 | <PRE |
397 | CLASS="PROGRAMLISTING" |
398 | >/* Extracting color components from a 32-bit color value */ |
399 | SDL_PixelFormat *fmt; |
400 | SDL_Surface *surface; |
401 | Uint32 temp, pixel; |
402 | Uint8 red, green, blue, alpha; |
403 | . |
404 | . |
405 | . |
406 | fmt=surface->format; |
407 | SDL_LockSurface(surface); |
408 | pixel=*((Uint32*)surface->pixels); |
409 | SDL_UnlockSurface(surface); |
410 | |
411 | /* Get Red component */ |
412 | temp=pixel&fmt->Rmask; /* Isolate red component */ |
413 | temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */ |
414 | temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */ |
415 | red=(Uint8)temp; |
416 | |
417 | /* Get Green component */ |
418 | temp=pixel&fmt->Gmask; /* Isolate green component */ |
419 | temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */ |
420 | temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */ |
421 | green=(Uint8)temp; |
422 | |
423 | /* Get Blue component */ |
424 | temp=pixel&fmt->Bmask; /* Isolate blue component */ |
425 | temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */ |
426 | temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */ |
427 | blue=(Uint8)temp; |
428 | |
429 | /* Get Alpha component */ |
430 | temp=pixel&fmt->Amask; /* Isolate alpha component */ |
431 | temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */ |
432 | temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */ |
433 | alpha=(Uint8)temp; |
434 | |
435 | printf("Pixel Color -> R: %d, G: %d, B: %d, A: %d\n", red, green, blue, alpha); |
436 | . |
437 | . |
438 | .</PRE |
439 | ></P |
440 | ></DIV |
441 | ><DIV |
442 | CLASS="REFSECT1" |
443 | ><A |
444 | NAME="AEN3252" |
445 | ></A |
446 | ><H2 |
447 | >See Also</H2 |
448 | ><P |
449 | ><A |
450 | HREF="sdlsurface.html" |
451 | ><SPAN |
452 | CLASS="STRUCTNAME" |
453 | >SDL_Surface</SPAN |
454 | ></A |
455 | >, |
456 | <A |
457 | HREF="sdlmaprgb.html" |
458 | ><TT |
459 | CLASS="FUNCTION" |
460 | >SDL_MapRGB</TT |
461 | ></A |
462 | ></P |
463 | ></DIV |
464 | ><DIV |
465 | CLASS="NAVFOOTER" |
466 | ><HR |
467 | ALIGN="LEFT" |
468 | WIDTH="100%"><TABLE |
469 | SUMMARY="Footer navigation table" |
470 | WIDTH="100%" |
471 | BORDER="0" |
472 | CELLPADDING="0" |
473 | CELLSPACING="0" |
474 | ><TR |
475 | ><TD |
476 | WIDTH="33%" |
477 | ALIGN="left" |
478 | VALIGN="top" |
479 | ><A |
480 | HREF="sdlpalette.html" |
481 | ACCESSKEY="P" |
482 | >Prev</A |
483 | ></TD |
484 | ><TD |
485 | WIDTH="34%" |
486 | ALIGN="center" |
487 | VALIGN="top" |
488 | ><A |
489 | HREF="index.html" |
490 | ACCESSKEY="H" |
491 | >Home</A |
492 | ></TD |
493 | ><TD |
494 | WIDTH="33%" |
495 | ALIGN="right" |
496 | VALIGN="top" |
497 | ><A |
498 | HREF="sdlsurface.html" |
499 | ACCESSKEY="N" |
500 | >Next</A |
501 | ></TD |
502 | ></TR |
503 | ><TR |
504 | ><TD |
505 | WIDTH="33%" |
506 | ALIGN="left" |
507 | VALIGN="top" |
508 | >SDL_Palette</TD |
509 | ><TD |
510 | WIDTH="34%" |
511 | ALIGN="center" |
512 | VALIGN="top" |
513 | ><A |
514 | HREF="video.html" |
515 | ACCESSKEY="U" |
516 | >Up</A |
517 | ></TD |
518 | ><TD |
519 | WIDTH="33%" |
520 | ALIGN="right" |
521 | VALIGN="top" |
522 | >SDL_Surface</TD |
523 | ></TR |
524 | ></TABLE |
525 | ></DIV |
526 | ></BODY |
527 | ></HTML |
528 | > |