Google

Transparency and patterned drawing



void drawing_mode(int mode, BITMAP *pattern, int x_anchor, int y_anchor);
Sets the graphics drawing mode. This only affects the geometric routines like putpixel, lines, rectangles, circles, polygons, floodfill, etc, not the text output, blitting, or sprite drawing functions. The mode should be one of the values: 

      DRAW_MODE_SOLID               - the default, solid color
                                      drawing
      DRAW_MODE_XOR                 - exclusive-or drawing
      DRAW_MODE_COPY_PATTERN        - multicolored pattern fill
      DRAW_MODE_SOLID_PATTERN       - single color pattern fill
      DRAW_MODE_MASKED_PATTERN      - masked pattern fill
      DRAW_MODE_TRANS               - translucent color blending
In DRAW_MODE_XOR, pixels are written to the bitmap with an exclusive-or operation rather than a simple copy, so drawing the same shape twice will erase it. Because it involves reading as well as writing the bitmap memory, xor drawing is a lot slower than the normal replace mode.

With the patterned modes, you provide a pattern bitmap which is tiled across the surface of the shape. Allegro stores a pointer to this bitmap rather than copying it, so you must not destroy the bitmap while it is still selected as the pattern. The width and height of the pattern must be powers of two, but they can be different, eg. a 64x16 pattern is fine, but a 17x3 one is not. The pattern is tiled in a grid starting at point (x_anchor, y_anchor). Normally you should just pass zero for these values, which lets you draw several adjacent shapes and have the patterns meet up exactly along the shared edges. Zero alignment may look peculiar if you are moving a patterned shape around the screen, however, because the shape will move but the pattern alignment will not, so in some situations you may wish to alter the anchor position.

When you select DRAW_MODE_COPY_PATTERN, pixels are simply copied from the pattern bitmap onto the destination bitmap. This allows the use of multicolored patterns, and means that the color you pass to the drawing routine is ignored. This is the fastest of the patterned modes.

In DRAW_MODE_SOLID_PATTERN, each pixel in the pattern bitmap is compared with the mask color, which is zero in 256 color modes or bright pink for truecolor data (maximum red and blue, zero green). If the pattern pixel is solid, a pixel of the color you passed to the drawing routine is written to the destination bitmap, otherwise a zero is written. The pattern is thus treated as a monochrome bitmask, which lets you use the same pattern to draw different shapes in different colors, but prevents the use of multicolored patterns.

DRAW_MODE_MASKED_PATTERN is almost the same as DRAW_MODE_SOLID_PATTERN, but the masked pixels are skipped rather than being written as zeros, so the background shows through the gaps.

In DRAW_MODE_TRANS, the global color_map table or truecolor blender functions are used to overlay pixels on top of the existing image. This must only be used after you have set up the color mapping table (for 256 color modes) or blender functions (for truecolor modes). Because it involves reading as well as writing the bitmap memory, translucent drawing is very slow if you draw directly to video RAM, so wherever possible you should use a memory bitmap instead.

void xor_mode(int on);
This is a shortcut for toggling xor drawing mode on and off. Calling xor_mode(TRUE) is equivalent to drawing_mode (DRAW_MODE_XOR, NULL, 0, 0); Calling xor_mode(FALSE) is equivalent to drawing_mode(DRAW_MODE_SOLID, NULL, 0, 0);

void solid_mode();
This is a shortcut for selecting solid drawing mode. It is equivalent to calling drawing_mode(DRAW_MODE_SOLID, NULL, 0, 0);

In paletted video modes, translucency and lighting are implemented with a 64k lookup table, which contain the result of combining any two colors c1 and c2. You must set up this table before you use any of the lighting or translucency routines. Depending on how you construct the table, a range of different effects are possible. For example, translucency can be implemented by using a color halfway between c1 and c2 as the result of the combination. Lighting is achieved by treating one of the colors as a light level (0-255) rather than a color, and setting up the table appropriately. A range of specialised effects are possible, for instance replacing any color with any other color and making individual source or destination colors completely solid or invisible.

