Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Bitmap
Collaboration diagram for Bitmap:

Topics

 Drawing
 Pixel Definition
 Shaders

Typedefs

typedef enum bj_blit_op bj_blit_op

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
}
enum  bj_bitmap_color_role { BJ_BITMAP_CLEAR_COLOR = (1 << 0) , BJ_BITMAP_COLORKEY = (1 << 1) }
enum  bj_mask_bg_mode { BJ_MASK_BG_TRANSPARENT = 0 , BJ_MASK_BG_OPAQUE , BJ_MASK_BG_REV_TRANSPARENT }
enum  bj_text_halign { BJ_TEXT_HALIGN_LEFT , BJ_TEXT_HALIGN_CENTER , BJ_TEXT_HALIGN_RIGHT }
enum  bj_text_valign { BJ_TEXT_VALIGN_TOP , BJ_TEXT_VALIGN_CENTER , BJ_TEXT_VALIGN_BOTTOM }

Functions

struct bj_bitmap * bj_allocate_bitmap (void)
struct bj_bitmap * bj_create_bitmap (size_t width, size_t height, enum bj_pixel_mode mode, size_t stride)
void bj_destroy_bitmap (struct bj_bitmap *bitmap)
struct bj_bitmap * bj_create_bitmap_from_file (const char *path, struct bj_error **error)
struct bj_bitmap * bj_create_bitmap_from_stream (struct bj_stream *stream, struct bj_error **error)
struct bj_bitmap * bj_create_bitmap_from_pixels (void *pixels, size_t width, size_t height, enum bj_pixel_mode mode, size_t stride)
struct bj_bitmap * bj_copy_bitmap (const struct bj_bitmap *bitmap)
struct bj_bitmap * bj_convert_bitmap (const struct bj_bitmap *bitmap, enum bj_pixel_mode mode)
struct bj_bitmap * bj_init_bitmap (struct bj_bitmap *bitmap, void *pixels, size_t width, size_t height, enum bj_pixel_mode mode, size_t stride)
void bj_assign_bitmap (struct bj_bitmap *bitmap, void *pixels, size_t width, size_t height, enum bj_pixel_mode mode, size_t stride)
void bj_reset_bitmap (struct bj_bitmap *bitmap)
void * bj_bitmap_pixel_data (struct bj_bitmap *bitmap)
void * bj_bitmap_pixels (struct bj_bitmap *bitmap)
size_t bj_bitmap_width (const struct bj_bitmap *bitmap)
size_t bj_bitmap_height (const struct bj_bitmap *bitmap)
int bj_bitmap_mode (const struct bj_bitmap *bitmap)
size_t bj_bitmap_stride (const struct bj_bitmap *bitmap)
void bj_bitmap_pixel_rgb (const struct bj_bitmap *bitmap, size_t x, size_t y, uint8_t *red, uint8_t *green, uint8_t *blue)
void bj_make_bitmap_rgb (const struct bj_bitmap *bitmap, size_t x, size_t y, uint8_t *red, uint8_t *green, uint8_t *blue)
uint32_t bj_pack_bitmap_rgb (struct bj_bitmap *bitmap, uint8_t red, uint8_t green, uint8_t blue)
uint32_t bj_make_bitmap_pixel (struct bj_bitmap *bitmap, uint8_t red, uint8_t green, uint8_t blue)
void bj_put_pixel (struct bj_bitmap *bitmap, size_t x, size_t y, uint32_t value)
void bj_clear_bitmap (struct bj_bitmap *bitmap)
void bj_set_bitmap_clear_color (struct bj_bitmap *bitmap, uint32_t color)
void bj_set_bitmap_colorkey (struct bj_bitmap *bitmap, uint32_t color)
void bj_set_bitmap_color (struct bj_bitmap *bitmap, uint32_t color, uint8_t roles)
void bj_enable_bitmap_colorkey (struct bj_bitmap *bitmap)
void bj_disable_bitmap_colorkey (struct bj_bitmap *bitmap)
void bj_enable_colorkey (struct bj_bitmap *bitmap, bj_bool enabled)
uint32_t bj_bitmap_pixel (const struct bj_bitmap *bitmap, size_t x, size_t y)
bj_bool bj_blit_bitmap (const struct bj_bitmap *src, const struct bj_rect *src_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, enum bj_blit_op op)
bj_bool bj_blit (const struct bj_bitmap *src, const struct bj_rect *src_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, enum bj_blit_op op)
bj_bool bj_blit_bitmap_stretched (const struct bj_bitmap *src, const struct bj_rect *src_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, enum bj_blit_op op)
bj_bool bj_blit_stretched (const struct bj_bitmap *src, const struct bj_rect *src_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, enum bj_blit_op op)
bj_bool bj_blit_bitmap_mask (const struct bj_bitmap *mask, const struct bj_rect *mask_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, uint32_t fg_native, uint32_t bg_native, bj_mask_bg_mode mode)
bj_bool bj_blit_mask (const struct bj_bitmap *mask, const struct bj_rect *mask_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, uint32_t fg_native, uint32_t bg_native, bj_mask_bg_mode mode)
bj_bool bj_blit_bitmap_mask_stretched (const struct bj_bitmap *mask, const struct bj_rect *mask_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, uint32_t fg_native, uint32_t bg_native, bj_mask_bg_mode mode)
bj_bool bj_blit_mask_stretched (const struct bj_bitmap *mask, const struct bj_rect *mask_area, struct bj_bitmap *dst, const struct bj_rect *dst_area, uint32_t fg_native, uint32_t bg_native, bj_mask_bg_mode mode)
unsigned bj_measure_text (const char *text, unsigned height)
void bj_draw_text (struct bj_bitmap *dst, unsigned height, struct bj_rect area, bj_text_halign halign, bj_text_valign valign, uint32_t fg_native, const char *text)
void bj_draw_textf (struct bj_bitmap *dst, unsigned height, struct bj_rect area, bj_text_halign halign, bj_text_valign valign, uint32_t fg_native, const char *fmt,...)
void bj_blit_text (struct bj_bitmap *dst, unsigned height, struct bj_rect area, bj_text_halign halign, bj_text_valign valign, uint32_t fg_native, uint32_t bg_native, bj_mask_bg_mode mode, const char *text)

