Banjo API 0.0.1
Multi-purpose C99 API
Loading...
Searching...
No Matches
Bitmap

Matrix of pixels. More...

Collaboration diagram for Bitmap:

Detailed Description

Typedefs

typedef struct bj_bitmap_t bj_bitmap
 Typedef for the bj_bitmap struct.
 

Enumerations

enum  bj_blit_op {
  BJ_BLIT_OP_COPY = 0 , BJ_BLIT_OP_XOR , BJ_BLIT_OP_OR , BJ_BLIT_OP_AND ,
  BJ_BLIT_OP_ADD_SAT , BJ_BLIT_OP_SUB_SAT
}
 Raster operation (ROP) to apply during blitting. More...
 

Functions

bj_bitmapbj_bitmap_alloc (void)
 Allocate a new bitmap object.
 
bj_bitmapbj_bitmap_new (size_t width, size_t height, bj_pixel_mode mode, size_t stride)
 Creates a new bj_bitmap with the specified width and height.
 
void bj_bitmap_del (bj_bitmap *p_bitmap)
 Deletes a bj_bitmap object and releases associated memory.
 
bj_bitmapbj_bitmap_new_from_file (const char *p_path, bj_error **p_error)
 Creates a new bitmap by loading from a file.
 
bj_bool bj_bitmap_blit_mask_stretched (const bj_bitmap *mask, const bj_rect *mask_area, bj_bitmap *dst, const bj_rect *dst_area, uint32_t fg_native, uint32_t bg_native, bj_mask_bg_mode mode)
 Masked blit with stretching (nearest neighbor). The mask must be 8bpp.
 
void bj_bitmap_print (bj_bitmap *dst, int x, int y, unsigned height, uint32_t fg_native, const char *text)
 Prints text using the default foreground color and transparent background.
 

Variables

bj_bitmapdst
 
bj_bitmap const bj_rectdst_area
 
bj_bitmap const bj_rect uint32_t fg_native
 
bj_bitmap const bj_rect uint32_t uint32_t bg_native
 
bj_bitmap const bj_rect uint32_t uint32_t bj_mask_bg_mode mode
 
*with alpha
 Prints text with explicit foreground/background and background mode.
 

Enumeration Type Documentation

◆ bj_blit_op

enum bj_blit_op

These operations define how source pixels combine with destination pixels during bj_bitmap_blit and bj_bitmap_blit_stretched. Some operations are optimized on specific formats (e.g., 32bpp).

Note
For mismatched pixel formats, colors are combined in linear integer RGB (8-bit per channel) after conversion from/to native formats.
Enumerator
BJ_BLIT_OP_COPY 

Copy source to destination (fast path when formats match)

BJ_BLIT_OP_XOR 

Bitwise XOR (channel-wise for >8bpp)

BJ_BLIT_OP_OR 

Bitwise OR.

BJ_BLIT_OP_AND 

Bitwise AND.

BJ_BLIT_OP_ADD_SAT 

Per-channel saturated add (clamped to 255)

BJ_BLIT_OP_SUB_SAT 

Per-channel saturated subtract (clamped to 0)

Function Documentation

◆ bj_bitmap_alloc()

bj_bitmap * bj_bitmap_alloc ( void )
Returns
A new bj_bitmap instance

◆ bj_bitmap_blit_mask_stretched()

bj_bool bj_bitmap_blit_mask_stretched ( const bj_bitmap * mask,
const bj_rect * mask_area,
bj_bitmap * dst,
const bj_rect * dst_area,
uint32_t fg_native,
uint32_t bg_native,
bj_mask_bg_mode mode )
Parameters
maskThe 8bpp mask bitmap (0..255 coverage).
mask_areaOptional area in the mask (0 = full mask).
dstThe destination bitmap.
dst_areaOptional destination area (0 = full destination).
fg_nativeForeground color packed for destination.
bg_nativeBackground color packed for destination.
modeThe background mode (see bj_mask_bg_mode).
Returns
BJ_TRUE if any pixel was written, BJ_FALSE otherwise.
Clipping & Mapping

