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