Skip to main content

Crate wasm96_sdk

Crate wasm96_sdk 

Source
Expand description

wasm96-sdk (handwritten)

This crate is used by guest WASM apps that run inside the wasm96 libretro core.

ABI model (Immediate Mode):

  • Host owns the framebuffer and handles rendering.
  • Guest issues drawing commands.
  • Guest exports setup, update, and draw.

This file intentionally contains no WIT and no codegen.

§Fonts & text: how it works

wasm96 provides a keyed font model:

  • You register a font under a u64 key (the SDK hashes &str keys for you).
  • Later you draw or measure text by referencing the same key.

In the Rust SDK:

§Fallback behavior (important)

The host (wasm96-core) implements a fallback if you try to measure/draw text using a font_key that was never registered:

  • graphics::text_key(...) falls back to the built-in Spleen font at size 16.
  • graphics::text_measure_key(...) uses the same fallback (Spleen size 16).

This means text “just works” out-of-the-box, but you should still register fonts when you care about style, metric stability, or performance.

§Which font format should you use?

  • Spleen (built-in, BDF) via graphics::font_register_spleen
    • Great default for pixel UIs / debug text.
    • Supported sizes: 8, 16, 24, 32, 64 (other sizes currently fail and return false).
  • BDF (custom) via graphics::font_register_bdf
    • Best for pixel-perfect fonts you control.
    • Host parses the BDF, builds a glyph map, and renders using the parsed bitmaps.
  • TTF/OTF (custom) via graphics::font_register_ttf
    • Best for scalable fonts.
    • Host uses font rasterization and draws glyphs as alpha-blended bitmaps.
  1. Pick a stable string key for each font you use (e.g. "ui", "title", "debug").
  2. Register fonts during setup() (once).
  3. Use text_measure_key for layout (e.g. centering).
  4. Use text_key to draw. Reuse keys; do not re-register each frame.

Example (built-in Spleen):

use wasm96_sdk::graphics;

#[no_mangle]
pub extern "C" fn setup() {
    graphics::set_size(320, 240);
    // Register built-in Spleen under a key you control.
    graphics::font_register_spleen("ui", 16);
}

#[no_mangle]
pub extern "C" fn draw() {
    graphics::background(0, 0, 0);
    graphics::set_color(255, 255, 255, 255);

    let size = graphics::text_measure_key("ui", "Hello wasm96");
    let x = (320i32 - size.width as i32) / 2;
    let y = 20;
    graphics::text_key(x, y, "ui", "Hello wasm96");
}

§Lifetimes and safety notes

  • text_key and text_measure_key pass pointers into guest memory to the host. The host reads the bytes immediately during the call, so the &str only needs to remain valid for the duration of the function call.
  • font_register_* similarly passes pointers to font data; the host copies/decodes immediately.

§Unregistering fonts

If you need to reclaim host-side font resources (rare for most games), call graphics::font_unregister. The key will no longer map to a font. Subsequent text usage with that key will again hit the host fallback (Spleen size 16).

Modules§

audio
Audio API.
graphics
Graphics API.
input
Input API.
prelude
Convenience prelude for guest apps.
storage
Storage API.
sys
Low-level raw ABI imports.
system
System API.

Structs§

TextSize
Text size dimensions.

Enums§

Button
Joypad button ids.