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

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
}

Functions

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)
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)
void bj_destroy_window (struct bj_window *window)
void bj_unbind_window (struct bj_window *window)
void bj_set_window_should_close (struct bj_window *window)
bj_bool bj_window_should_close (struct bj_window *window)
bj_bool bj_should_close_window (struct bj_window *window)
uint8_t bj_window_flags (struct bj_window *window)
bj_bool bj_window_has_flag (struct bj_window *window, uint8_t flag)
uint8_t bj_get_window_flags (struct bj_window *window, uint8_t flags)
bj_bool bj_window_is_key_pressed (const struct bj_window *window, int key)
int bj_get_key (const struct bj_window *window, int key)
int bj_window_size (const struct bj_window *window, int *width, int *height)
int bj_get_window_size (const struct bj_window *window, int *width, int *height)
void bj_set_window_draw_callback (struct bj_window *window, bj_window_draw_fn fn, void *user_data)
void bj_set_draw_callback (struct bj_window *window, bj_window_draw_fn fn, void *user_data)
void bj_set_window_resize_callback (struct bj_window *window, bj_window_resize_fn fn, void *user_data)
void bj_set_resize_callback (struct bj_window *window, bj_window_resize_fn fn, void *user_data)
void bj_window_enter_fullscreen (struct bj_window *window)
void bj_window_leave_fullscreen (struct bj_window *window)
void bj_set_window_fullscreen (struct bj_window *window, bj_bool enable)
bj_bool bj_window_is_fullscreen (struct bj_window *window)
bj_bool bj_is_window_fullscreen (struct bj_window *window)
void bj_invalidate_rect (struct bj_window *window, const struct bj_rect *rect)
static void bj_invalidate_window (struct bj_window *window)
struct bj_bitmap * bj_render_target_bitmap (struct bj_render_target *target)

Detailed Description

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.

Typical usage

