docs/html/sdlsetpalette.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >SDL_SetPalette</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_SetColors"
  17 HREF="sdlsetcolors.html"><LINK
  18 REL="NEXT"
  19 TITLE="SDL_SetGamma"
  20 HREF="sdlsetgamma.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="sdlsetcolors.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="sdlsetgamma.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="SDLSETPALETTE"
  74 ></A
  75 >SDL_SetPalette</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN1517"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >SDL_SetPalette&nbsp;--&nbsp;Sets the colors in the palette of an 8-bit surface.</DIV
  84 ><DIV
  85 CLASS="REFSYNOPSISDIV"
  86 ><A
  87 NAME="AEN1520"
  88 ></A
  89 ><H2
  90 >Synopsis</H2
  91 ><DIV
  92 CLASS="FUNCSYNOPSIS"
  93 ><A
  94 NAME="AEN1521"
  95 ></A
  96 ><P
  97 ></P
  98 ><PRE
  99 CLASS="FUNCSYNOPSISINFO"
 100 >#include "SDL.h"</PRE
 101 ><P
 102 ><CODE
 103 ><CODE
 104 CLASS="FUNCDEF"
 105 >int <B
 106 CLASS="FSFUNC"
 107 >SDL_SetPalette</B
 108 ></CODE
 109 >(SDL_Surface *surface, int flags, SDL_Color *colors, int firstcolor, int ncolors);</CODE
 110 ></P
 111 ><P
 112 ></P
 113 ></DIV
 114 ></DIV
 115 ><DIV
 116 CLASS="REFSECT1"
 117 ><A
 118 NAME="AEN1527"
 119 ></A
 120 ><H2
 121 >Description</H2
 122 ><P
 123 >Sets a portion of the palette for the given 8-bit surface.</P
 124 ><P
 125 >Palettized (8-bit) screen surfaces with the
 126 <TT
 127 CLASS="LITERAL"
 128 >SDL_HWPALETTE</TT
 129 > flag have two palettes, a logical
 130 palette that is used for mapping blits to/from the surface and a
 131 physical palette (that determines how the hardware will map the colors
 132 to the display). <A
 133 HREF="sdlblitsurface.html"
 134 >SDL_BlitSurface</A
 135 >
 136 always uses the logical palette when blitting surfaces (if it has to
 137 convert between surface pixel formats). Because of this, it is often
 138 useful to modify only one or the other palette to achieve various
 139 special color effects (e.g., screen fading, color flashes, screen dimming).</P
 140 ><P
 141 >This function can modify either the logical or physical palette by
 142 specifing <TT
 143 CLASS="LITERAL"
 144 >SDL_LOGPAL</TT
 145 > or
 146 <TT
 147 CLASS="LITERAL"
 148 >SDL_PHYSPAL</TT
 149 >the in the <TT
 150 CLASS="PARAMETER"
 151 ><I
 152 >flags</I
 153 ></TT
 154 >
 155 parameter.</P
 156 ><P
 157 >When <TT
 158 CLASS="PARAMETER"
 159 ><I
 160 >surface</I
 161 ></TT
 162 > is the surface associated with the current
 163 display, the display colormap will be updated with the requested colors.  If
 164 <TT
 165 CLASS="LITERAL"
 166 >SDL_HWPALETTE</TT
 167 > was set in <A
 168 HREF="sdlsetvideomode.html"
 169 >SDL_SetVideoMode</A
 170 > flags,
 171 <TT
 172 CLASS="FUNCTION"
 173 >SDL_SetPalette</TT
 174 > will always return <SPAN
 175 CLASS="RETURNVALUE"
 176 >1</SPAN
 177 >,
 178 and the palette is guaranteed to be set the way you desire, even if the window
 179 colormap has to be warped or run under emulation.</P
 180 ><P
 181 >The color components of a
 182 <A
 183 HREF="sdlcolor.html"
 184 ><SPAN
 185 CLASS="STRUCTNAME"
 186 >SDL_Color</SPAN
 187 ></A
 188 > structure
 189 are 8-bits in size, giving you a total of
 190 256<SUP
 191 >3</SUP
 192 >=16777216 colors.</P
 193 ></DIV
 194 ><DIV
 195 CLASS="REFSECT1"
 196 ><A
 197 NAME="AEN1547"
 198 ></A
 199 ><H2
 200 >Return Value</H2
 201 ><P
 202 >If <TT
 203 CLASS="PARAMETER"
 204 ><I
 205 >surface</I
 206 ></TT
 207 > is not a palettized surface, this function
 208 does nothing, returning <SPAN
 209 CLASS="RETURNVALUE"
 210 >0</SPAN
 211 >.  If all of the colors were set
 212 as passed to <TT
 213 CLASS="FUNCTION"
 214 >SDL_SetPalette</TT
 215 >, it will return
 216 <SPAN
 217 CLASS="RETURNVALUE"
 218 >1</SPAN
 219 >.  If not all the color entries were set exactly as
 220 given, it will return <SPAN
 221 CLASS="RETURNVALUE"
 222 >0</SPAN
 223 >, and you should look at the
 224 surface palette to determine the actual color palette.</P
 225 ></DIV
 226 ><DIV
 227 CLASS="REFSECT1"
 228 ><A
 229 NAME="AEN1555"
 230 ></A
 231 ><H2
 232 >Example</H2
 233 ><PRE
 234 CLASS="PROGRAMLISTING"
 235 >        /* Create a display surface with a grayscale palette */
 236         SDL_Surface *screen;
 237         SDL_Color colors[256];
 238         int i;
 239         .
 240         .
 241         .
 242         /* Fill colors with color information */
 243         for(i=0;i&#60;256;i++){
 244           colors[i].r=i;
 245           colors[i].g=i;
 246           colors[i].b=i;
 247         }
 248
 249         /* Create display */
 250         screen=SDL_SetVideoMode(640, 480, 8, SDL_HWPALETTE);
 251         if(!screen){
 252           printf("Couldn't set video mode: %s\n", SDL_GetError());
 253           exit(-1);
 254         }
 255
 256         /* Set palette */
 257         SDL_SetPalette(screen, SDL_LOGPAL|SDL_PHYSPAL, colors, 0, 256);
 258         .
 259         .
 260         .
 261         .</PRE
 262 ></DIV
 263 ><DIV
 264 CLASS="REFSECT1"
 265 ><A
 266 NAME="AEN1558"
 267 ></A
 268 ><H2
 269 >See Also</H2
 270 ><P
 271 ><A
 272 HREF="sdlsetcolors.html"
 273 >SDL_SetColors</A
 274 >,
 275 <A
 276 HREF="sdlsetvideomode.html"
 277 >SDL_SetVideoMode</A
 278 >,
 279 <A
 280 HREF="sdlsurface.html"
 281 >SDL_Surface</A
 282 >,
 283 <A
 284 HREF="sdlcolor.html"
 285 >SDL_Color</A
 286 ></P
 287 ></DIV
 288 ><DIV
 289 CLASS="NAVFOOTER"
 290 ><HR
 291 ALIGN="LEFT"
 292 WIDTH="100%"><TABLE
 293 SUMMARY="Footer navigation table"
 294 WIDTH="100%"
 295 BORDER="0"
 296 CELLPADDING="0"
 297 CELLSPACING="0"
 298 ><TR
 299 ><TD
 300 WIDTH="33%"
 301 ALIGN="left"
 302 VALIGN="top"
 303 ><A
 304 HREF="sdlsetcolors.html"
 305 ACCESSKEY="P"
 306 >Prev</A
 307 ></TD
 308 ><TD
 309 WIDTH="34%"
 310 ALIGN="center"
 311 VALIGN="top"
 312 ><A
 313 HREF="index.html"
 314 ACCESSKEY="H"
 315 >Home</A
 316 ></TD
 317 ><TD
 318 WIDTH="33%"
 319 ALIGN="right"
 320 VALIGN="top"
 321 ><A
 322 HREF="sdlsetgamma.html"
 323 ACCESSKEY="N"
 324 >Next</A
 325 ></TD
 326 ></TR
 327 ><TR
 328 ><TD
 329 WIDTH="33%"
 330 ALIGN="left"
 331 VALIGN="top"
 332 >SDL_SetColors</TD
 333 ><TD
 334 WIDTH="34%"
 335 ALIGN="center"
 336 VALIGN="top"
 337 ><A
 338 HREF="video.html"
 339 ACCESSKEY="U"
 340 >Up</A
 341 ></TD
 342 ><TD
 343 WIDTH="33%"
 344 ALIGN="right"
 345 VALIGN="top"
 346 >SDL_SetGamma</TD
 347 ></TR
 348 ></TABLE
 349 ></DIV
 350 ></BODY
 351 ></HTML
 352 >