Mercurial > sdl-ios-xcode

comparison docs/html/sdlpixelformat.html @ 0:74212992fb08

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