Skip to main content

เริ่มต้นใช้งาน

วิธีเขียน kernel, เรียกใช้จาก Udon และอ่านผลลัพธ์กลับ

ขั้นตอนรวดเร็ว​

  1. เขียน kernel พารามิเตอร์ 0 (ถ้าเป็น i32) รับ index ของพิกเซล ส่วนที่เหลือคือ argument ที่ตั้งจาก Udon ตามชื่อ export ได้หลายฟังก์ชันตามต้องการ คอมเมนต์เหนือแต่ละฟังก์ชันคือคำอธิบายใน inspector และมีสองแท็กที่ใช้ตั้งค่า: @size W x H (หรือ @size N สำหรับ N ครั้ง) คือจำนวนการเรียกต่อหนึ่ง Run() และ @traps เปิด Trap Check
#![no_std]
#[panic_handler] fn panic(_: &core::panic::PanicInfo) -> ! { loop {} }
#[link(wasm_import_module = "env")]
extern "C" {
fn input(i: i32) -> i32; // ไม่บังคับ: อ่านข้อมูลจาก SetInput()
fn hlsl_sin(x: f32) -> f32; // ไม่บังคับ: คณิตศาสตร์ GPU จริง
}

/// คูณแต่ละ word ของ input ด้วย `scale`
/// @size 256x256
#[no_mangle]
pub extern "C" fn main(id: i32, scale: i32) -> i32 {
unsafe { input(id) } * scale
}

/// หนึ่งตัวอย่าง sine ต่อการเรียก
/// @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 ด้วย stack เล็ก (หน่วยความจำ GPU อยู่ใน register ดูหัวข้อ ข้อจำกัด ด้านล่าง):
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

เพิ่ม ,+simd128 (และ ,+relaxed-simd) ใน features เพื่อใช้ core::arch::wasm32 SIMD

  1. คัดลอก .wasm ไปไว้ใน Assets/ ไม่มีอย่างอื่นถูกสร้าง: shader, material และ render texture อยู่ใน .wasm asset (ขยายใน Project window เพื่อดู)

  2. ลาก .wasm ไปที่ Hierarchy หรือ Scene view คุณจะได้ GameObject ที่มี WasmGpuRunner พร้อมใช้ซึ่งเก็บทุกฟังก์ชันที่ export inspector มี: .wasm, Function (ตัวที่ Run() เรียก), argument ในชื่อตามซอร์ส, Size และ Trap Check (ล็อกเมื่อ @size / @traps กำหนด) และ Test (รันบน GPU โดยไม่ต้องเข้า Play Mode)

  3. เรียกจากสคริปต์ U#:

public WasmGpuRunner runner;
void Start()
{
runner.callbackTarget = this;
runner.SetFunction("main"); // หรือคง Function จาก inspector
runner.SetNamedArgInt("scale", 3); // หรือ SetArgInt(1, 3): index พารามิเตอร์ wasm
runner.SetInput(myData);
runner.Run(); // RunFunction("tone") = SetFunction + Run
}
public void OnWasmComplete() { Debug.Log(runner.resultFunction + ": " + runner.resultLo[0] + (runner.trapped ? " (trapped)" : "")); }

แต่ละ runner รันทีละฟังก์ชัน (busy) และแต่ละฟังก์ชันเก็บค่า argument ของตัวเอง

ชื่อจากซอร์ส​

wasm แบบ release เก็บชื่อฟังก์ชันไว้แต่ทิ้งชื่อพารามิเตอร์ จึงอ่านจากซอร์สข้าง .wasm (โฟลเดอร์นั้นและ src/; ตั้ง Source Path ในการตั้ง import ของ .wasm ได้ถ้าต้องการ) ซอร์สในโปรเจกต์จะทำให้ .wasm reimport เมื่อเปลี่ยน รูปแบบ export ที่รองรับ:

ภาษาExportเปลี่ยนชื่อ
Rustpub extern "C" fn name(a: i32)#[export_name = "x"]
C / C++นิยามฟังก์ชัน int name(int a)__attribute__((export_name("x")))
Zigexport fn name(a: i32) i32—
AssemblyScriptexport function name(a: i32): i32—
TinyGo//export name หรือ //go:wasmexport name เหนือ func—

ถ้าไม่มีซอร์ส argument จะชื่อ arg1, arg2, … และ Size / Trap Check มาจากการตั้ง import

