PgSetAlpha()

Set the parameters for alpha blending in detail

Synopsis:

void PgSetAlpha(
        unsigned long const alpha_op, 
        PgMap_t const * const src_alpha_map,
        PgGradient_t const * const src_alpha_gradient,
        char unsigned const src_global_alpha,
        char unsigned const dst_global_alpha );

Description:

PgSetAlpha() sets the parameters for an alpha-blending operation.

The alpha_op argument is the current operation. Currently, the function supports only these flags:

Pg_ALPHA_OP_SRC_GLOBAL: The source alpha value is src_global_alpha.
Pg_ALPHA_OP_SRC_MAP: The source alpha is src_alpha_map. This bit can't be used in conjunction with Pg_ALPHA_OP_SRC_GLOBAL.
Pg_BLEND_SRC_SRC_ALPHA: The source multiplication factor is the source alpha (As,As,As,As).
Pg_BLEND_DST_ONE_MINUS_SRC_ALPHA: The destination multiplication factor is 1 - the source_alpha (1,1,1,1)-(As,As,As,As).

The other arguments are:

src_alpha_map

The alpha map to use as the source; NULL means no map. This argument is used if alpha_op has Pg_ALPHA_OP_SRC_MAP set.

This map, of type PgMap_t, indicates the alpha blending to be applied to each individual pixel. The map is "pinned" to the origin of your draw command and is tiled if the dimensions of the map are smaller than the dimension of the drawing operation. The PgMap_t structure is defined as follows:

typedef struct _Pg_map {
        PhDim_t dim;
        char *map;
        } PgMap_t;

The members include:

dim -- a PhDim_t structure that defines the size of area covered by the map, in pixels.
map -- the map itself.

src_alpha_gradient

The gradient alpha to use as the source. It isn't currently supported and should be NULL.

src_global_alpha

The constant source alpha value, which is used if Pg_ALPHA_OP_SRC_GLOBAL is set.

dst_global_alpha

The constant destination alpha value, which isn't currently used.

Pixels are computed as follows when alpha blending is turned on:

Rd=(Rs * (src_multiplier)) + (Rd * (dst_multiplier))
Gd=(Gs * (src_multiplier)) + (Gd * (dst_multiplier))
Bd=(Bs * (src_multiplier)) + (Bd * (dst_multiplier))

where Rs, Gs, and Bs are the red, green, and blue settings for the source, and Rd, Gd, and Bd are those for the destination. So: so:

PgSetAlpha(Pg_ALPHA_OP_SRC_GLOBAL | Pg_BLEND_SRC_SRC_ALPHA | 
           Pg_BLEND_DST_ONE_MINUS_SRC_ALPHA,
           NULL,
           NULL,
           64,
           0);

uses the following method to compute the resulting destination pixel:

Let's assume we're using a 24- or 32-bit graphics display. We need some masks to limit the values used for each color to the range 0 through 255:
```
RMask=0xFF
GMask=0xFF
BMask=0xFF
  
```
We'll also need the number of places to shift each color to put it in the correct channel:
```
RShift=16
GShift=8
BShift=0
  
```
Calculate the source and destination multipliers, based on the value of the src_global_alpha argument (64 in this example):
```
src_multiplier = 64  // (i.e. src_global_alpha)
dst_multiplier = 192 // (i.e. 256 - src_global_alpha)
  
```

Calculate each destination color as a combination of the source and existing destination colors, in the requested proportions (shifted to keep the bits that matter):

Rd=((Rs * src_multiplier) + (Rd * dst_multiplier)) >> 8
Gd=((Gs * src_multiplier) + (Gd * dst_multiplier)) >> 8
Bs=((Bs * src_multiplier) + (Bd * dst_multiplier)) >> 8

Build the destination pixel value by masking the color into 8 bits and then shifting the bits into their proper position:

dest_pixel = ((Rd & RMask) << RShift) | 
             ((Gd & GMask) << GShift) | 
             ((Bd & BMask) << BShift)

This code:

unsigned char alphamapdata[8][8]= {
    {0x00, 0x40, 0x80, 0xC0, 0xFF, 0xC0, 0x80, 0x40 },
    {0x40, 0x80, 0xC0, 0xFF, 0xC0, 0x80, 0x40, 0x00 },
    {0x80, 0xC0, 0xFF, 0xC0, 0x80, 0x40, 0x00, 0x40 },
    {0xC0, 0xFF, 0xC0, 0x80, 0x40, 0x00, 0x40, 0x80 },
    {0xFF, 0xC0, 0x80, 0x40, 0x00, 0x40, 0x80, 0xC0 },
    {0xC0, 0x80, 0x40, 0x00, 0x40, 0x80, 0xC0, 0xFF },
    {0x80, 0x40, 0x00, 0x40, 0x80, 0xC0, 0xFF, 0xC0 },
    {0x40, 0x00, 0x40, 0x80, 0xC0, 0xFF, 0xC0, 0x80 }
};

PgMap_t alphamap;

alphamap.dim.w=8;
alphamap.dim.h=8;
alphamap.map=alphamapdata;

PgSetAlpha (Pg_ALPHA_OP_SRC_MAP | Pg_BLEND_SRC_SRC_ALPHA | 
            Pg_BLEND_DST_ONE_MINUS_SRC_ALPHA,
            &alphamap, NULL, 0, 0);

is the same as above but uses the alpha map instead of an overall blend factor:

src_multiplier = *current_alpha_map_pos;
dst_multiplier = 256 - *current_alpha_map_pos;

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No

PgSetAlpha()

Synopsis:

Library:

Description:

Classification:

See also: