notaz.gp2x.de / sdl_omap.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
tune the preloads a bit
[sdl_omap.git] / docs / html / sdlsetalpha.html
CommitLineData
e14743d1 1<HTML
2><HEAD
3><TITLE
4>SDL_SetAlpha</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_SetColorKey"
17HREF="sdlsetcolorkey.html"><LINK
18REL="NEXT"
19TITLE="SDL_SetClipRect"
20HREF="sdlsetcliprect.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="sdlsetcolorkey.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="sdlsetcliprect.html"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><H1
72><A
73NAME="SDLSETALPHA"
74></A
75>SDL_SetAlpha</H1
76><DIV
77CLASS="REFNAMEDIV"
78><A
79NAME="AEN2096"
80></A
81><H2
82>Name</H2
83>SDL_SetAlpha&nbsp;--&nbsp;Adjust the alpha properties of a surface</DIV
84><DIV
85CLASS="REFSYNOPSISDIV"
86><A
87NAME="AEN2099"
88></A
89><H2
90>Synopsis</H2
91><DIV
92CLASS="FUNCSYNOPSIS"
93><A
94NAME="AEN2100"
95></A
96><P
97></P
98><PRE
99CLASS="FUNCSYNOPSISINFO"
100>#include "SDL.h"</PRE
101><P
102><CODE
103><CODE
104CLASS="FUNCDEF"
105>int <B
106CLASS="FSFUNC"
107>SDL_SetAlpha</B
108></CODE
109>(SDL_Surface *surface, Uint32 flag, Uint8 alpha);</CODE
110></P
111><P
112></P
113></DIV
114></DIV
115><DIV
116CLASS="REFSECT1"
117><A
118NAME="AEN2106"
119></A
120><H2
121>Description</H2
122><DIV
123CLASS="NOTE"
124><BLOCKQUOTE
125CLASS="NOTE"
126><P
127><B
128>Note: </B
129>This function and the semantics of SDL alpha blending have changed since version 1.1.4. Up until version 1.1.5, an alpha value of 0 was considered opaque and a value of 255 was considered transparent. This has now been inverted: 0 (<TT
130CLASS="LITERAL"
131>SDL_ALPHA_TRANSPARENT</TT
132>) is now considered transparent and 255 (<TT
133CLASS="LITERAL"
134>SDL_ALPHA_OPAQUE</TT
135>) is now considered opaque.</P
136></BLOCKQUOTE
137></DIV
138><P
139><TT
140CLASS="FUNCTION"
141>SDL_SetAlpha</TT
142> is used for setting the per-surface alpha
143value and/or enabling and disabling alpha blending.</P
144><P
145>The<TT
146CLASS="PARAMETER"
147><I
148>surface</I
149></TT
150> parameter specifies which surface whose alpha
151attributes you wish to adjust. <TT
152CLASS="PARAMETER"
153><I
154>flags</I
155></TT
156> is used to specify
157whether alpha blending should be used (<TT
158CLASS="LITERAL"
159>SDL_SRCALPHA</TT
160>) and
161whether the surface should use RLE acceleration for blitting
162(<TT
163CLASS="LITERAL"
164>SDL_RLEACCEL</TT
165>). <TT
166CLASS="PARAMETER"
167><I
168>flags</I
169></TT
170> can be an OR'd
171combination of these two options, one of these options or 0. If
172<TT
173CLASS="LITERAL"
174>SDL_SRCALPHA</TT
175> is not passed as a flag then all alpha
176information is ignored when blitting the surface. The
177<TT
178CLASS="PARAMETER"
179><I
180>alpha</I
181></TT
182> parameter is the per-surface alpha value; a
183surface need not have an alpha channel to use per-surface alpha and blitting
184can still be accelerated with <TT
185CLASS="LITERAL"
186>SDL_RLEACCEL</TT
187>.</P
188><DIV
189CLASS="NOTE"
190><BLOCKQUOTE
191CLASS="NOTE"
192><P
193><B
194>Note: </B
195>The per-surface alpha value of 128 is considered a special case and
196is optimised, so it's much faster than other per-surface values.</P
197></BLOCKQUOTE
198></DIV
199><P
200>Alpha effects surface blitting in the following ways:</P
201><DIV
202CLASS="INFORMALTABLE"
203><A
204NAME="AEN2126"
205></A
206><P
207></P
208><TABLE
209BORDER="0"
210CLASS="CALSTABLE"
211><TBODY
212><TR
213><TD
214ALIGN="LEFT"
215VALIGN="TOP"
216>RGBA-&#62;RGB with <TT
217CLASS="LITERAL"
218>SDL_SRCALPHA</TT
219></TD
220><TD
221ALIGN="LEFT"
222VALIGN="TOP"
223><P
224>The source is alpha-blended with the destination, using the alpha channel. <TT
225CLASS="LITERAL"
226>SDL_SRCCOLORKEY</TT
227> and the per-surface alpha are ignored.</P
228></TD
229></TR
230><TR
231><TD
232ALIGN="LEFT"
233VALIGN="TOP"
234>RGBA-&#62;RGB without <TT
235CLASS="LITERAL"
236>SDL_SRCALPHA</TT
237></TD
238><TD
239ALIGN="LEFT"
240VALIGN="TOP"
241><P
242>The RGB data is copied from the source. The source alpha channel and the per-surface alpha value are ignored.</P
243></TD
244></TR
245><TR
246><TD
247ALIGN="LEFT"
248VALIGN="TOP"
249>RGB-&#62;RGBA with <TT
250CLASS="LITERAL"
251>SDL_SRCALPHA</TT
252></TD
253><TD
254ALIGN="LEFT"
255VALIGN="TOP"
256><P
257>The source is alpha-blended with the destination using the per-surface alpha
258value. If <TT
259CLASS="LITERAL"
260>SDL_SRCCOLORKEY</TT
261> is set, only the pixels not
262matching the colorkey value are copied. The alpha channel of the copied pixels
263is set to opaque.</P
264></TD
265></TR
266><TR
267><TD
268ALIGN="LEFT"
269VALIGN="TOP"
270>RGB-&#62;RGBA without <TT
271CLASS="LITERAL"
272>SDL_SRCALPHA</TT
273></TD
274><TD
275ALIGN="LEFT"
276VALIGN="TOP"
277><P
278>The RGB data is copied from the source and the alpha value of the copied pixels
279is set to opaque. If <TT
280CLASS="LITERAL"
281>SDL_SRCCOLORKEY</TT
282> is set, only the pixels
283not matching the colorkey value are copied. </P
284></TD
285></TR
286><TR
287><TD
288ALIGN="LEFT"
289VALIGN="TOP"
290>RGBA-&#62;RGBA with <TT
291CLASS="LITERAL"
292>SDL_SRCALPHA</TT
293></TD
294><TD
295ALIGN="LEFT"
296VALIGN="TOP"
297><P
298>The source is alpha-blended with the destination using the source alpha
299channel. The alpha channel in the destination surface is left untouched.
300<TT
301CLASS="LITERAL"
302>SDL_SRCCOLORKEY</TT
303> is ignored.</P
304></TD
305></TR
306><TR
307><TD
308ALIGN="LEFT"
309VALIGN="TOP"
310>RGBA-&#62;RGBA without <TT
311CLASS="LITERAL"
312>SDL_SRCALPHA</TT
313></TD
314><TD
315ALIGN="LEFT"
316VALIGN="TOP"
317><P
318>The RGBA data is copied to the destination surface. If <TT
319CLASS="LITERAL"
320>SDL_SRCCOLORKEY</TT
321> is set, only the pixels not matching the colorkey value are copied.</P
322></TD
323></TR
324><TR
325><TD
326ALIGN="LEFT"
327VALIGN="TOP"
328>RGB-&#62;RGB with <TT
329CLASS="LITERAL"
330>SDL_SRCALPHA</TT
331></TD
332><TD
333ALIGN="LEFT"
334VALIGN="TOP"
335><P
336>The source is alpha-blended with the destination using the per-surface alpha value. If <TT
337CLASS="LITERAL"
338>SDL_SRCCOLORKEY</TT
339> is set, only the pixels not matching the colorkey value are copied.</P
340></TD
341></TR
342><TR
343><TD
344ALIGN="LEFT"
345VALIGN="TOP"
346>RGB-&#62;RGB without <TT
347CLASS="LITERAL"
348>SDL_SRCALPHA</TT
349></TD
350><TD
351ALIGN="LEFT"
352VALIGN="TOP"
353><P
354>The RGB data is copied from the source. If <TT
355CLASS="LITERAL"
356>SDL_SRCCOLORKEY</TT
357> is set, only the pixels not matching the colorkey value are copied.</P
358></TD
359></TR
360></TBODY
361></TABLE
362><P
363></P
364></DIV
365><DIV
366CLASS="NOTE"
367><BLOCKQUOTE
368CLASS="NOTE"
369><P
370><B
371>Note: </B
372> Note that RGBA-&#62;RGBA blits (with SDL_SRCALPHA set) keep the alpha
373of the destination surface. This means that you cannot compose two arbitrary
374RGBA surfaces this way and get the result you would expect from "overlaying"
375them; the destination alpha will work as a mask.</P
376><P
377>Also note that per-pixel and per-surface alpha cannot be combined;
378the per-pixel alpha is always used if available</P
379></BLOCKQUOTE
380></DIV
381></DIV
382><DIV
383CLASS="REFSECT1"
384><A
385NAME="AEN2179"
386></A
387><H2
388>Return Value</H2
389><P
390>This function returns <SPAN
391CLASS="RETURNVALUE"
392>0</SPAN
393>, or
394<SPAN
395CLASS="RETURNVALUE"
396>-1</SPAN
397> if there was an error.</P
398></DIV
399><DIV
400CLASS="REFSECT1"
401><A
402NAME="AEN2184"
403></A
404><H2
405>See Also</H2
406><P
407><A
408HREF="sdlmaprgba.html"
409><TT
410CLASS="FUNCTION"
411>SDL_MapRGBA</TT
412></A
413>,
414<A
415HREF="sdlgetrgba.html"
416><TT
417CLASS="FUNCTION"
418>SDL_GetRGBA</TT
419></A
420>,
421<A
422HREF="sdldisplayformatalpha.html"
423><TT
424CLASS="FUNCTION"
425>SDL_DisplayFormatAlpha</TT
426></A
427>,
428<A
429HREF="sdlblitsurface.html"
430><TT
431CLASS="FUNCTION"
432>SDL_BlitSurface</TT
433></A
434></P
435></DIV
436><DIV
437CLASS="NAVFOOTER"
438><HR
439ALIGN="LEFT"
440WIDTH="100%"><TABLE
441SUMMARY="Footer navigation table"
442WIDTH="100%"
443BORDER="0"
444CELLPADDING="0"
445CELLSPACING="0"
446><TR
447><TD
448WIDTH="33%"
449ALIGN="left"
450VALIGN="top"
451><A
452HREF="sdlsetcolorkey.html"
453ACCESSKEY="P"
454>Prev</A
455></TD
456><TD
457WIDTH="34%"
458ALIGN="center"
459VALIGN="top"
460><A
461HREF="index.html"
462ACCESSKEY="H"
463>Home</A
464></TD
465><TD
466WIDTH="33%"
467ALIGN="right"
468VALIGN="top"
469><A
470HREF="sdlsetcliprect.html"
471ACCESSKEY="N"
472>Next</A
473></TD
474></TR
475><TR
476><TD
477WIDTH="33%"
478ALIGN="left"
479VALIGN="top"
480>SDL_SetColorKey</TD
481><TD
482WIDTH="34%"
483ALIGN="center"
484VALIGN="top"
485><A
486HREF="video.html"
487ACCESSKEY="U"
488>Up</A
489></TD
490><TD
491WIDTH="33%"
492ALIGN="right"
493VALIGN="top"
494>SDL_SetClipRect</TD
495></TR
496></TABLE
497></DIV
498></BODY
499></HTML
500>
SDL with some OMAP hardware support