รูปแบบผลลัพธ์​

Export คืนค่าอ่านด้วย
i32resultLo[i]
f32resultFloat[i] อ่านกลับแบบ native ไม่ต้องวนลูป Udon ต่อค่า จึงมีผลเป็นล้านค่าได้
f64resultFloat[i] (ปัดเป็น f32: Udon อ่าน float คำนวณด้วย f64 แล้วคืนค่าที่ต้องการ)
i64resultLo[i] (32 บิตล่าง), resultHi[i] (32 บิตบน)
funcref / externrefresultLo[i]: index ของฟังก์ชัน, -1 = null

Argument: i32/i64/ref ตั้งด้วย SetArgInt, f32/f64 ตั้งด้วย SetArgFloat (argument f64 คือ float ที่ขยายแบบ exact; ส่ง double เป็นสอง float คือ hi = (float)d และ lo = (float)(d - hi) แล้วบวกเป็น f64 เมื่อต้องการครบตามบิต ดู Example/DeepZoom) v128 เป็น parameter หรือผลลัพธ์ของ export ไม่ได้ (Udon ไม่มีค่า 128 บิต) export แบบนี้จะถูกข้ามพร้อมคำเตือนตอน import

ถ้าไม่อยาก readback เลย ให้แสดง render texture: WASM2HLSL/Int Display (อยู่ใน Example/) อ่านเป็น RGBA8 แบบ pack หรือ palette ตามจำนวนรอบ

Trap Check​

Trap Check (@traps ในซอร์ส, inspector ของ runner หรือการตั้ง import ของ .wasm) ตั้ง runner.trapped เมื่อการเรียกใดโดน unreachable, หารด้วยศูนย์, เรียกช่อง call_indirect ผิด หรือลูปเกิน W_MAX_LOOP_ITER (65536) ครั้ง การเรียกนั้นจะคืน 0 ปิดไว้เป็นค่าเริ่มต้นเพราะเพิ่มแถวที่ต้อง readback อีกชุด

รองรับ​

ทุกชนิดค่าของ WebAssembly:

ชนิดบน GPUตรงเป๊ะ?
i32uintใช่
i64uint2 จำลอง (mul/div/rem/shift/rotate/clz/…)ใช่
f32floatfloat ของ GPU (การปัดบิตสุดท้ายอาจต่าง, div/sqrt คลาดไม่กี่ ulp, denormal อาจถูก flush)
f64uint2 เก็บบิต IEEE, float ซอฟต์แวร์ (อัลกอริทึมของ SoftFloat, round to nearest even)ใช่ ตรงทุกบิต รวม denormal, div, sqrt, การแปลง
v128uint4: SIMD ครบ (i8x16 … f64x2) รวม relaxed SIMD (กำหนดได้แน่นอน)lane จำนวนเต็มและ f64x2 ใช่; lane f32x4 เหมือน f32
funcref / externrefuint (index ฟังก์ชัน, 0xFFFFFFFF = null)ใช่
  • ชุดคำสั่ง MVP ครบ รวม sign-extension, การตัดแบบ saturating, memory.copy / memory.fill และบล็อก multi-value
  • การเรียกตรง, call_indirect (dispatch ด้วย chain ของ if), global ที่เปลี่ยนค่าได้ และ data segment
  • Reference types: ref.null / ref.is_null / ref.func, select แบบมีชนิด, ref local/global, หลายตาราง, table.get / set / size / grow (ล้มเหลวเสมอ เหมือน memory.grow) / fill / copy / init, elem.drop ตารางที่โค้ดเขียนจะเก็บแยกต่อพิกเซล และ call_indirect ผ่านมันจะ dispatch ตามฟังก์ชันที่เก็บไว้
  • Import: input(i32) -> i32 (word ดิบจาก SetInput) และคณิตศาสตร์ที่ map ไป HLSL intrinsic: 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, … (sinf/powf ใช้ได้ใน C ด้วย แต่ compiler_builtins ของ Rust link libm ซอฟต์แวร์ของตัวเองกับชื่อเหล่านั้น ให้ใช้นำหน้า hlsl_)

ข้อจำกัด (ข้อจำกัด by design ของ GPU shader)​

