|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
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) |
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.
bj_render_target_bitmap returns the window's framebuffer from inside a draw callback.In all cases you eventually release them with bj_destroy_bitmap (except the framebuffer, which the window owns).
"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:
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).
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.
| typedef enum bj_blit_op bj_blit_op |
| enum bj_bitmap_color_role |
| Enumerator | |
|---|---|
| BJ_BITMAP_CLEAR_COLOR | Clear/fill colour for bj_clear_bitmap() |
| BJ_BITMAP_COLORKEY | Transparency key for blitting (auto-enables) |
| 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).
| enum bj_mask_bg_mode |
Mask background mode for masked blits (glyph/text rendering).
| enum bj_text_halign |
| enum bj_text_valign |
| struct bj_bitmap * bj_allocate_bitmap | ( | void | ) |
| void bj_assign_bitmap | ( | struct bj_bitmap * | bitmap, |
| void * | pixels, | ||
| size_t | width, | ||
| size_t | height, | ||
| enum bj_pixel_mode | mode, | ||
| size_t | stride ) |
| size_t bj_bitmap_height | ( | const struct bj_bitmap * | bitmap | ) |
Get the height of the given bitmap.
| bitmap | The bitmap object, or 0. |
Referenced by setup().
| int bj_bitmap_mode | ( | const struct bj_bitmap * | bitmap | ) |
Get the pixel mode of the given bitmap.
| bitmap | The bitmap object, or 0. |
Referenced by darken_color().
| 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.
| bitmap | The bitmap object, or 0. |
| x | The X coordinate of the pixel. |
| y | The Y coordinate of the pixel. |
| void * bj_bitmap_pixel_data | ( | struct bj_bitmap * | bitmap | ) |
Reach the bitmap's raw pixel buffer for direct access.
| bitmap | The bitmap object, or 0. |
| 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.
| bitmap | The bitmap object, or 0, which writes nothing. | |
| x | The X coordinate of the pixel. | |
| y | The Y coordinate of the pixel. | |
| [out] | red | The red component, or 0 to skip it. |
| [out] | green | The green component, or 0 to skip it. |
| [out] | blue | The blue component, or 0 to skip it. |
| void * bj_bitmap_pixels | ( | struct bj_bitmap * | bitmap | ) |
| size_t bj_bitmap_stride | ( | const struct bj_bitmap * | bitmap | ) |
Get the number of bytes in a row of pixel data, including the padding.
| bitmap | The bitmap object, or 0. |
| size_t bj_bitmap_width | ( | const struct bj_bitmap * | bitmap | ) |
Get the width of the given bitmap.
| bitmap | The bitmap object, or 0. |
Referenced by setup().
| 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 | ( | 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.
| src | The source bitmap, or 0, which blits nothing. |
| src_area | Optional area to copy from in the source bitmap (0 = full source). |
| dst | The destination bitmap, or 0, which blits nothing. |
| 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). |
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.
The blit is automatically clipped to the destination bounds. If clipping occurs, the source area is adjusted accordingly to preserve pixel mapping.
If the source bitmap has colour keying enabled via bj_set_bitmap_colorkey, any source pixel equal to the key value is skipped.
Sub-byte formats (1/4/8bpp) are supported but may be slower due to bit packing.
Referenced by on_draw(), on_draw(), on_draw(), setup(), and setup().
| 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).
| 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 colour packed in the destination's native format. |
| bg_native | Background colour packed in the destination's native format. |
| mode | The background mode (see bj_mask_bg_mode). |
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).
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_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.
| 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 colour packed for destination. |
| bg_native | Background colour packed for destination. |
| mode | The background mode (see bj_mask_bg_mode). |
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.
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_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).
| src | The source bitmap, or 0, which blits nothing. |
| src_area | Optional area to copy from in the source bitmap (0 = full source). |
| dst | The destination bitmap, or 0, which blits nothing. |
| dst_area | Optional area to copy to in the destination bitmap (0 = full destination). |
| op | The raster operation to apply (see bj_blit_op). |
If source and destination rectangles have the same size, this function delegates to bj_blit_bitmap and uses the same fast paths.
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 keying on the source bitmap is honored (see bj_set_bitmap_colorkey).
Referenced by on_draw(), on_draw(), on_draw(), on_draw(), and setup().
| 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_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_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 ) |
| 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.
| dst | The destination bitmap, or 0, which draws nothing. |
| height | Target font height in pixels. |
| area | Target area for text placement and alignment. |
| halign | Horizontal alignment within the area. |
| valign | Vertical alignment within the area. |
| fg_native | Foreground colour in destination-native format. |
| bg_native | Background colour in destination-native format. |
| mode | Background mode (see bj_mask_bg_mode). |
| text | ASCII string with optional ANSI SGR sequences, whose characters draw as in bj_draw_text, or 0, which draws nothing. |
The string may embed standard SGR sequences following ‘ESC ’['`:
Unsupported or malformed sequences are ignored gracefully.
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.
The glyph mask atlas is cached per destination bitmap. Rendering uses nearest-neighbor scaling and an inner loop with integer blending.
text. Per ADR 0008, it will.Referenced by draw().
| void bj_clear_bitmap | ( | struct bj_bitmap * | bitmap | ) |
Fills the entire bitmap with the clear colour.
| bitmap | The 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.
Referenced by draw(), draw(), draw(), draw(), draw(), draw_maze(), on_draw(), on_draw(), setup(), and setup().
| 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.
| bitmap | The source bitmap, or 0. |
| mode | The new pixel mode. |
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.
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.
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.
Creates a new struct bj_bitmap by copying bitmap.
| bitmap | The source bitmap, or 0. |
The new bitmap has the same size, pixel mode, stride, pixels, clear colour and colour key as the source bitmap.
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.
| 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.
| 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.
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.
Referenced by setup(), setup(), setup(), setup(), and setup().
Creates a new bitmap by loading from a file.
| path | Path to the bitmap file, or 0, which loads nothing and leaves error alone. |
| error | Error location, or 0 to ignore failures. |
The new object must be deleted using bj_destroy_bitmap.
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.
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.
path. Per ADR 0008, it will.| 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.
| 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. |
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.
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.
| 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.
| stream | The stream, which stays yours, or 0, which gives 0 and leaves error alone. |
| error | Optional error location. |
| void bj_destroy_bitmap | ( | struct bj_bitmap * | bitmap | ) |
Deletes a struct bj_bitmap object and releases associated memory.
| bitmap | Pointer to the struct bj_bitmap object to delete, or 0, which does nothing. |
Referenced by setup(), setup(), teardown(), teardown(), teardown(), teardown(), teardown(), and teardown().
| void bj_disable_bitmap_colorkey | ( | struct bj_bitmap * | bitmap | ) |
Turn colour keying off for this bitmap, keeping the key colour.
| bitmap | The target bitmap, or 0, which does nothing. |
| 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.
| dst | The destination bitmap, or 0, which draws nothing. |
| height | Target font height in pixels (glyphs are scaled from the internal font cell size to this height). |
| area | Target area for text placement and alignment. |
| halign | Horizontal alignment within the area. |
| valign | Vertical alignment within the area. |
| fg_native | Foreground colour in destination-native format. |
| text | ASCII string with optional ANSI SGR sequences (see below), or 0, which draws nothing. |
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}.
The text supports a subset of ANSI SGR sequences introduced by ESC (\x1B):
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; glyphs entirely outside them are skipped.
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.
text. Per ADR 0008, it will.| 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.
| dst | The destination bitmap, or 0, which draws nothing. |
| height | The pixel height of the rendered font. |
| area | Target area for text placement and alignment. |
| halign | Horizontal alignment within the area. |
| valign | Vertical alignment within the area. |
| fg_native | Foreground colour in destination-native format. |
| fmt | The printf-style format string, or 0, which draws nothing. |
| ... | Additional arguments corresponding to the format string. |
fmt and the strings it formats. Per ADR 0008, it will.Referenced by draw().
| 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.
| bitmap | The target bitmap, or 0, which does nothing. |
| 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 ) |
| uint32_t bj_make_bitmap_pixel | ( | struct bj_bitmap * | bitmap, |
| 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 ) |
| unsigned bj_measure_text | ( | const char * | text, |
| unsigned | height ) |
Measures the pixel width of a text string at a given height.
| text | ASCII string (ANSI escape sequences are skipped), or 0, which measures 0. |
| height | Target font height in pixels. |
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.
text. Per ADR 0008, it will.| 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.
| bitmap | The bitmap whose pixel format is used, or 0. |
| red | The red component. |
| green | The green component. |
| blue | The blue component. |
Referenced by darken_color(), draw(), draw(), draw(), draw_maze(), on_draw(), on_draw(), on_draw(), on_draw(), setup(), setup(), setup(), and setup().
| 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.
| bitmap | The bitmap object, or 0, which does nothing. |
| x | The X coordinate of the pixel. |
| y | The Y coordinate of the pixel. |
| value | The pixel value to put. |
| void bj_reset_bitmap | ( | struct bj_bitmap * | bitmap | ) |
| void bj_set_bitmap_clear_color | ( | struct bj_bitmap * | bitmap, |
| uint32_t | color ) |
Set the colour bj_clear_bitmap fills with.
| bitmap | The target bitmap, or 0, which does nothing. |
| color | The colour, packed in the bitmap's native format (see bj_pack_bitmap_rgb). |
| void bj_set_bitmap_color | ( | struct bj_bitmap * | bitmap, |
| uint32_t | color, | ||
| uint8_t | roles ) |
| 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.
| bitmap | The target bitmap, or 0, which does nothing. |
| color | The transparent colour, packed in the bitmap's native format. |
Referenced by setup().