Skip to main content

Getting started

How to write a kernel, run it from Udon, and read the results back.

Quick start​

  1. Write a kernel. Parameter 0 (if i32) receives the pixel index; the others are arguments you set from Udon by name. Export as many functions as you like. The comment above each one is its inspector help, and two tags set it up: @size W x H (or @size N for N calls) is how many calls one Run() makes, and @traps turns on Trap Check.
#![no_std]
#[panic_handler] fn panic(_: &core::panic::PanicInfo) -> ! { loop {} }
#[link(wasm_import_module = "env")]
extern "C" {
fn input(i: i32) -> i32; // optional: reads SetInput() data
fn hlsl_sin(x: f32) -> f32; // optional: native GPU math
}

/// Multiplies each input word by `scale`.
/// @size 256x256
#[no_mangle]
pub extern "C" fn main(id: i32, scale: i32) -> i32 {
unsafe { input(id) } * scale
}

/// One sine sample per call.
/// @size 48000 @traps
#[no_mangle]
pub extern "C" fn tone(id: i32, freq: f32) -> f32 {
unsafe { hlsl_sin(id as f32 * freq * 0.000130899) }
}
  1. Build with a small stack (GPU memory lives in registers, see limits):
RUSTFLAGS="-C link-arg=-zstack-size=4096 -C target-cpu=mvp -C target-feature=+bulk-memory,+sign-ext,+nontrapping-fptoint" cargo build --release --target wasm32-unknown-unknown

Add ,+simd128 (and ,+relaxed-simd) to the features to use core::arch::wasm32 SIMD.

  1. Copy the .wasm into Assets/. Nothing else is created: the shader, material and render texture live inside the .wasm asset (expand it in the Project window to see them).

  2. Drag the .wasm into the Hierarchy or Scene view. You get a GameObject with a ready WasmGpuRunner that holds every exported function. Its inspector has: the .wasm, Function (the one Run() calls), its arguments under their source names, Size and Trap Check (locked when @size / @traps set them), and Test (runs it on the GPU without Play Mode).

  3. Call it from your U# script:

public WasmGpuRunner runner;
void Start()
{
runner.callbackTarget = this;
runner.SetFunction("main"); // or keep the inspector's Function
runner.SetNamedArgInt("scale", 3); // or SetArgInt(1, 3): wasm parameter index
runner.SetInput(myData);
runner.Run(); // RunFunction("tone") = SetFunction + Run
}
public void OnWasmComplete() { Debug.Log(runner.resultFunction + ": " + runner.resultLo[0] + (runner.trapped ? " (trapped)" : "")); }

One function runs at a time per runner (busy); each function keeps its own argument values.

Names from source​

Release wasm keeps function names but drops parameter names, so they are read from the source next to the .wasm (its folder and src/; point Source Path in the .wasm import settings elsewhere if needed). Source in the project reimports the .wasm when it changes. Recognised exports:

LanguageExportRename
Rustpub extern "C" fn name(a: i32)#[export_name = "x"]
C / C++any function definition int name(int a)__attribute__((export_name("x")))
Zigexport fn name(a: i32) i32—
AssemblyScriptexport function name(a: i32): i32—
TinyGo//export name or //go:wasmexport name above func—

Without source, arguments are called arg1, arg2, … and Size / Trap Check come from the import settings.

Output layout​

Export returnsRead with
i32resultLo[i]
f32resultFloat[i], read back natively with no per-value Udon loop, so millions of results are fine
f64resultFloat[i] (rounded to f32: Udon reads floats; compute in f64, return what you need)
i64resultLo[i] (low 32 bits), resultHi[i] (high 32 bits)
funcref / externrefresultLo[i]: function index, -1 = null

Arguments: i32/i64/refs are set with SetArgInt, f32/f64 with SetArgFloat (an f64 argument is a float widened exactly; pass a double as two floats, hi = (float)d and lo = (float)(d - hi), and add them in f64 when you need all its bits — see Example/DeepZoom). v128 can't be an export parameter or result (Udon has no 128-bit value); such exports are skipped with an import warning.

To skip readback entirely, show the render texture: WASM2HLSL/Int Display (in Example/) reads it as packed RGBA8 or an iteration palette.

Trap Check​

Trap Check (@traps in source, the runner inspector, or the .wasm import settings) sets runner.trapped when any call hits unreachable, divides by zero, calls a bad call_indirect slot, or loops more than W_MAX_LOOP_ITER (65536) times. That call returns 0. It is off by default because it adds one more set of rows to read back.

