Documentation / @ripl/3d

@ripl/3d

Experimental 3D rendering for Ripl — a unified API for 2D graphics rendering in the browser.

Note: This package is experimental and its API may change between releases.

Installation

npm install @ripl/3d

Overview

Extends Ripl's rendering pipeline with 3D capabilities. Projects 3D geometry onto Ripl's 2D canvas context using a virtual camera, depth sorting, and flat shading.

Features

• 3D math — Vectors, matrices, and transformations
• Camera — Configurable virtual camera with projection
• Shading — Flat shading with directional lighting
• Depth sorting — Automatic painter's algorithm for correct draw order
• 3D shapes — Built-in 3D shape primitives
• Interpolation — 3D-aware interpolators for smooth animation

Usage

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

const context = createContext('.mount-element');
const camera = createCamera({ /* options */ });
const cube = createCube({ /* options */ });

Documentation

Full documentation is available at ripl.rocks.

License

MIT

Classes

Class	Description
Camera	An interactive camera controlling the 3D context's view and projection, with mouse/touch orbit, pan, and zoom.
CanvasContext3D	Canvas 2D–backed 3D rendering context with face buffer and painter's algorithm sorting.
Cone	A 3D cone shape with configurable radius, height, and segment resolution.
Context3D	Base 3D rendering context providing view/projection matrices, camera, lighting, and projection. Subclassed by CanvasContext3D and WebGPUContext3D.
Cube	A 3D cube shape with uniform edge size.
Cylinder	A 3D cylinder shape with independent top and bottom radii for truncated cones.
Plane	A flat rectangular 3D plane oriented along the XY plane.
Shape3D	Base class for 3D shapes, handling model transforms, face projection, shading, and hit testing.
Sphere	A 3D sphere shape tessellated with configurable segments and rings.
Torus	A 3D torus (donut) shape with configurable major radius, tube radius, and tessellation.

Interfaces

Interface	Description
CameraInteractionConfig	Fine-grained configuration for a single camera interaction.
CameraInteractions	Configures which camera interactions (zoom, pivot, pan) are enabled.
CameraOptions	Options for constructing a camera, including position, projection type, and interaction config.
ConeState	State interface for a cone, defining radius, height, and segment count.
Context3DMeta	Typed metadata for 3D contexts.
Context3DOptions	Options for the 3D rendering context, extending the base context options with camera parameters.
CubeState	State interface for a cube, defining uniform edge size.
CylinderState	State interface for a cylinder, defining top/bottom radii, height, and segment count.
Face3D	A single face of a 3D mesh, defined by its vertices and an optional precomputed normal.
MeshSubmission	A mesh submission queued for a single frame.
PlaneState	State interface for a plane, defining width and height.
ProjectedFace3D	A projected face ready for 2D rendering with screen-space points, fill/stroke styles, and depth.
Shape3DState	State interface for a 3D shape, defining position and rotation around each axis.
SphereState	State interface for a sphere, defining radius, longitudinal segments, and latitudinal rings.
TorusState	State interface for a torus, defining major radius, tube radius, and segment counts.
Viewport	Viewport dimensions used for projection.

Type Aliases

Type Alias	Description
CameraInteractionOption	A camera interaction can be enabled/disabled with a boolean or configured with sensitivity.
LightMode	Determines whether the light direction is fixed in world space or follows the camera.
Matrix4	A column-major 4×4 matrix stored as a 16-element Float64Array.
ProjectedPoint	A 2D screen-space point with a depth component for z-ordering.
RenderStrategy	The rendering strategy used by a 3D context.
Shape3DOptions	Options for constructing a 3D shape, with all state properties optional.
Vector3	A 3-component vector represented as a labeled tuple [x, y, z].

Variables

Variable	Description
interpolateVector3	Interpolator factory for Vector3 values, using component-wise linear interpolation.
LIGHT_DIRECTION	Pre-normalised light direction vectors for common light positions.

Functions

Function	Description
computeFaceBrightness	Computes a 0–1 brightness value for a face given its normal and a light direction.
computeFaceNormal	Computes the surface normal of a face from its first three vertices via the cross product.
createCamera	Factory function that creates a new Camera bound to a 3D scene.
createCone	Factory function that creates a new Cone instance.
createContext	Creates a Canvas 2D–backed 3D rendering context attached to the given DOM target.
createCube	Factory function that creates a new Cube instance.
createCylinder	Factory function that creates a new Cylinder instance.
createPlane	Factory function that creates a new Plane instance.
createShape3D	Factory function that creates a new Shape3D instance.
createSphere	Factory function that creates a new Sphere instance.
createTorus	Factory function that creates a new Torus instance.
elementIsCone	Type guard that checks whether a value is a Cone instance.
elementIsCube	Type guard that checks whether a value is a Cube instance.
elementIsCylinder	Type guard that checks whether a value is a Cylinder instance.
elementIsPlane	Type guard that checks whether a value is a Plane instance.
elementIsShape3D	Type guard that checks whether a value is a Shape3D instance.
elementIsSphere	Type guard that checks whether a value is a Sphere instance.
elementIsTorus	Type guard that checks whether a value is a Torus instance.
mat4Clone	Returns a copy of the given matrix.
mat4Create	Creates a zeroed 4×4 matrix.
mat4Identity	Creates a 4×4 identity matrix.
mat4LookAt	Constructs a view matrix looking from eye toward target with the given up direction.
mat4Multiply	Multiplies two 4×4 matrices.
mat4Orthographic	Constructs an orthographic projection matrix.
mat4Perspective	Constructs a perspective projection matrix.
mat4RotateX	Applies a rotation around the X axis to a matrix.
mat4RotateY	Applies a rotation around the Y axis to a matrix.
mat4RotateZ	Applies a rotation around the Z axis to a matrix.
mat4Scale	Applies a scale transform to a matrix.
mat4TransformDirection	Transforms a direction vector by the upper-3×3 of a 4×4 matrix, ignoring translation.
mat4TransformPoint	Transforms a 3D point by a 4×4 matrix, performing the perspective divide.
mat4Translate	Applies a translation to a matrix.
projectPoint	Projects a 3D world-space point onto 2D screen-space via a view-projection matrix and viewport.
shadeFaceColor	Shades a color by a brightness factor (0–1), darkening or lightening the RGB channels.
typeIsVector3	Type guard that checks whether a value is a Vector3 tuple.
vec3Add	Returns the component-wise sum of two vectors.
vec3Cross	Computes the cross product of two vectors.
vec3Distance	Returns the Euclidean distance between two points.
vec3Dot	Computes the dot product of two vectors.
vec3Length	Returns the Euclidean length of a vector.
vec3Lerp	Linearly interpolates between two vectors by factor t.
vec3Negate	Negates all components of a vector.
vec3Normalize	Returns the unit-length direction of a vector, or the zero vector if length is 0.
vec3Scale	Scales a vector by a scalar.
vec3Sub	Returns the component-wise difference of two vectors.