Mercurial > sdl-ios-xcode
annotate docs/html/sdlpixelformat.html @ 55:55f1f1b3e27d
Added new docs for SDL 1.2.1
| author | Sam Lantinga <slouken@lokigames.com> |
|---|---|
| date | Sun, 10 Jun 2001 19:31:57 +0000 |
| parents | 74212992fb08 |
| children | e5bc29de3f0a |
| rev | line source |
|---|---|
| 0 | 1 <HTML |
| 2 ><HEAD | |
| 3 ><TITLE | |
| 4 >SDL_PixelFormat</TITLE | |
| 5 ><META | |
| 6 NAME="GENERATOR" | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64 |
| 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 | |
| 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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
76 NAME="AEN2756" |
| 0 | 77 ></A |
| 78 ><H2 | |
| 79 >Name</H2 | |
| 80 >SDL_PixelFormat -- Stores surface format information</DIV | |
| 81 ><DIV | |
| 82 CLASS="REFSECT1" | |
| 83 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
84 NAME="AEN2759" |
| 0 | 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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
104 NAME="AEN2762" |
| 0 | 105 ></A |
| 106 ><H2 | |
| 107 >Structure Data</H2 | |
| 108 ><DIV | |
| 109 CLASS="INFORMALTABLE" | |
| 110 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
111 NAME="AEN2764" |
| 0 | 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 >>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 | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
261 NAME="AEN2803" |
| 0 | 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 >-><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 >-><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 >-><TT | |
| 335 CLASS="STRUCTFIELD" | |
| 336 ><I | |
| 337 >format</I | |
| 338 ></TT | |
| 339 >-><TT | |
| 340 CLASS="STRUCTFIELD" | |
| 341 ><I | |
| 342 >palette</I | |
| 343 ></TT | |
| 344 >-><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->format; | |
| 364 | |
| 365 /* Check the bitdepth of the surface */ | |
| 366 if(fmt->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->pixels; | |
| 376 color=fmt->palette->colors[index]; | |
| 377 | |
| 378 /* Unlock the surface */ | |
| 379 SDL_UnlockSurface(surface); | |
| 380 printf("Pixel Color-> Red: %d, Green: %d, Blue: %d. Index: %d\n", | |
| 381 color->r, color->g, color->b, index); | |
| 382 . | |
| 383 .</PRE | |
| 384 ></P | |
| 385 ><P | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
386 >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
|
387 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
|
388 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
|
389 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
|
390 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
|
391 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
|
392 bits lost from each component when packing 8-bit color component in a pixel. |
| 0 | 393 <PRE |
| 394 CLASS="PROGRAMLISTING" | |
| 395 >/* Extracting color components from a 32-bit color value */ | |
| 396 SDL_PixelFormat *fmt; | |
| 397 SDL_Surface *surface; | |
| 398 Uint32 temp, pixel; | |
| 399 Uint8 red, green, blue, alpha; | |
| 400 . | |
| 401 . | |
| 402 . | |
| 403 fmt=surface->format; | |
| 404 SDL_LockSurface(surface); | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
405 pixel=*((Uint32*)surface->pixels); |
| 0 | 406 SDL_UnlockSurface(surface); |
| 407 | |
| 408 /* Get Red component */ | |
| 409 temp=pixel&fmt->Rmask; /* Isolate red component */ | |
| 410 temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */ | |
| 411 temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */ | |
| 412 red=(Uint8)temp; | |
| 413 | |
| 414 /* Get Green component */ | |
| 415 temp=pixel&fmt->Gmask; /* Isolate green component */ | |
| 416 temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */ | |
| 417 temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */ | |
| 418 green=(Uint8)temp; | |
| 419 | |
| 420 /* Get Blue component */ | |
| 421 temp=pixel&fmt->Bmask; /* Isolate blue component */ | |
| 422 temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */ | |
| 423 temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */ | |
| 424 blue=(Uint8)temp; | |
| 425 | |
| 426 /* Get Alpha component */ | |
| 427 temp=pixel&fmt->Amask; /* Isolate alpha component */ | |
| 428 temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */ | |
| 429 temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */ | |
| 430 alpha=(Uint8)temp; | |
| 431 | |
| 432 printf("Pixel Color -> R: %d, G: %d, B: %d, A: %d\n", red, green, blue, alpha); | |
| 433 . | |
| 434 . | |
| 435 .</PRE | |
| 436 ></P | |
| 437 ></DIV | |
| 438 ><DIV | |
| 439 CLASS="REFSECT1" | |
| 440 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
441 NAME="AEN2830" |
| 0 | 442 ></A |
| 443 ><H2 | |
| 444 >See Also</H2 | |
| 445 ><P | |
| 446 ><A | |
| 447 HREF="sdlsurface.html" | |
| 448 ><SPAN | |
| 449 CLASS="STRUCTNAME" | |
| 450 >SDL_Surface</SPAN | |
| 451 ></A | |
| 452 >, | |
| 453 <A | |
| 454 HREF="sdlmaprgb.html" | |
| 455 ><TT | |
| 456 CLASS="FUNCTION" | |
| 457 >SDL_MapRGB</TT | |
| 458 ></A | |
| 459 ></P | |
| 460 ></DIV | |
| 461 ><DIV | |
| 462 CLASS="NAVFOOTER" | |
| 463 ><HR | |
| 464 ALIGN="LEFT" | |
| 465 WIDTH="100%"><TABLE | |
| 466 WIDTH="100%" | |
| 467 BORDER="0" | |
| 468 CELLPADDING="0" | |
| 469 CELLSPACING="0" | |
| 470 ><TR | |
| 471 ><TD | |
| 472 WIDTH="33%" | |
| 473 ALIGN="left" | |
| 474 VALIGN="top" | |
| 475 ><A | |
| 476 HREF="sdlpalette.html" | |
| 477 >Prev</A | |
| 478 ></TD | |
| 479 ><TD | |
| 480 WIDTH="34%" | |
| 481 ALIGN="center" | |
| 482 VALIGN="top" | |
| 483 ><A | |
| 484 HREF="index.html" | |
| 485 >Home</A | |
| 486 ></TD | |
| 487 ><TD | |
| 488 WIDTH="33%" | |
| 489 ALIGN="right" | |
| 490 VALIGN="top" | |
| 491 ><A | |
| 492 HREF="sdlsurface.html" | |
| 493 >Next</A | |
| 494 ></TD | |
| 495 ></TR | |
| 496 ><TR | |
| 497 ><TD | |
| 498 WIDTH="33%" | |
| 499 ALIGN="left" | |
| 500 VALIGN="top" | |
| 501 >SDL_Palette</TD | |
| 502 ><TD | |
| 503 WIDTH="34%" | |
| 504 ALIGN="center" | |
| 505 VALIGN="top" | |
| 506 ><A | |
| 507 HREF="video.html" | |
| 508 >Up</A | |
| 509 ></TD | |
| 510 ><TD | |
| 511 WIDTH="33%" | |
| 512 ALIGN="right" | |
| 513 VALIGN="top" | |
| 514 >SDL_Surface</TD | |
| 515 ></TR | |
| 516 ></TABLE | |
| 517 ></DIV | |
| 518 ></BODY | |
| 519 ></HTML | |
| 520 > |