Detailed Description

Pictures in memory: load them, draw into them, copy them onto each other.

A bitmap is a rectangle of pixels stored in your program's memory. Banjo represents it as bj_bitmap, which carries the width and height of the rectangle, the format of each pixel (how many bits, which channel is red, etc.; see Pixel Definition), and the actual bytes. You use bitmaps for two related things: holding images loaded from disk (sprites, backgrounds, fonts), and as the framebuffer: the picture-in-memory your draw callback writes into before banjo presents it to the window.

Where bitmaps come from

In all cases you eventually release them with bj_destroy_bitmap (except the framebuffer, which the window owns).

"Blit": copy a rectangle of pixels from one bitmap to another

"Blit" is short for BLock Image Transfer, and it means: take some pixels from one bitmap (the source) and put them into another (the destination). It's the fundamental operation for composing scenes: putting a sprite on a background, drawing a tile from a tile sheet, putting text on the screen.

Banjo offers four flavours, all the same idea with one extra twist each:

  • bj_blit_bitmap - straight rectangle-to-rectangle copy, source and destination same size.
  • bj_blit_bitmap_stretched - same but the destination rectangle can be a different size; the source is scaled to fit.
  • bj_blit_bitmap_mask - paint a foreground and a background colour through an 8-bit coverage mask, such as a glyph; this is how text is drawn.
  • bj_blit_bitmap_mask_stretched - the same, with the mask scaled to the destination area.

For the classic sprite trick of a "transparent" colour that is skipped, set a colour key on the source with bj_set_bitmap_colorkey.

Plus bj_draw_text and bj_blit_text for text rendering using Banjo's built-in 8×8 font, and Drawing for filled shapes (lines, circles, rectangles, triangles).

A note on colour values

Different bitmaps can store pixels in different formats (24-bit RGB, 16-bit packed, 8-bit indexed palette, …). A hard-coded 0x00FF0000 "red" only means red in 32-bit RGB; in other formats it's something else entirely. So Banjo's drawing functions take pre-packed uint32_t values, and you build them with bj_pack_bitmap_rgb which asks the bitmap to pack (R, G, B) triples into its own native format. That way the same drawing code works whatever the destination format is.

See also
Pixel Definition for the pixel-format encoding, Drawing for shapes (lines, circles, rectangles, …), Bitmap for getting a window's framebuffer.

Typedef Documentation

◆ bj_blit_op

typedef enum bj_blit_op bj_blit_op

Definition at line 107 of file bitmap.h.

Enumeration Type Documentation

◆ bj_bitmap_color_role

Deprecated
The role mask went away with bj_set_bitmap_color; use bj_set_bitmap_clear_color and bj_set_bitmap_colorkey. Removed in 2.0.
Enumerator
BJ_BITMAP_CLEAR_COLOR 

Clear/fill colour for bj_clear_bitmap()

BJ_BITMAP_COLORKEY 

Transparency key for blitting (auto-enables)

