Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Changelog

[1.1.0 Alpha] - 2026-11-16

Added

  • bj_string type, owning UTF-8 string
    • bj_create_string, bj_destroy_string
    • bj_string_cstr, bj_string_view
    • bj_append_string
  • bj_str for non-owning strings (string views):
    • bj_str_from_cstr, bj_str_slice
    • bj_str_eq
  • UTF-8 decoding
    • bj_utf8_next, bj_utf8_prev
    • bj_utf8_validate, bj_utf8_scan
    • bj_utf8_encode
  • bj_audio_backends() to enumerate compiled audio backends (#152)
  • Runtime audio backend selection via bj_begin_system(BJ_AUDIO_SYSTEM, ...) (#152)
  • Audio backend listing in banjo-info example (#152)
  • Mazes: cells, passages and neighbour queries, on a representation that carries any topology (#159)
    • Orthogonal 2D maze grids
    • Carving and walling a single passage
    • Maze generation, one step at a time, so a maze can be built across frames and drawn as it is carved (#160)
    • Generation algorithms as a setup/step/teardown triplet, so a program can supply its own alongside the built-in ones
    • Marks a program can hand to a builder for the algorithm to record its progress into
    • Restarting a generation in place (#160)
    • The binary tree generation algorithm (#162)
    • The sidewinder generation algorithm
    • The Aldous-Broder generation algorithm
    • Wilson's generation algorithm
    • The hunt-and-kill generation algorithm
    • The backtracker generation algorithm, which gives the longest and most winding corridors of the six (#172)
    • Maze generation example, running algorithms side by side and naming each under the maze it drew
  • Uniform unsigned 32-bit random distribution (#166)
  • Pixel enumeration for lines and circles, so a program can walk the pixels a shape touches without drawing them
  • Supercovering grid ray traversal, which reports every cell a ray crosses and so never slips through the corner two walls share
  • Pixel enumeration example, comparing a line walk against a grid ray on the same geometry
  • bj_draw_line_mode() and bj_draw_polyline_mode() choose between the stepped line and a watertight one that seals sloped corners
  • New names across the public API following consistent readability conventions, each keeping its previous name working through 1.x (#180)
  • bj_rect_intersects(), a plain overlap test for when the intersection rectangle from bj_rect_intersection() is not needed (#180)
  • bj_vec3_mul_comp(), bj_vec4_mul_comp(), bj_vec4_scale_to_len(), bj_vec4_distance() and bj_vec4_distance_sq() (#180)
  • BJ_ERROR_INVALID_PARAMETER, reported when a required argument is missing, such as a 0 object or an absent callback, where those calls reported BJ_ERROR_INCORRECT_VALUE
  • BJ_ERROR_INVALID_DOMAIN, the new name of BJ_ERROR_INCORRECT_VALUE for a present value outside the domain its call accepts; the old name stays as an alias, removed in 2.0
  • banjo::static and banjo::shared CMake targets; static and shared installs into one prefix merge, banjo::banjo follows BUILD_SHARED_LIBS
  • BANJO_REAL_PRECISION CMake option choosing bj_real as float, double or long_double and passing it on to programs
  • real_size in struct bj_build_info, the size of bj_real in the library, so a program can check that it agrees with its own
  • -- ends the options of bj_parse_cli(): every argument after it fills a positional argument, even one starting with a dash, as with GNU tools
  • Unified data streams that read and write, whatever holds the bytes, the source picked by the constructor (ADR 0009)
    • Files read and written on demand, never loaded whole, and mapped into memory when opened read-only, with the flags of fopen: read, write, append, truncate, create and exclusive
    • Memory that grows as it is written, or the caller's buffer written in place, through bj_create_stream_from_memory()
    • TCP connections, through bj_create_stream_from_tcp()
    • Sources of the program's own, through a table of six functions
    • Bounded spans: a range of a stream that cannot read or write past its end, for parsers that check their bounds once
    • bj_stream_peek(), a pointer to bytes without moving the cursor, or 0 out of range
    • A sticky status that tells the end of the data from an error, as feof and ferror do
    • Readers and writers of 8- to 64-bit integers in little- or big-endian order, whatever the host
  • bj_create_bitmap_from_stream(), which loads a BMP from any stream, at its cursor
  • Stream examples: stream_memory.c, stream_file.c, stream_spans.c and stream_custom.c
  • Text wrappers that read and write UTF-8 over any stream, line by line or chunk by chunk (ADR 0011)
    • bj_text_wrapper over bj_stream: the wrapper borrows the stream and locks it, so nothing else can move the cursor under its buffers
    • Line reads that recognize LF, CRLF and lone CR in every file and deliver the line without its terminator; chunk reads capped on character boundaries, and a 0-byte chunk read that probes the end without consuming
    • bj_peek_text_wrapper(), one character of lookahead that previews exactly what the next read delivers
    • Malformed bytes become U+FFFD on both sides, as bj_string does; a character split across two reads is completed whole
    • Writes buffered until bj_flush_text_wrapper(), line endings LF by default with _NATIVE, _CR and _CRLF chosen at any time
    • On a stream that reads and writes, a write lands at the position the reads reached, overwriting in place, and reads resume after it
    • Destroying the wrapper flushes, returns the stream to where the delivered text ended, and releases the lock
  • BJ_STREAM_STATUS_LOCKED, recorded by transfers that take a stream held by a text wrapper, which move nothing; pure queries still answer
    • When the wrapper's own allocations fail, a read delivers and consumes nothing and a write accepts nothing, so a healed retry delivers the same text again

Changed

  • Stepping an angular state of infinite inertia keeps its velocity and angle and clears only the torque, like an immovable particle keeps translating
  • The transposes may run in place: they compute into a temporary, so out may alias the matrix, where the BJ_RESTRICT call was undefined
  • The stretched blits sample at each destination pixel's centre, ⌊src × (2i + 1) / (2 dst)⌋, where they sampled under the left and top edges
  • Colour blits refuse indexed sources or destinations, where they operated on palette indexes that have no colour
  • The fake audio backend calls its device callback at the sample rate on a playback thread, as the native backends do
  • The main loop paces itself from bj_set_frame_rate() alone, where the macOS and Windows backends also blocked on the refresh (#168)
  • Signature changes from the readability rework, all source-compatible unless noted (#180)
  • The shared library is versioned: libbanjo.so.<version> with its soname on Linux, libbanjo.<major>.dylib on macOS; Windows names unchanged
  • With MSVC the static library is banjo-static.lib, installable next to banjo.lib; other toolchains keep libbanjo.a
  • bj_create_stream_from_path() with BJ_STREAM_READ maps the file instead of copying it whole, and holds it open until the stream is destroyed; its path must be UTF-8
  • bj_seek_stream() leaves the cursor where it is for an origin outside enum bj_seek_origin, where it seeked from the end

Deprecated

The public API is reworked for call-site readability (#180): renamed symbols work through 1.x and are removed in 2.0.

Fixed

  • bj_create_stream() returns an empty valid stream instead of a raw malloc block with uninitialized fields
  • bj_seek_stream() clamps any ptrdiff_t offset without overflowing, where offsets near PTRDIFF_MAX were undefined behaviour
  • The BMP loader reads its header in little-endian order on every host, where it assumed a little-endian one
  • bj_circle_hits_segment_2d counts a negative radius as a zero one instead of squaring its magnitude
  • A point-degenerated segment of bj_segment_hits_segment_2d hits only when its point lies on the other segment's line
  • Every drawing primitive stays defined for any pair of int coordinates: 64-bit walks, clipped watertight rays and rejected circles
  • bj_create_bitmap_from_file() refuses RLE files whose header height is negative with BJ_ERROR_INVALID_FORMAT
  • bj_create_bitmap_from_pixels keeps the mode and stride of its empty bitmaps and refuses a value that is not a pixel mode
  • A static build installs banjo-static.pc naming the archive; banjo.pc no longer depends on the flavour built
  • A MinGW-built banjo.dll exported all its internals; every toolchain marks its exports with __declspec(dllexport)
  • Only BANJO_EXPORT functions are exported: internal functions and variables leaked into the shared library's symbol table
  • The shared library did not export bj_call_main(), so an MSVC DLL program failed to link; it is exported now
  • Keep the application alive on Emscripten after bj_run_app() returns, so the step callback runs and input is dispatched again
  • Use BJ_FALSE instead of 0 for bj_bool return in geometry (#142)
  • Add overflow checks for buffer size calculations in ALSA and MME audio backends (#145)
  • Validate XCreateGC return before use in X11 video backend (#146)
  • Validate keycode range before keymap allocation in X11 video backend (#147)
  • Fix erratic frame times on macOS and Windows, where the loop stalled at moments unrelated to the program (#168)
  • Fix macOS windows not being resizable, movable, or closable with the mouse (#169)
  • Fix wrong values from bj_uniform_int32_distribution() over ranges wider than INT32_MAX (#167)
  • Fix a crash when resizing a window that draws text: the glyph atlas was freed with the old framebuffer and then reused
  • Fix random.h: the bj_normal_*_minmax_distribution declarations were outside the include guard and are now inside it (#180)
  • Fix src/maze.c build warnings from #170: static keyword placement and two uint8_t narrowings in the passage-carving path (#180)
  • Fix bj_mat3_invert() and bj_mat3_invert_unsafe() returning the transpose of the inverse, which was only right for symmetric matrices
  • The bj_mat4 rotations turned the wrong way; they now follow the right-hand rule, reversing the direction for callers
  • bj_apply_gravity_2d() added g instead of the weight m * g; an immovable particle now gains nothing
  • bj_random_uniform_ld() returned its upper bound on platforms holding long double in 64 bits or fewer
  • Fix bj_sleep_ms() returning early on POSIX systems when a signal interrupted the sleep: it now sleeps again for the time that remains
  • The saturating blits clamped red and blue as one; each channel is now clamped on its own
  • The stretched blits no longer squeeze the whole source into a clipped destination: the scale is kept
  • Fix bj_convert_bitmap() returning an empty bitmap instead of 0 for a value that is not a pixel mode
  • Fix bj_copy_bitmap() dropping the clear colour and colour key of its source
  • bj_format_version() returns the full text's length even when the buffer cannot hold the stage number
  • A 4-bit RLE run alternates its high and low nibbles, as the BMP format specifies
  • Text functions drop no m after an ANSI sequence and measure past a malformed one, which misplaced centred text
  • bj_draw_rectangle() stayed inside its area and covers the same pixels as bj_draw_filled_rectangle()
  • Fix bj_draw_filled_triangle() leaving out the bottom row of a triangle whose bottom edge is flat
  • bj_shade_bitmap() with centre coords and without normalization scaled by twice the bitmap's size
  • bj_end_system() on a not-retained subsystem released the time and event support of others
  • The CoreAudio backend opened its device playing while the others open paused; every backend now opens paused
  • bj_create_audio_device() and bj_destroy_audio_device() failed cleanly without audio or with a 0 device
  • Fix bj_create_window() crashing when video is not running: it now fails with BJ_ERROR_VIDEO
  • bj_window_should_close() returned BJ_FALSE for a 0 window instead of BJ_TRUE
  • bj_parse_cli() matched long options by prefix, so --ver hit --verbose; long options now match their exact name
  • bj_parse_cli() reported every failure as BJ_ERROR_INVALID_DATA; it now reports the action's documented code
  • Fix bj_parse_cli() ignoring a 0 program name, which left the usage line without one: it now sets it to argv[0], as documented
  • bj_store_cli_double() accepted overflowing doubles, and bj_store_cli_uint() accepted negative values
  • Fix the positional-argument counts in the error messages of bj_parse_cli(), printed with ld and d from size_t values
  • bj_blit_bitmap_mask_stretched() with a 0 destination area now fills the whole destination
  • bj_blit_bitmap_mask_stretched() changed its scale when it clipped; it now maps from the unclipped areas
  • The stretched blits mapped some destination pixels one source pixel short, from a truncated 16.16 step
  • bj_blit_bitmap_mask() failed or misplaced the blit when the mask area passed the mask; it now clips as the colour blits do
  • Fix text drawn larger than 8 pixels changing its scale where it is clipped at an edge of the bitmap
  • examples/audio_pcm.c passed the sample rate as the channel count and the count as the rate
  • bj_play_audio_note() computed samples from the index instead of advancing the phase, so a changed frequency jumped the wave
  • bj_poll_event() and bj_dispatch_events() crashed without video; they now return the queued events alone
  • The library-loading functions crashed or reached the global scope for 0 names and handles; every platform does nothing now
  • The ALSA backend loaded libasound.so, which only development installs; it now loads libasound.so.2
  • bj_build_information() left out the CoreAudio and fake backends; bj_build_info gains their two flags
  • The X11 and ALSA backends linked the libraries they load at runtime, so the shared library required them to start
  • The library failed to compile without any video or audio backend; it now builds and starts nothing, failing to open one
  • The stopwatch reads wrote to a const stopwatch that was never reset; they now return 0 and leave it alone
  • bj_poll_event(), bj_dispatch_event() and bj_close_on_escape() crashed on a 0 event
  • bj_play_audio_note() played stale samples for 0 note data or a wrong format; it now writes silence in all three cases
  • Ending audio left a device's playback thread running and destroyed it later; audio now closes its devices on end
  • bj_destroy_window() crashed on a window left open when video ended; video now destroys its windows on end
  • bj_compute_pixel_mode() missed the masks of BJ_PIXEL_MODE_XRGB1555, so BMP files with them loaded raw
  • bj_create_bitmap() mishandled unholdable modes and zero sizes: an empty bitmap now keeps its size, mode and stride
  • The colour key compared the whole stored value, so an unused set top byte never matched; it compares the colour bits now
  • Fix bj_parse_cli() skipping an empty argument: it now fills the next positional argument, as any argument without a leading dash does
  • banjo-info --help printed the help as a parse error with status 1; it prints and exits with status 0
  • bj_draw_filled_triangle() missed or passed the outline of sloped edges; each row now spans the stepped lines
  • bj_circle_hits_segment_2d() hit short segments differently: a point now gets the same BJ_EPSILON tolerance
  • bj_mat4_rotate_arcball() gave NaNs for nearby points; the cosine is now kept within [-1, 1]
  • bj_set_memory_defaults() installed 0 callbacks it then called; such a set is refused and the installed ones stay
  • bj_pack_pixel_rgb() and bj_unpack_pixel_rgb() read past their layout table for an unknown mode, which now has no colour
  • 16-bit colour reads gave 248 for a full 5-bit channel; narrower channels now widen by repeating their top bits
  • bj_step_angular_2d() left the angle outside [-π, π] for steps past one turn; it now unwraps as needed
  • Two draws in one expression took unspecified order and gave compiler-dependent values; the first draw gives the high bits
  • The real uniform draws could return their upper bound for small spans; a result reaching high gives the next lower value
  • A colour outside [0, 1] saturated by no rule and differed by platform; the conversion now saturates, NaN giving 0
  • The clocks before bj_begin() gave 0 or only nanoseconds; they start on first use now, and bj_begin() restarts the run time
  • bj_sleep_ms() slept forever on Windows for a negative duration; a negative one now returns at once
  • bj_begin() retained time and events once for all, so per-system releases emptied the queue; it retains each system now
  • bj_begin_system() accepted a combination and retained nothing; it now fails, and bj_end_system() does nothing
  • The normalize functions treated near-zero vectors differently from scale_to_len; both now use the BJ_EPSILON length
  • bj_create_bitmap_from_file() wrote through a null pointer when it ran out of memory converting an indexed BMP
  • bj_compute_bitmap_stride() wrapped for rows too long for size_t, making rows shorter than their width; such rows refuse now
  • Fix bj_create_bitmap_from_file() crashing for a 0 path: it now returns 0 and leaves the error location alone
  • bj_unpack_pixel_rgb() and bj_bitmap_pixel_rgb() crashed on a 0 channel location; they now skip those channels
  • bj_receive_tcp() and bj_send_tcp() returned 0 for a 0 stream, reading as closed; they now return -1
  • The UDP sends reported a socket error for 0 data; they return -1 now, as the TCP transfers do for such buffers
  • bj_resolve_address(), bj_connect_tcp_stream() and bj_send_udp() failed wrong for a 0 host; they now just fail
  • The CLI functions crashed on 0 parsers, arguments, destinations and buffers; they now fail or measure only
  • Fix the twelve bj_random_*() distributions crashing for a 0 callback: they now draw from the global bj_rand() engine, as a maze builder does
  • The gravity and drag functions crashed on a 0 particle; they now do nothing, as the other particle functions do
  • bj_memcpy() to bj_memzero() passed 0 to the C library, undefined even at size 0; they now do nothing
  • The stream functions crashed on 0 streams and streams over 0 data; they now give 0, and such data gives no stream
  • Fix bj_log_message() passing a 0 format to vsnprintf(): it now logs nothing and returns 0
  • Fix bj_format_version() writing through a 0 buffer of a size above 0: it now only measures the text, as it did for a size of 0
  • Fix bj_call_main() calling a 0 function: it now returns -1
  • Fix bj_push_event() copying from a 0 event: it now queues nothing
  • Audio devices opened without properties or a callback now default to 16-bit mono 44100 Hz and play silence
  • A 0 title raised an exception on macOS; it now gives an empty title on every backend
  • A level outside enum bj_log_level read past the table; such a level is named UNKNOWN and logs uncoloured
  • Fix bj_store_cli_double() raising a conversion warning in MinGW builds, from the isinf() macro: it now tells an overflow apart without it
  • The log level stayed uncoloured beside a long message; the level is now coloured whenever its codes fit

[1.0.0] - 2026-07-26

Initial release.

Added

  • Window management with software framebuffer and multiple pixel formats
  • Fullscreen mode and resizable windows with resize callbacks
  • Bitmap operations: blitting (copy, stretched, color-keyed), BMP loading
  • Text rendering with ANSI color code support
  • Drawing primitives: lines, rectangles, triangles, circles, polylines (filled and outlined)
  • Per-pixel shader functions for procedural image generation
  • Real-time PCM audio playback with custom sample generation callbacks
  • Built-in waveform generators: sine, square, triangle, sawtooth
  • Support for INT16 and F32 audio formats
  • Playback control: play, pause, stop, reset
  • Event system with keyboard, mouse, and window events
  • Callback and polling modes for event handling
  • Key repeat support and standard Virtual-Key codes
  • Mouse button and cursor movement tracking
  • TCP support: listeners and stream connections
  • UDP support: datagram send/receive with broadcast
  • IPv4 and IPv6 address resolution
  • Connection timeouts, keep-alive, and non-blocking I/O
  • Network simulation for testing
  • Precision-agnostic math (configurable float/double/long double)
  • Vector types: 2D, 3D, 4D with full algebra (dot, cross, normalize, distance)
  • Matrix types: 3x3, 3x2, 4x4, 4x3 for 2D and 3D transforms
  • Quaternions with slerp interpolation and matrix conversion
  • Utilities: clamp, smoothstep, lerp, epsilon-aware comparisons
  • 1D classical mechanics: acceleration, velocity, position
  • 2D particle simulation with gravity, drag, and point gravity
  • 2D rigid body dynamics with torque and semi-implicit Euler integration
  • 2D collision detection: line segment intersection, circle-segment collision
  • Random number generation with PCG32 (independent streams)
  • Distribution helpers: uniform, bernoulli, normal/gaussian
  • Time utilities: Unix timestamp, monotonic clock, stopwatch for delta timing
  • File and memory-backed data streams with unified API
  • Pixel format encoding: indexed (1/4/8-bit), bitfield (RGB565, XRGB1555), byte-per-channel
  • Axis-aligned rectangles with intersection and union operations
  • Command-line argument parsing
  • Logging and error handling infrastructure