Color mapping tables can be precalculated with the colormap utility, or generated at runtime. The COLOR_MAP structure is defined as: 

typedef struct {
   unsigned char data[PAL_SIZE][PAL_SIZE];
} COLOR_MAP;
extern COLOR_MAP *color_map;
Global pointer to the color mapping table. This must be set before using any translucent or lit drawing functions in a 256 color video mode!

void create_light_table(COLOR_MAP *table, const PALETTE pal, int r, g, b, void (*callback)(int pos));
Fills the specified color mapping table with lookup data for doing lighting effects with the specified palette. When combining the colors c1 and c2 with this table, c1 is treated as a light level from 0-255. At light level 255 the table will output color c2 unchanged, at light level 0 it will output the r, g, b value you specify to this function, and at intermediate light levels it will output a color somewhere between the two extremes. The r, g, and b values are in the range 0-63. If the callback function is not NULL, it will be called 256 times during the calculation, allowing you to display a progress indicator.

void create_trans_table(COLOR_MAP *table, const PALETTE pal, int r, g, b, void (*callback)(int pos));
Fills the specified color mapping table with lookup data for doing translucency effects with the specified palette. When combining the colors c1 and c2 with this table, the result will be a color somewhere between the two. The r, g, and b parameters specify the solidity of each color component, ranging from 0 (totally transparent) to 255 (totally solid). For 50% solidity, pass 128. This function treats source color #0 as a special case, leaving the destination unchanged whenever a zero source pixel is encountered, so that masked sprites will draw correctly. If the callback function is not NULL, it will be called 256 times during the calculation, allowing you to display a progress indicator.

void create_color_table(COLOR_MAP *table, const PALETTE pal, void (*blend)(PALETTE pal, int x, int y, RGB *rgb), void (*callback)(int pos));
Fills the specified color mapping table with lookup data for doing customised effects with the specified palette, calling the blend function to determine the results of each color combination. Your blend routine will be passed a pointer to the palette and the two colors which are to be combined, and should fill in the RGB structure with the desired result in 0-63 format. Allegro will then search the palette for the closest match to the RGB color that you requested, so it doesn't matter if the palette has no exact match for this color. If the callback function is not NULL, it will be called 256 times during the calculation, allowing you to display a progress indicator.

void create_blender_table(COLOR_MAP *table, const PALETTE pal, void (*callback)(int pos));
Fills the specified color mapping table with lookup data for doing a paletted equivalent of whatever truecolor blender mode is currently selected. After calling set_trans_blender(), set_blender_mode(), or any of the other truecolor blender mode routines, you can use this function to create an 8 bit mapping table that will have the same results as whatever 24 bit blending mode you have enabled.

In truecolor video modes, translucency and lighting are implemented by a blender function in the form: 

unsigned long (*BLENDER_FUNC)(unsigned long x, y, n);
This routine takes two color parameters, decomposes them into their red, green, and blue components, combines them according to the interpolation value n, and then merges the result back into a single return color value.

Since these routines may be used from various different color depths, there are three such callbacks, one for use with 15 bit 5.5.5 pixels, one for 16 bit 5.6.5 pixels, and one for 24 bit 8.8.8 pixels (this can be shared between the 24 and 32 bit code since the bit packing is the same).

void set_trans_blender(int r, int g, int b, int a);
Selects the default set of truecolor blender routines, which perform a simple linear interpolation between the source and destination colors. When a translucent drawing function is called, the alpha parameter set by this routine is used as the interpolation factor, which controls the solidity of the drawing (range 0 to 255). When a lit sprite drawing function is called, the alpha value passed to this routine is ignored, and instead the color passed to the sprite function is used to select an alpha level. The blender routine will then be used to interpolate between the sprite color and the RGB values that were passed to this function (ranging 0-255).

void set_alpha_blender();
Enables the special alpha-channel blending mode, which is used for drawing 32 bit RGBA sprites. After calling this function, you can use draw_trans_sprite() or draw_trans_rle_sprite() to draw a 32 bit source image onto any hicolor or truecolor destination. The alpha values will be taken directly from the source graphic, so you can vary the solidity of each part of the image. You can't use any of the normal translucency functions while this mode is active, though, so you should reset to one of the normal blender modes (eg. set_trans_blender()) before drawing anything other than 32 bit RGBA sprites.