Definition at line 115 of file bitmap.h.

◆ bj_blit_op

enum bj_blit_op

Raster operation (ROP) to apply during blitting.

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

Note
For mismatched pixel formats, colours 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)

Definition at line 98 of file bitmap.h.

◆ bj_mask_bg_mode

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 colour (where mask coverage is 0) and the foreground colour (where mask coverage is 255), with linear interpolation for values in between.
  • BJ_MASK_BG_REV_TRANSPARENT: Carved mode. The background colour 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.
Enumerator
BJ_MASK_BG_TRANSPARENT 

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)

Definition at line 708 of file bitmap.h.

◆ bj_text_halign

Horizontal alignment for text rendering.

Enumerator
BJ_TEXT_HALIGN_LEFT 

Align text to the left edge of the area.

BJ_TEXT_HALIGN_CENTER 

Center text horizontally within the area.

BJ_TEXT_HALIGN_RIGHT 

Align text to the right edge of the area.

Definition at line 717 of file bitmap.h.

◆ bj_text_valign

Vertical alignment for text rendering.

Enumerator
BJ_TEXT_VALIGN_TOP 

Align text to the top edge of the area.

BJ_TEXT_VALIGN_CENTER 

Center text vertically within the area.

BJ_TEXT_VALIGN_BOTTOM 

Align text to the bottom edge of the area.

Definition at line 726 of file bitmap.h.

Function Documentation

◆ bj_allocate_bitmap()

struct bj_bitmap * bj_allocate_bitmap ( void )
Deprecated
Low-level primitive with no public replacement; use bj_create_bitmap / bj_destroy_bitmap. Removed in 2.0.

◆ bj_assign_bitmap()

void bj_assign_bitmap ( struct bj_bitmap * bitmap,
void * pixels,
size_t width,
size_t height,
enum bj_pixel_mode mode,
size_t stride )
Deprecated
Low-level primitive with no public replacement; see bj_init_bitmap. Removed in 2.0.

◆ bj_bitmap_height()

size_t bj_bitmap_height ( const struct bj_bitmap * bitmap)

Get the height of the given bitmap.

Parameters
bitmapThe bitmap object, or 0.
Returns
The bitmap height as number of pixels, or 0 if bitmap is 0.
Examples
load_bmp.c.

Referenced by setup().

◆ bj_bitmap_mode()

int bj_bitmap_mode ( const struct bj_bitmap * bitmap)

Get the pixel mode of the given bitmap.

Parameters
bitmapThe bitmap object, or 0.
Returns
The bitmap pixel mode, or BJ_PIXEL_MODE_UNKNOWN if bitmap is 0.
Examples
random_distribution.c.

Referenced by darken_color().

◆ bj_bitmap_pixel()

uint32_t bj_bitmap_pixel ( const struct bj_bitmap * bitmap,
size_t x,
size_t y )

Gets the colour of a bitmap pixel, given its coordinates.

Parameters
bitmapThe bitmap object, or 0.
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
Returns
The colour at (x, y), or 0 if bitmap is 0 or (x, y) lies outside the bitmap.

◆ bj_bitmap_pixel_data()

void * bj_bitmap_pixel_data ( struct bj_bitmap * bitmap)

Reach the bitmap's raw pixel buffer for direct access.

Parameters
bitmapThe bitmap object, or 0.
Returns
A pointer to the first byte of pixel data, or 0 if bitmap is 0 or empty.

◆ bj_bitmap_pixel_rgb()

void bj_bitmap_pixel_rgb ( const struct bj_bitmap * bitmap,
size_t x,
size_t y,
uint8_t * red,
uint8_t * green,
uint8_t * blue )

Read the pixel at (x, y) as separate R, G, B components.

Parameters
bitmapThe bitmap object, or 0, which writes nothing.
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
[out]redThe red component, or 0 to skip it.
[out]greenThe green component, or 0 to skip it.
[out]blueThe blue component, or 0 to skip it.

◆ bj_bitmap_pixels()

void * bj_bitmap_pixels ( struct bj_bitmap * bitmap)
Deprecated
Renamed to bj_bitmap_pixel_data. Removed in 2.0.

◆ bj_bitmap_stride()

size_t bj_bitmap_stride ( const struct bj_bitmap * bitmap)

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

Parameters
bitmapThe bitmap object, or 0.
Returns
The bitmap stride, or 0 if bitmap is 0.

◆ bj_bitmap_width()

size_t bj_bitmap_width ( const struct bj_bitmap * bitmap)

Get the width of the given bitmap.

