PgSetAlpha(), PgSetAlphaCx()

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 );

void PgSetAlphaCx(
        PhGC_t *gc,
        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 );

Arguments:

gc
PgSetAlphaCx() only. A pointer to a graphics context, as returned by PgCreateGC() or PgGetGC().
alpha_op
The current operation; a combination of:
src_alpha_map
A pointer to 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.

src_alpha_gradient
A pointer to the gradient alpha to use as the source. It isn't currently supported; set it to NULL.
src_global_alpha
The constant source alpha value, which is used if you set Pg_ALPHA_OP_SRC_GLOBAL.
dst_global_alpha
The constant destination alpha value, which is used if you set Pg_ALPHA_OP_DST_GLOBAL.

Library:

ph

Description:

These functions set the parameters for an alpha-blending or alpha-test operation. PgSetAlpha() works on the current graphics context, while you can specify the graphics context for PgSetAlphaCx().

The basic formula for alpha blending is:

    source multiplier is one of Pg_BLEND_SRC*
    destination multiplier is one of Pg_BLEND_DST*


    Sm = source pixel        *   source multiplier
    Dm = destination pixel   *   destination multiplier
    destination pixel = Sm + Dm

Note: You can OR only one source and only one destination multiplier flag into alpha_op. You can't combine source or destination flags.

Operation flags

The following operation flags are defined:

Pg_ALPHA_OP_SRC_GLOBAL
The source alpha value (As) 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_ALPHA_OP_DST_GLOBAL
The destination alpha (Ad) value is dst_global_alpha.
Pg_ALPHA_OP_TEST
Perform an alpha test rather than an alpha blend. See the test flags below.

Multiplier flags

Flags are defined for source and destination multipliers. In the descriptions below, all channels are represented in a range from 0 to 1; that is, they have been normalized from their actual range of 0-255. As RGB colors, (1,1,1) is white, (0,0,0) is black, (0.5,0.5,0.5) is grey, (1, 0, 0) is full red, and so on.

The following descriptions assume an RGB or ARGB color model for the formulas, so As is the source pixel's alpha channel, Rs is the source pixel's red channel, Ad is the destination pixel's alpha channel, Rd is the destination pixel's red channel, and so on. For more information about color models, see PgColor_t.

Source multiplier flags

Pg_BLEND_SRC_0
Multiply the source pixel by 0: Sm = (As,Rs,Gs,Bs) * (0,0,0,0).
Pg_BLEND_SRC_1
Multiply the source pixel by 1 (no change): Sm = (As,Rs,Gs,Bs) * (1,1,1,1).
Pg_BLEND_SRC_D
Multiply the source pixel by D: Sm = (As,Rs,Gs,Bs) * (Ad,Rd,Gd,Bd).
Pg_BLEND_SRC_1mD
Multiply the source pixel by 1-D: Sm = (As,Rs,Gs,Bs) * (1-Ad,1-Rd,1-Gd,1-Bd).
Pg_BLEND_SRC_As
The source pixel is multiplied by As: Sm = (As,Rs,Gs,Bs) * (As,As,As,As).
Pg_BLEND_SRC_1mAs
Multiply the source pixel by 1-As: Sm = (As,Rs,Gs,Bs) * (1-As,1-As,1-As,1-As).
Pg_BLEND_SRC_Ad
Multiply the source pixel by Ad: Sm = (As,Rs,Gs,Bs) * (Ad,Ad,Ad,Ad).
Pg_BLEND_SRC_1mAd
Multiply the source pixel by 1-Ad: Sm = (As,Rs,Gs,Bs) * (1-Ad,1-Ad,1-Ad,1-Ad).
Pg_BLEND_SRC_A1As
Multiply the source pixel's alpha channel by 1, and the rest of the pixel by As: Sm = (As,Rs,Gs,Bs) * (1,As,As,As).
Pg_BLEND_SRC_1mA1As
Multiply the source pixel's alpha channel by 0, and the rest of the pixel by 1-As: Sm = (As,Rs,Gs,Bs) * (1-1,1-As,1-As,1-As).
Pg_BLEND_SRC_A1Ad
Multiply the source pixel's alpha channel by 1, and the rest of the pixel by Ad: Sm = (As,Rs,Gs,Bs) * (1,Ad,Ad,Ad).
Pg_BLEND_SRC_1mA1Ad
Multiply the source pixel's alpha channel by 0, and the rest of the pixel by 1-Ad: Sm = (As,Rs,Gs,Bs) * (1-1,1-Ad,1-Ad,1-Ad).
Pg_BLEND_SRC_A0As
Multiply the source pixel's alpha channel by 0, and the rest of the pixel by As: Sm = (As,Rs,Gs,Bs) * (0,As,As,As).
Pg_BLEND_SRC_1mA0As
Multiply the source pixel's alpha channel by 1, and the rest of the pixel by 1-As: Sm = (As,Rs,Gs,Bs) * (1-0,1-As,1-As,1-As).
Pg_BLEND_SRC_A0Ad
Multiply the source pixel's alpha channel by 0, and the rest of the pixel by Ad: Sm = (As,Rs,Gs,Bs) * (0,Ad,Ad,Ad).
Pg_BLEND_SRC_1mA0Ad
Multiply the source pixel's alpha channel by 1, and the rest of the pixel by 1-Ad: Sm = (As,Rs,Gs,Bs) * (1-0,1-Ad,1-Ad,1-Ad).
Pg_BLEND_SRC_SRC_ALPHA
Deprecated; use Pg_BLEND_SRC_As.
Pg_BLEND_DST_ONE_MINUS_SRC_ALPHA
Deprecated; use Pg_BLEND_DST_1mAs.

