@cesium/engine 26.1.0 → 26.3.0

package/Source/Core/VectorPipeline.js

@@ -0,0 +1,1211 @@
+// @ts-check
+
+import PixelDatatype from "../Renderer/PixelDatatype.js";
+import Sampler from "../Renderer/Sampler.js";
+import Texture from "../Renderer/Texture.js";
+import BufferPolygon from "../Scene/BufferPolygon.js";
+import BufferPolygonMaterial from "../Scene/BufferPolygonMaterial.js";
+import BufferPolyline from "../Scene/BufferPolyline.js";
+import BufferPolylineMaterial from "../Scene/BufferPolylineMaterial.js";
+import Cartesian2 from "./Cartesian2.js";
+import Cartesian3 from "./Cartesian3.js";
+import Cartographic from "./Cartographic.js";
+import Color from "./Color.js";
+import CesiumMath from "./Math.js";
+import Matrix4 from "./Matrix4.js";
+import PixelFormat from "./PixelFormat.js";
+import defined from "./defined.js";
+import Rectangle from "./Rectangle.js";
+
+/** @import BufferPrimitive from "../Scene/BufferPrimitive.js"; */
+/** @import BufferPrimitiveCollection from "../Scene/BufferPrimitiveCollection.js"; */
+/** @import BufferPolygonCollection from "../Scene/BufferPolygonCollection.js"; */
+/** @import BufferPolylineCollection from "../Scene/BufferPolylineCollection.js"; */
+/** @import Context from "../Renderer/Context.js"; */
+/** @import Ellipsoid from "./Ellipsoid.js"; */
+/** @import TilingScheme from "./TilingScheme.js"; */
+/** @import {TypedArray, TypedArrayConstructor} from "./globalTypes.js"; */
+
+const GRID_TARGET_SEGMENTS_PER_CELL = 16;
+const GRID_NEIGHBOR_PADDING_SCALE = 0.35;
+
+const scratchPolyline = new BufferPolyline();
+const scratchPolylineMaterial = new BufferPolylineMaterial();
+const scratchPolygon = new BufferPolygon();
+const scratchPolygonMaterial = new BufferPolygonMaterial();
+const scratchLocalPosition = new Cartesian3();
+const scratchWorldPosition = new Cartesian3();
+const scratchCartographic = new Cartographic();
+const scratchSegmentStart = new Cartesian2();
+const scratchSegmentEnd = new Cartesian2();
+const scratchPickColor = new Color();
+
+/**
+ * Vector geometry intersecting a terrain tile, mapped into the tile's [0,1]^2 UV domain.
+ *
+ * @typedef {object} VectorTileData
+ *
+ * @property {boolean} show Whether this vector data should be rendered.
+ * @property {boolean} hasPolylines Whether polyline lookup data was baked.
+ * @property {boolean} hasPolygons Whether polygon lookup data was baked.
+ * @property {Map<BufferPrimitiveCollection<BufferPrimitive>, number>} collectionVersions Version of each
+ *   collection the data was baked from, for staleness checks.
+ * @property {Rectangle} rectangle Cartographic rectangle the data was baked for.
+ * @property {number} minimumTileScreenPixels Lower bound on the tile's screen size, in pixels,
+ *   used to convert screen-space line widths into tile UV.
+ * @property {Cartesian2} metersPerUv Ground size of the tile, in meters, along each UV axis. Measured on a
+ *   plane tangent at the tile's center, so it drifts from true surface distance toward the tile's edges.
+ * @property {boolean} [hasPixelWidths] Whether any polyline width is in screen pixels.
+ * @property {boolean} [hasMeterWidths] Whether any polyline width is in meters.
+ *
+ * Stage 1: Collect vector segments and polygon rings intersecting tile.
+ * @property {number[][]} [polylineSegments] Tile-clipped polyline segments as [ax, ay, bx, by] in tile UV space.
+ * @property {number[]} [polylineSegmentPrimitiveIndices] Index per segment, mapping to material for the segment.
+ * @property {Float64Array[]} [polygonRings] Tile-clipped polygon rings as flat [x0, y0, x1, y1, ...] in tile UV space.
+ * @property {number[]} [polygonRingPrimitiveIndices] Index per ring, mapping to material for the ring.
+ * @property {Float32Array[]} [widths] Signed primitive widths, by primitive index.
+ * @property {Uint8Array[]} [colors] Primitive colors, by primitive index.
+ * @property {Uint8Array[]} [pickColors] Primitive pick colors, by primitive index.
+ * @property {number} [primitiveCount] Number of vector primitives in tile.
+ *
+ * Stage 2: Build CPU grid structures.
+ * @property {Float32Array} [polylineSegmentTexels] Packed RGBA line segments (ax, ay, bx, by) in tile UV space, -1 filled.
+ * @property {number} [polylineSegmentTextureWidth] Width of the segment texture, in texels.
+ * @property {number} [polylineSegmentTextureHeight] Height of the segment texture, in texels.
+ * @property {Float32Array} [polylineSegmentPrimitiveIndicesTexels] Index per segment, mapping to material for the segment.
+ * @property {Uint32Array} [polylineGridCellIndices] Polyline grid header [gridWidth, gridHeight, ...per-cell end offsets].
+ * @property {Float32Array} [polygonEdgeTexels] Packed RGBA polygon ring edges (ax, ay, bx, by), clipped per grid cell, -1 filled.
+ * @property {number} [polygonEdgeTextureWidth] Width of the polygon edge texture, in texels.
+ * @property {number} [polygonEdgeTextureHeight] Height of the polygon edge texture, in texels.
+ * @property {Float32Array} [polygonEdgePrimitiveIndicesTexels] Index per polygon edge, mapping to material for the edge.
+ * @property {Uint32Array} [polygonGridCellIndices] Polygon grid header [gridWidth, gridHeight, ...per-cell end offsets].
+ *
+ * Stage 3: Build GPU texture resources, uploaded lazily at draw time.
+ * @property {Texture} [polylineSegmentTexture] GPU texture of polylineSegmentTexels.
+ * @property {Texture} [polylineSegmentPrimitiveIndicesTexture] GPU texture of primitive indices per segment.
+ * @property {Texture} [widthTexture] GPU texture of primitive widths, by primitive index.
+ * @property {Texture} [colorTexture] GPU texture of primitive colors, by primitive index.
+ * @property {Texture} [pickColorTexture] GPU texture of primitive pick colors, by primitive index.
+ * @property {Texture} [polylineGridCellIndicesTexture] GPU texture of polylineGridCellIndices.
+ * @property {Texture} [polygonEdgeTexture] GPU texture of polygonEdgeTexels.
+ * @property {Texture} [polygonEdgePrimitiveIndicesTexture] GPU texture of primitive indices per polygon edge.
+ * @property {Texture} [polygonGridCellIndicesTexture] GPU texture of polygonGridCellIndices.
+ *
+ * @private
+ */
+
+/**
+ * Snapshot of a vector collection — projected vertex positions and
+ * per-primitive material properties — extracted in a single pass so the
+ * collection can be marked clean immediately afterward.
+ *
+ * @typedef {object} VectorCollectionData
+ *
+ * @property {number} version State of `collection._version` at time data was last updated.
+ * @property {Rectangle} rectangle The rectangle of the vector collection's bounding volume.
+ * @property {Float64Array} positions Collection positions, projected to the ellipsoid as [lng, lat] in radians.
+ * @property {Float32Array} widths Signed primitive widths, by primitive index. A negative magnitude marks
+ *   a width in meters on the ground; a positive one marks a width in screen pixels. Zero-filled for
+ *   polygon collections.
+ * @property {boolean} [widthInMeters] Whether widths are in meters on the ground rather than screen pixels.
+ * @property {Uint8Array} colors Primitive colors, by primitive index.
+ * @property {Uint8Array} pickColors Primitive pick colors, by primitive index. Zero-filled when the
+ *   collection does not allow picking.
+ *
+ * @private
+ */
+
+/**
+ * Pipeline for vector data rendered using clamped {@link HeightReference} modes.
+ *
+ * Projects vector data into the [0,1]^2 UV domain of a given {@link TilingScheme}, clips to tile
+ * bounds, and packs grid-indexed segment lookup tables consumed by Globe and 3D Tiles renderers.
+ *
+ * @see VectorProvider
+ * @ignore
+ */
+class VectorPipeline {
+  /**
+   * @param {BufferPolylineCollection} collection
+   * @param {Ellipsoid} ellipsoid
+   * @param {VectorCollectionData} [result]
+   * @returns {VectorCollectionData}
+   */
+  static packPolylineCollectionData(collection, ellipsoid, result) {
+    if (
+      defined(result) &&
+      collection._dirtyCount === 0 &&
+      collection._version === result.version
+    ) {
+      return result;
+    }
+
+    const primitiveCount = collection.primitiveCount;
+    const boundingVolume = collection.boundingVolume;
+
+    const rectangle = Rectangle.fromBoundingSphere(boundingVolume, ellipsoid);
+    const positions = _getProjectedPositions(collection, ellipsoid);
+
+    const widths = new Float32Array(primitiveCount);
+    const colors = new Uint8Array(primitiveCount * 4);
+    const pickColors = new Uint8Array(primitiveCount * 4);
+    const widthInMeters = collection.widthUnits === "meters";
+
+    for (let i = 0; i < primitiveCount; i++) {
+      const polyline = /** @type {BufferPolyline} */ (
+        collection.get(i, scratchPolyline)
+      );
+
+      // Append materials unconditionally, to simplify indexing and updates.
+      const polylineMaterial = /** @type {BufferPolylineMaterial} */ (
+        polyline.getMaterial(scratchPolylineMaterial)
+      );
+
+      widths[i] = widthInMeters
+        ? -polylineMaterial.width
+        : polylineMaterial.width;
+
+      colors[i * 4] = Color.floatToByte(polylineMaterial.color.red);
+      colors[i * 4 + 1] = Color.floatToByte(polylineMaterial.color.green);
+      colors[i * 4 + 2] = Color.floatToByte(polylineMaterial.color.blue);
+      colors[i * 4 + 3] = Color.floatToByte(polylineMaterial.color.alpha);
+
+      _writePickColor(pickColors, i, polyline._pickId);
+    }
+
+    return Object.assign(
+      result ?? {},
+      /** @type {VectorCollectionData} */ ({
+        version: collection._version,
+        rectangle: rectangle,
+        positions: positions,
+        widths: widths,
+        widthInMeters: widthInMeters,
+        colors: colors,
+        pickColors: pickColors,
+      }),
+    );
+  }
+
+  /**
+   * Projects all visible polylines in a collection into tile-local UV segments,
+   * clipped to the tile, appending [ax, ay, bx, by] to the segments array.
+   *
+   * @param {BufferPolylineCollection} collection
+   * @param {VectorCollectionData} collectionData
+   * @param {Rectangle} rectangle
+   * @param {VectorTileData} result
+   */
+  static packPolylineSegments(collection, collectionData, rectangle, result) {
+    result.polylineSegments ??= [];
+    result.widths ??= [];
+    result.colors ??= [];
+    result.pickColors ??= [];
+    result.polylineSegmentPrimitiveIndices ??= [];
+    result.primitiveCount ??= 0;
+    result.rectangle ??= Rectangle.clone(rectangle);
+
+    const width = rectangle.width;
+    const primitiveCount = collection.primitiveCount;
+    const positions = collectionData.positions;
+
+    for (let i = 0; i < primitiveCount; i++) {
+      const polyline = /** @type {BufferPolyline} */ (
+        collection.get(i, scratchPolyline)
+      );
+      if (!polyline.show) {
+        continue;
+      }
+
+      const vertexCount = polyline.vertexCount;
+      const vertexOffset = polyline.vertexOffset;
+
+      // A line whose centerline lies outside the tile still covers pixels inside it.
+      const margin = Math.max(
+        CesiumMath.EPSILON3,
+        _halfWidthToTileUv(collectionData.widths[i], result),
+      );
+
+      for (let j = 0; j + 1 < vertexCount; j++) {
+        const segmentStart = Cartesian2.fromArray(
+          // @ts-expect-error https://github.com/CesiumGS/cesium/pull/13302
+          positions,
+          (vertexOffset + j) * 2,
+          scratchSegmentStart,
+        );
+
+        const segmentEnd = Cartesian2.fromArray(
+          // @ts-expect-error https://github.com/CesiumGS/cesium/pull/13302
+          positions,
+          (vertexOffset + j + 1) * 2,
+          scratchSegmentEnd,
+        );
+
+        _projectSegmentToTileUv(segmentStart, segmentEnd, rectangle, width);
+
+        const clipped = _clipSegmentToTile(segmentStart, segmentEnd, margin);
+
+        if (clipped) {
+          result.polylineSegments.push([
+            segmentStart.x,
+            segmentStart.y,
+            segmentEnd.x,
+            segmentEnd.y,
+          ]);
+          result.polylineSegmentPrimitiveIndices.push(
+            result.primitiveCount + i,
+          );
+        }
+      }
+    }
+
+    // Append materials unconditionally, to simplify indexing and updates.
+    result.widths.push(collectionData.widths);
+    result.colors.push(collectionData.colors);
+    result.pickColors.push(collectionData.pickColors);
+    if (primitiveCount > 0) {
+      result.hasPixelWidths ||= !collectionData.widthInMeters;
+      result.hasMeterWidths ||= collectionData.widthInMeters;
+    }
+
+    result.primitiveCount += primitiveCount;
+  }
+
+  /**
+   * Packs UV-space segments into a grid-indexed segment lookup. Returns the packed
+   * segment texels (RGBA, -1 filled) plus a grid-cell index header.
+   *
+   * @param {VectorTileData} result
+   */
+  static packPolylineGrid(result) {
+    const segments = result.polylineSegments;
+    const segmentPrimitiveIndices = result.polylineSegmentPrimitiveIndices;
+
+    const gridSize = Math.max(
+      1,
+      Math.ceil(Math.sqrt(segments.length / GRID_TARGET_SEGMENTS_PER_CELL)),
+    );
+
+    const grid = new Array(gridSize * gridSize);
+    for (let i = 0; i < grid.length; i++) {
+      grid[i] = [];
+    }
+
+    let packedSegmentCount = 0;
+    // Each segment is assigned to every cell its padded bounding box overlaps, so
+    // the shader also sees lines just outside the cell it samples.
+    const cellPadding = GRID_NEIGHBOR_PADDING_SCALE / gridSize;
+    const widths = _concatTypedArrays(result.widths);
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const padding = Math.max(
+        cellPadding,
+        _halfWidthToTileUv(widths[segmentPrimitiveIndices[i]], result),
+      );
+      const minX = Math.max(0.0, Math.min(segment[0], segment[2]) - padding);
+      const maxX = Math.min(1.0, Math.max(segment[0], segment[2]) + padding);
+      const minY = Math.max(0.0, Math.min(segment[1], segment[3]) - padding);
+      const maxY = Math.min(1.0, Math.max(segment[1], segment[3]) + padding);
+
+      const startCellX = _clampCellIndex(Math.floor(minX * gridSize), gridSize);
+      const endCellX = _clampCellIndex(Math.floor(maxX * gridSize), gridSize);
+      const startCellY = _clampCellIndex(Math.floor(minY * gridSize), gridSize);
+      const endCellY = _clampCellIndex(Math.floor(maxY * gridSize), gridSize);
+
+      for (let y = startCellY; y <= endCellY; y++) {
+        for (let x = startCellX; x <= endCellX; x++) {
+          grid[y * gridSize + x].push(i);
+          packedSegmentCount++;
+        }
+      }
+    }
+
+    const [textureWidth, textureHeight] =
+      _nextPowerOfTwoSize(packedSegmentCount);
+    const capacity = textureWidth * textureHeight;
+
+    const segmentTexels = new Float32Array(capacity * 4).fill(-1.0);
+    const segmentPrimitiveIndicesTexels = new Float32Array(capacity).fill(-1.0);
+
+    const gridCellIndices = new Uint32Array(grid.length + 2);
+    gridCellIndices[0] = gridSize;
+    gridCellIndices[1] = gridSize;
+
+    let offset = 0;
+    for (let i = 0; i < grid.length; i++) {
+      const cellSegments = grid[i];
+      for (let j = 0; j < cellSegments.length; j++) {
+        const segmentIndex = cellSegments[j];
+        const segment = segments[segmentIndex];
+        segmentTexels[offset * 4] = segment[0]; // R
+        segmentTexels[offset * 4 + 1] = segment[1]; // G
+        segmentTexels[offset * 4 + 2] = segment[2]; // B
+        segmentTexels[offset * 4 + 3] = segment[3]; // A
+
+        const primitiveIndex = segmentPrimitiveIndices[segmentIndex];
+        segmentPrimitiveIndicesTexels[offset] = primitiveIndex;
+
+        offset++;
+      }
+      gridCellIndices[i + 2] = offset;
+    }
+
+    result.polylineSegmentTexels = segmentTexels;
+    result.polylineSegmentTextureWidth = textureWidth;
+    result.polylineSegmentTextureHeight = textureHeight;
+    result.polylineSegmentPrimitiveIndicesTexels =
+      segmentPrimitiveIndicesTexels;
+    result.polylineGridCellIndices = gridCellIndices;
+  }
+
+  /**
+   * @param {BufferPolygonCollection} collection
+   * @param {Ellipsoid} ellipsoid
+   * @param {VectorCollectionData} [result]
+   * @returns {VectorCollectionData}
+   */
+  static packPolygonCollectionData(collection, ellipsoid, result) {
+    if (
+      defined(result) &&
+      collection._dirtyCount === 0 &&
+      collection._version === result.version
+    ) {
+      return result;
+    }
+
+    const primitiveCount = collection.primitiveCount;
+    const boundingVolume = collection.boundingVolume;
+
+    const rectangle = Rectangle.fromBoundingSphere(boundingVolume, ellipsoid);
+    const positions = _getProjectedPositions(collection, ellipsoid);
+
+    // Widths are unused by polygon fills; zero-filled so polygons share the
+    // primitive index space (and width/color textures) with polylines.
+    const widths = new Float32Array(primitiveCount);
+    const colors = new Uint8Array(primitiveCount * 4);
+    const pickColors = new Uint8Array(primitiveCount * 4);
+
+    for (let i = 0; i < primitiveCount; i++) {
+      const polygon = /** @type {BufferPolygon} */ (
+        collection.get(i, scratchPolygon)
+      );
+
+      // Append materials unconditionally, to simplify indexing and updates.
+      const polygonMaterial = /** @type {BufferPolygonMaterial} */ (
+        polygon.getMaterial(scratchPolygonMaterial)
+      );
+
+      colors[i * 4] = Color.floatToByte(polygonMaterial.color.red);
+      colors[i * 4 + 1] = Color.floatToByte(polygonMaterial.color.green);
+      colors[i * 4 + 2] = Color.floatToByte(polygonMaterial.color.blue);
+      colors[i * 4 + 3] = Color.floatToByte(polygonMaterial.color.alpha);
+
+      _writePickColor(pickColors, i, polygon._pickId);
+    }
+
+    return Object.assign(
+      result ?? {},
+      /** @type {VectorCollectionData} */ ({
+        version: collection._version,
+        rectangle: rectangle,
+        positions: positions,
+        widths: widths,
+        colors: colors,
+        pickColors: pickColors,
+      }),
+    );
+  }
+
+  /**
+   * Projects all visible polygon rings (outer rings and holes) in a collection
+   * into tile-local UV space, clipped to the tile, appending each surviving
+   * ring as a flat [x0, y0, x1, y1, ...] closed loop.
+   *
+   * @param {BufferPolygonCollection} collection
+   * @param {VectorCollectionData} collectionData
+   * @param {Rectangle} rectangle
+   * @param {VectorTileData} result
+   */
+  static packPolygonRings(collection, collectionData, rectangle, result) {
+    result.polygonRings ??= [];
+    result.polygonRingPrimitiveIndices ??= [];
+    result.widths ??= [];
+    result.colors ??= [];
+    result.pickColors ??= [];
+    result.primitiveCount ??= 0;
+    result.rectangle ??= Rectangle.clone(rectangle);
+
+    const width = rectangle.width;
+    const primitiveCount = collection.primitiveCount;
+    const positions = collectionData.positions;
+
+    for (let i = 0; i < primitiveCount; i++) {
+      const polygon = /** @type {BufferPolygon} */ (
+        collection.get(i, scratchPolygon)
+      );
+      if (!polygon.show) {
+        continue;
+      }
+
+      const vertexOffset = polygon.vertexOffset;
+      const vertexCount = polygon.vertexCount;
+      const holes = polygon.getHoles();
+
+      // Ring r spans [ringStart, ringEnd): the outer ring, then each hole.
+      // The shader's even-odd test makes hole rings cancel enclosing coverage.
+      for (let r = 0; r <= holes.length; r++) {
+        const ringStart = r === 0 ? 0 : holes[r - 1];
+        const ringEnd = r === holes.length ? vertexCount : holes[r];
+        const ringVertexCount = ringEnd - ringStart;
+        if (ringVertexCount < 3) {
+          continue;
+        }
+
+        const ringUv = _projectRingToTileUv(
+          positions,
+          vertexOffset + ringStart,
+          ringVertexCount,
+          rectangle,
+          width,
+        );
+
+        // Clip to the tile plus the shared tile clip margin. A ring enclosing
+        // the whole tile clips to the tile rectangle itself, so tiles
+        // interior to a large polygon remain covered.
+        const clipped = _clipRingToRect(
+          ringUv,
+          ringVertexCount,
+          -CesiumMath.EPSILON3,
+          1.0 + CesiumMath.EPSILON3,
+          -CesiumMath.EPSILON3,
+          1.0 + CesiumMath.EPSILON3,
+          scratchClippedRing,
+        );
+        if (clipped.vertexCount < 3) {
+          continue;
+        }
+
+        result.polygonRings.push(
+          clipped.positions.slice(0, clipped.vertexCount * 2),
+        );
+        result.polygonRingPrimitiveIndices.push(result.primitiveCount + i);
+      }
+    }
+
+    // Append materials unconditionally, to simplify indexing and updates.
+    result.widths.push(collectionData.widths);
+    result.colors.push(collectionData.colors);
+    result.pickColors.push(collectionData.pickColors);
+
+    result.primitiveCount += primitiveCount;
+  }
+
+  /**
+   * Packs UV-space polygon rings into a grid-indexed edge lookup. Each ring
+   * is clipped to every grid cell it overlaps — unlike polyline segments,
+   * which are only assigned to cells — so a cell's edges form closed loops
+   * and a fragment can evaluate even-odd coverage from its own cell alone.
+   *
+   * @param {VectorTileData} result
+   */
+  static packPolygonGrid(result) {
+    const rings = result.polygonRings;
+    const ringPrimitiveIndices = result.polygonRingPrimitiveIndices;
+
+    let ringEdgeCount = 0;
+    for (let i = 0; i < rings.length; i++) {
+      ringEdgeCount += rings[i].length / 2;
+    }
+
+    const gridSize = Math.max(
+      1,
+      Math.ceil(Math.sqrt(ringEdgeCount / GRID_TARGET_SEGMENTS_PER_CELL)),
+    );
+
+    // Per-cell packed edges [ax, ay, bx, by, primitiveIndex, ...].
+    /** @type {number[][]} */
+    const grid = new Array(gridSize * gridSize);
+    for (let i = 0; i < grid.length; i++) {
+      grid[i] = [];
+    }
+
+    // Rings are appended in primitive order, so each cell's edge list stays
+    // grouped by primitive; the shader resolves parity per group.
+    let packedEdgeCount = 0;
+    for (let r = 0; r < rings.length; r++) {
+      const ring = rings[r];
+      const primitiveIndex = ringPrimitiveIndices[r];
+      const ringVertexCount = ring.length / 2;
+
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      for (let k = 0; k < ringVertexCount; k++) {
+        minX = Math.min(minX, ring[k * 2]);
+        maxX = Math.max(maxX, ring[k * 2]);
+        minY = Math.min(minY, ring[k * 2 + 1]);
+        maxY = Math.max(maxY, ring[k * 2 + 1]);
+      }
+
+      const startCellX = _clampCellIndex(Math.floor(minX * gridSize), gridSize);
+      const endCellX = _clampCellIndex(Math.floor(maxX * gridSize), gridSize);
+      const startCellY = _clampCellIndex(Math.floor(minY * gridSize), gridSize);
+      const endCellY = _clampCellIndex(Math.floor(maxY * gridSize), gridSize);
+
+      for (let y = startCellY; y <= endCellY; y++) {
+        for (let x = startCellX; x <= endCellX; x++) {
+          // Expand the clip rectangle slightly so fragments at shared cell
+          // boundaries fall strictly inside the clipped loops. Smaller than
+          // the tile clip margin above: that one is a fraction of a tile and
+          // preserves geometry across the shared tile boundary, while this is
+          // a fraction of a grid cell and only has to exceed the float32
+          // rounding of a UV coordinate.
+          const clipped = _clipRingToRect(
+            ring,
+            ringVertexCount,
+            x / gridSize - CesiumMath.EPSILON5,
+            (x + 1) / gridSize + CesiumMath.EPSILON5,
+            y / gridSize - CesiumMath.EPSILON5,
+            (y + 1) / gridSize + CesiumMath.EPSILON5,
+            scratchClippedRing,
+          );
+          const clippedCount = clipped.vertexCount;
+          if (clippedCount < 3) {
+            continue;
+          }
+
+          const clippedPositions = clipped.positions;
+          const cell = grid[y * gridSize + x];
+          for (let k = 0; k < clippedCount; k++) {
+            const k2 = (k + 1) % clippedCount;
+            const ax = clippedPositions[k * 2];
+            const ay = clippedPositions[k * 2 + 1];
+            const bx = clippedPositions[k2 * 2];
+            const by = clippedPositions[k2 * 2 + 1];
+            // Horizontal edges never toggle parity against the shader's
+            // horizontal ray; clipping produces many along cell bounds.
+            if (ay === by) {
+              continue;
+            }
+            cell.push(ax, ay, bx, by, primitiveIndex);
+            packedEdgeCount++;
+          }
+        }
+      }
+    }
+
+    const [textureWidth, textureHeight] = _nextPowerOfTwoSize(packedEdgeCount);
+    const capacity = textureWidth * textureHeight;
+
+    const edgeTexels = new Float32Array(capacity * 4).fill(-1.0);
+    const edgePrimitiveIndicesTexels = new Float32Array(capacity).fill(-1.0);
+
+    const gridCellIndices = new Uint32Array(grid.length + 2);
+    gridCellIndices[0] = gridSize;
+    gridCellIndices[1] = gridSize;
+
+    let offset = 0;
+    for (let i = 0; i < grid.length; i++) {
+      const cellEdges = grid[i];
+      for (let j = 0; j < cellEdges.length; j += 5) {
+        edgeTexels[offset * 4] = cellEdges[j]; // R
+        edgeTexels[offset * 4 + 1] = cellEdges[j + 1]; // G
+        edgeTexels[offset * 4 + 2] = cellEdges[j + 2]; // B
+        edgeTexels[offset * 4 + 3] = cellEdges[j + 3]; // A
+
+        edgePrimitiveIndicesTexels[offset] = cellEdges[j + 4];
+
+        offset++;
+      }
+      gridCellIndices[i + 2] = offset;
+    }
+
+    result.polygonEdgeTexels = edgeTexels;
+    result.polygonEdgeTextureWidth = textureWidth;
+    result.polygonEdgeTextureHeight = textureHeight;
+    result.polygonEdgePrimitiveIndicesTexels = edgePrimitiveIndicesTexels;
+    result.polygonGridCellIndices = gridCellIndices;
+  }
+
+  /**
+   * Creates the width and color textures indexed by the primitive index space
+   * shared between polylines and polygons.
+   *
+   * @param {Context} context
+   * @param {VectorTileData} result
+   */
+  static packPrimitiveTextures(context, result) {
+    const [primTextureWidth, primTextureHeight] = _nextPowerOfTwoSize(
+      result.primitiveCount,
+    );
+
+    const widthTextureView = new Float32Array(
+      primTextureWidth * primTextureHeight,
+    );
+    widthTextureView.set(_concatTypedArrays(result.widths));
+    result.widthTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RED,
+      pixelDatatype: PixelDatatype.FLOAT,
+      source: {
+        width: primTextureWidth,
+        height: primTextureHeight,
+        arrayBufferView: widthTextureView,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+
+    const colorTextureView = new Uint8Array(
+      primTextureWidth * primTextureHeight * 4,
+    );
+    colorTextureView.set(_concatTypedArrays(result.colors));
+    result.colorTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RGBA,
+      pixelDatatype: PixelDatatype.UNSIGNED_BYTE,
+      source: {
+        width: primTextureWidth,
+        height: primTextureHeight,
+        arrayBufferView: colorTextureView,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+
+    const pickColorTextureView = new Uint8Array(
+      primTextureWidth * primTextureHeight * 4,
+    );
+    pickColorTextureView.set(_concatTypedArrays(result.pickColors));
+    result.pickColorTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RGBA,
+      pixelDatatype: PixelDatatype.UNSIGNED_BYTE,
+      source: {
+        width: primTextureWidth,
+        height: primTextureHeight,
+        arrayBufferView: pickColorTextureView,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+  }
+
+  /**
+   * @param {Context} context
+   * @param {VectorTileData} result
+   */
+  static packPolylineTextures(context, result) {
+    result.polylineSegmentTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RGBA,
+      pixelDatatype: PixelDatatype.FLOAT,
+      source: {
+        width: result.polylineSegmentTextureWidth,
+        height: result.polylineSegmentTextureHeight,
+        arrayBufferView: result.polylineSegmentTexels,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+
+    result.polylineSegmentPrimitiveIndicesTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RED,
+      pixelDatatype: PixelDatatype.FLOAT,
+      source: {
+        width: result.polylineSegmentTextureWidth,
+        height: result.polylineSegmentTextureHeight,
+        arrayBufferView: result.polylineSegmentPrimitiveIndicesTexels,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+
+    result.polylineGridCellIndicesTexture = _createGridCellIndicesTexture(
+      context,
+      result.polylineGridCellIndices,
+    );
+  }
+
+  /**
+   * @param {Context} context
+   * @param {VectorTileData} result
+   */
+  static packPolygonTextures(context, result) {
+    result.polygonEdgeTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RGBA,
+      pixelDatatype: PixelDatatype.FLOAT,
+      source: {
+        width: result.polygonEdgeTextureWidth,
+        height: result.polygonEdgeTextureHeight,
+        arrayBufferView: result.polygonEdgeTexels,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+
+    result.polygonEdgePrimitiveIndicesTexture = new Texture({
+      context,
+      pixelFormat: PixelFormat.RED,
+      pixelDatatype: PixelDatatype.FLOAT,
+      source: {
+        width: result.polygonEdgeTextureWidth,
+        height: result.polygonEdgeTextureHeight,
+        arrayBufferView: result.polygonEdgePrimitiveIndicesTexels,
+      },
+      sampler: Sampler.NEAREST,
+      flipY: false,
+    });
+
+    result.polygonGridCellIndicesTexture = _createGridCellIndicesTexture(
+      context,
+      result.polygonGridCellIndices,
+    );
+  }
+
+  /**
+   * @param {VectorTileData} data
+   */
+  static freeResources(data) {
+    data.polylineSegmentTexture?.destroy();
+    data.widthTexture?.destroy();
+    data.colorTexture?.destroy();
+    data.pickColorTexture?.destroy();
+    data.polylineSegmentPrimitiveIndicesTexture?.destroy();
+    data.polylineGridCellIndicesTexture?.destroy();
+    data.polygonEdgeTexture?.destroy();
+    data.polygonEdgePrimitiveIndicesTexture?.destroy();
+    data.polygonGridCellIndicesTexture?.destroy();
+  }
+}
+
+/////////////////////////////////////////////////////////////////////////////
+// INTERNAL METHODS
+
+/**
+ * Writes a primitive's pick color, as RGBA bytes, at the given primitive index.
+ *
+ * @param {Uint8Array} pickColors
+ * @param {number} index
+ * @param {number} pickId Pick color of the primitive, as a packed RGBA value.
+ * @private
+ */
+function _writePickColor(pickColors, index, pickId) {
+  Color.fromRgba(pickId, scratchPickColor);
+  pickColors[index * 4] = Color.floatToByte(scratchPickColor.red);
+  pickColors[index * 4 + 1] = Color.floatToByte(scratchPickColor.green);
+  pickColors[index * 4 + 2] = Color.floatToByte(scratchPickColor.blue);
+  pickColors[index * 4 + 3] = Color.floatToByte(scratchPickColor.alpha);
+}
+
+/**
+ * Converts half of a line's width, plus its antialiased edge, to tile UV.
+ *
+ * @param {number} width Signed line width; negative magnitudes are in meters, positive in pixels.
+ * @param {VectorTileData} tileData
+ * @returns {number}
+ * @private
+ */
+function _halfWidthToTileUv(width, tileData) {
+  if (width >= 0.0) {
+    return ((width + 1.0) * 0.5) / tileData.minimumTileScreenPixels;
+  }
+
+  // A meter is a different amount of UV on each axis; callers apply one isotropic
+  // margin, so use the axis that yields the larger of the two.
+  const metersPerUv = tileData.metersPerUv;
+  return (-width * 0.5) / Math.min(metersPerUv.x, metersPerUv.y);
+}
+
+/**
+ * Projects a polyline segment (start/end Cartesian2s, x=lng, y=lat, in radians) into the
+ * tile's [0,1]^2 UV domain. Endpoint B's longitude is first unwrapped to within
+ * π of A so an antimeridian-crossing segment stays geometrically short instead
+ * of spanning the globe; then both endpoints are shifted together to the 2π
+ * frame nearest the tile center so a segment adjacent to (or crossing) the
+ * tile's west/east edge projects correctly. Result written to input Cartesian2s.
+ *
+ * Only supporting geographic tiling scheme (UV maps linearly to lon/lat)
+ *
+ * @param {Cartesian2} a [lonA, latA] radians, modified in place.
+ * @param {Cartesian2} b [lonB, latB] radians, modified in place.
+ * @param {Rectangle} rectangle
+ * @param {number} width
+ * @private
+ */
+function _projectSegmentToTileUv(a, b, rectangle, width) {
+  let lonA = a.x;
+  let lonB = b.x;
+
+  // Unwrap B relative to A so the segment follows the shortest longitudinal
+  // path (handles antimeridian-crossing segments).
+  lonB = lonA + CesiumMath.negativePiToPi(lonB - lonA);
+
+  // Shift the whole segment to the 2π frame nearest the tile center.
+  const center = rectangle.west + width * 0.5;
+  const shift = center + CesiumMath.negativePiToPi(lonA - center) - lonA;
+  lonA += shift;
+  lonB += shift;
+
+  const height = rectangle.north - rectangle.south;
+  a.x = (lonA - rectangle.west) / width;
+  a.y = (a.y - rectangle.south) / height;
+  b.x = (lonB - rectangle.west) / width;
+  b.y = (b.y - rectangle.south) / height;
+}
+
+/**
+ * Clips a UV-space segment to the tile domain expanded by `margin` on each
+ * side ([-margin, 1 + margin]^2) using Liang-Barsky, so a segment just outside
+ * the tile boundary is still kept. Writes the clipped endpoints to result;
+ * returns false when the segment is entirely outside.
+ *
+ * @param {Cartesian2} a
+ * @param {Cartesian2} b
+ * @param {number} margin
+ * @returns {boolean}
+ * @private
+ */
+function _clipSegmentToTile(a, b, margin) {
+  const lo = -margin;
+  const hi = 1.0 + margin;
+
+  let tMin = 0.0;
+  let tMax = 1.0;
+
+  const ax = a.x;
+  const ay = a.y;
+  const bx = b.x;
+  const by = b.y;
+
+  const dx = bx - ax;
+  const dy = by - ay;
+  const p = [-dx, dx, -dy, dy];
+  const q = [ax - lo, hi - ax, ay - lo, hi - ay];
+
+  for (let i = 0; i < 4; i++) {
+    if (Math.abs(p[i]) < 1.0e-12) {
+      if (q[i] < 0.0) {
+        return false;
+      }
+      continue;
+    }
+
+    const t = q[i] / p[i];
+    if (p[i] < 0.0) {
+      tMin = Math.max(tMin, t);
+    } else {
+      tMax = Math.min(tMax, t);
+    }
+
+    if (tMin > tMax) {
+      return false;
+    }
+  }
+
+  a.x = ax + tMin * dx;
+  a.y = ay + tMin * dy;
+  b.x = ax + tMax * dx;
+  b.y = ay + tMax * dy;
+
+  return true;
+}
+
+/**
+ * @param {number} index
+ * @param {number} gridSize
+ * @returns {number}
+ * @private
+ */
+function _clampCellIndex(index, gridSize) {
+  return Math.max(0, Math.min(gridSize - 1, index));
+}
+
+// Growable module scratch for ring projection and Sutherland-Hodgman clipping.
+/**
+ * @type {Float64Array}
+ * @private
+ */
+let scratchRingUv = new Float64Array(512);
+/**
+ * @type {Float64Array}
+ * @private
+ */
+let scratchClipWorking = new Float64Array(512);
+
+/**
+ * A ring clipped by {@link _clipRingToRect}.
+ *
+ * `positions` is reallocated when the clipped ring outgrows it, so callers
+ * must read it back from this object after each call rather than caching it.
+ *
+ * @typedef {object} ClippedRing
+ * @property {Float64Array} positions Flat [x0, y0, x1, y1, ...] ring coordinates.
+ * @property {number} vertexCount Number of valid vertices in `positions`.
+ * @private
+ */
+
+/**
+ * @type {ClippedRing}
+ * @private
+ */
+const scratchClippedRing = {
+  positions: new Float64Array(512),
+  vertexCount: 0,
+};
+
+/**
+ * Projects a polygon ring ([lng, lat] radian pairs from `positions`) into the
+ * tile's [0,1]^2 UV domain. Longitudes are sequentially unwrapped so an
+ * antimeridian-crossing ring stays continuous, then the whole ring is shifted
+ * to the 2π frame nearest the tile center (matching the polyline projection).
+ * Returns a module scratch valid until the next call.
+ *
+ * Only supporting geographic tiling scheme (UV maps linearly to lon/lat)
+ *
+ * @param {Float64Array} positions Projected collection positions ([lng, lat] radians).
+ * @param {number} vertexStart Index of the ring's first vertex.
+ * @param {number} vertexCount Number of vertices in the ring.
+ * @param {Rectangle} rectangle
+ * @param {number} width
+ * @returns {Float64Array} Flat [u0, v0, u1, v1, ...] ring coordinates.
+ * @private
+ */
+function _projectRingToTileUv(
+  positions,
+  vertexStart,
+  vertexCount,
+  rectangle,
+  width,
+) {
+  if (scratchRingUv.length < vertexCount * 2) {
+    scratchRingUv = new Float64Array(vertexCount * 4);
+  }
+  const result = scratchRingUv;
+  const height = rectangle.north - rectangle.south;
+
+  let previousLon = positions[vertexStart * 2];
+  result[0] = previousLon;
+  result[1] = positions[vertexStart * 2 + 1];
+  for (let i = 1; i < vertexCount; i++) {
+    const lon =
+      previousLon +
+      CesiumMath.negativePiToPi(positions[(vertexStart + i) * 2] - previousLon);
+    result[i * 2] = lon;
+    result[i * 2 + 1] = positions[(vertexStart + i) * 2 + 1];
+    previousLon = lon;
+  }
+
+  const center = rectangle.west + width * 0.5;
+  const lon0 = result[0];
+  const shift = center + CesiumMath.negativePiToPi(lon0 - center) - lon0;
+
+  for (let i = 0; i < vertexCount; i++) {
+    result[i * 2] = (result[i * 2] + shift - rectangle.west) / width;
+    result[i * 2 + 1] = (result[i * 2 + 1] - rectangle.south) / height;
+  }
+
+  return result;
+}
+
+/**
+ * Clips a closed ring to an axis-aligned rectangle with Sutherland-Hodgman.
+ * Writes the clipped ring into `result`, whose `vertexCount` is 0 when the
+ * ring is entirely outside the rectangle.
+ *
+ * @param {Float64Array} ring Flat [x0, y0, x1, y1, ...] ring coordinates.
+ * @param {number} vertexCount
+ * @param {number} minX
+ * @param {number} maxX
+ * @param {number} minY
+ * @param {number} maxY
+ * @param {ClippedRing} result
+ * @returns {ClippedRing} The modified result parameter.
+ * @private
+ */
+function _clipRingToRect(ring, vertexCount, minX, maxX, minY, maxY, result) {
+  let input = ring;
+  let inputCount = vertexCount;
+
+  // axis (0 = x, 1 = y), keep side (1 = keep >= limit, -1 = keep <= limit).
+  for (let plane = 0; plane < 4; plane++) {
+    const axis = plane >> 1;
+    const sign = (plane & 1) === 0 ? 1.0 : -1.0;
+    const limit =
+      plane === 0 ? minX : plane === 1 ? maxX : plane === 2 ? minY : maxY;
+
+    // Ping-pong between the working scratch and the result, writing odd
+    // planes to the result so the fourth and final plane lands there.
+    // Each input vertex emits at most 2 output vertices.
+    const requiredLength = inputCount * 4 + 4;
+    const isWorkingPlane = (plane & 1) === 0;
+    let output = isWorkingPlane ? scratchClipWorking : result.positions;
+    if (output.length < requiredLength) {
+      output = new Float64Array(requiredLength * 2);
+      if (isWorkingPlane) {
+        scratchClipWorking = output;
+      } else {
+        result.positions = output;
+      }
+    }
+
+    let outputCount = 0;
+    let prevX = input[(inputCount - 1) * 2];
+    let prevY = input[(inputCount - 1) * 2 + 1];
+    let prevInside = sign * ((axis === 0 ? prevX : prevY) - limit) >= 0.0;
+
+    for (let i = 0; i < inputCount; i++) {
+      const x = input[i * 2];
+      const y = input[i * 2 + 1];
+      const inside = sign * ((axis === 0 ? x : y) - limit) >= 0.0;
+
+      if (inside !== prevInside) {
+        // Pin the clipped coordinate exactly to the plane so boundary edges
+        // stay axis-aligned.
+        const t =
+          axis === 0
+            ? (limit - prevX) / (x - prevX)
+            : (limit - prevY) / (y - prevY);
+        output[outputCount * 2] = axis === 0 ? limit : prevX + t * (x - prevX);
+        output[outputCount * 2 + 1] =
+          axis === 0 ? prevY + t * (y - prevY) : limit;
+        outputCount++;
+      }
+      if (inside) {
+        output[outputCount * 2] = x;
+        output[outputCount * 2 + 1] = y;
+        outputCount++;
+      }
+
+      prevX = x;
+      prevY = y;
+      prevInside = inside;
+    }
+
+    if (outputCount === 0) {
+      result.vertexCount = 0;
+      return result;
+    }
+
+    input = output;
+    inputCount = outputCount;
+  }
+
+  result.vertexCount = inputCount;
+  return result;
+}
+
+/**
+ * @param {number} count
+ * @returns {number[]}
+ * @private
+ */
+function _nextPowerOfTwoSize(count) {
+  const width = CesiumMath.nextPowerOfTwo(
+    Math.max(1, Math.ceil(Math.sqrt(count))),
+  );
+  const height = CesiumMath.nextPowerOfTwo(
+    Math.max(1, Math.ceil(count / width)),
+  );
+  return [width, height];
+}
+
+/**
+ * Creates a grid header texture, wrapped to a 2D power-of-two size so the
+ * header length is not limited by the maximum texture width.
+ *
+ * @param {Context} context
+ * @param {Uint32Array} gridCellIndices
+ * @returns {Texture}
+ * @private
+ */
+function _createGridCellIndicesTexture(context, gridCellIndices) {
+  const [width, height] = _nextPowerOfTwoSize(gridCellIndices.length);
+  const texels = new Float32Array(width * height);
+  texels.set(gridCellIndices);
+  return new Texture({
+    context: context,
+    pixelFormat: PixelFormat.RED,
+    pixelDatatype: PixelDatatype.FLOAT,
+    source: {
+      width: width,
+      height: height,
+      arrayBufferView: texels,
+    },
+    sampler: Sampler.NEAREST,
+    flipY: false,
+  });
+}
+
+/**
+ * Returns the collection's vertex positions, projected to [lng, lat]
+ * coordinates, in radians, on the given ellipsoid.
+ *
+ * @param {BufferPrimitiveCollection<BufferPrimitive>} collection
+ * @param {Ellipsoid} ellipsoid
+ * @param {Float64Array} [result]
+ * @ignore
+ */
+function _getProjectedPositions(collection, ellipsoid, result) {
+  if (!defined(result)) {
+    result = new Float64Array(collection._positionCountMax * 2);
+  }
+
+  const positions = collection._positionView;
+  const modelMatrix = collection.modelMatrix;
+
+  for (let i = 0; i < collection._positionCount; i++) {
+    const local = Cartesian3.fromArray(
+      // @ts-expect-error https://github.com/CesiumGS/cesium/pull/13302
+      positions,
+      i * 3,
+      scratchLocalPosition,
+    );
+    const world = Matrix4.multiplyByPoint(
+      modelMatrix,
+      local,
+      scratchWorldPosition,
+    );
+    const cartographic = ellipsoid.cartesianToCartographic(
+      world,
+      scratchCartographic,
+    );
+
+    result[i * 2] = cartographic.longitude;
+    result[i * 2 + 1] = cartographic.latitude;
+  }
+
+  return result;
+}
+
+/**
+ * Concatenates N typed arrays.
+ * @template {TypedArray} T
+ * @param {T[]} arrays
+ * @returns {T}
+ * @ignore
+ */
+function _concatTypedArrays(arrays) {
+  let byteLength = 0;
+  for (const array of arrays) {
+    byteLength += array.byteLength;
+  }
+
+  const TypedArray = /** @type {TypedArrayConstructor} */ (
+    arrays[0].constructor
+  );
+  const result = new TypedArray(byteLength / TypedArray.BYTES_PER_ELEMENT);
+
+  let offset = 0;
+  for (const array of arrays) {
+    result.set(array, offset);
+    offset += array.length;
+  }
+
+  return /** @type {T} */ (result);
+}
+
+export default VectorPipeline;