ข้อจำกัดเหตุผลวิธีแก้
ไม่มี recursionHLSL ไม่มี call stack ตัวแปลงจะ error พร้อมบอกวงจรเขียนเป็นลูปใหม่
หน่วยความจำที่เขียนได้ ≤ 64000 bytesLinear memory คืออาร์เรย์ register uint4 ต่อพิกเซล (fxc จำกัด 4096 register) ขนาดคือจุดสิ้นสุดข้อมูล + stack ไม่ใช่จำนวน page ที่ประกาศ ข้อมูลค่าคงที่ไม่นับรวม (ดูหัวข้อ ตารางค่าคงที่ขนาดใหญ่)-zstack-size=4096, static ที่เปลี่ยนค่าได้เล็กๆ, ไม่มี heap
memory.grow เสมอ failหน่วยความจำคงที่ใช้ no_std โดยไม่มี allocator
f64 ช้าGPU มือถือ/Quest ไม่มี double จึงทุก operation ของ f64 เป็นคำสั่งจำนวนเต็มราว 100 ตัว (div/sqrt ลูป 55–63 ครั้ง) shader ที่ใช้ f64 compile ช้าด้วย: Example/DeepZoom ราว 1 นาที และเวลาของ fxc เพิ่มแบบเหนือเชิงเส้น export เดียวที่ใช้ f64 หลายสิบแบบจึงอาจกินหลายนาทีใช้ f32 ถ้าความแม่นยำพอ แบ่ง kernel f64 ใหญ่เป็นหลาย export: แต่ละ export compile เฉพาะโค้ดที่ไปถึง
Math import รันเป็น f32hlsl_sin(f64) ฯลฯ เรียก float intrinsic ของ GPUเขียนฟังก์ชันนั้นเป็น f64 เองเมื่อต้องการความแม่นยำ
ไม่มี thread, exception, GC, tail call, memory.init / data.dropแสดงผลใน pixel shader ไม่ได้—
โมดูลใหญ่ compile ช้าfxc inline ทุกฟังก์ชัน kernel ~6 KB ใช้ ~10 วินาที ส่วน libm ซอฟต์แวร์ของ Rust (f32::sin ผ่าน compiler_builtins) ใช้หลายนาทีใช้ hlsl_* แทน libm และ keep kernel เล็กๆ

หน่วยความจำเป็นของส่วนตัวต่อพิกเซลและรีเซตทุกครั้งที่รัน พิกเซลคุยกันไม่ได้ ผลลัพธ์ที่ return เท่านั้นคือ output

ตารางค่าคงที่ขนาดใหญ่ (ไม่มีขีดจำกัด)​

ข้อมูลแบบ read-only (.rodata: ตาราง static / const, string, lookup table) ที่ 1 KB ขึ้นไปถูกอ่านจากเท็กซ์เจอร์ จึงไม่ใช้ register และมีได้หลาย MB เกิดขึ้นตอน import โดยไม่ต้องแก้ซอร์ส

static PALETTE: [u32; 16384] = make_palette(); // 64 KB: เกินขีดจำกัด register แต่เป็น .rodata ก็ใช้ได้
  • .wasm asset ได้เท็กซ์เจอร์ rom (RGBA32 linear, หนึ่ง word ต่อ texel กว้าง 4096) ตั้งเป็น _WasmRom บน material ของทุก export แล้ว summary แสดงขนาดข้าง "GPU memory per call"
  • การอ่านคิดหนึ่ง texture fetch ต่อ word; register ยังเร็วกว่าสำหรับตารางเล็กๆ ที่ใช้บ่อย Import settings > Texture Constants From (bytes) กำหนดเกณฑ์ (ค่าเริ่ม 1024; 0 คือเก็บทุกอย่างใน register)
  • การเขียนลงในนั้นตั้งแฟล็ก trap (การเขียน .rodata เป็น undefined behaviour ใน Rust/C อยู่แล้ว) ข้อมูล static mut ที่เปลี่ยนค่าได้อยู่ใน register
  • ต้องมีชื่อ segment ใน wasm name section ซึ่ง cargo build และ clang เก็บไว้ wasm-opt --strip / wasm-strip จะลบทิ้ง ตอนนั้นทุกอย่างอยู่ใน register
  • ทดสอบ: Tests~/run.sh mode 8 อ่านตาราง 96 KB (word, byte, ไม่ตรงขอบ, คัดลอกไป stack แล้วแก้) ตรงทุกบิตกับ Node

เอกสาร: ภาพรวม