[sdl_omap.git] / docs / html / sdlsetpalette.html

<HTML
><HEAD
><TITLE
>SDL_SetPalette</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="SDL Library Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Video"
HREF="video.html"><LINK
REL="PREVIOUS"
TITLE="SDL_SetColors"
HREF="sdlsetcolors.html"><LINK
REL="NEXT"
TITLE="SDL_SetGamma"
HREF="sdlsetgamma.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFF8DC"
TEXT="#000000"
LINK="#0000ee"
VLINK="#551a8b"
ALINK="#ff0000"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>SDL Library Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sdlsetcolors.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlsetgamma.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLSETPALETTE"
></A
>SDL_SetPalette</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1517"
></A
><H2
>Name</H2
>SDL_SetPalette&nbsp;--&nbsp;Sets the colors in the palette of an 8-bit surface.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN1520"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN1521"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int <B
CLASS="FSFUNC"
>SDL_SetPalette</B
></CODE
>(SDL_Surface *surface, int flags, SDL_Color *colors, int firstcolor, int ncolors);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1527"
></A
><H2
>Description</H2
><P
>Sets a portion of the palette for the given 8-bit surface.</P
><P
>Palettized (8-bit) screen surfaces with the
<TT
CLASS="LITERAL"
>SDL_HWPALETTE</TT
> flag have two palettes, a logical
palette that is used for mapping blits to/from the surface and a
physical palette (that determines how the hardware will map the colors
to the display). <A
HREF="sdlblitsurface.html"
>SDL_BlitSurface</A
>
always uses the logical palette when blitting surfaces (if it has to
convert between surface pixel formats). Because of this, it is often
useful to modify only one or the other palette to achieve various
special color effects (e.g., screen fading, color flashes, screen dimming).</P
><P
>This function can modify either the logical or physical palette by
specifing <TT
CLASS="LITERAL"
>SDL_LOGPAL</TT
> or
<TT
CLASS="LITERAL"
>SDL_PHYSPAL</TT
>the in the <TT
CLASS="PARAMETER"
><I
>flags</I
></TT
>
parameter.</P
><P
>When <TT
CLASS="PARAMETER"
><I
>surface</I
></TT
> is the surface associated with the current
display, the display colormap will be updated with the requested colors.  If
<TT
CLASS="LITERAL"
>SDL_HWPALETTE</TT
> was set in <A
HREF="sdlsetvideomode.html"
>SDL_SetVideoMode</A
> flags,
<TT
CLASS="FUNCTION"
>SDL_SetPalette</TT
> will always return <SPAN
CLASS="RETURNVALUE"
>1</SPAN
>,
and the palette is guaranteed to be set the way you desire, even if the window
colormap has to be warped or run under emulation.</P
><P
>The color components of a
<A
HREF="sdlcolor.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_Color</SPAN
></A
> structure
are 8-bits in size, giving you a total of
256<SUP
>3</SUP
>=16777216 colors.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1547"
></A
><H2
>Return Value</H2
><P
>If <TT
CLASS="PARAMETER"
><I
>surface</I
></TT
> is not a palettized surface, this function
does nothing, returning <SPAN
CLASS="RETURNVALUE"
>0</SPAN
>.  If all of the colors were set
as passed to <TT
CLASS="FUNCTION"
>SDL_SetPalette</TT
>, it will return
<SPAN
CLASS="RETURNVALUE"
>1</SPAN
>.  If not all the color entries were set exactly as
given, it will return <SPAN
CLASS="RETURNVALUE"
>0</SPAN
>, and you should look at the
surface palette to determine the actual color palette.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1555"
></A
><H2
>Example</H2
><PRE
CLASS="PROGRAMLISTING"
>        /* Create a display surface with a grayscale palette */
        SDL_Surface *screen;
        SDL_Color colors[256];
        int i;
        .
        .
        .
        /* Fill colors with color information */
        for(i=0;i&#60;256;i++){
          colors[i].r=i;
          colors[i].g=i;
          colors[i].b=i;
        }

        /* Create display */
        screen=SDL_SetVideoMode(640, 480, 8, SDL_HWPALETTE);
        if(!screen){
          printf("Couldn't set video mode: %s\n", SDL_GetError());
          exit(-1);
        }

        /* Set palette */
        SDL_SetPalette(screen, SDL_LOGPAL|SDL_PHYSPAL, colors, 0, 256);
        .
        .
        .
        .</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1558"
></A
><H2
>See Also</H2
><P
><A
HREF="sdlsetcolors.html"
>SDL_SetColors</A
>,
<A
HREF="sdlsetvideomode.html"
>SDL_SetVideoMode</A
>,
<A
HREF="sdlsurface.html"
>SDL_Surface</A
>,
<A
HREF="sdlcolor.html"
>SDL_Color</A
></P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sdlsetcolors.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sdlsetgamma.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_SetColors</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="video.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_SetGamma</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	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 -- 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<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	>