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:

• One or more operation flags. If Pg_ALPHA_OP_SRC* or Pg_ALPHA_OP_DST_GLOBAL isn't set, the alpha value from the source pixel (As) is used.

  And:

  • A source multiplier flag — if no flag is set, the default Pg_BLEND_SRC_0 is used.
  • A destination multiplier flag — if no flag is set, the default Pg_BLEND_DST_0 is used.

  Or:

  • The alpha test operation flag Pg_ALPHA_OP_TEST.
  • A test type flag — if no flag is set, the default Pg_TEST_NEVER is used.

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

---

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:

• anywhere in the alphamap that is less than 128 (0x80) a white pixel is drawn
• anywhere that is equal to or greater than 128 in the alphamap the destination pixel is unmodified.

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

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