V2 API and Demo Coverage

Use this page as the index for the V2 public surface. The reference link is the canonical contract; the demo link shows the closest runnable example. “Facade exercised” means the demo uses MeshLine, which creates the low-level class internally. “Reference only” identifies an API that is documented but does not yet have a dedicated live demo.

The regular MeshLine façade and surface profile support the WebGPU and WebGL2 renderers. The root MeshLineCompute export requires WebGPU compute support and has no WebGL2 simulation fallback. The optional gpu-culling and gpu-path entries require native WebGPU and Three.js r183 or newer; their demos report the complete fallback when those features are unavailable.

Root package exports

Export	Canonical reference	Runnable coverage	Coverage note
MeshLine (named and default)	MeshLine	Basic, Sandbox	Preferred entry point for screen lines and surfaces.
MeshLineCompute	MeshLineCompute	Compute Curves	Experimental WebGPU-only storage-buffer simulation façade; regular MeshLine remains the cross-backend path.
MeshLineGeometry	MeshLineGeometry	Waves, Follow	Facade exercised; use the class directly only for low-level composition.
MeshLineNodeMaterial	MeshLineNodeMaterial	Basic, Sandbox	Facade exercised across color, gradient, dash, maps, and opacity. Basic also runs widthFn, gradientFn, opacityFn, dashFn, uvFn, and discardFn through the public facade.
MeshLineSurfaceGeometry	Surface low-level API	Surface, Variable Topology	Facade exercised; the topology gallery covers joins, caps, and reversals.
MeshLineSurfaceNodeMaterial	Surface low-level API	Metallic Tube, Surface Road	Facade exercised with lighting, maps, roughness, and metalness.
MeshLinePicker	GPU Picking	Laser Heist	Exercises instanced, GPU-positioned lines that CPU raycasting cannot resolve.
MeshLinePickerHelper	Picker debug helper	Laser Heist	The picker-debug mode visualizes the pick pass.
lineCoord	Stroke coordinate	Metallic Tube	Normalized cross-section coordinate for TSL hooks; the tube normal is built from it.
circlePositions	Position helpers	Basic	Directly exercised.
squarePositions	Position helpers	Sandbox	Select the square shape.
rectanglePositions	Position helpers	Rice Field	Used for the water-border paths.
sineWavePositions	Position helpers	Sandbox	Select the sine-wave shape.
straightLine	Position helpers	Sandbox	Select the straight-line shape.
storagePositions	Position helpers	Lorenz Trails, Isobars	WebGPU storage-buffer gpuPositionNode, with optional ring-buffer trails, closed loops, and dual-buffer morphing.
straightLineBetween	Position helpers	Reference only	Copy-paste examples cover tuples and Three.js vectors.

Stable-layout update APIs

These methods update an existing MeshLine; they are not constructor options.

Method	Best use	Reference	Runnable coverage
setPositions(points, updateBounding?)	Replace all point data while reusing compatible buffers.	Updating geometry efficiently	Waves, Follow
setPositionRange(points, startPoint, options?)	Patch one stable CPU-billboard span and upload its neighbor halo.	MeshLineGeometry range updates	Draw Lines patches every active stroke follower each frame; surfaces and smoothed topology must use setPositions().
addVertexAttribute(name, components?) / addVertexAttributes(layout) / setVertexValues(name, values, startVertex?)	Allocate separate or portable packed custom per-vertex data and bulk-update it.	Vertex attributes	Draw Lines, Follow, Flying Baguettes
addInstanceAttribute(name, components?) / addInstanceAttributes(layout) / setInstanceValues(name, values, startInstance?)	Allocate separate or portable packed custom per-instance data and bulk-update it.	Instance management	GPU Instancing rewrites only the rings that wrap each frame with post-upload bulk writes.
getVertexBufferUsage(options?) / validateVertexBufferBudget(options?)	Inspect or enforce the eight-buffer portable WebGPU target before pipeline creation.	Instance management	API regression coverage validates separate and interleaved vertex/instance layouts.
setInstanceValue(name, index, value)	Make an occasional scalar instance edit.	Instance management	GPU Instancing

Draw Lines also uploads each new stroke's colors as one contiguous setVertexValues() range, so the update APIs are visible in a running scene rather than a diagram.

V2 profiles and optional entry points

Capability	Import / entry	Canonical reference	Runnable coverage
World-space road/ribbon surfaces	MeshLine or the two root surface classes	World-Space Surfaces	Surface, Surface Road, Metallic Tube, Variable Topology
Experimental WebGPU compute curves	root MeshLineCompute export	MeshLineCompute	Compute Curves
Native-WebGPU chunk culling	makio-meshline/gpu-culling	GPU Culling	GPU Culling; append ?culling=0 for the unculled baseline.
Experimental native-WebGPU point path	makio-meshline/gpu-path	GPU Path	GPU Path, Variable Topology
GPU picking and debug visualization	root MeshLinePicker exports	GPU Picking	Laser Heist
React Three Fiber wrapper	root package through a local R3F component	React Three Fiber	Standalone R3F example; the wrapper covers current non-deprecated MeshLineConfigureOptions except autoResize.
Vue wrapper	root package through a local Vue component	Vue	Standalone Vue example; the wrapper omits autoResize and deprecated scalar dash aliases.

GPU Path demo switches

The experimental path demo uses query parameters so the compared workloads remain deterministic:

Query	Effect
?gpu=0	Force the complete CPU MeshLine fallback.
?simplify=0	Keep the native GPU path but disable local-space simplification.
?topology=variable	Enable true over-limit miter bevel topology.
?topology=bevel or ?topology=round	Select the requested true outer join.
&cap=square or &cap=round	Select a non-butt open-path cap.

For behavioral changes from V1, start with Migrate to V2. For the reasoning and compatibility gates behind these profiles, see the V2 Design Contract.