@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/core/instanced/instanced-material.js

@@ -0,0 +1,228 @@
+import { ShaderChunk, } from 'three';
+import { declareBeforeMain, openMain } from '../shader-source';
+/**
+ * Vertex declarations: the index and matrices samplers, and the fetches that read them.
+ *
+ * Unguarded, unlike upstream's `#ifdef USE_INSTANCING_INDIRECT`. The guard is what made it safe to
+ * append to a chunk every material compiles; injected into one shader at a time, it would only ever
+ * test a define this same call sets.
+ */
+const INSTANCED_DECLARATIONS = /* glsl */ `
+  uniform highp sampler2D indexTexture;
+
+  // The id this draw’s instance holds. A mutable global rather than a local of main, so the
+  // fetches below can read it; main assigns it before anything else runs.
+  float instanceIndex;
+
+  // Resolves a draw to the instance it should read. The culling pass writes the surviving ids into
+  // indexTexture in draw order, so gl_InstanceID addresses it directly.
+  float getIndirectIndex( int id ) {
+    int size = textureSize( indexTexture, 0 ).x;
+    return texelFetch( indexTexture, ivec2( id % size, id / size ), 0 ).r;
+  }
+
+  #ifdef USE_INSTANCING_MATRIX_INDIRECT
+
+    uniform highp sampler2D matricesTexture;
+
+    mat4 getInstancedMatrix() {
+      int size = textureSize( matricesTexture, 0 ).x;
+      int j = int( instanceIndex ) * 4;
+      int x = j % size;
+      int y = j / size;
+      vec4 v1 = texelFetch( matricesTexture, ivec2( x, y ), 0 );
+      vec4 v2 = texelFetch( matricesTexture, ivec2( x + 1, y ), 0 );
+      vec4 v3 = texelFetch( matricesTexture, ivec2( x + 2, y ), 0 );
+      vec4 v4 = texelFetch( matricesTexture, ivec2( x + 3, y ), 0 );
+      return mat4( v1, v2, v3, v4 );
+    }
+
+  #else
+
+    // No transforms written, so nothing to sample: a mesh placing its instances some other way — a
+    // line batch, by two endpoints — allocates no matrices texture at all, and the transform chunks
+    // that read this go on compiling.
+    mat4 getInstancedMatrix() {
+      return mat4( 1.0 );
+    }
+
+  #endif
+`;
+/**
+ * What every instanced draw resolves before anything reads it: the instance this draw stands for,
+ * and its transform.
+ *
+ * The matrix is declared here rather than where the transform chunks use it, so it lands in `main`
+ * whether or not the material includes those chunks. It shadows the `attribute mat4 instanceMatrix`
+ * three declares for any `isInstancedMesh` object — which is what the placeholder attribute on
+ * `InstancedMeshImpl` exists to satisfy — and a material doing its own transform simply never reads
+ * it.
+ */
+const INSTANCED_RESOLVE = /* glsl */ `
+  instanceIndex = getIndirectIndex( gl_InstanceID );
+  mat4 instanceMatrix = getInstancedMatrix();
+`;
+/** Vertex color declarations: the colors sampler and its fetch. */
+const INSTANCED_COLOR_DECLARATIONS = /* glsl */ `
+  uniform highp sampler2D colorsTexture;
+
+  vec4 getColorTexture() {
+    int size = textureSize( colorsTexture, 0 ).x;
+    int j = int( instanceIndex );
+    int x = j % size;
+    int y = j / size;
+    return texelFetch( colorsTexture, ivec2( x, y ), 0 );
+  }
+`;
+/**
+ * Seeds `vColor`, folds in the geometry's vertex color and then the instance's — the chunk
+ * substituted for `<color_vertex>`, whose composition it keeps.
+ *
+ * Every stage here, where upstream splits them across `<color_vertex>` and `batching_vertex`. They
+ * cannot move apart: three seeds `vColor` at `<color_vertex>` and every multiply has to follow it, so
+ * with the rest of the instancing injected at the top of `main` — ahead of both — the only place the
+ * instance color still reads right is beside the seed.
+ *
+ * `USE_COLOR` is the define three sets for `material.vertexColors`; upstream tests a
+ * `USE_VERTEX_COLOR` that three never defines, so a geometry's vertex colors were dropped rather than
+ * multiplied in. `color` is a `vec4` under it because the substitution defines `USE_COLOR_ALPHA` as
+ * well, which is what three's attribute declaration keys on — a geometry carrying only rgb has the
+ * alpha filled in by GL.
+ */
+const INSTANCED_COLOR_VERTEX = /* glsl */ `
+  vColor = vec4( 1.0 );
+
+  #ifdef USE_COLOR
+    vColor *= color;
+  #endif
+
+  vColor *= getColorTexture();
+`;
+let patched = false;
+/**
+ * Prepares three's global `ShaderChunk` for indirect instancing, once per process.
+ *
+ * Only what a *stock* material needs, because only a stock material has these chunks to begin with:
+ * the transform chunks that apply the instance matrix, widened to fire under the indirect define as
+ * well, and the color chunk substituted for `<color_vertex>`. Everything else an instanced draw
+ * needs is injected into the one shader being compiled — see the module docs. Nothing here changes
+ * another material's output: the widened branches are inert without `USE_INSTANCING_INDIRECT`, which
+ * only an instanced mesh sets on the material it is drawing with, and the added chunk is reached only
+ * through the substitution below.
+ */
+export function patchInstancedShaderChunks() {
+    if (patched)
+        return;
+    patched = true;
+    // three types `ShaderChunk` as a fixed record, so the custom `instanced_*` key is reached through
+    // an index view.
+    const chunks = ShaderChunk;
+    chunks.instanced_color_vertex = INSTANCED_COLOR_VERTEX;
+    // Let the stock transform chunks honor the indirect define alongside three's own `USE_INSTANCING`.
+    chunks.project_vertex = withIndirectInstancing(chunks.project_vertex);
+    chunks.worldpos_vertex = withIndirectInstancing(chunks.worldpos_vertex);
+    chunks.defaultnormal_vertex = withIndirectInstancing(chunks.defaultnormal_vertex);
+}
+/**
+ * Wraps a material so the program it compiles reads one mesh's instancing textures.
+ *
+ * Wraps the material three handed the mesh rather than the mesh's own, because those differ: a scene
+ * with an `overrideMaterial` draws every object with that one instead, and an override that skipped
+ * the wrap would stack every instance on a single transform. Undoing it afterward is what makes
+ * wrapping a material the mesh does not own safe — three tracks whether the program it cached was
+ * built for an instanced draw and rebuilds when the next object disagrees, so the plain meshes
+ * sharing that override compile their own way.
+ *
+ * The one case this does not cover is two instanced meshes sharing a material: both are
+ * `isInstancedMesh`, so three sees nothing to disagree with and the second draws against the
+ * first's textures. Give each mesh its own material.
+ * @param material - The material about to draw.
+ * @param textures - The textures its program should fetch from, read at compile time so a texture
+ *   added later is still picked up.
+ * @returns Restores the material exactly as it arrived. Call it once, after the draw.
+ */
+export function patchInstancedMaterial(material, textures) {
+    // Saved raw rather than bound, which is what the rule below would have us do: restoring a bound
+    // copy would put a *different* function back on the material, and the next draw would bind that
+    // one in turn — a fresh layer every frame, each wrapping the last. The receiver is supplied at
+    // the two call sites instead.
+    /* eslint-disable @typescript-eslint/unbound-method -- restored verbatim; called with `.call`. */
+    const baseOnBeforeCompile = material.onBeforeCompile;
+    const baseCacheKey = material.customProgramCacheKey;
+    /* eslint-enable @typescript-eslint/unbound-method */
+    // Distinguishes the program from the material's unwrapped one, and from a wrapped one compiled
+    // before a texture was added, since each changes the generated GLSL. Every texture that can arrive
+    // late is named: the matrices are allocated by the first transform written, and a program built
+    // before that reads identity.
+    //
+    // The uniforms contribute their whole schema and not just their presence. Two meshes that declare
+    // different uniforms generate different GLSL, so a key that recorded only "has uniforms" would let
+    // the second draw against the first's layout.
+    const key = () => `${!!textures.matricesTexture}_${!!textures.colorsTexture}_${textures.uniforms.shaderKey}`;
+    material.customProgramCacheKey = () => `efp_${key()}_${baseCacheKey.call(material)}`;
+    material.onBeforeCompile = (shader, renderer) => {
+        // Instancing first, the material's own handler after — the same order the batched meshes use,
+        // and an invariant materials rely on: a patch that reads a per-instance uniform can only find
+        // it once the prologue below has declared it. Nothing here depends on the reverse; the
+        // material patches that exist anchor on `#include` chunks this leaves untouched.
+        injectInstancing(shader, textures);
+        baseOnBeforeCompile.call(material, shader, renderer);
+    };
+    return () => {
+        material.onBeforeCompile = baseOnBeforeCompile;
+        material.customProgramCacheKey = baseCacheKey;
+    };
+}
+/**
+ * Injects the index, matrix, uniform and color instancing into a compiling shader.
+ * @param shader - The program parameters to edit.
+ * @param textures - The textures to bind.
+ * @throws {Error} If the vertex shader has no `main` to inject into.
+ */
+function injectInstancing(shader, textures) {
+    // Cloned so a shared material (e.g. `scene.overrideMaterial`) does not accumulate our defines.
+    shader.defines = { ...shader.defines, USE_INSTANCING_INDIRECT: '' };
+    shader.uniforms.indexTexture = { value: textures.indexTexture };
+    if (textures.matricesTexture) {
+        shader.defines.USE_INSTANCING_MATRIX_INDIRECT = '';
+        shader.uniforms.matricesTexture = { value: textures.matricesTexture };
+    }
+    textures.uniforms.patchShader(shader, 'instanceIndex');
+    shader.vertexShader = declareBeforeMain(shader.vertexShader, INSTANCED_DECLARATIONS);
+    // Written after the uniform prologue precisely so it runs before it: `openMain` inserts at the top
+    // of `main`, and the prologue's fetch addresses the texture by the index resolved here.
+    shader.vertexShader = openMain(shader.vertexShader, INSTANCED_RESOLVE);
+    injectInstancedColor(shader, textures.colorsTexture);
+}
+/**
+ * Points a compiling shader at the per-instance colors, when it is a shader that can read them.
+ *
+ * Per-instance color is the one part of instancing that stays on three's chunks, because it has to
+ * meet `vColor` where three seeds it — `<color_vertex>` in the vertex stage, declared for the stage
+ * that reads it by `<color_pars_fragment>`. **Both**, not either: a material carrying the fragment
+ * half alone would take the defines and then interpolate a varying nothing ever assigned. A shader
+ * keeping neither is doing its own color, which is what three's line material does — so this is a
+ * skip rather than a failure.
+ * @param shader - The program parameters to edit.
+ * @param colorsTexture - The per-instance colors, or `null` while none have been written.
+ */
+function injectInstancedColor(shader, colorsTexture) {
+    const readsColorChunks = shader.vertexShader.includes('<color_vertex>') &&
+        shader.fragmentShader.includes('<color_pars_fragment>');
+    if (!colorsTexture || !readsColorChunks)
+        return;
+    const defines = (shader.defines ??= {});
+    defines.USE_INSTANCING_COLOR_INDIRECT = '';
+    defines.USE_COLOR_ALPHA = '';
+    shader.uniforms.colorsTexture = { value: colorsTexture };
+    shader.vertexShader = declareBeforeMain(shader.vertexShader, INSTANCED_COLOR_DECLARATIONS);
+    shader.vertexShader = shader.vertexShader.replace('<color_vertex>', '<instanced_color_vertex>');
+}
+/**
+ * Widens a chunk's `USE_INSTANCING` guard to also fire under indirect instancing.
+ * @param chunk - The stock chunk source.
+ * @returns The widened chunk.
+ */
+function withIndirectInstancing(chunk) {
+    return chunk.replace('#ifdef USE_INSTANCING', '#if defined USE_INSTANCING || defined USE_INSTANCING_INDIRECT');
+}

