Banjo API 0.0.1
Multi-purpose C99 API
|
Matrix of pixels. More...
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_bitmap * | bj_bitmap_alloc (void) |
Allocate a new bitmap object. | |
bj_bitmap * | bj_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_bitmap * | bj_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_bitmap * | dst |
bj_bitmap const bj_rect * | dst_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. | |
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).
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 ) |
mask | The 8bpp mask bitmap (0..255 coverage). |
mask_area | Optional area in the mask (0 = full mask). |
dst | The destination bitmap. |
dst_area | Optional destination area (0 = full destination). |
fg_native | Foreground color packed for destination. |
bg_native | Background color packed for destination. |
mode | The background mode (see bj_mask_bg_mode). |
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.
Mask values are interpreted as linear coverage (0..255). Alpha blending uses integer arithmetic: mix(dst, src, a)
→ (dst*(255-a) + src*a)/255
.
void bj_bitmap_del | ( | bj_bitmap * | p_bitmap | ) |
p_bitmap | Pointer to the bj_bitmap object to delete. |
bj_bitmap * bj_bitmap_new | ( | size_t | width, |
size_t | height, | ||
bj_pixel_mode | mode, | ||
size_t | stride ) |
width | Width of the bitmap. |
height | Height of the bitmap. |
mode | The pixel mode. |
stride | The suggested bitmap stride. |
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.
p_path | Path to the bitmap file. |
p_error | Pointer to an error object to store any errors encountered during loading. |
The new object must be deleted using bj_bitmap_del.
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.
While reading indexed Bitmap works, 1, 4 and 8bpp images are automatically converted to 24bpp images for now.
void bj_bitmap_print | ( | bj_bitmap * | dst, |
int | x, | ||
int | y, | ||
unsigned | height, | ||
uint32_t | fg_native, | ||
const char * | text ) |
dst | The destination bitmap. |
x | X coordinate of the baseline origin. |
y | Y coordinate of the baseline origin. |
height | Target font height in pixels (glyphs are scaled from the internal font cell size to this height). |
fg_native | Foreground color in destination-native format. |
text | UTF-8/ASCII string with optional ANSI SGR sequences (see below). |
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.The function uses the internal monochrome font mask and performs a masked blit in transparent background mode (foreground over destination).
Text is clipped to the destination bounds. Out-of-range glyphs are skipped.
* with alpha |
dst | The destination bitmap. |
x | X coordinate of the baseline origin. |
y | Y coordinate of the baseline origin. |
height | Target font height in pixels. |
fg_native | Foreground color in destination-native format. |
bg_native | Background color in destination-native format. |
mode | Background mode (see bj_mask_bg_mode). |
text | UTF-8/ASCII string with optional ANSI SGR sequences. |
The string may embed standard SGR sequences following ‘ESC ’['`:
\x1B[0m
Reset both foreground and background to the defaults passed as fg_native
/bg_native
.\x1B[30..37m
(basic), \x1B[90..97m
(bright)\x1B[40..47m
(basic), \x1B[100..107m
(bright)\x1B[39m
Reset foreground to the call’s fg_native
.\x1B[49m
Reset background to the call’s bg_native
.\x1B[38;2;R;G;Bm
\x1B[48;2;R;G;Bm
Unsupported or malformed sequences are ignored gracefully.
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 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. / /
p_pixels | A pre-allocated array of pixels / |
width | Width of the bitmap. / |
height | Height of the bitmap. / |
mode | The pixel mode. / |
stride | The suggested bitmap stride. / |
p_pixels
is 0. / / 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
. / /
p_bitmap | The source bitmap. / / |
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
. / /
p_bitmap | The source bitmap. / |
mode | The new pixel mode. / / |
mode
as pixel mode. / The pixels are then converted to fill-in the new buffer. / / 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. / / 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. / /
p_bitmap | The bitmap object. / |
p_pixels | The pixel buffer data. / |
width | Width of the bitmap. / |
height | Height of the bitmap. / |
mode | The pixel mode. / |
stride | The suggested bitmap stride. / / If the pixel buffer provided by p_pixels is 0, the buffer will allocate / / |
////////////////////////////////////////////////////////////////////////////// / Resets a bj_bitmap object making it ready for a new init or free. / /
p_bitmap | Pointer to the bj_bitmap object to reset. ////////////////////////////////////////////////////////////////////////////// void bj_bitmap_reset( bj_bitmap* p_bitmap ); |
////////////////////////////////////////////////////////////////////////////// / Get the underlying pixels data for direct access. / /
p_bitmap | The bitmap object. / |
////////////////////////////////////////////////////////////////////////////// / Get the width of the given bitmap / /
p_bitmap | The bitmap object. / |
////////////////////////////////////////////////////////////////////////////// / Get the height of the given bitmap / /
p_bitmap | The bitmap object. / |
////////////////////////////////////////////////////////////////////////////// / Get the pixel mode of the given bitmap / /
p_bitmap | The bitmap object. / |
////////////////////////////////////////////////////////////////////////////// / Get the number of bytes in a row of pixel data, including the padding. / /
p_bitmap | The bitmap object. / |
////////////////////////////////////////////////////////////////////////////// / Gets the RGB value of a pixel given its 32-bits representation. / /
p_bitmap | The bitmap object / |
x | The X coordinate of the pixel. / |
y | The Y coordinate of the pixel. / |
p_red | A location to the red component / |
p_green | A location to the green component / |
p_blue | A 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. / /
p_bitmap | The bitmap object. / |
red | The red component of the color / |
green | The green component of the color / |
blue | The blue component of the color / |
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. / /
p_bitmap | The bitmap object. / |
x | The X coordinate of the pixel. / |
y | The Y coordinate of the pixel. / |
value | The 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. / /
p_bitmap | The 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. / /
p_bitmap | The target bitmap. / |
enabled | Whether the color key should be enabled. / |
key_value | The 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. / /
p_bitmap | The bitmap object. / |
x | The X coordinate of the pixel. / |
y | The Y coordinate of the pixel. / |
////////////////////////////////////////////////////////////////////////////// / Sets the color used for clearing the bitmap. / /
p_bitmap | The target bitmap. / |
clear_color | The 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. / /
src | The source bitmap. / |
src_area | Optional area to copy from in the source bitmap (0 = full source). / |
dst | The destination bitmap. / |
dst_area | Optional area to copy to in the destination bitmap (0 = same size at {0,0}). / |
op | The raster operation to apply (see bj_blit_op). / |
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}
. / / 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. / / ////////////////////////////////////////////////////////////////////////////// / Stretched bitmap blitting (nearest neighbor). / /
src | The source bitmap. / |
src_area | Optional area to copy from in the source bitmap (0 = full source). / |
dst | The destination bitmap. / |
dst_area | Optional area to copy to in the destination bitmap (0 = full destination). / |
op | The raster operation to apply (see bj_blit_op). / |
////////////////////////////////////////////////////////////////////////////// / Mask background mode for masked blits (glyph/text rendering). / /
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). / /
mask | The 8bpp mask bitmap (0 = fully transparent, 255 = fully opaque). / |
mask_area | Optional area in the mask to use (0 = full mask). / |
dst | The destination bitmap. / |
dst_area | Optional destination area (0 = place at {0,0} with mask_area size). / |
fg_native | Foreground color packed in the destination's native format. / |
bg_native | Background color packed in the destination's native format. / |
mode | The background mode (see bj_mask_bg_mode). / |
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. / /