Parameters
bitmapThe bitmap object, or 0.
Returns
The bitmap width as number of pixels, or 0 if bitmap is 0.
Examples
load_bmp.c.

Referenced by setup().

◆ bj_blit()

bj_bool bj_blit ( const struct bj_bitmap * src,
const struct bj_rect * src_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
enum bj_blit_op op )
Deprecated
Renamed to bj_blit_bitmap. Removed in 2.0.

◆ bj_blit_bitmap()

bj_bool bj_blit_bitmap ( const struct bj_bitmap * src,
const struct bj_rect * src_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
enum bj_blit_op op )

Bitmap blitting operation from a source to a destination bitmap.

Parameters
srcThe source bitmap, or 0, which blits nothing.
src_areaOptional area to copy from in the source bitmap (0 = full source).
dstThe destination bitmap, or 0, which blits nothing.
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}. Otherwise only the position of dst_area is used: the copied area keeps the size of the source area.

Clipping

The blit is automatically clipped to the destination bounds. If clipping occurs, the source area is adjusted accordingly to preserve pixel mapping.

Colour Key

If the source bitmap has colour keying enabled via bj_set_bitmap_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.

Examples
bitmap_blit.c, bitmap_blit_colorkey.c, and sprite_animation.c.

Referenced by on_draw(), on_draw(), on_draw(), setup(), and setup().

◆ bj_blit_bitmap_mask()