The destination area is clipped to the destination bounds. The source mask area is proportionally adjusted so that the visible sub-rectangle of the stretched glyph corresponds to the same sub-rectangle of the source. This avoids visual “wrap-around” artifacts when partially off-screen.

Coverage

Mask values are interpreted as linear coverage (0..255). Alpha blending uses integer arithmetic: mix(dst, src, a)(dst*(255-a) + src*a)/255.

◆ bj_bitmap_del()

void bj_bitmap_del ( bj_bitmap * p_bitmap)
Parameters
p_bitmapPointer to the bj_bitmap object to delete.
Examples
bitmap_blit.c, load_bmp.c, and sprite_animation.c.

◆ bj_bitmap_new()

bj_bitmap * bj_bitmap_new ( size_t width,
size_t height,
bj_pixel_mode mode,
size_t stride )
Parameters
widthWidth of the bitmap.
heightHeight of the bitmap.
modeThe pixel mode.
strideThe suggested bitmap stride.
Returns
A pointer to the newly created bj_bitmap object.

The stride corresponds to the size in bytes of a row. If the value is less than the required stride, the actual minimum stride is used. Set it to 0 to automatically compute the stride.

Examples
bitmap_blit.c, and sprite_animation.c.

◆ bj_bitmap_new_from_file()

bj_bitmap * bj_bitmap_new_from_file ( const char * p_path,
bj_error ** p_error )
Parameters
p_pathPath to the bitmap file.
p_errorPointer to an error object to store any errors encountered during loading.
Returns
A pointer to the newly created bj_bitmap object, or 0 if loading failed.

The new object must be deleted using bj_bitmap_del.

Pixel Mode

Banjo supports the reading or 1, 4, 8, 24 and 32 bits per pixels images. Reading RLE encoding for 4 and 8 bpp is also supported.

According to the file compression (MSDN) and the pixel byte size, the created Bitmap will have one of the following pixel mode:

Bits Per Pixel Compression bj_pixel_mode
1 BI_RGB BJ_PIXEL_MODE_INDEXED_1
4 BI_RGB BJ_PIXEL_MODE_INDEXED_4
4 BJ_RLE4 BJ_PIXEL_MODE_INDEXED_4
8 BI_RGB BJ_PIXEL_MODE_INDEXED_8
8 BI_RLE8 BJ_PIXEL_MODE_INDEXED_8
16 BI_RGB BJ_PIXEL_MODE_XRGB1555
16 BI_BITFIELDS Depends on bit fields
24 BI_RGB BJ_PIXEL_MODE_BGR24
32 BI_RGB BJ_PIXEL_MODE_XRGB8888
32 BI_BITFIELDS Depends on bit fields

Banjo does not support all bitfield configuration. The following table shows our supported bit fields:

Bits Per Pixel Red Mask Green Mask Blue Mask bj_pixel_mode
16 0x0000F800 0x000007E0 0x0000001F BJ_PIXEL_MODE_RGB565
32 0x00FF0000 0x0000FF00 0x000000FF BJ_PIXEL_MODE_XRGB8888

Any other configuration leads to either BJ_PIXEL_MODE_UNKNOWN or a failure in loading the file.

Once loaded, the pixel mode can be retrieved using bj_bitmap_mode.

Edge cases
  • If a bitmap indicates a color palette size but the file does not contain any palette, a same size palette is provided with the first index set to black (red = 0x00, green = 0x00, blue = 0x00) and remaining colors to white (red = 0xFF, green = 0xFF, blue = 0xFF). Banjo does not consider such bitmaps as invalid, but a warning message is logged.
Limitations

While reading indexed Bitmap works, 1, 4 and 8bpp images are automatically converted to 24bpp images for now.

See also
BMP file format (Wikipedia)
Bitmap Compression (MSDN)
Examples
bitmap_blit.c, load_bmp.c, and sprite_animation.c.

◆ bj_bitmap_print()

void bj_bitmap_print ( bj_bitmap * dst,
int x,
int y,
unsigned height,
uint32_t fg_native,
const char * text )
Parameters
dstThe destination bitmap.
xX coordinate of the baseline origin.
yY coordinate of the baseline origin.
heightTarget font height in pixels (glyphs are scaled from the internal font cell size to this height).
fg_nativeForeground color in destination-native format.
textUTF-8/ASCII string with optional ANSI SGR sequences (see below).
ANSI Color Formatting

