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