|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
Typedefs | |
| typedef void(* | bj_window_draw_fn) (struct bj_window *window, struct bj_render_target *target, const struct bj_rect *dirty, void *user_data) |
| typedef void(* | bj_window_resize_fn) (struct bj_window *window, int width, int height, void *user_data) |
| typedef enum bj_window_flag | bj_window_flag |
Enumerations | |
| enum | bj_window_flag { BJ_WINDOW_FLAG_NONE = 0x00 , BJ_WINDOW_FLAG_CLOSE = 0x01 , BJ_WINDOW_FLAG_KEY_REPEAT = 0x02 , BJ_WINDOW_FLAG_RESIZABLE = 0x04 , BJ_WINDOW_FLAG_FULLSCREEN = 0x08 , BJ_WINDOW_FLAG_ALL = 0xFF } |
Open and manage the on-screen window, and read keyboard state.
This subsystem lets your program open a rectangular area on the user's screen, a window, that you can draw into and that receives keyboard and mouse input. Every graphical Banjo program starts by opening one with bj_create_window and tearing it down with bj_destroy_window on exit.
A window has a title (the text in its top bar), a position and a size (both in pixels), and a set of flags that control behaviour such as "should this window close on the next frame?". You read those flags with bj_window_flags / bj_window_has_flag and query individual key states with bj_window_is_key_pressed. The actual keyboard and mouse events (press, release, motion, enter/leave) arrive through the separate Event subsystem; the window owns the keyboard focus, the event subsystem delivers what it sees.
Drawing into a window goes through the Bitmap subsystem. Every window owns a "framebuffer" (a bj_bitmap the size of the window) and you draw into it from a callback that banjo fires when the window has pending damage. Register the callback with bj_set_window_draw_callback and request the next paint with bj_invalidate_window or bj_invalidate_rect.
Windows are fixed-size by default. Pass BJ_WINDOW_FLAG_RESIZABLE to bj_create_window to let the user resize one. When a resizable window changes size, banjo recreates its framebuffer at the new size and calls the callback you registered with bj_set_window_resize_callback, handing you the new width and height. What happens next is up to you: banjo imposes no scaling policy. A retro game typically keeps a fixed internal resolution and rescales it onto the framebuffer, while another program might recompute a projection or rebuild its layout.
Fullscreen is a separate switch: bj_window_enter_fullscreen and bj_window_leave_fullscreen toggle it at runtime and BJ_WINDOW_FLAG_FULLSCREEN starts there. It is borderless desktop fullscreen (the display keeps its resolution) and it rides the same path as a resize: going in or out changes the drawable size, so your resize callback fires with the new size and you handle it exactly as above. A window need not be resizable to go fullscreen.
See start.c for the same shape wired up, and pong.c for the capstone version.
Windowing works on Linux, Windows, macOS, and WebAssembly. By default you don't pick the platform: bj_begin (called with BJ_VIDEO_SYSTEM) probes the compiled-in backends at startup, in the order bj_video_backends lists them (Emscripten, Win32, Cocoa, Wayland, X11, then fake), and uses the first that initialises. To override that, call bj_begin_system before bj_begin and pass a name from bj_video_backends (or NULL to keep auto-selecting); the chosen backend is then pinned for the subsystem's lifetime. A no-op fallback (the fake backend) means bj_create_window can return a valid handle even on a headless host where no real window can be shown; in that case the framebuffer still exists in memory, just nothing is displayed. On success, startup logs video selected: <name>; on total failure, which includes a build with no video backend at all, bj_begin returns BJ_FALSE with BJ_ERROR_INITIALIZE.
| typedef void(* bj_window_draw_fn) (struct bj_window *window, struct bj_render_target *target, const struct bj_rect *dirty, void *user_data) |
Redraw callback signature.
Banjo invokes this when it decides "draw the window now." The user repaints target, typically by reaching the software bitmap with bj_render_target_bitmap and writing into it. The callback may also bail out (e.g. no model changes) without drawing anything.
| window | The window being drawn. |
| target | Render target valid only for this call. Don't cache. |
| dirty | Accumulated damage rect. NULL means "whole window
is dirty": repaint the entire surface. A non-NULL rect is in framebuffer pixels. |
| user_data | The pointer registered with bj_set_window_draw_callback. |
| typedef enum bj_window_flag bj_window_flag |
| typedef void(* bj_window_resize_fn) (struct bj_window *window, int width, int height, void *user_data) |
Window-resize callback signature.
Banjo invokes this when the window's drawable area changes size (the user drags a corner, the window is maximised, it enters or leaves fullscreen, etc.). By the time it fires Banjo has already recreated the window's framebuffer at the new size, so the next draw callback paints into a correctly-sized surface. This callback is your chance to react: recompute a projection or layout, resize your own off-screen surfaces, or do nothing. Banjo also delivers one initial call when you register the callback (see bj_set_window_resize_callback), so first-time layout belongs here too.
You do not reconfigure the framebuffer here. It is owned by Banjo and already matches width by height. A game that runs at a fixed internal resolution leaves its own bitmap untouched and simply recomputes how it scales that bitmap onto the framebuffer at draw time.
| window | The window that was resized. |
| width | New framebuffer width in pixels. |
| height | New framebuffer height in pixels. |
| user_data | The pointer registered with bj_set_window_resize_callback. |
| enum bj_window_flag |
A set of flags describing some properties of a bj_window.
These flags can be provided at window creation with bj_create_window. The may also change during the window lifetime. You can use bj_window_flags / bj_window_has_flag to query the status of any flag on an active window instance.
| Enumerator | |
|---|---|
| BJ_WINDOW_FLAG_NONE | No Flag. |
| BJ_WINDOW_FLAG_CLOSE | Window should be closed by the application. |
| BJ_WINDOW_FLAG_KEY_REPEAT | Key repeat event is enabled (see bj_set_key_callback). |
| BJ_WINDOW_FLAG_RESIZABLE | User may resize the window. Off by default (see bj_set_window_resize_callback). |
| BJ_WINDOW_FLAG_FULLSCREEN | Start the window fullscreen (see bj_window_enter_fullscreen). |
| BJ_WINDOW_FLAG_ALL | All flags set. |
| struct bj_window * bj_bind_window | ( | const char * | title, |
| uint16_t | x, | ||
| uint16_t | y, | ||
| uint16_t | width, | ||
| uint16_t | height, | ||
| uint8_t | flags, | ||
| struct bj_error ** | error ) |
| struct bj_window * bj_create_window | ( | const char * | title, |
| uint16_t | x, | ||
| uint16_t | y, | ||
| uint16_t | width, | ||
| uint16_t | height, | ||
| uint8_t | flags, | ||
| struct bj_error ** | error ) |
Create a window with the given attributes.
| title | Title of the window, or NULL for an empty one. |
| x | Horizontal on-screen position, in pixels. |
| y | Vertical on-screen position, in pixels. |
| width | Width of the window, in pixels. |
| height | Height of the window, in pixels. |
| flags | OR'd combination of bj_window_flag. |
| error | Optional pointer to receive error information on failure. May be NULL. |
title. Per ADR 0008, it will.Referenced by setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), and setup().
| void bj_destroy_window | ( | struct bj_window * | window | ) |
Destroy a window and release its resources.
Ending video, through bj_end or the last bj_end_system, destroys every window still open the same way; destroying one of those afterwards does nothing.
| window | The window to destroy. NULL does nothing. |
Referenced by teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), teardown(), and teardown().
| int bj_get_key | ( | const struct bj_window * | window, |
| int | key ) |
| uint8_t bj_get_window_flags | ( | struct bj_window * | window, |
| uint8_t | flags ) |
| int bj_get_window_size | ( | const struct bj_window * | window, |
| int * | width, | ||
| int * | height ) |
Mark a region of window as needing a repaint.
Unions rect into the window's pending damage. Banjo fires the draw callback (bj_set_window_draw_callback) on the next draw tick with the accumulated damage as the dirty argument, then resets damage to empty.
Passing rect = NULL promotes the pending damage to whole-window and keeps it whole-window until the callback fires (subsequent rect invalidations are absorbed).
Calling this from inside the draw callback accumulates into the next tick's damage; it does not retrigger the current one.
| window | The target window. NULL is a no-op. |
| rect | Region in framebuffer pixels, or NULL for whole window. |
Referenced by bj_invalidate_window().
|
inlinestatic |
Mark the whole window as needing a repaint.
Shorthand for bj_invalidate_rect(window, NULL).
| window | The target window. NULL is a no-op. |
Definition at line 513 of file window.h.
Referenced by regenerate(), roll(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), step(), step(), step(), step(), step(), step(), step(), and step().
| struct bj_bitmap * bj_render_target_bitmap | ( | struct bj_render_target * | target | ) |
Reach the software framebuffer behind a render target.
The draw callback (bj_set_window_draw_callback) receives a bj_render_target. For a software-rendered window this accessor returns the backing bj_bitmap so you can draw with the Bitmap and Drawing functions. Future hardware-backed targets will return NULL and offer their own accessor.
The returned bitmap is owned by Banjo and shares the render target's lifetime: it is valid only for the duration of the callback that received the target. Don't cache the pointer between callbacks.
| target | Render target handed to a draw callback. NULL is a silent no-op that returns NULL. |
NULL if this render target isn't software-backed.Referenced by on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), on_draw(), and on_draw().
| void bj_set_draw_callback | ( | struct bj_window * | window, |
| bj_window_draw_fn | fn, | ||
| void * | user_data ) |
| void bj_set_resize_callback | ( | struct bj_window * | window, |
| bj_window_resize_fn | fn, | ||
| void * | user_data ) |
| void bj_set_window_draw_callback | ( | struct bj_window * | window, |
| bj_window_draw_fn | fn, | ||
| void * | user_data ) |
Register the redraw callback for window.
Banjo invokes fn when it decides the window should be repainted. What "decides" means depends on the backend: on Wayland the compositor signals via a frame callback, on X11 it's either an Expose event or a soft-paced timer, on Win32 it's WM_PAINT, and on Emscripten it's requestAnimationFrame. The user just invalidates a rect and draws when called back.
Replaces any previously-registered callback; pass fn = NULL to clear. Without a callback registered, banjo logs a one-time warning the first time it tries to call one and then stays silent.
| window | The target window. NULL is a no-op. |
| fn | The function to call, or NULL to clear. |
| user_data | Pointer forwarded to every callback invocation, NULL included. |
Referenced by setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), setup(), and setup().
| void bj_set_window_resize_callback | ( | struct bj_window * | window, |
| bj_window_resize_fn | fn, | ||
| void * | user_data ) |
Register the resize callback for window.
Banjo invokes fn whenever the window's drawable size changes. By then it has already recreated the framebuffer at the new size, and it marks the whole window dirty right after (so a draw follows). Use the callback to recompute anything that depends on the window size; you never resize the framebuffer yourself.
Registering a callback also delivers one immediate call with the window's current size, before any drawing, so the same handler can do first-time layout and then react to later resizes. Platforms differ on whether they emit a resize at window creation; banjo makes that initial call uniform. Because the framebuffer already matches that size, the initial call only notifies; it recreates nothing.
Replaces any previously-registered callback; pass fn = NULL to clear (clearing does not fire). The current size is also available at any time from bj_window_size.
| window | The target window. NULL is a no-op. |
| fn | The function to call on resize, or NULL to clear. |
| user_data | Pointer forwarded to every callback invocation, NULL included. |
| void bj_set_window_should_close | ( | struct bj_window * | window | ) |
Flag a window to be closed.
Flagging does not close the window; the application still calls bj_destroy_window. The flag cannot be cleared once set.
| window | The window to flag. NULL does nothing. |
Referenced by key_callback(), and step().
| void bj_unbind_window | ( | struct bj_window * | window | ) |
| void bj_window_enter_fullscreen | ( | struct bj_window * | window | ) |
Put window into fullscreen.
Fullscreen changes the window's drawable size (to the display and back). Banjo recreates the framebuffer and fires your bj_set_window_resize_callback with the new size, exactly like a user-driven resize, so a program that already handles resize handles fullscreen for free.
It is best-effort and platform dependent (a borderless desktop-sized window on some backends, a real display mode on others; on the web it needs a user gesture). Pass BJ_WINDOW_FLAG_FULLSCREEN to bj_create_window to start fullscreen, and query the current state with bj_window_is_fullscreen.
Calling it when the window is already fullscreen is a no-op. A window does not need BJ_WINDOW_FLAG_RESIZABLE to go fullscreen.
| window | The target window. NULL is a no-op. |
| uint8_t bj_window_flags | ( | struct bj_window * | window | ) |
Return all of a window's flags.
| window | The window to query. NULL returns 0. |
Report whether a window has a given flag set.
| window | The window to query. NULL reports BJ_FALSE. |
| flag | A single bj_window_flag (or an OR'd combination, in which case any one being set reports BJ_TRUE). |
Report whether window is currently fullscreen.
| window | The window to query. NULL reports BJ_FALSE. |
BJ_TRUE if the window is fullscreen, BJ_FALSE otherwise.Report whether a key is currently held down on a window.
The right tool for continuous-state input like paddle or camera control; for press/release edges use the Event callbacks.
The state follows the key events pushed for the window with bj_push_key_event, as the backends do on input, from the moment they are pushed, whether or not they have been polled yet. A key repeat keeps the key down.
| window | The target window, or NULL. |
| key | Key code in [0, 0xFE] (see bj_key). |
window is NULL or key is out of range). Referenced by update().
| void bj_window_leave_fullscreen | ( | struct bj_window * | window | ) |
Return window from fullscreen to a normal window.
The inverse of bj_window_enter_fullscreen; the same resize path applies. A no-op when the window is not fullscreen.
| window | The target window. NULL is a no-op. |
Report whether a window's close flag is set.
| window | The window to query. NULL reports BJ_TRUE. |
Referenced by step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), and step().
| int bj_window_size | ( | const struct bj_window * | window, |
| int * | width, | ||
| int * | height ) |
Retrieve a window's drawable size, in pixels.
| window | The window to query. NULL writes nothing and returns 0. | |
| [out] | width | Destination for the width, or NULL to skip it. |
| [out] | height | Destination for the height, or NULL to skip it. |