SYNOPSIS

       #include "SDL.h"

       int SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);

DESCRIPTION

              Note:

              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 consid-
              ered   transparent.   This   has   now    been    inverted:    0
              (SDL_ALPHA_TRANSPARENT)  is  now  considered transparent and 255
              (SDL_ALPHA_OPAQUE) is now considered opaque.

       SDL_SetAlpha is used for setting the  per-surface  alpha  value  and/or
       enabling and disabling alpha blending.

       Thesurface parameter specifies which surface whose alpha attributes you
       wish to adjust. flags is used to specify whether alpha blending  should
       be used (SDL_SRCALPHA) and whether the surface should use RLE accelera-
       tion for blitting (SDL_RLEACCEL). flags can be an OR'd  combination  of
       these  two  options,  one of these options or 0. If SDL_SRCALPHA is not
       passed as a flag then all alpha information is  ignored  when  blitting
       the surface. The alpha parameter is the per-surface alpha value; a sur-
       face need not have an alpha channel to use per-surface alpha and  blit-
       ting can still be accelerated with SDL_RLEACCEL.

              Note:

              The  per-surface alpha value of 128 is considered a special case
              and is optimised, so it's much  faster  than  other  per-surface
              values.

       Alpha effects surface blitting in the following ways:

       RGBA->RGB with SDL_SRCALPHA
                           The  source  is alpha-blended with the destination,
                           using the alpha channel.  SDL_SRCCOLORKEY  and  the
                           per-surface alpha are ignored.

       RGBA->RGB without SDL_SRCALPHA
                           The  RGB data is copied from the source. The source
                           alpha channel and the per-surface alpha  value  are
                           ignored.

       RGB->RGBA with SDL_SRCALPHA
                           The  source  is  alpha-blended with the destination
                           using the per-surface alpha value.  If  SDL_SRCCOL-
                           ORKEY is set, only the pixels not matching the col-
                           orkey value are copied. The alpha  channel  of  the
                           copied pixels is set to opaque.
                           The RGBA data is copied to the destination surface.
                           If SDL_SRCCOLORKEY is  set,  only  the  pixels  not
                           matching the colorkey value are copied.

       RGB->RGB with SDL_SRCALPHA
                           The  source  is  alpha-blended with the destination
                           using the per-surface alpha value.  If  SDL_SRCCOL-
                           ORKEY is set, only the pixels not matching the col-
                           orkey value are copied.

       RGB->RGB without SDL_SRCALPHA
                           The RGB data is copied from the source. If SDL_SRC-
                           COLORKEY  is  set, only the pixels not matching the
                           colorkey value are copied.

              Note:

               Note that RGBA->RGBA blits (with  SDL_SRCALPHA  set)  keep  the
              alpha  of  the  destination  surface. This means that you cannot
              compose two arbitrary RGBA surfaces this way and get the  result
              you  would  expect from "overlaying" them; the destination alpha
              will work as a mask.

              Also note that per-pixel and per-surface alpha  cannot  be  com-
              bined; the per-pixel alpha is always used if available

RETURN VALUE

       This function returns 0, or -1 if there was an error.

SEE ALSO

       SDL_MapRGBA, SDL_GetRGBA, SDL_DisplayFormatAlpha, SDL_BlitSurface



SDL                         Tue 11 Sep 2001, 23:01             SDL_SetAlpha(3)