Crate oxide_sdk

Expand description

§Oxide SDK

Guest-side SDK for building WebAssembly applications that run inside the Oxide browser. This crate provides safe Rust wrappers around the raw host-imported functions exposed by the "oxide" wasm import module.

§Quick Start

Add oxide-sdk to your Cargo.toml and set crate-type = ["cdylib"]:

[lib]
crate-type = ["cdylib"]

[dependencies]
oxide-sdk = "0.2"

Then write your app:

use oxide_sdk::*;

#[no_mangle]
pub extern "C" fn start_app() {
    log("Hello from Oxide!");
    canvas_clear(30, 30, 46, 255);
    canvas_text(20.0, 40.0, 28.0, 255, 255, 255, "Welcome to Oxide");
}

Build with cargo build --target wasm32-unknown-unknown --release.

§Interactive Apps

For apps that need a render loop, export on_frame:

use oxide_sdk::*;

#[no_mangle]
pub extern "C" fn start_app() {
    log("Interactive app started");
}

#[no_mangle]
pub extern "C" fn on_frame(_dt_ms: u32) {
    canvas_clear(30, 30, 46, 255);
    let (mx, my) = mouse_position();
    canvas_circle(mx, my, 20.0, 255, 100, 100, 255);

    if ui_button(1, 20.0, 20.0, 100.0, 30.0, "Click me!") {
        log("Button was clicked!");
    }
}

§API Categories

Category	Functions
Canvas	`canvas_clear`, `canvas_rect`, `canvas_circle`, `canvas_text`, `canvas_line`, `canvas_image`, `canvas_dimensions`
Console	`log`, `warn`, `error`
HTTP	`fetch`, `fetch_get`, `fetch_post`, `fetch_post_proto`, `fetch_put`, `fetch_delete`
Protobuf	`proto::ProtoEncoder`, `proto::ProtoDecoder`
Storage	`storage_set`, `storage_get`, `storage_remove`, `kv_store_set`, `kv_store_get`, `kv_store_delete`
Audio	`audio_play`, `audio_play_url`, `audio_pause`, `audio_resume`, `audio_stop`, `audio_set_volume`, `audio_channel_play`
Timers	`set_timeout`, `set_interval`, `clear_timer`, `time_now_ms`
Navigation	`navigate`, `push_state`, `replace_state`, `get_url`, `history_back`, `history_forward`
Input	`mouse_position`, `mouse_button_down`, `key_down`, `key_pressed`, `scroll_delta`
Widgets	`ui_button`, `ui_checkbox`, `ui_slider`, `ui_text_input`
Crypto	`hash_sha256`, `hash_sha256_hex`, `base64_encode`, `base64_decode`
Other	`clipboard_write`, `clipboard_read`, `random_u64`, `random_f64`, `notify`, `upload_file`, `load_module`

§Full API Documentation

See https://docs.oxide.foundation/oxide_sdk/ for the complete API reference, or browse the individual function documentation below.

Modules§

proto: Lightweight protobuf wire-format encoder/decoder.

Structs§

FetchResponse: Response from an HTTP fetch call.
UploadedFile: File returned from the native file picker.

Constants§

Functions§