The text supports a subset of ANSI SGR sequences introduced by ESC (\x1B):

  • \x1B[0m Reset colors to defaults.
  • \x1B[30..37m Set foreground to basic colors (black, red, green, yellow, blue, magenta, cyan, white).
  • \x1B[90..97m Set foreground to bright basic colors.
  • \x1B[39m Reset foreground to the default provided in the call.
  • \x1B[38;2;R;G;Bm Set truecolor foreground.
  • Background-related codes are ignored by this function (use bj_bitmap_blit_text for background control).
Behavior

The function uses the internal monochrome font mask and performs a masked blit in transparent background mode (foreground over destination).

Clipping

Text is clipped to the destination bounds. Out-of-range glyphs are skipped.

Variable Documentation

◆ alpha

* with alpha
Initial value:
= (1 - coverage) and glyph interiors remain untouched.
*
* \par Clipping
*
* Each glyph is pre-clipped to the destination bounds. The source mask
* sub-rectangle is adjusted proportionally so edge glyphs render correctly
* without wrap-around artifacts.
*
* \par Performance
*
* The glyph mask atlas is cached per destination bitmap. Rendering uses
* nearest-neighbor scaling and an inner loop with integer blending.
*
* */
void bj_bitmap_blit_text(
int x,
int y,
unsigned height,
uint32_t fg_native,
uint32_t bg_native,
bj_mask_bg_mode mode,
const char* text
)
bj_bitmap * dst
Definition bitmap.h:575
struct bj_bitmap_t bj_bitmap
Typedef for the bj_bitmap struct.
Definition bitmap.h:40
Parameters
dstThe destination bitmap.
xX coordinate of the baseline origin.
yY coordinate of the baseline origin.
heightTarget font height in pixels.
fg_nativeForeground color in destination-native format.
bg_nativeBackground color in destination-native format.
modeBackground mode (see bj_mask_bg_mode).
textUTF-8/ASCII string with optional ANSI SGR sequences.
ANSI Color Formatting

The string may embed standard SGR sequences following ‘ESC ’['`:

  • Reset
    • \x1B[0m Reset both foreground and background to the defaults passed as fg_native/bg_native.
  • Basic / Bright colors
    • Foreground: \x1B[30..37m (basic), \x1B[90..97m (bright)
    • Background: \x1B[40..47m (basic), \x1B[100..107m (bright)
  • Defaults
    • \x1B[39m Reset foreground to the call’s fg_native.
    • \x1B[49m Reset background to the call’s bg_native.
  • Truecolor
    • Foreground: \x1B[38;2;R;G;Bm
    • Background: \x1B[48;2;R;G;Bm

Unsupported or malformed sequences are ignored gracefully.

Background Modes
  • BJ_MASK_BG_TRANSPARENT: foreground is composited where glyph coverage > 0.
  • BJ_MASK_BG_OPAQUE: the glyph box is a band: mix(bg, fg, coverage).
  • BJ_MASK_BG_REV_TRANSPARENT: carved-out mode where background is painted

◆ dst

bj_bitmap* dst
Creates a new bj_bitmap with the specified width and height.

Contrary to \ref bj_bitmap_new, the pixel data is explicitely provided
by the caller through `p_pixels`.
The caller is responsible for ensuring the allocated pixel data matches
`width, `height`, `mode` and `stride`.

/ / You can use bj_compute_bitmap_stride with width and mode to / retrieve the most suitable value for stride. / It's also possible to set stride to 0 and let Banjo compute it / automatically. / /

Parameters
p_pixelsA pre-allocated array of pixels /
widthWidth of the bitmap. /
heightHeight of the bitmap. /
modeThe pixel mode. /
strideThe suggested bitmap stride. /
Returns
A new instance of bj_bitmap. / /
Behaviour
/ / Returns 0 if p_pixels is 0. / /
Memory Management
/ / The caller is responsible for the memory management of p_pixels. / bj_bitmap will not modify it and it will not be released upon calling / bj_bitmap_del. / / The caller is responsible for releasing the bitmap using bj_bitmap_del. / ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_new_from_pixels( void* p_pixels, size_t width, size_t height, bj_pixel_mode mode, size_t stride );

////////////////////////////////////////////////////////////////////////////// / Creates a new bj_bitmap by copying p_bitmap. / /

Parameters
p_bitmapThe source bitmap. / /
Returns
A pointer to the newly created bj_bitmap object. / / The new bitmap will have exactly the same properties than the source bitmap. / /
Memory Management
/ / The caller is responsible from releasing the bitmap using / bj_bitmap_del. / / If p_source was initially created using bj_bitmap_new_from_pixels, / the "weak" property of the bitmap is not maintained in the new bitmap and / the caller is not responsible for manually releasing its pixel data. / ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_copy( const bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Creates a new bj_bitmap by converting p_bitmap. / /

Parameters
p_bitmapThe source bitmap. /
modeThe new pixel mode. / /
Returns
A pointer to the newly created bj_bitmap object. / / The new bitmap is provided by creating a new empty bitmap matching source's / width and height, but using mode as pixel mode. / The pixels are then converted to fill-in the new buffer. / /
Behaviour
/ / Returns bj_bitmap_copy(p_bitmap) if mode == bj_bitmap_mode(p_bitmap). / / Returns 0 if mode is BJ_PIXEL_MODE_UNKNOWN or an unsupported value. / /
Memory Management
/ / The caller is responsible from releasing the bitmap using / bj_bitmap_del. / / If p_bitmap was initially created using bj_bitmap_new_from_pixels, / the "weak" property of the bitmap is not maintained in the new bitmap and / the caller is not responsible for manually releasing its pixel data. / ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_convert( const bj_bitmap* p_bitmap, bj_pixel_mode mode );

////////////////////////////////////////////////////////////////////////////// / Initializes a new bj_bitmap with the specified width and height. / /

Parameters
p_bitmapThe bitmap object. /
p_pixelsThe pixel buffer data. /
widthWidth of the bitmap. /
heightHeight of the bitmap. /
modeThe pixel mode. /
strideThe suggested bitmap stride. / / If the pixel buffer provided by p_pixels is 0, the buffer will allocate / /
Returns
A pointer to the newly created bj_bitmap object. / / The stride corresponds to the size in bytes of a row. / If the value is less than the required stride, the actual minimum stride / is used. ////////////////////////////////////////////////////////////////////////////// bj_bitmap* bj_bitmap_init( bj_bitmap* p_bitmap, void* p_pixels, size_t width, size_t height, bj_pixel_mode mode, size_t stride );

////////////////////////////////////////////////////////////////////////////// / Resets a bj_bitmap object making it ready for a new init or free. / /

Parameters
p_bitmapPointer to the bj_bitmap object to reset. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_reset( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the underlying pixels data for direct access. / /

Parameters
p_bitmapThe bitmap object. /
Returns
The buffer data. ////////////////////////////////////////////////////////////////////////////// void* bj_bitmap_pixels( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the width of the given bitmap / /

Parameters
p_bitmapThe bitmap object. /
Returns
The bitmap width as number of pixels. ////////////////////////////////////////////////////////////////////////////// size_t bj_bitmap_width( const bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the height of the given bitmap / /

Parameters
p_bitmapThe bitmap object. /
Returns
The bitmap height as number of pixels. ////////////////////////////////////////////////////////////////////////////// size_t bj_bitmap_height( const bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the pixel mode of the given bitmap / /

Parameters
p_bitmapThe bitmap object. /
Returns
The bitmap pixel mode. ////////////////////////////////////////////////////////////////////////////// int bj_bitmap_mode( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Get the number of bytes in a row of pixel data, including the padding. / /

Parameters
p_bitmapThe bitmap object. /
Returns
The bitmap stride ////////////////////////////////////////////////////////////////////////////// size_t bj_bitmap_stride( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Gets the RGB value of a pixel given its 32-bits representation. / /

Parameters
p_bitmapThe bitmap object /
xThe X coordinate of the pixel. /
yThe Y coordinate of the pixel. /
p_redA location to the red component /
p_greenA location to the green component /
p_blueA location to the blue component / ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_rgb( const bj_bitmap* p_bitmap, size_t x, size_t y, uint8_t* p_red, uint8_t* p_green, uint8_t* p_blue );

////////////////////////////////////////////////////////////////////////////// / Returns an opaque value representing a pixel color, given its RGB composition. / /

Parameters
p_bitmapThe bitmap object. /
redThe red component of the color /
greenThe green component of the color /
blueThe blue component of the color /
Returns
An opaque uint32_t value. / ////////////////////////////////////////////////////////////////////////////// uint32_t bj_bitmap_pixel_value( bj_bitmap* p_bitmap, uint8_t red, uint8_t green, uint8_t blue );

////////////////////////////////////////////////////////////////////////////// / Change the pixel color at given coordinate. / /

Parameters
p_bitmapThe bitmap object. /
xThe X coordinate of the pixel. /
yThe Y coordinate of the pixel. /
valueThe pixel value to put. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_put_pixel( bj_bitmap* p_bitmap, size_t x, size_t y, uint32_t value );

////////////////////////////////////////////////////////////////////////////// / Fills the entire bitmap with the clear color. / /

Parameters
p_bitmapThe bitmap object to reset. / / The clear color can be set with bj_bitmap_set_clear_color. / This function effectively fills all the pixels of the bitmap with / the clear color. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_clear( bj_bitmap* p_bitmap );

////////////////////////////////////////////////////////////////////////////// / Enables or disables color key transparency for blitting. / /

Parameters
p_bitmapThe target bitmap. /
enabledWhether the color key should be enabled. /
key_valueThe pixel value (in bitmap's native format) considered transparent. / / When color keying is enabled on the source bitmap, blitters skip any / source pixel equal to key_value. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_set_colorkey( bj_bitmap* p_bitmap, bj_bool enabled, uint32_t key_value );

////////////////////////////////////////////////////////////////////////////// / Gets the color of a bitmap pixel, given its coordinates. / /

Parameters
p_bitmapThe bitmap object. /
xThe X coordinate of the pixel. /
yThe Y coordinate of the pixel. /
Returns
The color at (x, y). / /
Memory Safety
/ / This function does not perform any bound checking on the pixel coordinates. / It is up to you to ensure the coordinates lie between / [0, bj_bitmap->width * bj_bitmap->height]. / Writing outside of these bounds will result in undefined behavior or / corrupted memory access. ////////////////////////////////////////////////////////////////////////////// uint32_t bj_bitmap_get( const bj_bitmap* p_bitmap, size_t x, size_t y );

////////////////////////////////////////////////////////////////////////////// / Sets the color used for clearing the bitmap. / /

Parameters
p_bitmapThe target bitmap. /
clear_colorThe new clear color. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_set_clear_color( bj_bitmap* p_bitmap, uint32_t clear_color );

////////////////////////////////////////////////////////////////////////////// / Bitmap blitting operation from a source to a destination bitmap. / /

Parameters
srcThe source bitmap. /
src_areaOptional area to copy from in the source bitmap (0 = full source). /
dstThe destination bitmap. /
dst_areaOptional area to copy to in the destination bitmap (0 = same size at {0,0}). /
opThe raster operation to apply (see bj_blit_op). /
Returns
BJ_TRUE if a blit actually happened, BJ_FALSE otherwise. / / If src_area is 0, the entire source is copied. / If dst_area is 0, the destination area defaults to {.x=0,.y=0,.w=src_area.w,.h=src_area.h}. / /
Clipping
/ / The blit is automatically clipped to the destination bounds. If clipping / occurs, the source area is adjusted accordingly to preserve pixel mapping. / /
Color Key
/ / If the source bitmap has color keying enabled via bj_bitmap_set_colorkey, / any source pixel equal to the key value is skipped. / /
Pixel Formats
/ / - If src->mode == dst->mode and op == BJ_BLIT_OP_COPY, a fast path is used. / - Otherwise, pixels are converted via RGB and the ROP is applied per channel. / /
Limitations
/ / Sub-byte formats (1/4/8bpp) are supported but may be slower due to bit packing. / ////////////////////////////////////////////////////////////////////////////// bj_bool bj_bitmap_blit( const bj_bitmap* src, const bj_rect* src_area, bj_bitmap* dst, const bj_rect* dst_area, bj_blit_op op);

////////////////////////////////////////////////////////////////////////////// / Stretched bitmap blitting (nearest neighbor). / /

Parameters
srcThe source bitmap. /
src_areaOptional area to copy from in the source bitmap (0 = full source). /
dstThe destination bitmap. /
dst_areaOptional area to copy to in the destination bitmap (0 = full destination). /
opThe raster operation to apply (see bj_blit_op). /
Returns
BJ_TRUE if a blit actually happened, BJ_FALSE otherwise. / / If source and destination rectangles have the same size, this function / delegates to bj_bitmap_blit and uses the same fast paths. / /
Clipping
/ / The destination rectangle is clipped to the destination bounds, and the / source rectangle is proportionally adjusted to ensure visual consistency. / /
Color Key
/ / Color keying on the source bitmap is honored (see bj_bitmap_set_colorkey). / ////////////////////////////////////////////////////////////////////////////// bj_bool bj_bitmap_blit_stretched( const bj_bitmap* src, const bj_rect* src_area, bj_bitmap* dst, const bj_rect* dst_area, bj_blit_op op);

////////////////////////////////////////////////////////////////////////////// / Mask background mode for masked blits (glyph/text rendering). / /

Modes
/ - BJ_MASK_BG_TRANSPARENT: / Only the foreground is drawn where the mask coverage > 0. Destination / pixels outside the mask are preserved (no background fill). / - BJ_MASK_BG_OPAQUE: / The entire destination rectangle is written as a blend between the / background color (where mask coverage is 0) and the foreground color / (where mask coverage is 255), with linear interpolation for values in / between. / - BJ_MASK_BG_REV_TRANSPARENT: / Carved mode. The background color is composited where the mask coverage / is outside the glyph (i.e., with alpha = 1 - coverage). Pixels inside / the glyph (coverage=255) keep the destination value, effectively cutting / the text out of the background. / typedef enum { BJ_MASK_BG_TRANSPARENT = 0, //!< Foreground over destination where mask>0 BJ_MASK_BG_OPAQUE, //!< Opaque band: mix(background, foreground, mask) BJ_MASK_BG_REV_TRANSPARENT //!< Carved: mix(destination, background, 1-mask) } bj_mask_bg_mode;

////////////////////////////////////////////////////////////////////////////// / Masked blit (non-stretched). The mask must be 8bpp (coverage 0..255). / /

Parameters
maskThe 8bpp mask bitmap (0 = fully transparent, 255 = fully opaque). /
mask_areaOptional area in the mask to use (0 = full mask). /
dstThe destination bitmap. /
dst_areaOptional destination area (0 = place at {0,0} with mask_area size). /
fg_nativeForeground color packed in the destination's native format. /
bg_nativeBackground color packed in the destination's native format. /
modeThe background mode (see bj_mask_bg_mode). /
Returns
BJ_TRUE if any pixel was written, BJ_FALSE otherwise. / /
Behavior
/ / - For BJ_MASK_BG_TRANSPARENT, foreground is source-over composited / onto destination wherever the mask is non-zero. / - For BJ_MASK_BG_OPAQUE, each pixel in the dest area is mix(bg, fg, mask). / - For BJ_MASK_BG_REV_TRANSPARENT, the background is composited with / alpha (1 - mask) and glyph interiors are left untouched. / /
Pixel Formats
/ / The mask must be 8 bits per pixel. Destination can be any supported pixel / mode; colors must be provided in destination-native format (see / bj_bitmap_pixel_value). / /
Clipping
/ / The destination area is clipped to the destination bounds. The mask area / is clipped to the mask bounds. Both rectangles must have identical sizes. / ////////////////////////////////////////////////////////////////////////////// bj_bool bj_bitmap_blit_mask( const bj_bitmap* mask, const bj_rect* mask_area, /* NULL = full mask