Mercurial > sdl-ios-xcode
annotate docs/html/sdlpixelformat.html @ 1125:a6011e1394d9
Apparently MacOS X will sometimes pass command line arguments to a Cocoa
app as an openFile() message, so we have to make sure we were launched from
the Finder before accepting these as drag'n'drop documents, or they will just
duplicate what's already in argc/argv.
| author | Ryan C. Gordon <icculus@icculus.org> |
|---|---|
| date | Mon, 22 Aug 2005 14:18:15 +0000 |
| parents | 355632dca928 |
| 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 > |