@plasius/gpu-renderer

Framework-independent WebGPU rendering for browser applications. Render triangle meshes with the wavefront path tracer, draw native raster surfaces, or use the frame lifecycle and XR integration APIs in your own rendering pipeline.

The APIs expose GPU resource ownership, render passes and sample accumulation directly. Use them from JavaScript or TypeScript when you want explicit control over your application's WebGPU pipeline.

Apache-2.0 · ESM and CommonJS · TypeScript declarations included.

Install

npm install @plasius/gpu-renderer

Use Node.js 24 or later for package tooling and a WebGPU-capable browser over HTTPS or localhost for rendering. This is a browser GPU runtime; installing it in Node does not provide a GPU device. A bundler resolves the package imports. Initialization rejects when WebGPU or the requested resources are unavailable; your application should present that error and an appropriate retry/fallback UI.

Quick start: render a mesh

Add a canvas to your page:

<canvas id="scene" width="640" height="360" aria-label="Rendered triangle"></canvas>

The following browser module renders a single emissive triangle:

import { createWavefrontPathTracingComputeRenderer } from "@plasius/gpu-renderer";

const renderer = await createWavefrontPathTracingComputeRenderer({
  canvas: "#scene",
  width: 640,
  height: 360,
  maxDepth: 2,
  samplesPerPixel: 1,
  meshes: [{
    id: 1,
    positions: [-1, -1, 0, 1, -1, 0, 0, 1, 0],
    indices: [0, 1, 2],
    normals: [0, 0, 1, 0, 0, 1, 0, 0, 1],
    emission: [8, 7, 5, 1],
  }],
});

await renderer.renderFrame();

// Call this from your route or component cleanup.
export function dispose() {
  renderer.destroy();
}

Supply decoded triangle geometry and material/texture data through meshes. The renderer does not fetch glTF files: use a loader such as @plasius/gpu-shared, or adapt canonical decoded assets with createCanonicalWavefrontMeshInputs. The canonical adapter maps the core 0.5 material texture slots; it currently accepts UV0 and identity texture transforms. Other selections/transforms fail explicitly so authored appearance is not silently changed. See the canonical integration contract. For an interactive model viewer with loading, integrity checks, camera gestures and quality controls, use the shared package's model-inspection entry.

Choose a rendering API

| API | Purpose | | --- | --- | | createWavefrontPathTracingComputeRenderer | Tiled, mesh-BVH path tracing with material transport, environment lighting and optional progressive accumulation | | createNativeSceneRenderer | Native raster triangles, authored surface maps, shadows and optional animated water | | createGpuRenderer | Device/canvas setup, clear pass, frame hooks and XR binding for a host-owned pipeline | | createProfessionalAnimatedSceneRenderer | The validated WebGPU animation scene path with skinned assets and root-motion requirements | | createAnimatedSceneRenderer | The existing canvas animation-adventure surface | | createRayTracingRenderPlan | Rendering plan metadata; it does not draw a scene |

All factories are exported from @plasius/gpu-renderer. Keep the import and GPU initialization inside the route that needs them. The host owns loading/error UI, visibility policy, accessible controls, and disposal when leaving the view.

Progressive rendering

Set progressive: true when creating the wavefront renderer. Its creation-time samplesPerPixel sets batch capacity; each renderFrame({ samplesPerPixel }) may submit a smaller batch. Await batches serially and stop scheduling when your sample target is reached or the view is hidden. renderFrame() waits for GPU completion by default.

Camera and scene changes reset accumulated radiance. updateCamera() preserves the loaded meshes, materials and acceleration resources; do not call it between refinement passes if the view has not changed. resetAccumulation() discards history explicitly. Denoising runs after accumulation.

getSnapshot().accumulatedSamplesPerPixel counts submitted samples. If you use synchronous renderOnce(), await renderer.device.queue.onSubmittedWorkDone() before labelling that work complete. Public sampling is fixed per frame; experimental per-pixel adaptive metadata does not enable adaptive rendering. See the wavefront guide for memory, timing, transport flags and progressive behavior.

Frame lifecycle without a scene

Use createGpuRenderer when your application owns the rendering pipeline. This example clears the canvas and runs the frame lifecycle; it does not load or draw 3D models:

import { createGpuRenderer } from "@plasius/gpu-renderer";

const renderer = await createGpuRenderer({
  canvas: "#scene",
  clearColor: "#102035",
});
renderer.resize(640, 360);
renderer.start();

export function dispose() {
  renderer.destroy();
}

API and integration guides

• Wavefront path tracing, materials and progressive refinement.
• Native surfaces, texture maps and clearcoat.
• Canonical ingestion, frame hooks, worker manifests, XR and diagnostics. Snippets in this reference use host-provided decoded assets and services.
• Animation scene contracts.
• Complete public TypeScript declarations.
• Crate material-study implementation notes. Fixture helpers are internal; mount the study through @plasius/gpu-shared/material-study.

Experimental transport switches use the featureFlags options described in the wavefront guide. The package consumes supplied decisions; it does not connect to an account or remote flag service. Plasius production consumers also apply their route capabilities and rollout policy before mounting a scene.

Development

For checkout setup and required validation, start with the development guide.

npm run demo requires Python 3 and serves the parent workspace. With the checkout named gpu-renderer, visit http://localhost:8000/gpu-renderer/demo/. The development guide also describes the source layout. See CONTRIBUTING.md.

Release integrity

CI keeps the administrative contributor registry outside Git and npm package artifacts using exact, case-normalised path checks. CI runs only for pushes to repository-owned branches on explicit [self-hosted, Linux, X64] runners. External fork pull requests trigger no CI execution; a maintainer must review and move a contribution to a repository-owned branch to produce required checks. Before branch CI starts, an authorised maintainer reviews the exact commit and locks its repository branch as read-only, enforcing the lock for administrators and disabling force pushes, deletion, and fork syncing. After reading back the lock and commit SHA, admit only that branch's fully qualified workflow ref for gpu-renderer/.github/workflows/ci.yml in Public CI - Quarantined. Top-level push jobs identify their workflow by branch ref; SHA-only admission did not schedule the reviewed job. Remove the temporary workflow entry and verify its removal before unlocking or updating the branch, and after delivery. Preserve all other group restrictions. Never admit mutable branch or PR refs. See ADR-0028 for the procedure. The trusted admission, build-test, and artifact-integrity checks keep their existing names for branch protection. Scheduled dependency validation also uses bounded self-hosted capacity and accepts only main. Release preparation and publication use a two-run exact-main protocol on GitHub-hosted Node.js 24.18.0 LTS. A read-only job seals the package tarball and SBOM before a dependency-free production job publishes that exact artifact through npm OIDC with provenance; there is no npm write-token fallback. CD remains disabled until the npm trusted publisher binding and protected-branch-only production environment are independently verified.