Mercurial > sdl-ios-xcode
annotate docs/html/sdlpixelformat.html @ 4159:a1b03ba2fcd0 SDL-1.2
Updated copyright date
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Mon, 08 Dec 2008 00:25:42 +0000 |
parents | e867f327aa54 |
children |
rev | line source |
---|---|
0 | 1 <HTML |
2 ><HEAD | |
3 ><TITLE | |
4 >SDL_PixelFormat</TITLE | |
5 ><META | |
6 NAME="GENERATOR" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ |
0 | 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
31 SUMMARY="Header navigation table" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
49 ACCESSKEY="P" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
63 ACCESSKEY="N" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
74 ></A |
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
75 >SDL_PixelFormat</H1 |
0 | 76 ><DIV |
77 CLASS="REFNAMEDIV" | |
78 ><A | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
79 NAME="AEN3178" |
0 | 80 ></A |
81 ><H2 | |
82 >Name</H2 | |
83 >SDL_PixelFormat -- Stores surface format information</DIV | |
84 ><DIV | |
85 CLASS="REFSECT1" | |
86 ><A | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
87 NAME="AEN3181" |
0 | 88 ></A |
89 ><H2 | |
90 >Structure Definition</H2 | |
91 ><PRE | |
92 CLASS="PROGRAMLISTING" | |
1279
e867f327aa54
*** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents:
803
diff
changeset
|
93 >typedef struct SDL_PixelFormat { |
0 | 94 SDL_Palette *palette; |
95 Uint8 BitsPerPixel; | |
96 Uint8 BytesPerPixel; | |
1279
e867f327aa54
*** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents:
803
diff
changeset
|
97 Uint8 Rloss, Gloss, Bloss, Aloss; |
0 | 98 Uint8 Rshift, Gshift, Bshift, Ashift; |
1279
e867f327aa54
*** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents:
803
diff
changeset
|
99 Uint32 Rmask, Gmask, Bmask, Amask; |
0 | 100 Uint32 colorkey; |
101 Uint8 alpha; | |
102 } SDL_PixelFormat;</PRE | |
103 ></DIV | |
104 ><DIV | |
105 CLASS="REFSECT1" | |
106 ><A | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
107 NAME="AEN3184" |
0 | 108 ></A |
109 ><H2 | |
110 >Structure Data</H2 | |
111 ><DIV | |
112 CLASS="INFORMALTABLE" | |
113 ><A | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
114 NAME="AEN3186" |
0 | 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
264 NAME="AEN3225" |
0 | 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 | |
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
389 >Pixel formats above 8-bit are an entirely different experience. They are |
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
390 considered to be "TrueColor" formats and the color information is stored in the |
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
391 pixels themselves, not in a palette. The mask, shift and loss fields tell us |
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
392 how the color information is encoded. The mask fields allow us to isolate each |
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
393 color component, the shift fields tell us the number of bits to the right of |
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
394 each component in the pixel value and the loss fields tell us the number of |
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
395 bits lost from each component when packing 8-bit color component in a pixel. |
0 | 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); | |
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
408 pixel=*((Uint32*)surface->pixels); |
0 | 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
444 NAME="AEN3252" |
0 | 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 | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
469 SUMMARY="Footer navigation table" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
481 ACCESSKEY="P" |
0 | 482 >Prev</A |
483 ></TD | |
484 ><TD | |
485 WIDTH="34%" | |
486 ALIGN="center" | |
487 VALIGN="top" | |
488 ><A | |
489 HREF="index.html" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
490 ACCESSKEY="H" |
0 | 491 >Home</A |
492 ></TD | |
493 ><TD | |
494 WIDTH="33%" | |
495 ALIGN="right" | |
496 VALIGN="top" | |
497 ><A | |
498 HREF="sdlsurface.html" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
499 ACCESSKEY="N" |
0 | 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" | |
803
355632dca928
Updated SDL HTML documentation
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
515 ACCESSKEY="U" |
0 | 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 | |
1279
e867f327aa54
*** empty log message ***
Sam Lantinga <slouken@libsdl.org>
parents:
803
diff
changeset
|
528 > |