bj_bool bj_blit_bitmap_mask ( const struct bj_bitmap * mask,
const struct bj_rect * mask_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
uint32_t fg_native,
uint32_t bg_native,
bj_mask_bg_mode 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 colour packed in the destination's native format.
bg_nativeBackground colour packed in the destination's native format.
modeThe background mode (see bj_mask_bg_mode).
Returns
BJ_TRUE if the clipped areas are not empty and the blit ran, BJ_FALSE if nothing is visible, a bitmap is 0, the mask is not 8 bits per pixel or the areas differ in size.
Behaviour
  • 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; colours must be provided in destination-native format (see bj_pack_bitmap_rgb).

Clipping

Both rectangles must have identical sizes, as requested. The mask area is then clipped to the mask bounds and the destination area to the destination bounds, each clip cutting the other area by the same amount, so the mask stays aligned with the destination.

◆ bj_blit_bitmap_mask_stretched()

bj_bool bj_blit_bitmap_mask_stretched ( const struct bj_bitmap * mask,
const struct bj_rect * mask_area,
struct bj_bitmap * dst,
const struct 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.

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 colour packed for destination.
bg_nativeBackground colour packed for destination.
modeThe background mode (see bj_mask_bg_mode).
Returns
BJ_TRUE if the clipped destination area is not empty and the blit ran, BJ_FALSE if nothing is visible, a bitmap is 0 or the mask is not 8 bits per pixel.
Clipping & Mapping

The mask area is mapped onto the destination area as requested, and only the destination area is clipped, to the destination bounds: a clipped edge shows the matching part of the scaled mask, and destination pixels that map outside the mask are left unchanged.

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, rounded to the nearest integer.

◆ bj_blit_bitmap_stretched()

bj_bool bj_blit_bitmap_stretched ( const struct bj_bitmap * src,
const struct bj_rect * src_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
enum bj_blit_op op )

Stretched bitmap blitting (nearest neighbor).

Parameters
srcThe source bitmap, or 0, which blits nothing.
src_areaOptional area to copy from in the source bitmap (0 = full source).
dstThe destination bitmap, or 0, which blits nothing.
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_blit_bitmap 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. Destination pixels that map outside the source bitmap are left unchanged.

Colour Key

Colour keying on the source bitmap is honored (see bj_set_bitmap_colorkey).

Examples
bitmap_blit_colorkey.c, drawing_2d.c, load_bmp.c, maze.c, and sprite_animation.c.

Referenced by on_draw(), on_draw(), on_draw(), on_draw(), and setup().

◆ bj_blit_mask()

bj_bool bj_blit_mask ( const struct bj_bitmap * mask,
const struct bj_rect * mask_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
uint32_t fg_native,
uint32_t bg_native,
bj_mask_bg_mode mode )
Deprecated
Renamed to bj_blit_bitmap_mask. Removed in 2.0.

◆ bj_blit_mask_stretched()

bj_bool bj_blit_mask_stretched ( const struct bj_bitmap * mask,
const struct bj_rect * mask_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
uint32_t fg_native,
uint32_t bg_native,
bj_mask_bg_mode mode )
Deprecated
Renamed to bj_blit_bitmap_mask_stretched. Removed in 2.0.

◆ bj_blit_stretched()

bj_bool bj_blit_stretched ( const struct bj_bitmap * src,
const struct bj_rect * src_area,
struct bj_bitmap * dst,
const struct bj_rect * dst_area,
enum bj_blit_op op )
Deprecated
Renamed to bj_blit_bitmap_stretched. Removed in 2.0.

◆ bj_blit_text()

void bj_blit_text ( struct bj_bitmap * dst,
unsigned height,
struct bj_rect area,
bj_text_halign halign,
bj_text_valign valign,
uint32_t fg_native,
uint32_t bg_native,
bj_mask_bg_mode mode,
const char * text )

Prints text with explicit foreground/background and background mode.

Parameters
dstThe destination bitmap, or 0, which draws nothing.
heightTarget font height in pixels.
areaTarget area for text placement and alignment.
halignHorizontal alignment within the area.
valignVertical alignment within the area.
fg_nativeForeground colour in destination-native format.
bg_nativeBackground colour in destination-native format.
modeBackground mode (see bj_mask_bg_mode).
textASCII string with optional ANSI SGR sequences, whose characters draw as in bj_draw_text, or 0, which draws nothing.
ANSI Colour 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 colours
    • 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 with alpha = (1 - coverage) and glyph interiors remain untouched.
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.

Performance

The glyph mask atlas is cached per destination bitmap. Rendering uses nearest-neighbor scaling and an inner loop with integer blending.

Todo
This function does not yet enforce UTF-8 on text. Per ADR 0008, it will.
Examples
drawing_text.c.

Referenced by draw().

◆ bj_clear_bitmap()

void bj_clear_bitmap ( struct bj_bitmap * bitmap)

Fills the entire bitmap with the clear colour.

Parameters
bitmapThe bitmap object to reset, or 0, which does nothing.

The clear colour is set with bj_set_bitmap_clear_color (default black). This function fills every pixel of the bitmap with it.

Examples
bitmap_blit.c, drawing_2d.c, interpolation.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, sprite_animation.c, and start.c.

Referenced by draw(), draw(), draw(), draw(), draw(), draw_maze(), on_draw(), on_draw(), setup(), and setup().

◆ bj_convert_bitmap()

struct bj_bitmap * bj_convert_bitmap ( const struct bj_bitmap * bitmap,
enum bj_pixel_mode mode )

Creates a new struct bj_bitmap by converting bitmap.

Parameters
bitmapThe source bitmap, or 0.
modeThe new pixel mode.
Returns
A pointer to the newly created struct bj_bitmap object, or 0 if bitmap is 0.

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_copy_bitmap(bitmap) if mode == bj_bitmap_mode(bitmap).

Returns 0 if mode is BJ_PIXEL_MODE_UNKNOWN or an unsupported value.

A bitmap of an indexed mode has no palette to give or take colours, so converting to or from an indexed mode gives black pixels, of value 0.

Memory Management

The caller is responsible from releasing the bitmap using bj_destroy_bitmap.

If bitmap was initially created using bj_create_bitmap_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_copy_bitmap()

struct bj_bitmap * bj_copy_bitmap ( const struct bj_bitmap * bitmap)

Creates a new struct bj_bitmap by copying bitmap.

Parameters
bitmapThe source bitmap, or 0.
Returns
A pointer to the newly created struct bj_bitmap object, or 0 if bitmap is 0 or memory runs out.

The new bitmap has the same size, pixel mode, stride, pixels, clear colour and colour key as the source bitmap.

Memory Management

The caller is responsible from releasing the bitmap using bj_destroy_bitmap.

If bitmap was initially created using bj_create_bitmap_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_create_bitmap()

struct bj_bitmap * bj_create_bitmap ( size_t width,
size_t height,
enum bj_pixel_mode mode,
size_t stride )

Creates a new struct bj_bitmap with the specified width and height.

Parameters
widthWidth of the bitmap.
heightHeight of the bitmap.
modeThe pixel mode.
strideThe suggested bitmap stride.
Returns
A pointer to the newly created struct bj_bitmap object, or 0 for a mode whose stride bj_compute_bitmap_stride gives as 0, such as BJ_PIXEL_MODE_UNKNOWN, for a width whose row does not fit a size_t, whatever stride, or when memory runs out.

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.

A width or a height of 0 gives an empty bitmap, which keeps its width, height, mode and stride, and has no pixel data: bj_bitmap_pixel_data returns 0 for it.

Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, maze.c, and sprite_animation.c.

Referenced by setup(), setup(), setup(), setup(), and setup().

◆ bj_create_bitmap_from_file()

struct bj_bitmap * bj_create_bitmap_from_file ( const char * path,
struct bj_error ** error )

Creates a new bitmap by loading from a file.

Parameters
pathPath to the bitmap file, or 0, which loads nothing and leaves error alone.
errorError location, or 0 to ignore failures.
Returns
A pointer to the newly created struct bj_bitmap object, or 0 if loading failed.

The new object must be deleted using bj_destroy_bitmap.

Pixel Mode

Banjo reads images of 1, 4, 8, 16, 24 and 32 bits per pixel, and the RLE compression of 4-bit and 8-bit images.

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 enum bj_pixel_mode
1 BI_RGB BJ_PIXEL_MODE_BGR24
4 BI_RGB BJ_PIXEL_MODE_BGR24
4 BI_RLE4 BJ_PIXEL_MODE_BGR24
8 BI_RGB BJ_PIXEL_MODE_BGR24
8 BI_RLE8 BJ_PIXEL_MODE_BGR24
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 enum bj_pixel_mode
16 0x00007C00 0x000003E0 0x0000001F BJ_PIXEL_MODE_XRGB1555
16 0x0000F800 0x000007E0 0x0000001F BJ_PIXEL_MODE_RGB565
32 0x00FF0000 0x0000FF00 0x000000FF BJ_PIXEL_MODE_XRGB8888

Other masks that do not overlap give a bitmap of mode BJ_PIXEL_MODE_UNKNOWN holding the file's rows unchanged, with the file's row size as stride; overlapping masks fail with BJ_ERROR_INVALID_FORMAT.

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

Edge cases
  • A file whose header calls for a colour palette but that contains none fails with BJ_ERROR_INVALID_FORMAT.
  • A pixel whose palette index lies outside the palette takes the palette's first colour, and a warning is logged.
  • In an RLE image, the pixels that a delta escape or an early end-of-bitmap marker skips take the palette's first colour.
Errors
  • The errors of opening the file, such as BJ_ERROR_FILE_NOT_FOUND.
  • BJ_ERROR_INVALID_DOMAIN for a header value out of range: a signature other than BM, an information header other than the 40-byte BITMAPINFOHEADER, a width or height of 0 or a pixel count past 32 bits, a plane count other than 1, a depth other than 1, 4, 8, 16, 24 and 32 bits, or RLE8 or RLE4 compression at a depth other than 8 or 4.
  • BJ_ERROR_INVALID_FORMAT for a part that is missing or inconsistent: a file that ends early, pixel data that does not start inside the file and right after the headers and palette, an unknown compression, a palette size out of range or a missing palette, bit fields at a depth other than 16 and 32 bits or overlapping, or RLE data that writes outside the image.
  • BJ_ERROR_CANNOT_ALLOCATE when memory runs out.
Limitations

Indexed images, of 1, 4 and 8 bits per pixel, RLE included, are converted to BJ_PIXEL_MODE_BGR24 through their palette, as the table shows.

See also
BMP file format (Wikipedia)
Bitmap Compression (MSDN)
Todo
This function does not yet enforce UTF-8 on path. Per ADR 0008, it will.
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, load_bmp.c, and sprite_animation.c.

Referenced by setup(), setup(), setup(), and setup().

◆ bj_create_bitmap_from_pixels()

struct bj_bitmap * bj_create_bitmap_from_pixels ( void * pixels,
size_t width,
size_t height,
enum bj_pixel_mode mode,
size_t stride )

Creates a new struct bj_bitmap with the specified width and height.

Contrary to bj_create_bitmap, the pixel data is explicitly provided by the caller through pixels. The caller is reponsible 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
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 pixels is 0, for a value of mode that is not a pixel mode, or for a width whose row does not fit a size_t, whatever stride. An empty bitmap, from a width or height of 0, or from a mode with no measured row size and a stride of 0, keeps its width, height, mode and stride and has no pixel data; a given stride stands for the row size of the modes that have no measured one.

Memory Management

The caller is responsible for the memory management of pixels. Creating the bitmap leaves pixels unchanged, drawing into the bitmap writes to them, and bj_destroy_bitmap does not release them.

The caller is responsible for releasing the bitmap using bj_destroy_bitmap.

◆ bj_create_bitmap_from_stream()

struct bj_bitmap * bj_create_bitmap_from_stream ( struct bj_stream * stream,
struct bj_error ** error )

Loads a BMP image from a stream into a new bitmap.

The image starts at the stream's cursor, so one stream can hold several, one after the other, or a BMP inside a bigger file. The decoding, the pixel modes and the errors are those of bj_create_bitmap_from_file.

On success, the cursor moves past the file size the BMP header declares, up to the end of the stream, where the next image would start. On failure, a stream that can seek keeps its cursor where it was. A stream that cannot seek, such as a TCP stream, is read for the file size the header declares.

Parameters
streamThe stream, which stays yours, or 0, which gives 0 and leaves error alone.
errorOptional error location.
Returns
A new bitmap, or 0.

◆ bj_destroy_bitmap()

void bj_destroy_bitmap ( struct bj_bitmap * bitmap)

Deletes a struct bj_bitmap object and releases associated memory.

Parameters
bitmapPointer to the struct bj_bitmap object to delete, or 0, which does nothing.
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, load_bmp.c, maze.c, and sprite_animation.c.

Referenced by setup(), setup(), teardown(), teardown(), teardown(), teardown(), teardown(), and teardown().

◆ bj_disable_bitmap_colorkey()

void bj_disable_bitmap_colorkey ( struct bj_bitmap * bitmap)

Turn colour keying off for this bitmap, keeping the key colour.

Parameters
bitmapThe target bitmap, or 0, which does nothing.

◆ bj_draw_text()

void bj_draw_text ( struct bj_bitmap * dst,
unsigned height,
struct bj_rect area,
bj_text_halign halign,
bj_text_valign valign,
uint32_t fg_native,
const char * text )

Prints text in a foreground colour over a transparent background.

Parameters
dstThe destination bitmap, or 0, which draws nothing.
heightTarget font height in pixels (glyphs are scaled from the internal font cell size to this height).
areaTarget area for text placement and alignment.
halignHorizontal alignment within the area.
valignVertical alignment within the area.
fg_nativeForeground colour in destination-native format.
textASCII string with optional ANSI SGR sequences (see below), or 0, which draws nothing.
Area and Alignment

The text is positioned within the specified area according to the alignment parameters. For simple left/top positioning (like the old x/y interface), use a zero-size rect: (struct bj_rect){x, y, 0, 0}.

ANSI Colour Formatting

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

  • \x1B[0m Reset colours to defaults.
  • \x1B[30..37m Set foreground to basic colours (black, red, green, yellow, blue, magenta, cyan, white).
  • \x1B[90..97m Set foreground to bright basic colours.
  • \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_blit_text for background control).
Behaviour

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; glyphs entirely outside them are skipped.

Characters

The built-in 8×8 font covers ASCII. Every byte from 0x80 up, such as each byte of a UTF-8 multi-byte character, draws as ?, and a newline draws as an empty glyph rather than starting a new line.

Todo
This function does not yet enforce UTF-8 on text. Per ADR 0008, it will.
Examples
drawing_text.c, and maze.c.

Referenced by draw(), and on_draw().

◆ bj_draw_textf()

void bj_draw_textf ( struct bj_bitmap * dst,
unsigned height,
struct bj_rect area,
bj_text_halign halign,
bj_text_valign valign,
uint32_t fg_native,
const char * fmt,
... )

Prints formatted text into a bitmap, similar to printf.

This function formats the full string using vsnprintf into a temporary buffer (heap-allocated), then renders it with bj_draw_text.

Parameters
dstThe destination bitmap, or 0, which draws nothing.
heightThe pixel height of the rendered font.
areaTarget area for text placement and alignment.
halignHorizontal alignment within the area.
valignVertical alignment within the area.
fg_nativeForeground colour in destination-native format.
fmtThe printf-style format string, or 0, which draws nothing.
...Additional arguments corresponding to the format string.
Supported formatting
Exactly the same as the C library printf (C99). All flags, width, precision (including *), length modifiers, and conversions are supported.
Note
This routine renders foreground only. For background or mask modes, use bj_blit_text (or provide a printf variant of it).
Todo
This function does not yet enforce UTF-8 on fmt and the strings it formats. Per ADR 0008, it will.
Examples
drawing_text.c, and random_distribution.c.

Referenced by draw().

◆ bj_enable_bitmap_colorkey()

void bj_enable_bitmap_colorkey ( struct bj_bitmap * bitmap)

Turn colour keying on for this bitmap (as a blit source).

The key colour itself is set with bj_set_bitmap_colorkey, which also enables keying; this is only needed to re-enable after a bj_disable_bitmap_colorkey.

Parameters
bitmapThe target bitmap, or 0, which does nothing.

◆ bj_enable_colorkey()

void bj_enable_colorkey ( struct bj_bitmap * bitmap,
bj_bool enabled )

◆ bj_init_bitmap()

struct bj_bitmap * bj_init_bitmap ( struct bj_bitmap * bitmap,
void * pixels,
size_t width,
size_t height,
enum bj_pixel_mode mode,
size_t stride )
Deprecated
Low-level primitive with no public replacement (a caller-owned bj_bitmap placed over your own pixels); use bj_create_bitmap / bj_create_bitmap_from_pixels. Removed in 2.0.

◆ bj_make_bitmap_pixel()

uint32_t bj_make_bitmap_pixel ( struct bj_bitmap * bitmap,
uint8_t red,
uint8_t green,
uint8_t blue )
Deprecated
Renamed to bj_pack_bitmap_rgb. Removed in 2.0.

◆ bj_make_bitmap_rgb()

void bj_make_bitmap_rgb ( const struct bj_bitmap * bitmap,
size_t x,
size_t y,
uint8_t * red,
uint8_t * green,
uint8_t * blue )
Deprecated
Renamed to bj_bitmap_pixel_rgb. Removed in 2.0.

◆ bj_measure_text()

unsigned bj_measure_text ( const char * text,
unsigned height )

Measures the pixel width of a text string at a given height.

Parameters
textASCII string (ANSI escape sequences are skipped), or 0, which measures 0.
heightTarget font height in pixels.
Returns
The width in pixels that the text would occupy when rendered.

This function counts visible characters (skipping ANSI escape sequences) and computes the total width including inter-glyph spacing: each glyph is as wide as height, and glyphs are 1 pixel apart.

Todo
This function does not yet enforce UTF-8 on text. Per ADR 0008, it will.

◆ bj_pack_bitmap_rgb()

uint32_t bj_pack_bitmap_rgb ( struct bj_bitmap * bitmap,
uint8_t red,
uint8_t green,
uint8_t blue )

Pack an (R, G, B) triple into the bitmap's native pixel format.

The returned value can be handed to bj_put_pixel, bj_set_bitmap_colorkey, the drawing functions, and so on.

Parameters
bitmapThe bitmap whose pixel format is used, or 0.
redThe red component.
greenThe green component.
blueThe blue component.
Returns
The packed, format-native pixel value, or 0 if bitmap is 0.
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, interpolation.c, maze.c, pixel_enumeration.c, pong.c, random_distribution.c, sprite_animation.c, and start.c.

Referenced by darken_color(), draw(), draw(), draw(), draw_maze(), on_draw(), on_draw(), on_draw(), on_draw(), setup(), setup(), setup(), and setup().

◆ bj_put_pixel()

void bj_put_pixel ( struct bj_bitmap * bitmap,
size_t x,
size_t y,
uint32_t value )

Change the pixel colour at given coordinate.

A position outside the bitmap leaves the bitmap unchanged.

Parameters
bitmapThe bitmap object, or 0, which does nothing.
xThe X coordinate of the pixel.
yThe Y coordinate of the pixel.
valueThe pixel value to put.
Examples
drawing_2d.c, physics_particle.c, and random_distribution.c.

Referenced by draw(), and draw().

◆ bj_reset_bitmap()

void bj_reset_bitmap ( struct bj_bitmap * bitmap)
Deprecated
Low-level primitive with no public replacement; use bj_destroy_bitmap. Removed in 2.0.

◆ bj_set_bitmap_clear_color()

void bj_set_bitmap_clear_color ( struct bj_bitmap * bitmap,
uint32_t color )

Set the colour bj_clear_bitmap fills with.

Parameters
bitmapThe target bitmap, or 0, which does nothing.
colorThe colour, packed in the bitmap's native format (see bj_pack_bitmap_rgb).
Examples
bitmap_blit.c, maze.c, random_distribution.c, and sprite_animation.c.

Referenced by on_draw(), setup(), setup(), and setup().

◆ bj_set_bitmap_color()

void bj_set_bitmap_color ( struct bj_bitmap * bitmap,
uint32_t color,
uint8_t roles )

◆ bj_set_bitmap_colorkey()

void bj_set_bitmap_colorkey ( struct bj_bitmap * bitmap,
uint32_t color )

Set the transparent colour used when this bitmap is a blit source, and enable colour keying.

During bj_blit_bitmap and bj_blit_bitmap_stretched, a source pixel equal to color is skipped. Only the bits that hold colour in the bitmap's mode are compared: not the unused top bits of BJ_PIXEL_MODE_XRGB8888 and BJ_PIXEL_MODE_XRGB1555, nor the bits past the size of a pixel. Setting the key turns keying on; toggle it later with bj_enable_bitmap_colorkey / bj_disable_bitmap_colorkey.

Parameters
bitmapThe target bitmap, or 0, which does nothing.
colorThe transparent colour, packed in the bitmap's native format.
Examples
bitmap_blit_colorkey.c.

Referenced by setup().