1<HTML 2><HEAD 3><TITLE 4>SDL_PixelFormat</TITLE 5><META 6NAME="GENERATOR" 7CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ 8"><LINK 9REL="HOME" 10TITLE="SDL Library Documentation" 11HREF="index.html"><LINK 12REL="UP" 13TITLE="Video" 14HREF="video.html"><LINK 15REL="PREVIOUS" 16TITLE="SDL_Palette" 17HREF="sdlpalette.html"><LINK 18REL="NEXT" 19TITLE="SDL_Surface" 20HREF="sdlsurface.html"></HEAD 21><BODY 22CLASS="REFENTRY" 23BGCOLOR="#FFF8DC" 24TEXT="#000000" 25LINK="#0000ee" 26VLINK="#551a8b" 27ALINK="#ff0000" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>SDL Library Documentation</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="sdlpalette.html" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56></TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="sdlsurface.html" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><H1 72><A 73NAME="SDLPIXELFORMAT" 74></A 75>SDL_PixelFormat</H1 76><DIV 77CLASS="REFNAMEDIV" 78><A 79NAME="AEN3178" 80></A 81><H2 82>Name</H2 83>SDL_PixelFormat -- Stores surface format information</DIV 84><DIV 85CLASS="REFSECT1" 86><A 87NAME="AEN3181" 88></A 89><H2 90>Structure Definition</H2 91><PRE 92CLASS="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 105CLASS="REFSECT1" 106><A 107NAME="AEN3184" 108></A 109><H2 110>Structure Data</H2 111><DIV 112CLASS="INFORMALTABLE" 113><A 114NAME="AEN3186" 115></A 116><P 117></P 118><TABLE 119BORDER="0" 120CLASS="CALSTABLE" 121><TBODY 122><TR 123><TD 124ALIGN="LEFT" 125VALIGN="TOP" 126><TT 127CLASS="STRUCTFIELD" 128><I 129>palette</I 130></TT 131></TD 132><TD 133ALIGN="LEFT" 134VALIGN="TOP" 135>Pointer to the <A 136HREF="sdlpalette.html" 137>palette</A 138>, or <TT 139CLASS="LITERAL" 140>NULL</TT 141> if the <TT 142CLASS="STRUCTFIELD" 143><I 144>BitsPerPixel</I 145></TT 146>>8</TD 147></TR 148><TR 149><TD 150ALIGN="LEFT" 151VALIGN="TOP" 152><TT 153CLASS="STRUCTFIELD" 154><I 155>BitsPerPixel</I 156></TT 157></TD 158><TD 159ALIGN="LEFT" 160VALIGN="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 165ALIGN="LEFT" 166VALIGN="TOP" 167><TT 168CLASS="STRUCTFIELD" 169><I 170>BytesPerPixel</I 171></TT 172></TD 173><TD 174ALIGN="LEFT" 175VALIGN="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 180ALIGN="LEFT" 181VALIGN="TOP" 182><TT 183CLASS="STRUCTFIELD" 184><I 185>[RGBA]mask</I 186></TT 187></TD 188><TD 189ALIGN="LEFT" 190VALIGN="TOP" 191>Binary mask used to retrieve individual color values</TD 192></TR 193><TR 194><TD 195ALIGN="LEFT" 196VALIGN="TOP" 197><TT 198CLASS="STRUCTFIELD" 199><I 200>[RGBA]loss</I 201></TT 202></TD 203><TD 204ALIGN="LEFT" 205VALIGN="TOP" 206>Precision loss of each color component (2<SUP 207>[RGBA]loss</SUP 208>)</TD 209></TR 210><TR 211><TD 212ALIGN="LEFT" 213VALIGN="TOP" 214><TT 215CLASS="STRUCTFIELD" 216><I 217>[RGBA]shift</I 218></TT 219></TD 220><TD 221ALIGN="LEFT" 222VALIGN="TOP" 223>Binary left shift of each color component in the pixel value</TD 224></TR 225><TR 226><TD 227ALIGN="LEFT" 228VALIGN="TOP" 229><TT 230CLASS="STRUCTFIELD" 231><I 232>colorkey</I 233></TT 234></TD 235><TD 236ALIGN="LEFT" 237VALIGN="TOP" 238>Pixel value of transparent pixels</TD 239></TR 240><TR 241><TD 242ALIGN="LEFT" 243VALIGN="TOP" 244><TT 245CLASS="STRUCTFIELD" 246><I 247>alpha</I 248></TT 249></TD 250><TD 251ALIGN="LEFT" 252VALIGN="TOP" 253>Overall surface alpha value</TD 254></TR 255></TBODY 256></TABLE 257><P 258></P 259></DIV 260></DIV 261><DIV 262CLASS="REFSECT1" 263><A 264NAME="AEN3225" 265></A 266><H2 267>Description</H2 268><P 269>A <SPAN 270CLASS="STRUCTNAME" 271>SDL_PixelFormat</SPAN 272> describes the format of the pixel data stored at the <TT 273CLASS="STRUCTFIELD" 274><I 275>pixels</I 276></TT 277> field of a <A 278HREF="sdlsurface.html" 279><SPAN 280CLASS="STRUCTNAME" 281>SDL_Surface</SPAN 282></A 283>. Every surface stores a <SPAN 284CLASS="STRUCTNAME" 285>SDL_PixelFormat</SPAN 286> in the <TT 287CLASS="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 296CLASS="STRUCTFIELD" 297><I 298>BitsPerPixel</I 299></TT 300> and 1 <TT 301CLASS="STRUCTFIELD" 302><I 303>BytesPerPixel</I 304></TT 305>. Since <TT 306CLASS="STRUCTFIELD" 307><I 308>BytesPerPixel</I 309></TT 310> is 1, all pixels are represented by a Uint8 which contains an index into <TT 311CLASS="STRUCTFIELD" 312><I 313>palette</I 314></TT 315>-><TT 316CLASS="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 321CLASS="STRUCTNAME" 322>surface</SPAN 323>-><TT 324CLASS="STRUCTFIELD" 325><I 326>pixels</I 327></TT 328> and we use that index to read the <A 329HREF="sdlcolor.html" 330><SPAN 331CLASS="STRUCTNAME" 332>SDL_Color</SPAN 333></A 334> structure from <SPAN 335CLASS="STRUCTNAME" 336>surface</SPAN 337>-><TT 338CLASS="STRUCTFIELD" 339><I 340>format</I 341></TT 342>-><TT 343CLASS="STRUCTFIELD" 344><I 345>palette</I 346></TT 347>-><TT 348CLASS="STRUCTFIELD" 349><I 350>colors</I 351></TT 352>. Like so: 353<PRE 354CLASS="PROGRAMLISTING" 355>SDL_Surface *surface; 356SDL_PixelFormat *fmt; 357SDL_Color *color; 358Uint8 index; 359 360. 361. 362 363/* Create surface */ 364. 365. 366fmt=surface->format; 367 368/* Check the bitdepth of the surface */ 369if(fmt->BitsPerPixel!=8){ 370 fprintf(stderr, "Not an 8-bit surface.\n"); 371 return(-1); 372} 373 374/* Lock the surface */ 375SDL_LockSurface(surface); 376 377/* Get the topleft pixel */ 378index=*(Uint8 *)surface->pixels; 379color=fmt->palette->colors[index]; 380 381/* Unlock the surface */ 382SDL_UnlockSurface(surface); 383printf("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 390considered to be "TrueColor" formats and the color information is stored in the 391pixels themselves, not in a palette. The mask, shift and loss fields tell us 392how the color information is encoded. The mask fields allow us to isolate each 393color component, the shift fields tell us the number of bits to the right of 394each component in the pixel value and the loss fields tell us the number of 395bits lost from each component when packing 8-bit color component in a pixel. 396<PRE 397CLASS="PROGRAMLISTING" 398>/* Extracting color components from a 32-bit color value */ 399SDL_PixelFormat *fmt; 400SDL_Surface *surface; 401Uint32 temp, pixel; 402Uint8 red, green, blue, alpha; 403. 404. 405. 406fmt=surface->format; 407SDL_LockSurface(surface); 408pixel=*((Uint32*)surface->pixels); 409SDL_UnlockSurface(surface); 410 411/* Get Red component */ 412temp=pixel&fmt->Rmask; /* Isolate red component */ 413temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */ 414temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */ 415red=(Uint8)temp; 416 417/* Get Green component */ 418temp=pixel&fmt->Gmask; /* Isolate green component */ 419temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */ 420temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */ 421green=(Uint8)temp; 422 423/* Get Blue component */ 424temp=pixel&fmt->Bmask; /* Isolate blue component */ 425temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */ 426temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */ 427blue=(Uint8)temp; 428 429/* Get Alpha component */ 430temp=pixel&fmt->Amask; /* Isolate alpha component */ 431temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */ 432temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */ 433alpha=(Uint8)temp; 434 435printf("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 442CLASS="REFSECT1" 443><A 444NAME="AEN3252" 445></A 446><H2 447>See Also</H2 448><P 449><A 450HREF="sdlsurface.html" 451><SPAN 452CLASS="STRUCTNAME" 453>SDL_Surface</SPAN 454></A 455>, 456<A 457HREF="sdlmaprgb.html" 458><TT 459CLASS="FUNCTION" 460>SDL_MapRGB</TT 461></A 462></P 463></DIV 464><DIV 465CLASS="NAVFOOTER" 466><HR 467ALIGN="LEFT" 468WIDTH="100%"><TABLE 469SUMMARY="Footer navigation table" 470WIDTH="100%" 471BORDER="0" 472CELLPADDING="0" 473CELLSPACING="0" 474><TR 475><TD 476WIDTH="33%" 477ALIGN="left" 478VALIGN="top" 479><A 480HREF="sdlpalette.html" 481ACCESSKEY="P" 482>Prev</A 483></TD 484><TD 485WIDTH="34%" 486ALIGN="center" 487VALIGN="top" 488><A 489HREF="index.html" 490ACCESSKEY="H" 491>Home</A 492></TD 493><TD 494WIDTH="33%" 495ALIGN="right" 496VALIGN="top" 497><A 498HREF="sdlsurface.html" 499ACCESSKEY="N" 500>Next</A 501></TD 502></TR 503><TR 504><TD 505WIDTH="33%" 506ALIGN="left" 507VALIGN="top" 508>SDL_Palette</TD 509><TD 510WIDTH="34%" 511ALIGN="center" 512VALIGN="top" 513><A 514HREF="video.html" 515ACCESSKEY="U" 516>Up</A 517></TD 518><TD 519WIDTH="33%" 520ALIGN="right" 521VALIGN="top" 522>SDL_Surface</TD 523></TR 524></TABLE 525></DIV 526></BODY 527></HTML 528> 529