Documentation / @ripl/webgpu

@ripl/webgpu

WebGPU 3D rendering context for Ripl. Replaces the Canvas 2D painter's algorithm in @ripl/3d with a true GPU rasterization pipeline featuring hardware depth testing, WGSL shaders, and Lambertian shading.

Installation

npm install @ripl/webgpu

Quick Start

import {
    createContext,
} from '@ripl/webgpu';

import {
    createCamera,
} from '@ripl/3d';

import {
    createRenderer, createScene,
} from '@ripl/web';

import {
    createCube,
} from '@ripl/3d';

const context = await createContext('#app');
const scene = createScene(context);
const renderer = createRenderer(scene);

const camera = createCamera(scene, {
    position: [0, 2, 5],
    target: [0, 0, 0],
});

const cube = createCube({ size: 1,
    fill: '#4488ff' });
scene.add(cube);
renderer.render();

Features

• WebGPU rendering — true GPU rasterization with hardware depth buffer
• Drop-in replacement — same Shape3D elements work with both Canvas 2D and WebGPU contexts
• WGSL shaders — vertex and fragment shaders with Lambertian diffuse lighting
• MSAA — 4x multisample anti-aliasing
• Async initialisation — createContext returns a Promise for GPU adapter/device negotiation

Classes

Class	Description
GeometryManager	Manages GPU buffer allocation and per-frame mesh accumulation.
WebGPUContext3D	WebGPU-backed 3D rendering context with hardware depth testing and WGSL shaders.

Interfaces

Interface	Description
DrawCommand	A single draw call within a flush result.
FlushResult	Result of flushing all queued meshes — buffers and per-mesh draw commands.
PipelineOptions	Options for creating the render pipeline.
PipelineState	Holds all GPU pipeline objects and layouts needed for rendering.
WebGPUContextOptions	Options for constructing a WebGPU 3D context.

Variables

Variable	Description
FRAGMENT_SHADER	WGSL fragment shader with Lambertian diffuse lighting.
MODEL_BIND_GROUP_LAYOUT_ENTRIES	Bind group layout entries for the per-model uniforms (group 1).
MODEL_UNIFORM_SIZE	Size in bytes of the model uniform buffer: mat4(64) + mat4(64) = 128 bytes.
SCENE_BIND_GROUP_LAYOUT_ENTRIES	Bind group layout entries for the scene-level uniforms (group 0).
SCENE_UNIFORM_SIZE	Size in bytes of the scene uniform buffer: mat4(64) + vec3(12) + f32(4) = 80 bytes, aligned to 16 = 80.
VERTEX_BUFFER_LAYOUT	Vertex buffer layout describing position, normal, and color attributes.
VERTEX_SHADER	WGSL vertex shader for 3D mesh rendering with per-vertex color and normal.
VERTEX_STRIDE	Byte stride for a single vertex: position(3) + normal(3) + color(4) = 10 floats × 4 bytes.

Functions

Function	Description
createContext	Creates a WebGPU 3D rendering context attached to the given DOM target.
createPipeline	Creates the render pipeline and associated layouts on the given device.
requestDevice	Requests a WebGPU adapter and device, throwing if unsupported.
triangulatefaces	Triangulates a list of Face3D into interleaved vertex data and index arrays.