Mercurial > sdl-ios-xcode
annotate docs/html/sdlpixelformat.html @ 803:355632dca928
Updated SDL HTML documentation
| author | Sam Lantinga <slouken@libsdl.org> |
|---|---|
| date | Tue, 10 Feb 2004 15:15:40 +0000 |
| parents | e5bc29de3f0a |
| children | e867f327aa54 |
| 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" | |
| 93 >typedef struct{ | |
| 94 SDL_Palette *palette; | |
| 95 Uint8 BitsPerPixel; | |
| 96 Uint8 BytesPerPixel; | |
| 97 Uint32 Rmask, Gmask, Bmask, Amask; | |
| 98 Uint8 Rshift, Gshift, Bshift, Ashift; | |
| 99 Uint8 Rloss, Gloss, Bloss, Aloss; | |
| 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 | |
| 528 > |