start.c

Hello, Window: open a window, draw shapes, react to ESC.

Hello, Window: open a window, draw shapes, react to ESC. This is the canonical first program in Banjo. It opens a 640×480 window and registers a draw callback that paints a red circle and a cyan rectangle, then runs an event loop until the user closes the window or presses ESC.

What you'll learn

• Drive the program through Banjo's application lifecycle by passing setup, step, and teardown callbacks to bj_run_app.
• Initialise Banjo's video subsystem with bj_begin.
• Open a window with bj_bind_window. The window owns its framebuffer; there's no separate renderer object to create.
• Install the built-in ESC-to-close key callback (bj_set_key_callback + bj_close_on_escape).
• Register a draw callback with bj_set_draw_callback. Inside the callback, reach the framebuffer with bj_render_target_bitmap, clear it, and draw 2D primitives.
• Request the first paint with bj_invalidate_window. Banjo fires the callback on the next natural-cadence event; you never call a present.
• Pump events with bj_dispatch_events until the user asks to quit.
• Tear everything down in reverse order with bj_unbind_window and bj_end.

Prerequisites

You need CMake 3.21+, a C99 compiler, and (on Linux) the platform development headers. See the Prerequisites topic for the one-shot install command for your distro.

Project setup

Create a new directory:

mkdir my_banjo_app && cd my_banjo_app

Drop this file in as main.c, then create CMakeLists.txt:

cmake_minimum_required(VERSION 3.21)
project(MyBanjoApp C)
 
include(FetchContent)
FetchContent_Declare(
    banjo
    GIT_REPOSITORY https://forge.codework-orange.com/OragonEfreet/banjo.git
    GIT_TAG        v0.1.5  # pin a release tag (see the Releases page)
)
FetchContent_MakeAvailable(banjo)
 
add_executable(my_banjo_app main.c)
target_link_libraries(my_banjo_app PRIVATE banjo)

Build and run:

cmake -B build
cmake --build build
./build/my_banjo_app

(On Windows the binary lives under build\Debug\ or build\Release\.)

Walkthrough

1. The application lifecycle

Every banjo program is driven by an application handle. main itself is small and uniform across tutorials: bj_run_app receives the setup, step, and teardown callbacks directly, creates an internal app handle, drives the loop, and releases the handle on return. Everything interesting happens inside the three callbacks.

On Linux/macOS/Windows bj_run_app is a plain loop. On Emscripten it hands the step callback to the browser's run loop instead. Your callbacks don't need to know which.

2. Initialisation (the setup callback)

bj_begin starts the requested subsystems, here just video. It returns BJ_FALSE if no backend was selected (see Windows for the fall-through chain). On failure, calling bj_quit_app then returning tells the run loop to skip the step phase and proceed straight to teardown.

bj_bind_window opens a 640×480 window titled "My First Banjo App" and allocates the per-window framebuffer behind it; there's no separate renderer object to manage.

bj_set_key_callback with bj_close_on_escape is a one-liner shortcut: it installs a built-in callback that closes the active window when ESC is pressed.

bj_set_draw_callback registers on_draw as the function banjo fires whenever the window has pending damage. bj_invalidate_window marks the whole window dirty so banjo paints it on the next natural-cadence event (compositor frame callback, WM_PAINT, drawRect:, requestAnimationFrame, whichever the backend uses).

3. The draw callback

Banjo passes the callback a bj_render_target. Reach the software framebuffer with bj_render_target_bitmap, then draw with the regular Bitmap and Drawing functions: bj_clear_bitmap fills it with the current clear colour, bj_make_bitmap_pixel converts an (R, G, B) triple into a packed pixel value matching the bitmap's pixel mode (so the same code works whether the framebuffer is RGB565 or XRGB8888), and bj_draw_filled_circle / bj_draw_rectangle mutate the framebuffer. The backend presents what you drew after the callback returns; you never call a present.