static void on_draw(bj_window* w, bj_render_target* t,
const bj_rect* dirty, void* user_data) {
/* draw shapes / blits / text into fb *‍/
}
/* in setup: *‍/
bj_begin(BJ_VIDEO_SYSTEM, NULL);
bj_window* w = bj_create_window("My App", 100, 100, 640, 480, 0, NULL);
bj_set_window_draw_callback(w, on_draw, NULL);
bj_invalidate_window(w); /* request the first paint *‍/
/* in step, which bj_run_app paces (see bj_set_frame_rate): *‍/
bj_dispatch_events();
/* call bj_invalidate_window(w) here if the model changed *‍/
static void on_draw(struct bj_window *w, struct bj_render_target *target, const struct bj_rect *dirty, void *user_data)
Definition bitmap_blit.c:32
void bj_clear_bitmap(struct bj_bitmap *bitmap)
Fills the entire bitmap with the clear colour.
struct bj_render_target bj_render_target
Definition api.h:369
struct bj_bitmap bj_bitmap
Definition api.h:340
struct bj_window bj_window
Definition api.h:384
Axis-aligned rectangle: a top-left corner plus a width and height.
Definition rect.h:33
struct bj_bitmap * bj_render_target_bitmap(struct bj_render_target *target)
Reach the software framebuffer behind a render target.

See start.c for the same shape wired up, and pong.c for the capstone version.

Platforms and runtime selection

Note
The "Platforms and runtime selection" block in audio.h is the sibling of this one. Keep them in sync (priority order, fake-fallback behaviour, log line).

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.

See also
Event for input events from the active window, Bitmap and Drawing for Drawing into a window, Examples for the first-program walkthrough, Building Banjo for which video platforms are enabled in a given build and what they need to run.

Typedef Documentation

◆ bj_window_draw_fn

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.

Parameters
windowThe window being drawn.
targetRender target valid only for this call. Don't cache.
dirtyAccumulated damage rect. NULL means "whole window is dirty": repaint the entire surface. A non-NULL rect is in framebuffer pixels.
user_dataThe pointer registered with bj_set_window_draw_callback.

Definition at line 144 of file window.h.

◆ bj_window_flag

Definition at line 201 of file window.h.

◆ bj_window_resize_fn

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.

Parameters
windowThe window that was resized.
widthNew framebuffer width in pixels.
heightNew framebuffer height in pixels.
user_dataThe pointer registered with bj_set_window_resize_callback.
See also
bj_set_window_resize_callback, bj_window_size

Definition at line 177 of file window.h.

Enumeration Type Documentation

◆ 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.

Definition at line 192 of file window.h.

Function Documentation

◆ bj_bind_window()

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 )
Deprecated
Renamed to bj_create_window. Removed in 2.0.

◆ bj_create_window()

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.

Parameters
titleTitle of the window, or NULL for an empty one.
xHorizontal on-screen position, in pixels.
yVertical on-screen position, in pixels.
widthWidth of the window, in pixels.
heightHeight of the window, in pixels.
flagsOR'd combination of bj_window_flag.
errorOptional pointer to receive error information on failure. May be NULL.
Returns
A pointer to the new window, or NULL on failure. The caller owns it and must release it with bj_destroy_window.
Error Codes
  • BJ_ERROR_VIDEO: Video is not running, or window creation failed (display unavailable, etc.)
Todo
This function does not yet enforce UTF-8 on title. Per ADR 0008, it will.
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, event_callbacks.c, event_polling.c, interpolation.c, load_bmp.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, shaders.c, sprite_animation.c, start.c, and window.c.

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

◆ bj_destroy_window()

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.

Parameters
windowThe window to destroy. NULL does nothing.
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, event_callbacks.c, event_polling.c, interpolation.c, load_bmp.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, shaders.c, sprite_animation.c, start.c, and window.c.

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

◆ bj_get_key()

int bj_get_key ( const struct bj_window * window,
int key )
Deprecated
Renamed to bj_window_is_key_pressed (now returns bj_bool). Removed in 2.0.

◆ bj_get_window_flags()

uint8_t bj_get_window_flags ( struct bj_window * window,
uint8_t flags )
Deprecated
Split into bj_window_flags and bj_window_has_flag. Removed in 2.0.

◆ bj_get_window_size()

int bj_get_window_size ( const struct bj_window * window,
int * width,
int * height )
Deprecated
Renamed to bj_window_size. Removed in 2.0.

◆ bj_invalidate_rect()

void bj_invalidate_rect ( struct bj_window * window,
const struct bj_rect * rect )

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.

Parameters
windowThe target window. NULL is a no-op.
rectRegion in framebuffer pixels, or NULL for whole window.
See also
bj_invalidate_window, bj_set_window_draw_callback

Referenced by bj_invalidate_window().

◆ bj_invalidate_window()

void bj_invalidate_window ( struct bj_window * window)
inlinestatic

Mark the whole window as needing a repaint.

Shorthand for bj_invalidate_rect(window, NULL).

Parameters
windowThe target window. NULL is a no-op.
See also
bj_invalidate_rect, bj_set_window_draw_callback
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, interpolation.c, load_bmp.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, shaders.c, sprite_animation.c, and start.c.

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().

◆ bj_is_window_fullscreen()

bj_bool bj_is_window_fullscreen ( struct bj_window * window)
Deprecated
Renamed to bj_window_is_fullscreen. Removed in 2.0.

◆ bj_render_target_bitmap()

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.

Parameters
targetRender target handed to a draw callback. NULL is a silent no-op that returns NULL.
Returns
The backing software bitmap, or NULL if this render target isn't software-backed.
See also
bj_set_window_draw_callback
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, interpolation.c, load_bmp.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, shaders.c, sprite_animation.c, and start.c.

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().

◆ bj_set_draw_callback()

void bj_set_draw_callback ( struct bj_window * window,
bj_window_draw_fn fn,
void * user_data )
Deprecated
Renamed to bj_set_window_draw_callback. Removed in 2.0.

◆ bj_set_resize_callback()

void bj_set_resize_callback ( struct bj_window * window,
bj_window_resize_fn fn,
void * user_data )
Deprecated
Renamed to bj_set_window_resize_callback. Removed in 2.0.

◆ bj_set_window_draw_callback()

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.

Parameters
windowThe target window. NULL is a no-op.
fnThe function to call, or NULL to clear.
user_dataPointer forwarded to every callback invocation, NULL included.
See also
bj_invalidate_rect, bj_invalidate_window, bj_window_draw_fn
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, interpolation.c, load_bmp.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, shaders.c, sprite_animation.c, and start.c.

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

◆ bj_set_window_fullscreen()

void bj_set_window_fullscreen ( struct bj_window * window,
bj_bool enable )

◆ bj_set_window_resize_callback()

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.

Note
Only a window created with BJ_WINDOW_FLAG_RESIZABLE can be resized by the user. A fixed-size window (the default) still receives the one initial call above, but no further resize calls.
Parameters
windowThe target window. NULL is a no-op.
fnThe function to call on resize, or NULL to clear.
user_dataPointer forwarded to every callback invocation, NULL included.
See also
bj_window_resize_fn, bj_window_size, bj_set_window_draw_callback
Examples
event_callbacks.c, event_polling.c, and maze.c.

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

◆ bj_set_window_should_close()

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.

Parameters
windowThe window to flag. NULL does nothing.
See also
bj_window_should_close
Examples
event_callbacks.c, event_polling.c, and random_distribution.c.

Referenced by key_callback(), and step().

◆ bj_should_close_window()

bj_bool bj_should_close_window ( struct bj_window * window)
Deprecated
Renamed to bj_window_should_close. Removed in 2.0.

◆ bj_unbind_window()

void bj_unbind_window ( struct bj_window * window)
Deprecated
Renamed to bj_destroy_window. Removed in 2.0.

◆ bj_window_enter_fullscreen()

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.

Parameters
windowThe target window. NULL is a no-op.
See also
bj_window_leave_fullscreen, BJ_WINDOW_FLAG_FULLSCREEN, bj_window_is_fullscreen

◆ bj_window_flags()

uint8_t bj_window_flags ( struct bj_window * window)

Return all of a window's flags.

Parameters
windowThe window to query. NULL returns 0.
Returns
An OR'd combination of bj_window_flag.
See also
bj_window_has_flag

◆ bj_window_has_flag()

bj_bool bj_window_has_flag ( struct bj_window * window,
uint8_t flag )

Report whether a window has a given flag set.

Parameters
windowThe window to query. NULL reports BJ_FALSE.
flagA single bj_window_flag (or an OR'd combination, in which case any one being set reports BJ_TRUE).
Returns
BJ_TRUE if the flag is set, BJ_FALSE otherwise.

◆ bj_window_is_fullscreen()

bj_bool bj_window_is_fullscreen ( struct bj_window * window)

Report whether window is currently fullscreen.

Parameters
windowThe window to query. NULL reports BJ_FALSE.
Returns
BJ_TRUE if the window is fullscreen, BJ_FALSE otherwise.
See also
bj_window_enter_fullscreen, bj_window_leave_fullscreen

◆ bj_window_is_key_pressed()

bj_bool bj_window_is_key_pressed ( const struct bj_window * window,
int key )

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.

Parameters
windowThe target window, or NULL.
keyKey code in [0, 0xFE] (see bj_key).
Returns
BJ_TRUE if the key is down, BJ_FALSE otherwise (also when window is NULL or key is out of range).
Examples
pong.c.

Referenced by update().

◆ bj_window_leave_fullscreen()

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.

Parameters
windowThe target window. NULL is a no-op.
See also
bj_window_enter_fullscreen, bj_window_is_fullscreen

◆ bj_window_should_close()

bj_bool bj_window_should_close ( struct bj_window * window)

Report whether a window's close flag is set.

Parameters
windowThe window to query. NULL reports BJ_TRUE.
Returns
BJ_TRUE if the close flag is set, BJ_FALSE otherwise.
See also
bj_set_window_should_close
Examples
bitmap_blit.c, bitmap_blit_colorkey.c, drawing_2d.c, drawing_text.c, event_callbacks.c, event_polling.c, interpolation.c, load_bmp.c, maze.c, physics_kinematics.c, physics_particle.c, pixel_enumeration.c, pong.c, random_distribution.c, shaders.c, sprite_animation.c, start.c, and window.c.

Referenced by step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), step(), and step().

◆ bj_window_size()

int bj_window_size ( const struct bj_window * window,
int * width,
int * height )

Retrieve a window's drawable size, in pixels.

Parameters
windowThe window to query. NULL writes nothing and returns 0.
[out]widthDestination for the width, or NULL to skip it.
[out]heightDestination for the height, or NULL to skip it.
Returns
1 on success, 0 on error.