alt_held: Returns true if Alt is held.
audio_channel_play: Play audio on a specific channel. Multiple channels play simultaneously. Channel 0 is the default used by audio_play. Use channels 1+ for layered sound effects, background music, etc.
audio_channel_set_volume: Set volume for a specific channel (0.0 silent, 1.0 normal, up to 2.0 boost).
audio_channel_stop: Stop playback on a specific channel.
audio_duration: Get the total duration of the currently loaded track in milliseconds. Returns 0 if unknown or nothing is loaded.
audio_get_volume: Get the current audio volume.
audio_is_playing: Returns true if audio is currently playing (not paused and not empty).
audio_pause: Pause audio playback.
audio_play: Play audio from encoded bytes (WAV, MP3, OGG, FLAC). The host decodes and plays the audio. Returns 0 on success, negative on error.
audio_play_url: Fetch audio from a URL and play it. The host performs the HTTP fetch and decodes the audio. Returns 0 on success, negative on error.
audio_position: Get the current playback position in milliseconds.
audio_resume: Resume paused audio playback.
audio_seek: Seek to a position in milliseconds. Returns 0 on success, negative on error.
audio_set_loop: Enable or disable looping on the default channel. When enabled, subsequent audio_play calls will loop indefinitely.
audio_set_volume: Set audio volume. 1.0 is normal, 0.0 is silent, up to 2.0 for boost.
audio_stop: Stop audio playback and clear the queue.
base64_decode: Decode a base64-encoded string back to bytes.
base64_encode: Base64-encode arbitrary bytes.
canvas_circle: Draw a filled circle.
canvas_clear: Clear the canvas with a solid RGBA color.
canvas_dimensions: Returns (width, height) of the canvas in pixels.
canvas_image: Draw an image on the canvas from encoded image bytes (PNG, JPEG, GIF, WebP). The browser decodes the image and renders it at the given rectangle.
canvas_line: Draw a line between two points.
canvas_rect: Draw a filled rectangle.
canvas_text: Draw text on the canvas.
clear_hyperlinks: Remove all previously registered hyperlinks.
clear_timer: Cancel a timer previously created with set_timeout or set_interval.
clipboard_read: Read text from the system clipboard.
clipboard_write: Copy text to the system clipboard.
ctrl_held: Returns true if Ctrl (or Cmd on macOS) is held.
error: Print an error to the browser console.
fetch: Perform an HTTP request. Returns the status code and response body.
fetch_delete: HTTP DELETE.
fetch_get: HTTP GET request.
fetch_post: HTTP POST with raw bytes.
fetch_post_proto: HTTP POST with protobuf body (sets Content-Type: application/protobuf).
fetch_put: HTTP PUT with raw bytes.
get_location: Get the device’s mock geolocation as a "lat,lon" string.
get_state: Retrieve the opaque state bytes attached to the current history entry. Returns None if no state has been set.
get_url: Get the URL of the currently loaded page.
hash_sha256: Compute the SHA-256 hash of the given data. Returns 32 bytes.
hash_sha256_hex: Return SHA-256 hash as a lowercase hex string.
history_back: Navigate backward in history. Returns true if a navigation was queued.
history_forward: Navigate forward in history. Returns true if a navigation was queued.
history_length: Return the total number of entries in the history stack.
key_down: Returns true if the given key is currently held down. See KEY_* constants for key codes.
key_pressed: Returns true if the given key was pressed this frame.
kv_store_delete: Delete a key from the persistent KV store. Returns true on success.
kv_store_get: Retrieve a value from the persistent KV store. Returns None if the key does not exist.
kv_store_get_str: Convenience wrapper: retrieve a UTF-8 string value.
kv_store_set: Store a key-value pair in the persistent on-disk KV store. Returns true on success.
kv_store_set_str: Convenience wrapper: store a UTF-8 string value.
load_module: Fetch and execute another .wasm module from a URL. The loaded module shares the same canvas, console, and storage context. Returns 0 on success, negative error code on failure.
log: Print a message to the browser console (log level).
modifiers: Returns modifier key state as a bitmask: bit 0 = Shift, bit 1 = Ctrl, bit 2 = Alt.
mouse_button_clicked: Returns true if the given mouse button was clicked this frame.
mouse_button_down: Returns true if the given mouse button is currently held down. Button 0 = primary (left), 1 = secondary (right), 2 = middle.
mouse_position: Get the mouse position in canvas-local coordinates.
navigate: Navigate to a new URL. The URL can be absolute or relative to the current page. Navigation happens asynchronously after the current start_app returns. Returns 0 on success, negative on invalid URL.
notify: Send a notification to the user (rendered in the browser console).
push_state: Push a new entry onto the browser’s history stack without triggering a module reload. This is analogous to history.pushState() in web browsers.
random_f64: Get a random f64 in [0, 1).
random_u64: Get a random u64 from the host.
register_hyperlink: Register a rectangular region on the canvas as a clickable hyperlink.
replace_state: Replace the current history entry (no new entry is pushed). Analogous to history.replaceState().
scroll_delta: Get the scroll wheel delta for this frame.
set_interval: Schedule a repeating timer that fires every interval_ms milliseconds. When it fires the host calls your exported on_timer(callback_id). Returns a timer ID that can be passed to clear_timer.
set_timeout: Schedule a one-shot timer that fires after delay_ms milliseconds. When it fires the host calls your exported on_timer(callback_id). Returns a timer ID that can be passed to clear_timer.
shift_held: Returns true if Shift is held.
storage_get: Retrieve a value from local storage. Returns empty string if not found.
storage_remove: Remove a key from local storage.
storage_set: Store a key-value pair in sandboxed local storage.
time_now_ms: Get the current time in milliseconds since the UNIX epoch.
ui_button: Render a button at the given position. Returns true if it was clicked on the previous frame.
ui_checkbox: Render a checkbox. Returns the current checked state.
ui_slider: Render a slider. Returns the current value.
ui_text_input: Render a single-line text input. Returns the current text content.
upload_file: Opens the native OS file picker and returns the selected file. Returns None if the user cancels.
url_decode: Decode a percent-encoded string.
url_encode: Percent-encode a string for safe inclusion in URL components.
url_resolve: Resolve a relative URL against a base URL (WHATWG algorithm). Returns None if either URL is invalid.
warn: Print a warning to the browser console.

Crate oxide_sdk

Crate oxide_sdk Copy item path

§Oxide SDK

§Quick Start

§Interactive Apps

§API Categories

§Full API Documentation

Modules§

Structs§

Constants§

Functions§

Crate oxide_sdk