The dirty argument carries the damaged region: a sub-rect when only part of the window needs repainting (uncovered from behind another window, OS resize, etc.), or NULL when the whole window is dirty. This tutorial just repaints the whole scene each call; load_bmp.c shows the partial-damage path.

4. The step callback

The step callback receives a bj_tick_info giving real wall-clock delta (seconds since the previous step) and a [0, 1) alpha interpolation factor against the configured fixed-step rate. This program ignores both since it doesn't run physics; the physics examples (physics_kinematics.c, physics_particle.c) and the interpolation.c demo put them to use.

bj_dispatch_events drains the event queue and fires registered event callbacks (including the ESC handler installed in setup). Calling bj_quit_app from inside the step exits the loop on the next iteration; here we forward the window's close request from bj_should_close_window.

Notice there is no manual sleep here. bj_run_app paces the loop for you at 60 iterations per second by default, yielding the CPU between iterations so a windowed program doesn't pin a core. Change or remove the cap with bj_set_frame_rate (pass 0 to run uncapped).

Because the scene is static, step does not invalidate the window each iteration; banjo only fires the draw callback when there's damage. A real animated program would bj_invalidate_window every step to drive its redraws.

5. The teardown callback

Release in reverse order: bj_unbind_window, then bj_end. The test harness's allocator tracking will scream if any of these are skipped. See the error management topic (Error Management) for the leak diagnostic. The app handle is released automatically when bj_run_app returns.

What's next

• event_callbacks.c and event_polling.c: handle input more richly than just ESC-to-quit.
• drawing_2d.c and drawing_text.c: every primitive and the text renderer.
• bitmap_blit.c, load_bmp.c, sprite_animation.c: bring images into your framebuffer.
• audio_pcm.c: add sound.

See the Windows and Audio topics for the subsystem rundowns.

 
#include <banjo/app.h>
#include <banjo/main.h>
#include <banjo/bitmap.h>
#include <banjo/draw.h>
#include <banjo/event.h>
#include <banjo/system.h>
#include <banjo/time.h>
#include <banjo/window.h>
 
bj_window*   window   = 0;
 
static void on_draw(
    struct bj_window*        w,
    struct bj_render_target* target,
    const struct bj_rect*    dirty,
    void*                    user_data
) {
    (void)w; (void)dirty; (void)user_data;
    bj_bitmap* bmp = bj_render_target_bitmap(target);
    bj_clear_bitmap(bmp);
 
    const uint32_t red  = bj_make_bitmap_pixel(bmp, 0xFF, 0x00, 0x00);
    const uint32_t cyan = bj_make_bitmap_pixel(bmp, 0x00, 0xFF, 0xFF);
 
    bj_draw_filled_circle(bmp, 320, 240, 100, red);
    bj_draw_rectangle(bmp, &(bj_rect){.x = 200, .y = 120, .w = 240, .h = 240}, cyan);
}
 
static void* setup(struct bj_app* app, void* init_data) {
    (void)init_data;
 
    if (!bj_begin(BJ_VIDEO_SYSTEM, 0)) {
        bj_quit_app(app, 1);
        return 0;
    }
 
    window   = bj_bind_window("My First Banjo App", 100, 100, 640, 480, 0, 0);
    bj_set_key_callback(bj_close_on_escape, 0);
    bj_set_draw_callback(window, on_draw, 0);
    bj_invalidate_window(window);
    return 0;
}
 
static void step(struct bj_app* app, struct bj_tick_info tick, void* user_data) {
    (void)tick;
    (void)user_data;
 
    bj_dispatch_events();
 
    if (bj_should_close_window(window)) {
        bj_quit_app(app, 0);
    }
}
 
static void teardown(struct bj_app* app, void* user_data) {
    (void)app; (void)user_data;
 
    bj_unbind_window(window);
    bj_end();
}
 
int main(int argc, char* argv[]) {
    (void)argc; (void)argv;
    return bj_run_app(setup, step, 0, teardown, 0);
}