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 -- 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 >>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 >-><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 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->format; 407 SDL_LockSurface(surface); 408 pixel=*((Uint32*)surface->pixels); 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 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 > 529
