oxihuman_wasm/lib.rs
1// Copyright (C) 2026 COOLJAPAN OU (Team KitaSan)
2// SPDX-License-Identifier: Apache-2.0
3
4//! WebAssembly (and native) bindings for the OxiHuman morph engine.
5//!
6//! The main type is [`WasmEngine`], a thin wrapper around
7//! [`oxihuman_morph::engine::HumanEngine`] that exposes a flat, JavaScript-
8//! friendly API. In native builds it works exactly the same way — useful for
9//! server-side rendering or CLI tools that embed the WASM surface.
10//!
11//! # Buffer protocol
12//!
13//! [`WasmEngine::build_mesh_bytes`] returns a compact binary buffer. The
14//! layout is described by [`BUFFER_FORMAT_VERSION`]:
15//!
16//! ```text
17//! [version: u32 LE]
18//! [n_verts: u32 LE]
19//! [n_idx: u32 LE]
20//! [positions: f32 * 3 * n_verts]
21//! [normals: f32 * 3 * n_verts]
22//! [uvs: f32 * 2 * n_verts]
23//! [indices: u32 * n_idx]
24//! ```
25//!
26//! # JavaScript usage example
27//!
28//! ```js
29//! import init, { WasmEngine } from './oxihuman_wasm.js';
30//!
31//! await init();
32//! const engine = WasmEngine.new_from_obj_bytes(objBytes);
33//! engine.set_height(0.8);
34//! engine.set_weight(0.4);
35//! const buf = engine.build_mesh_bytes(); // Uint8Array
36//! const view = new DataView(buf.buffer);
37//! const nVerts = view.getUint32(4, true); // little-endian
38//! // upload positions starting at byte offset 12 to WebGL / WebGPU
39//! ```
40
41pub mod buffer;
42pub mod buffer_transfer;
43pub mod compressed_target;
44pub mod engine;
45pub mod error;
46pub mod memory_profile;
47pub mod pack;
48pub mod service_worker;
49
50// Engine implementation sub-modules (private; re-exported via `engine`).
51mod engine_anim;
52mod engine_core;
53mod engine_io;
54mod engine_targets;
55
56/// Full wasm-bindgen JS/TS API surface. Enabled with `--features bindgen`.
57#[cfg(feature = "bindgen")]
58pub mod wasm_api;
59
60/// TypeScript `.d.ts` supplemental type declarations. Enabled with `--features bindgen`.
61#[cfg(feature = "bindgen")]
62pub mod ts_types;
63
64// Re-exports for public API surface.
65pub use buffer::parse_mesh_bytes_header;
66pub use engine::{Particle, ParticleSystem, WasmEngine};
67
68/// Buffer format tag for the raw mesh bytes returned by `build_mesh_bytes()`.
69/// Layout: [n_verts: u32 LE][n_idx: u32 LE][positions: f32*3*n][normals: f32*3*n][uvs: f32*2*n][indices: u32*m]
70pub const BUFFER_FORMAT_VERSION: u32 = 1;
71
72#[cfg(test)]
73mod wasm_tests;