docs/html/sdlpixelformat.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >SDL_PixelFormat</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
   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 SUMMARY="Header navigation table"
  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"
  49 ACCESSKEY="P"
  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"
  63 ACCESSKEY="N"
  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"
  74 ></A
  75 >SDL_PixelFormat</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN3178"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >SDL_PixelFormat&nbsp;--&nbsp;Stores surface format information</DIV
  84 ><DIV
  85 CLASS="REFSECT1"
  86 ><A
  87 NAME="AEN3181"
  88 ></A
  89 ><H2
  90 >Structure Definition</H2
  91 ><PRE
  92 CLASS="PROGRAMLISTING"
  93 >typedef struct SDL_PixelFormat {
  94   SDL_Palette *palette;
  95   Uint8  BitsPerPixel;
  96   Uint8  BytesPerPixel;
  97   Uint8  Rloss, Gloss, Bloss, Aloss;
  98   Uint8  Rshift, Gshift, Bshift, Ashift;
  99   Uint32 Rmask, Gmask, Bmask, Amask;
 100   Uint32 colorkey;
 101   Uint8  alpha;
 102 } SDL_PixelFormat;</PRE
 103 ></DIV
 104 ><DIV
 105 CLASS="REFSECT1"
 106 ><A
 107 NAME="AEN3184"
 108 ></A
 109 ><H2
 110 >Structure Data</H2
 111 ><DIV
 112 CLASS="INFORMALTABLE"
 113 ><A
 114 NAME="AEN3186"
 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 >&#62;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
 264 NAME="AEN3225"
 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 >-&#62;<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 >-&#62;<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 >-&#62;<TT
 338 CLASS="STRUCTFIELD"
 339 ><I
 340 >format</I
 341 ></TT
 342 >-&#62;<TT
 343 CLASS="STRUCTFIELD"
 344 ><I
 345 >palette</I
 346 ></TT
 347 >-&#62;<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-&#62;format;
 367
 368 /* Check the bitdepth of the surface */
 369 if(fmt-&#62;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-&#62;pixels;
 379 color=fmt-&#62;palette-&#62;colors[index];
 380
 381 /* Unlock the surface */
 382 SDL_UnlockSurface(surface);
 383 printf("Pixel Color-&#62; Red: %d, Green: %d, Blue: %d. Index: %d\n",
 384           color-&#62;r, color-&#62;g, color-&#62;b, index);
 385 .
 386 .</PRE
 387 ></P
 388 ><P
 389 >Pixel formats above 8-bit are an entirely different experience. They are
 390 considered to be "TrueColor" formats and the color information is stored in the
 391 pixels themselves, not in a palette. The mask, shift and loss fields tell us
 392 how the color information is encoded. The mask fields allow us to isolate each
 393 color component, the shift fields tell us the number of bits to the right of
 394 each component in the pixel value and the loss fields tell us the number of
 395 bits lost from each component when packing 8-bit color component in a pixel.
 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-&#62;format;
 407 SDL_LockSurface(surface);
 408 pixel=*((Uint32*)surface-&#62;pixels);
 409 SDL_UnlockSurface(surface);
 410
 411 /* Get Red component */
 412 temp=pixel&#38;fmt-&#62;Rmask; /* Isolate red component */
 413 temp=temp&#62;&#62;fmt-&#62;Rshift;/* Shift it down to 8-bit */
 414 temp=temp&#60;&#60;fmt-&#62;Rloss; /* Expand to a full 8-bit number */
 415 red=(Uint8)temp;
 416
 417 /* Get Green component */
 418 temp=pixel&#38;fmt-&#62;Gmask; /* Isolate green component */
 419 temp=temp&#62;&#62;fmt-&#62;Gshift;/* Shift it down to 8-bit */
 420 temp=temp&#60;&#60;fmt-&#62;Gloss; /* Expand to a full 8-bit number */
 421 green=(Uint8)temp;
 422
 423 /* Get Blue component */
 424 temp=pixel&#38;fmt-&#62;Bmask; /* Isolate blue component */
 425 temp=temp&#62;&#62;fmt-&#62;Bshift;/* Shift it down to 8-bit */
 426 temp=temp&#60;&#60;fmt-&#62;Bloss; /* Expand to a full 8-bit number */
 427 blue=(Uint8)temp;
 428
 429 /* Get Alpha component */
 430 temp=pixel&#38;fmt-&#62;Amask; /* Isolate alpha component */
 431 temp=temp&#62;&#62;fmt-&#62;Ashift;/* Shift it down to 8-bit */
 432 temp=temp&#60;&#60;fmt-&#62;Aloss; /* Expand to a full 8-bit number */
 433 alpha=(Uint8)temp;
 434
 435 printf("Pixel Color -&#62; 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
 444 NAME="AEN3252"
 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
 469 SUMMARY="Footer navigation table"
 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"
 481 ACCESSKEY="P"
 482 >Prev</A
 483 ></TD
 484 ><TD
 485 WIDTH="34%"
 486 ALIGN="center"
 487 VALIGN="top"
 488 ><A
 489 HREF="index.html"
 490 ACCESSKEY="H"
 491 >Home</A
 492 ></TD
 493 ><TD
 494 WIDTH="33%"
 495 ALIGN="right"
 496 VALIGN="top"
 497 ><A
 498 HREF="sdlsurface.html"
 499 ACCESSKEY="N"
 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"
 515 ACCESSKEY="U"
 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 >