Supported​

Every WebAssembly value type:

TypeOn the GPUExact?
i32uintyes
i64uint2, emulated (mul/div/rem/shift/rotate/clz/…)yes
f32floatGPU float (last-bit rounding may differ, div/sqrt within a few ulp, denormals may flush)
f64uint2 holding the IEEE bits, software float (SoftFloat's algorithms, round to nearest even)yes, bit-exact incl. subnormals, div, sqrt, conversions
v128uint4: all of SIMD (i8x16 … f64x2) plus relaxed SIMD (deterministic)integer and f64x2 lanes yes; f32x4 lanes like f32
funcref / externrefuint (function index, 0xFFFFFFFF = null)yes
  • Full MVP instruction set, plus sign-extension, saturating truncation, memory.copy / memory.fill, multi-value blocks.
  • Direct calls, call_indirect (dispatched with an if chain), mutable globals, data segments.
  • Reference types: ref.null / ref.is_null / ref.func, typed select, ref locals/globals, multiple tables, table.get / set / size / grow (always fails, like memory.grow) / fill / copy / init, elem.drop. A table that code writes to is kept per pixel, and call_indirect through it dispatches on the function stored there.
  • Imports: input(i32) -> i32 (raw words from SetInput) and math mapped to HLSL intrinsics: hlsl_sin, hlsl_cos, hlsl_tan, hlsl_asin, hlsl_acos, hlsl_atan, hlsl_atan2, hlsl_sinh, hlsl_cosh, hlsl_tanh, hlsl_exp, hlsl_exp2, hlsl_log, hlsl_log2, hlsl_log10, hlsl_pow, hlsl_sqrt, hlsl_fmod, hlsl_fmin, hlsl_fmax, … (plain sinf/powf work too in C, but Rust's compiler_builtins links its own software libm for those names — use the hlsl_ prefix).

Limits (by design of GPU shaders)​

LimitWhyWorkaround
No recursionHLSL has no call stack; the converter errors with the cycle.Rewrite as a loop.
≤ 64000 bytes of writable memoryLinear memory is a per-pixel uint4 register array (fxc cap 4096 registers). The size is data end + stack, not the declared pages. Constant data does not count (see Big constant tables).-zstack-size=4096, small mutable statics, no heap.
memory.grow always failsMemory is fixed.Use no_std without an allocator.
f64 is slowQuest/mobile GPUs have no doubles, so every f64 op is ~100 integer instructions (div/sqrt loop 55–63 times). Shaders using f64 compile slower: ~1 min for Example/DeepZoom, and fxc's time grows faster than linearly, so one export using dozens of different f64 ops can take many minutes.Use f32 where it is precise enough. Split big f64 kernels into several exports: each export compiles only the code it reaches.
Math imports run in f32hlsl_sin(f64) etc. call the GPU's float intrinsic.Write the function in f64 yourself when you need the precision.
No threads, exceptions, GC, tail calls, memory.init / data.dropNot expressible in a pixel shader.—
Large modules compile slowlyfxc inlines every function. A ~6 KB kernel takes ~10 s; Rust's software libm (f32::sin via compiler_builtins) takes many minutes.Use hlsl_* imports instead of libm; keep kernels small.

Memory is private to each pixel and resets every run; pixels cannot talk to each other. Return values are the only output.

Big constant tables (no limit)​

Read-only data (.rodata: static / const tables, strings, lookup tables) of 1 KB or more is read from a texture, so it takes no registers and can be megabytes. It happens on import, with nothing to change in the source:

static PALETTE: [u32; 16384] = make_palette(); // 64 KB: over the register limit, fine as .rodata
  • The .wasm asset gets a rom texture (RGBA32 linear, one word per texel, 4096 wide), already set as _WasmRom on every export's material. The summary shows its size next to "GPU memory per call".
  • Reads cost one texture fetch per word; registers stay faster for small hot tables. Import settings > Texture Constants From (bytes) sets the threshold (default 1024); 0 keeps everything in registers.
  • Writing into it sets the trap flag (.rodata writes are undefined behaviour in Rust/C anyway). Mutable static mut data stays in registers.
  • It needs the segment names in the wasm name section, which cargo build and clang keep. wasm-opt --strip / wasm-strip remove them; then everything stays in registers.
  • Tested: Tests~/run.sh mode 8 reads a 96 KB table (words, bytes, unaligned, copied to the stack and modified) bit-for-bit like Node.

Docs: Overview