Destination multiplier flags

Pg_BLEND_DST_0
Multiply the destination pixel by 0: Dm = (Ad,Rd,Gd,Bd) * (0,0,0,0).
Pg_BLEND_DST_1
Multiply the destination pixel by 1 (no change): Dm = (Ad,Rd,Gd,Bd) * (1,1,1,1).
Pg_BLEND_DST_S
Multiply the destination pixel by S: Dm = (Ad,Rd,Gd,Bd) * (As,Rs,Gs,Bs).
Pg_BLEND_DST_1mS
Multiply the destination pixel by 1-S: Dm = (Ad,Rd,Gd,Bd) * (1-As,1-Rs,1-Gs,1-Bs).
Pg_BLEND_DST_As
Multiply the destination pixel by As: Dm = (Ad,Rd,Gd,Bd) * (As,As,As,As).
Pg_BLEND_DST_1mAs
Multiply the destination pixel by 1-As: Dm = (Ad,Rd,Gd,Bd) * (1-As,1-As,1-As,1-As).
Pg_BLEND_DST_Ad
Multiply the destination pixel by Ad: Dm = (Ad,Rd,Gd,Bd) * (Ad,Ad,Ad,Ad).
Pg_BLEND_DST_1mAd
Multiply the destination pixel by 1-Ad: Dm = (Ad,Rd,Gd,Bd) * (1-Ad,1-Ad,1-Ad,1-Ad).
Pg_BLEND_DST_A1As
Multiply the destination pixel's alpha channel by 1, and the rest of the pixel by As: Dm = (Ad,Rd,Gd,Bd) * (1,As,As,As).
Pg_BLEND_DST_1mA1As
Multiply the destination pixel's alpha channel by 0, and the rest of the pixel by 1-As: Dm = (Ad,Rd,Gd,Bd) * (1-1,1-As,1-As,1-As).
Pg_BLEND_DST_A1Ad
Multiply the destination pixel's alpha channel by 1, and the rest of the pixel by Ad: Dm = (Ad,Rd,Gd,Bd) * (1,Ad,Ad,Ad).
Pg_BLEND_DST_1mA1Ad
Multiply the destination pixel's alpha channel by 0, and the rest of the pixel by 1-Ad: Dm = (Ad,Rd,Gd,Bd) * (1-1,1-Ad,1-Ad,1-Ad).
Pg_BLEND_DST_A0As
Multiply the destination pixel's alpha channel by 0, and the rest of the pixel by As: Dm = (Ad,Rd,Gd,Bd) * (0,As,As,As).
Pg_BLEND_DST_1mA0As
Multiply the destination pixel's alpha channel by 1, and the rest of the pixel by 1-As: Dm = (Ad,Rd,Gd,Bd) * (1-0,1-As,1-As,1-As).
Pg_BLEND_DST_A0Ad
Multiply the destination pixel's alpha channel by 0, and the rest of the pixel by Ad: Dm = (Ad,Rd,Gd,Bd) * (0,Ad,Ad,Ad).
Pg_BLEND_DST_1mA0Ad
Multiply the destination pixel's alpha channel by 1, and the rest of the pixel by 1-Ad: Dm = (Ad,Rd,Gd,Bd) * (1-0,1-Ad,1-Ad,1-Ad).

Alpha test flags:

Pg_TEST_NEVER
Never write source pixels to the destination. The destination remains unmodified.
Pg_TEST_ALWAYS
Always write source pixels to the destination.
Pg_TEST_LESS_THAN
If As is less than Ad, write the source pixel to the destination.
Pg_TEST_LESS_THAN_OR_EQUAL
If As is less than or equal to Ad, write the source pixel to the destination.
Pg_TEST_EQUAL
If As is equal to Ad, write the source pixel to the destination.
Pg_TEST_GREATER_THAN_OR_EQUAL
If As is greater than or equal to Ad, write the source pixel to the destination.
Pg_TEST_GREATER_THAN
If As is greater than Ad, write the source pixel to the destination.
Pg_TEST_NOT_EQUAL
If As is not equal to Ad, write the source pixel to the destination.

Examples:

To use the alpha test option:

PgSetAlpha(Pg_ALPHA_OP_SRC_MAP | Pg_ALPHA_OP_DST_GLOBAL |
           Pg_ALPHA_OP_TEST | Pg_TEST_LESS_THAN, &alpha_map,
           NULL, 0, 0x80);
PgAlphaOn();
PgSetFillColor(Pg_WHITE);
PgDrawRect(&canvas_size, Pg_DRAW_FILL);
PgAlphaOff();

In this example, when the graphics driver is rendering the white rectangle:

To use the alpha map option:

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.bpl=8;
alphamap.bpp=8;
alphamap.map=alphamapdata;

PgSetAlpha (Pg_ALPHA_OP_SRC_MAP | Pg_BLEND_SRC_As |
            Pg_BLEND_DST_1mAs,
            &alphamap, NULL, 0, 0);

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PgAlphaOff*(), PgAlphaOn*(), PgMap_t, PgColor_t, PgSetAlphaBlend*(), PhDim_t

Alpha Blending Support in the Raw Drawing and Animation chapter of the Photon Programmer's Guide