void set_write_alpha_blender();
Enables the special alpha-channel editing mode, which is used for drawing alpha channels over the top of an existing 32 bit RGB sprite, to turn it into an RGBA format image. After calling this function, you can set the drawing mode to DRAW_MODE_TRANS and then write draw color values (0-255) onto a 32 bit image. This will leave the color values unchanged, but alter the alpha to whatever values you are writing. After enabling this mode you can also use draw_trans_sprite() to superimpose an 8 bit alpha mask over the top of an existing 32 bit sprite.

void set_add_blender(int r, int g, int b, int a);
Enables an additive color blender mode for combining lit or translucent truecolor pixels.

void set_burn_blender(int r, int g, int b, int a);
Enables a burn blender mode for combining lit or translucent truecolor pixels. Here the lightness values of the colours of the source image reduce the lightness of the destination image, darkening the image.

void set_color_blender(int r, int g, int b, int a);
Enables a color blender mode for combining lit or translucent truecolor pixels. Applies only the hue and saturation of the source image to the destination image. The luminance of the destination image is not affected.

void set_difference_blender(int r, int g, int b, int a);
Enables a difference blender mode for combining lit or translucent truecolor pixels. This makes an image which has colours calculated by the difference between the source and destination colours.

void set_dissolve_blender(int r, int g, int b, int a);
Enables a dissolve blender mode for combining lit or translucent truecolor pixels. Randomly replaces the colours of some pixels in the destination image with those of the source image. The number of pixels replaced depends on the alpha value (higher value, more pixels replaced; you get the idea :).

void set_dodge_blender(int r, int g, int b, int a);
Enables a dodge blender mode for combining lit or translucent truecolor pixels. The lightness of colours in the source lighten the colours of the destination. White has the most effect; black has none.

void set_hue_blender(int r, int g, int b, int a);
Enables a hue blender mode for combining lit or translucent truecolor pixels. This applies the hue of the source to the destination.

void set_invert_blender(int r, int g, int b, int a);
Enables an invert blender mode for combining lit or translucent truecolor pixels. Blends the inverse (or negative) colour of the source with the destination.

void set_luminance_blender(int r, int g, int b, int a);
Enables a luminance blender mode for combining lit or translucent truecolor pixels. Applies the luminance of the source to the destination. The colour of the destination is not affected.

void set_multiply_blender(int r, int g, int b, int a);
Enables a multiply blender mode for combining lit or translucent truecolor pixels. Combines the source and destination images, multiplying the colours to produce a darker colour. If a colour is multiplied by white it remains unchanged; when multiplied by black it also becomes black.

void set_saturation_blender(int r, int g, int b, int a);
Enables a saturation blender mode for combining lit or translucent truecolor pixels. Applies the saturation of the source to the destination image.

void set_screen_blender(int r, int g, int b, int a);
Enables a screen blender mode for combining lit or translucent truecolor pixels. This blender mode lightens the colour of the destination image by multiplying the inverse of the source and destination colours. Sort of like the opposite of the multiply blender mode.

void set_blender_mode(BLENDER_FUNC b15, b16, b24, int r, g, b, a);
Specifies a custom set of truecolor blender routines, which can be used to implement whatever special interpolation modes you need. This function shares a single blender between the 24 and 32 bit modes.

void set_blender_mode_ex(BLENDER_FUNC b15, b16, b24, b32, b15x, b16x, b24x, int r, g, b, a);
Like set_blender_mode(), but allows you to specify a more complete set of blender routines. The b15, b16, b24, and b32 routines are used when drawing pixels onto destinations of the same format, while b15x, b16x, and b24x are used by draw_trans_sprite() and draw_trans_rle_sprite() when drawing RGBA images onto destination bitmaps of another format. These blenders will be passed a 32 bit x parameter, along with a y value of a different color depth, and must try to do something sensible in response.