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