load_bmp.c

Tutorial: Load a BMP file from disk, query its size, and blit it to the window framebuffer.

Tutorial: Load a BMP file from disk, query its size, and blit it to the window framebuffer.This tutorial introduces the bitmap loader and the blit operation: the two pieces you need to move pre-made artwork from disk into your window. Banjo includes a self-contained BMP reader, so there is no external image library to install.

What you'll learn

• Load a BMP file with bj_create_bitmap_from_file.
• Query a bitmap's dimensions with bj_bitmap_width and bj_bitmap_height, then use them to size the window.
• Copy one bitmap into another with bj_blit_stretched, which does the scaling for you.
• Free the loaded bitmap with bj_destroy_bitmap, in the right order (after bj_end).

Prerequisites

You've worked through start.c (window + draw callback) and understand what a framebuffer is. The drawing-primitive tutorial (drawing_2d.c) is helpful but not required.

Walkthrough

1. Load before initialising video

The bitmap is loaded before bj_begin. That order is deliberate: bj_create_bitmap_from_file doesn't depend on the video subsystem (it only allocates memory and reads from disk), so you can load assets up-front and bail out if something is missing before paying for video initialisation. The BANJO_ASSETS_DIR macro expands to the path of the bundled assets directory at build time, so the example is location-independent.

2. Size the window to the asset

Once the bitmap is loaded, bj_bitmap_width and bj_bitmap_height tell you the source size. The tutorial scales up by 10× so the sprite sheet is large enough to read; for a real game you'd usually keep 1:1.

3. bj_blit_stretched does the scaling

bj_blit_stretched copies the source bitmap into the destination (here, the window's framebuffer) and stretches as needed to fit. Passing NULL for either rectangle means "use the entire bitmap". The last argument is the blit operation; BJ_BLIT_OP_COPY is a straight pixel copy with no blending. The companion bj_blit (no stretch) is faster when you don't need scaling.

4. Clean up in the right order

Window → bj_end → loaded bitmaps. Destroying the bitmap last guarantees that no Banjo subsystem still references it when bj_destroy_bitmap returns its memory.

What's next

• bitmap_blit.c: sub-rectangle blits (used for sprite sheets).
• bitmap_blit_colorkey.c: colour-key transparency for sprites.
• sprite_animation.c: frame-based animation from a sheet.
• The Bitmap topic for the full bitmap API.

 
#include <banjo/app.h>
#include <banjo/main.h>
#include <banjo/bitmap.h>
#include <banjo/event.h>
#include <banjo/log.h>
#include <banjo/memory.h>
#include <banjo/system.h>
#include <banjo/time.h>
#include <banjo/window.h>
 
bj_window* window               = 0;
bj_bitmap* bmp_sprite_sheet     = 0;
 
// Static image: just stretch-blit the loaded sprite sheet to the
// framebuffer whenever banjo asks for a paint. The user's model (the
// loaded bitmap) persists across calls.
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_blit_stretched(bmp_sprite_sheet, 0, bj_render_target_bitmap(target), 0, BJ_BLIT_OP_COPY);
}
 
static void* setup(struct bj_app* app, void* init_data) {
    (void)init_data;
 
    // Load a BMP file from disk. BANJO_ASSETS_DIR is a macro pointing to the
    // assets directory. The second parameter is an optional error pointer.
    // Returns NULL on failure (file not found, invalid format, etc.).
    bmp_sprite_sheet = bj_create_bitmap_from_file(BANJO_ASSETS_DIR"/bmp/gabe-idle-run.bmp", 0);
 
    if (!bj_begin(BJ_VIDEO_SYSTEM, 0)) {
        bj_quit_app(app, 1);
        return 0;
    }
 
    // Create a window sized to the loaded bitmap. bj_bitmap_width() and
    // bj_bitmap_height() query the dimensions. We scale by 10 for visibility
    // since the sprite sheet is small.
    window = bj_bind_window("sprite sheet - Banjo", 0, 0,
        bj_bitmap_width(bmp_sprite_sheet) * 10,
        bj_bitmap_height(bmp_sprite_sheet) * 10,
        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)user_data;
    bj_unbind_window(window);
    bj_end();
 
    // Always destroy loaded bitmaps to free memory. Do this after bj_end()
    // to ensure the bitmap isn't referenced by any Banjo subsystems.
    bj_destroy_bitmap(bmp_sprite_sheet);
}
 
int main(int argc, char* argv[]) {
    (void)argc; (void)argv;
    return bj_run_app(setup, step, 0, teardown, 0);
}