package/dist/core/lines/BatchedLines.d.ts

@@ -0,0 +1,137 @@
+import { type Box3, type BufferGeometry, type Camera, type Group, type Material, type Scene, type Sphere, Vector3, type Vector3Like, type WebGLRenderer } from 'three';
+import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+import { InstancedMeshImpl, type InstancedMeshImplParams } from '../instanced/InstancedMesh';
+import { FrustumCullingLines } from './FrustumCullingLines';
+import { RaycastingLines } from './RaycastingLines';
+/**
+ * An instanced mesh whose instances are placed by two endpoints instead of a matrix.
+ *
+ * That sentence is the whole of it. A wide line is a quad expanded *after* projection — three's line
+ * shader takes a segment's two ends into clip space and offsets the corners by a width measured in
+ * screen pixels — so no matrix maps the template onto the segment, and the placement cannot be a
+ * transform. Everything else an instanced mesh does applies unchanged: slots, visibility, growth,
+ * per-instance uniforms, the draw list that is also the paint order, and the material wiring.
+ *
+ * What this class holds is what "placed by endpoints" changes:
+ *
+ * - **The endpoints**, as two per-instance uniforms rather than the instanced attributes
+ *   `LineSegmentsGeometry` would carry. They are named for those attributes deliberately: the
+ *   uniform prologue declares them as locals of `main`, so three's own shader goes on reading its own
+ *   names and needs no rewriting beyond dropping the declarations — see `objects/materials/LineMaterial`.
+ * - **The bounds**, swept from the endpoints, because the template geometry's own are in the
+ *   parametric space the shader expands from and mean nothing in the plan.
+ * - **Picking**, which has to run in screen space at each member's own width — see {@link RaycastingLines}.
+ *
+ * And what it stops needing by being one: the endpoints are addressed by id, so paint order is a
+ * `customSort` over the draw list like every other batch's rather than a packing of the buffer;
+ * hiding a member drops it from that list instead of collapsing it in the shader; and the geometry
+ * carries no instanced attributes, so nothing has to work around the instance ceiling three caches
+ * the first time it binds one.
+ *
+ * Render it with {@link BatchedLines}.
+ */
+export declare class BatchedLinesImpl extends InstancedMeshImpl {
+    /** Marks this as a line batch. three's brand pattern, so a holder can tell the batch kinds apart. */
+    readonly isBatchedLines = true;
+    /**
+     * The segment template every member is drawn from, and the whole of what the geometry carries: the
+     * per-instance data three would put in instanced attributes is in the uniforms instead.
+     *
+     * Built here rather than mounted as a child element, because it is not a choice the way an atlas's
+     * quad is — three's own class is the definition of the template.
+     */
+    geometry: LineSegmentsGeometry;
+    /**
+     * The material three's line shader compiles from, narrowed because both the fallback width and the
+     * resolution screen-space widths are measured against are read off it.
+     *
+     * Seeded with a throwaway the `<LineMaterial>` child replaces on mount, as the base seeds one for
+     * R3F's `<TextureMaterial>` to replace — but a *line* material, because those two are read before
+     * anything has been drawn.
+     */
+    material: LineMaterial;
+    /** Draw order is paint order, which a container decides through `customSort` rather than depth. */
+    sortObjects: boolean;
+    /** Screen space, at each member's own width — see {@link RaycastingLines}. */
+    protected raycasting: RaycastingLines;
+    /** By the ribbon each member draws rather than the segment it runs — see {@link FrustumCullingLines}. */
+    protected culling: FrustumCullingLines;
+    /**
+     * @param params - Instance capacity; the buffers grow past it on demand.
+     */
+    constructor(params?: InstancedMeshImplParams);
+    /**
+     * Reads a member's endpoints.
+     * @param id - The member to read.
+     * @param start - Receives the segment start.
+     * @param end - Receives the segment end.
+     */
+    getPointsAt(id: number, start: Vector3, end: Vector3): void;
+    /**
+     * Writes a member's endpoints, invalidating the bounds they define.
+     *
+     * Writes what it is given, like every other setter here. Skipping an unchanged segment is the
+     * caller's to do — `LineInstance` compares first, exactly as the write helpers do for the meshes
+     * that carry transforms and colors — so a member is never read back on a path that means to write.
+     * @param id - The member to write.
+     * @param start - The segment start.
+     * @param end - The segment end.
+     */
+    setPointsAt(id: number, start: Vector3Like, end: Vector3Like): void;
+    /**
+     * A member's own width, or a negative value while it has none and draws at the material's.
+     * @param id - The member to read.
+     * @returns The width.
+     */
+    getWidthAt(id: number): number;
+    /**
+     * Sets a member's width, in the units the material's `worldUnits` selects.
+     *
+     * Optional, and the batch cannot make it otherwise — a member nobody set a width for keeps the
+     * material's, which every `LineMaterial` has. That fallback is marked by a *negative* width
+     * rather than by zero, because zero expands the segment quad to no area: it draws nothing, which
+     * is a thing a caller can ask for and not the same request. Callers that treat a width as user
+     * input should clamp it at zero, so a nonsensical negative reads as invisible rather than as "use
+     * the material's".
+     * @param id - The member to write.
+     * @param width - The width; negative to fall back to the material's, zero to draw nothing.
+     */
+    setWidthAt(id: number, width: number): void;
+    /**
+     * Encloses one member: the sphere through its two endpoints.
+     *
+     * Takes no account of the width, as three's own line bounds do not either — the ends are where a
+     * segment runs, and the ribbon drawn around them is a screen-space skin whose size in the plan
+     * depends on the camera.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingSphereAt(id: number, target: Sphere): Sphere;
+    /**
+     * Encloses one member in a box: the two endpoints, and nothing between them to measure.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingBoxAt(id: number, target: Box3): Box3;
+    /** Frees the segment template, which this batch built rather than three or R3F. */
+    dispose(): void;
+    /**
+     * Clears a member as it is handed out, so a reused slot keeps nothing of the one that held it.
+     *
+     * Everything it could inherit, not only what a caller usually sets: a container that writes a
+     * color and a width but no endpoints would otherwise draw the removed member's line.
+     * @param id - The member being handed out.
+     */
+    protected resetInstance(id: number): void;
+    onBeforeRender(renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group): void;
+    protected patchMaterial(material: Material): () => void;
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with anything
+ * three puts in the catalog when the canvas mounts.
+ */
+export declare const BatchedLines: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<BatchedLinesImpl, import("@react-three/fiber").MathProps<BatchedLinesImpl> & import("@react-three/fiber").ReactProps<BatchedLinesImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<BatchedLinesImpl, typeof BatchedLinesImpl>, "object">>>>;
+//# sourceMappingURL=BatchedLines.d.ts.map

package/dist/core/lines/BatchedLines.js

@@ -0,0 +1,215 @@
+import { extend } from '@react-three/fiber';
+import { Vector3, Vector4, } from 'three';
+import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+import { InstancedMeshImpl } from '../instanced/InstancedMesh';
+import { FrustumCullingLines } from './FrustumCullingLines';
+import { END_UNIFORM, patchLineMaterial, START_UNIFORM, WIDTH_UNIFORM } from './lines-material';
+import { RaycastingLines } from './RaycastingLines';
+/**
+ * An instanced mesh whose instances are placed by two endpoints instead of a matrix.
+ *
+ * That sentence is the whole of it. A wide line is a quad expanded *after* projection — three's line
+ * shader takes a segment's two ends into clip space and offsets the corners by a width measured in
+ * screen pixels — so no matrix maps the template onto the segment, and the placement cannot be a
+ * transform. Everything else an instanced mesh does applies unchanged: slots, visibility, growth,
+ * per-instance uniforms, the draw list that is also the paint order, and the material wiring.
+ *
+ * What this class holds is what "placed by endpoints" changes:
+ *
+ * - **The endpoints**, as two per-instance uniforms rather than the instanced attributes
+ *   `LineSegmentsGeometry` would carry. They are named for those attributes deliberately: the
+ *   uniform prologue declares them as locals of `main`, so three's own shader goes on reading its own
+ *   names and needs no rewriting beyond dropping the declarations — see `objects/materials/LineMaterial`.
+ * - **The bounds**, swept from the endpoints, because the template geometry's own are in the
+ *   parametric space the shader expands from and mean nothing in the plan.
+ * - **Picking**, which has to run in screen space at each member's own width — see {@link RaycastingLines}.
+ *
+ * And what it stops needing by being one: the endpoints are addressed by id, so paint order is a
+ * `customSort` over the draw list like every other batch's rather than a packing of the buffer;
+ * hiding a member drops it from that list instead of collapsing it in the shader; and the geometry
+ * carries no instanced attributes, so nothing has to work around the instance ceiling three caches
+ * the first time it binds one.
+ *
+ * Render it with {@link BatchedLines}.
+ */
+export class BatchedLinesImpl extends InstancedMeshImpl {
+    /** Marks this as a line batch. three's brand pattern, so a holder can tell the batch kinds apart. */
+    isBatchedLines = true;
+    /**
+     * The segment template every member is drawn from, and the whole of what the geometry carries: the
+     * per-instance data three would put in instanced attributes is in the uniforms instead.
+     *
+     * Built here rather than mounted as a child element, because it is not a choice the way an atlas's
+     * quad is — three's own class is the definition of the template.
+     */
+    geometry = new LineSegmentsGeometry();
+    /**
+     * The material three's line shader compiles from, narrowed because both the fallback width and the
+     * resolution screen-space widths are measured against are read off it.
+     *
+     * Seeded with a throwaway the `<LineMaterial>` child replaces on mount, as the base seeds one for
+     * R3F's `<TextureMaterial>` to replace — but a *line* material, because those two are read before
+     * anything has been drawn.
+     */
+    material = new LineMaterial();
+    /** Draw order is paint order, which a container decides through `customSort` rather than depth. */
+    sortObjects = true;
+    /** Screen space, at each member's own width — see {@link RaycastingLines}. */
+    raycasting = new RaycastingLines();
+    /** By the ribbon each member draws rather than the segment it runs — see {@link FrustumCullingLines}. */
+    culling = new FrustumCullingLines();
+    /**
+     * @param params - Instance capacity; the buffers grow past it on demand.
+     */
+    constructor(params = {}) {
+        super(params);
+        // Declared by the class rather than by a caller, because the shader reading them is the one three
+        // ships and two of the names are its own.
+        this.addUniforms({
+            vertex: { [START_UNIFORM]: 'vec3', [END_UNIFORM]: 'vec3', [WIDTH_UNIFORM]: 'float' },
+        });
+    }
+    /**
+     * Reads a member's endpoints.
+     * @param id - The member to read.
+     * @param start - Receives the segment start.
+     * @param end - Receives the segment end.
+     */
+    getPointsAt(id, start, end) {
+        this.getUniformAt(id, START_UNIFORM, start);
+        this.getUniformAt(id, END_UNIFORM, end);
+    }
+    /**
+     * Writes a member's endpoints, invalidating the bounds they define.
+     *
+     * Writes what it is given, like every other setter here. Skipping an unchanged segment is the
+     * caller's to do — `LineInstance` compares first, exactly as the write helpers do for the meshes
+     * that carry transforms and colors — so a member is never read back on a path that means to write.
+     * @param id - The member to write.
+     * @param start - The segment start.
+     * @param end - The segment end.
+     */
+    setPointsAt(id, start, end) {
+        this.setUniformAt(id, START_UNIFORM, _start.set(start.x, start.y, start.z));
+        this.setUniformAt(id, END_UNIFORM, _end.set(end.x, end.y, end.z));
+        this.invalidateBounds();
+    }
+    /**
+     * A member's own width, or a negative value while it has none and draws at the material's.
+     * @param id - The member to read.
+     * @returns The width.
+     */
+    getWidthAt(id) {
+        return this.getUniformAt(id, WIDTH_UNIFORM);
+    }
+    /**
+     * Sets a member's width, in the units the material's `worldUnits` selects.
+     *
+     * Optional, and the batch cannot make it otherwise — a member nobody set a width for keeps the
+     * material's, which every `LineMaterial` has. That fallback is marked by a *negative* width
+     * rather than by zero, because zero expands the segment quad to no area: it draws nothing, which
+     * is a thing a caller can ask for and not the same request. Callers that treat a width as user
+     * input should clamp it at zero, so a nonsensical negative reads as invisible rather than as "use
+     * the material's".
+     * @param id - The member to write.
+     * @param width - The width; negative to fall back to the material's, zero to draw nothing.
+     */
+    setWidthAt(id, width) {
+        this.setUniformAt(id, WIDTH_UNIFORM, width);
+    }
+    /**
+     * Encloses one member: the sphere through its two endpoints.
+     *
+     * Takes no account of the width, as three's own line bounds do not either — the ends are where a
+     * segment runs, and the ribbon drawn around them is a screen-space skin whose size in the plan
+     * depends on the camera.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingSphereAt(id, target) {
+        this.getPointsAt(id, _start, _end);
+        target.center.addVectors(_start, _end).multiplyScalar(0.5);
+        target.radius = _start.distanceTo(_end) / 2;
+        return target;
+    }
+    /**
+     * Encloses one member in a box: the two endpoints, and nothing between them to measure.
+     * @param id - The member.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingBoxAt(id, target) {
+        this.getPointsAt(id, _start, _end);
+        return target.makeEmpty().expandByPoint(_start).expandByPoint(_end);
+    }
+    /** Frees the segment template, which this batch built rather than three or R3F. */
+    dispose() {
+        super.dispose();
+        this.geometry.dispose();
+    }
+    /**
+     * Clears a member as it is handed out, so a reused slot keeps nothing of the one that held it.
+     *
+     * Everything it could inherit, not only what a caller usually sets: a container that writes a
+     * color and a width but no endpoints would otherwise draw the removed member's line.
+     * @param id - The member being handed out.
+     */
+    resetInstance(id) {
+        super.resetInstance(id);
+        this.setPointsAt(id, ORIGIN, ORIGIN);
+        this.setWidthAt(id, MATERIAL_WIDTH);
+        this.setColorAt(id, UNTINTED);
+    }
+    onBeforeRender(renderer, scene, camera, geometry, material, group) {
+        // What screen-space widths are measured against, and only the renderer knows it. Set from the
+        // mesh rather than the material's own hook, which three calls after this one — picking reads it
+        // between frames, and would otherwise read one that is a frame stale.
+        renderer.getViewport(_viewport);
+        this.material.resolution.set(_viewport.z, _viewport.w);
+        super.onBeforeRender(renderer, scene, camera, geometry, material, group);
+    }
+    patchMaterial(material) {
+        // Only a line material can draw a segment at all, so anything else three hands over — a scene's
+        // `overrideMaterial`, a shadow pass's depth material — takes the instancing patch alone and
+        // simply does not draw them.
+        if (!isLineMaterial(material))
+            return super.patchMaterial(material);
+        // First, so the instancing patch wraps *around* it: at compile time the prologue the line patch
+        // reads has to be injected before it runs.
+        const unpatchLine = patchLineMaterial(material);
+        const unpatchInstancing = super.patchMaterial(material);
+        return () => {
+            unpatchInstancing();
+            unpatchLine();
+        };
+    }
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with anything
+ * three puts in the catalog when the canvas mounts.
+ */
+export const BatchedLines = extend(BatchedLinesImpl);
+/**
+ * Whether a material is one three's line shader compiles from.
+ * @param material - The material three is about to draw with.
+ * @returns Whether it can draw segments.
+ */
+function isLineMaterial(material) {
+    return material.isLineMaterial === true;
+}
+/**
+ * The width a member starts at: negative, which is how "none of its own" is marked, so it draws at
+ * the material's. See {@link BatchedLinesImpl.setWidthAt} for why the marker is a negative value and
+ * not zero.
+ */
+const MATERIAL_WIDTH = -1;
+/** The tint a member starts at: untinted and opaque, so it draws in the material's own color. */
+const UNTINTED = new Vector4(1, 1, 1, 1);
+/** What a member's endpoints are cleared to: a segment with no length, and so no area. */
+const ORIGIN = new Vector3();
+// Scratch, each filled and consumed within one synchronous call.
+const _start = new Vector3();
+const _end = new Vector3();
+const _viewport = new Vector4();

package/dist/core/lines/FrustumCullingLines.d.ts

@@ -0,0 +1,44 @@
+import { type Camera, type Sphere } from 'three';
+import { type LineMaterial } from 'three/addons/lines/LineMaterial.js';
+import { type CullingHost, FrustumCulling } from '../instanced/FrustumCulling';
+/** What {@link FrustumCullingLines} reads off the batch it culls, beyond what every instanced mesh offers. */
+interface CullingHostLines extends CullingHost {
+    /** The material, whose width a member with none of its own draws at, and whose units they are in. */
+    material: LineMaterial;
+    /**
+     * A member's own width, or a negative value while it has none.
+     * @param id - The member.
+     * @returns The width.
+     */
+    getWidthAt(id: number): number;
+}
+/**
+ * Culling for a line batch: each member tested by where it is *drawn*, not where it runs.
+ *
+ * A member's bounds are its two endpoints, which is the segment. What covers pixels is the ribbon the
+ * shader expands around it — after projection, by a width counted in screen pixels — so a member with
+ * both ends off screen still shows if that ribbon crosses the edge, and culling on the ends alone
+ * pops it there.
+ *
+ * The margin is added here rather than to the bounds themselves because it is not a property of the
+ * member: it depends on the camera, and on how far *this* member is from it. Which is also why it is
+ * per member rather than one figure for the batch — a member already knows its own width, and a batch
+ * of hairlines beside one wide route would otherwise be padded by the widest of them.
+ */
+export declare class FrustumCullingLines extends FrustumCulling {
+    protected instanceSphere(host: CullingHostLines, id: number, camera: Camera, target: Sphere): Sphere;
+    /**
+     * How far past its endpoints one member draws, in the units its bounds are measured in.
+     *
+     * Measured at the far side of the member, since a screen-space width covers more of the plan the
+     * further away it is — the near side would under-pad the end that is further off.
+     * @param host - The batch being culled.
+     * @param id - The member.
+     * @param camera - The camera the width is measured from.
+     * @param sphere - What encloses it, in the batch's own space.
+     * @returns The margin.
+     */
+    private drawnMargin;
+}
+export {};
+//# sourceMappingURL=FrustumCullingLines.d.ts.map