@deck.gl/extensions 9.4.0-beta.4 → 9.4.1

package/package.json

@@ -3,7 +3,7 @@
   "description": "Plug-and-play functionalities for deck.gl layers",
   "license": "MIT",
   "type": "module",
-  "version": "9.4.0-beta.4",
+  "version": "9.4.1",
   "publishConfig": {
     "access": "public"
   },
@@ -42,14 +42,14 @@
     "prepublishOnly": "npm run build-bundle && npm run build-bundle -- --env=dev"
   },
   "dependencies": {
-    "@luma.gl/shadertools": "^9.4.0-beta.7",
-    "@luma.gl/webgl": "^9.4.0-beta.7",
+    "@luma.gl/shadertools": "^9.4.2",
+    "@luma.gl/webgl": "^9.4.2",
     "@math.gl/core": "^4.1.0"
   },
   "peerDependencies": {
-    "@deck.gl/core": "~9.4.0-beta.3",
-    "@luma.gl/core": "~9.4.0-beta.7",
-    "@luma.gl/engine": "~9.4.0-beta.7"
+    "@deck.gl/core": "~9.4.0",
+    "@luma.gl/core": "~9.4.0",
+    "@luma.gl/engine": "~9.4.0"
   },
-  "gitHead": "510649703132adbd49cbfa7d25a49363aec03265"
+  "gitHead": "7de3aa41176da9d6dcc11562fb5fa8b9d0cb11a4"
 }

package/src/path-style/path-style-extension.ts

@@ -14,6 +14,7 @@ import {
   dashShaders,
   Defines,
   offsetShaders,
+  pathStylePipelineShaders,
   scatterplotDashShaders,
   textBackgroundDashShaders
 } from './shaders.glsl';
@@ -318,8 +319,11 @@ export default class PathStyleExtension extends LayerExtension<ResolvedPathStyle
       return {modules: [pathStyle]};
     }
 
-    // PathLayer: existing logic
+    // PathLayer: one ordered coordinate stage plus capability-specific declarations and setup.
     let result = {} as {inject: Record<string, string>};
+    if (extension.opts.dash || extension.opts.offset) {
+      result = mergeShaders(result, pathStylePipelineShaders);
+    }
     const defines: Defines = {};
     if (extension.opts.dash) {
       result = mergeShaders(result, dashShaders);

package/src/path-style/shaders.glsl.ts

@@ -12,9 +12,9 @@
  *    scalar `getDashOffsets` helper remains available for compatibility but does not back the
  *    managed attribute.
  * 2. **Screen pixels** — the common basis for reconciling flat and billboard extrusion.
- *    At the dash injection point, `width` is in common units for a flat path but pixels for
- *    a billboarded path, whose conversion also includes `project.focalDistance`.
- *    `dashWidthPixels` is correct in both branches.
+ *    At the dash injection point, the pre-offset stroke half-width is in common units for a
+ *    flat path but pixels for a billboarded path, whose conversion also includes
+ *    `project.focalDistance`.
  * 3. **Half-widths along the path** — the units of `vPathPosition.y`, tested by the fragment
  *    shader. One unit spans `dashWidthPixels` screen pixels.
  *
@@ -28,8 +28,8 @@ export type Defines = {
    */
   HIGH_PRECISION_DASH?: boolean;
   /**
-   * Set whenever the dash shaders are injected, so that the offset shaders can adjust dash
-   * varyings only when they actually exist.
+   * Set whenever the dash shaders are injected. It guards PathLayer's additional arclength
+   * varyings and the dash stage of the shared PathStyle pipeline.
    */
   DASH_ENABLED?: boolean;
   /**
@@ -38,53 +38,47 @@ export type Defines = {
   PATH_STYLE_OFFSET?: boolean;
 };
 
-export const dashShaders = {
+/**
+ * Ordered PathStyle coordinate pipeline shared by the dash and offset capabilities.
+ *
+ * Offset rendering temporarily widens PathLayer's geometry so the shifted stroke fits inside the
+ * generated mesh. This stage first maps PathLayer's varyings back to the pre-offset stroke, then
+ * derives dash coordinates from that width. Keeping both operations in one injection
+ * avoids making their result depend on the order in which the capability shaders are merged.
+ * It also owns their deferred fragment rejection, after PathLayer has evaluated derivatives.
+ */
+export const pathStylePipelineShaders = {
   inject: {
-    'vs:#decl': `
-in vec2 instanceDashArrays;
-#ifdef HIGH_PRECISION_DASH
-// [distance from the start of the path, total length of the path], in common space.
-in vec2 instanceDashOffsets;
+    'vs:#main-end': `
+#ifdef PATH_STYLE_OFFSET
+  float offsetWidth = abs(instanceOffsets * 2.0) + 1.0;
+  float offsetDir = sign(instanceOffsets);
+  vPathPosition.x = (vPathPosition.x + offsetDir) * offsetWidth - offsetDir;
+  vPathPosition.y *= offsetWidth;
+  vPathLength *= offsetWidth;
+#ifdef DASH_ENABLED
+  vPathBounds *= offsetWidth;
+#endif
 #endif
-out vec2 vDashArray;
-out float vDashOffset;
-out float vDashPathLength;
 
-// Also declared in the fragment stage. The vertex stage needs dashAlignMode so that it can
-// reduce the dash phase modulo the same period the fragment stage will test against, and
-// dashUnits to scale the dash array into that period's units.
-layout(std140) uniform pathStyleUniforms {
-  float dashAlignMode;
-  bool dashGapPickable;
-  highp int dashUnits;
-} pathStyle;
-`,
+#ifdef DASH_ENABLED
+// DECKGL_FILTER_SIZE may have widened width for offset geometry. Dash coordinates are measured
+// against the pre-offset stroke, so recover its half-width before converting dash units.
+float strokeHalfWidth = width.x;
+#ifdef PATH_STYLE_OFFSET
+strokeHalfWidth /= offsetWidth;
+#endif
 
-    'vs:#main-end': `
-// How many screen pixels one unit of vPathPosition.y covers. The two extrusion branches of
-// the path layer leave this in different units, and both differences have to be undone here
-// for a billboarded path to dash like a flat one.
-//
-// Flat paths extrude in common space, so \`width\` is in common units and a unit of
-// vPathPosition.y is width.x * project.scale pixels.
-//
-// Billboarded paths extrude in clip space, so \`width\` is already in pixels at this point -
-// the clip-space conversion happens inside getLineJoinOffset. That conversion also folds in
-// project.focalDistance, which scales the half-width the segment delta is divided by but not
-// the delta itself, so a unit of vPathPosition.y ends up focalDistance pixels wider than the
-// stroke it is supposed to be relative to.
+// How many screen pixels one unit of vPathPosition.y covers. Flat paths extrude in common space;
+// billboarded paths extrude in clip space, whose conversion also includes focalDistance.
 float dashWidthPixels = path.billboard
-  ? width.x * project.focalDistance
-  : width.x * project.scale;
+  ? strokeHalfWidth * project.focalDistance
+  : strokeHalfWidth * project.scale;
+float strokeHalfWidthPixels = path.billboard
+  ? strokeHalfWidth
+  : strokeHalfWidth * project.scale;
 
-// The actual half stroke width on screen, which is what 'widths' is relative to. It differs
-// from dashWidthPixels by exactly the spurious focalDistance above, so expressing 'widths'
-// as a ratio of the two corrects the billboard case onto the flat one - getDashArray is
-// documented relative to the stroke, and flat paths already honor that.
-float strokeHalfWidthPixels = path.billboard ? width.x : width.x * project.scale;
-
-// Everything reduces to "how many screen pixels is one dash unit", divided through by the
-// pixels per unit of vPathPosition.y, so the fragment shader needs no notion of units at all.
+// Convert every public dash unit to the half-width coordinate used by the fragment shader.
 // Keep the cases in sync with DASH_UNITS in path-style-extension.ts.
 float dashUnitPixels = strokeHalfWidthPixels;
 if (pathStyle.dashUnits == 1) {
@@ -116,6 +110,68 @@ vDashOffset = dashPeriod > 0.0 ? mod(dashOffsetAndLength.x, dashPeriod) : 0.0;
 vDashOffset = 0.0;
 vDashPathLength = 0.0;
 #endif
+#endif
+`,
+    'fs:#main-end': `
+#ifdef DASH_ENABLED
+  // PathLayer computes analytic-edge derivatives in its fragment body. A discard in
+  // #main-start can remove helper invocations and make those derivatives undefined, so all
+  // dash-related termination is deferred until the layer has completed that work.
+  #ifdef ANTIALIASING
+  if (inRoundedDashGap) {
+    // The rounded dash cap and PathLayer silhouette are two geometric constraints on the
+    // same fragment. Intersect their coverage instead of multiplying two edge ramps; at the
+    // cap/body shoulder both ramps are half covered and multiplication would create a dark
+    // quarter-covered notch. Keep the sub-pixel duty cycle separable from the path silhouette.
+    float pathCoverage = smoothedge(0.0, edgePixels);
+    float resolvedCapMultiplier =
+      min(pathCoverage, roundedDashResolvedCoverage) / max(pathCoverage, 1e-6);
+    dashCoverage = mix(
+      resolvedCapMultiplier,
+      roundedDashDutyCycle,
+      roundedDashSubPixelBlend
+    );
+  }
+  #endif
+  if (shouldDiscardDash) {
+    discard;
+  }
+  fragColor.a *= dashCoverage;
+#endif
+#ifdef PATH_STYLE_OFFSET
+#ifndef ANTIALIASING
+  // With analytic antialiasing, PathLayer evaluates this boundary using the remapped
+  // vPathPosition and retains the complete centered coverage ramp. The hard clip remains for
+  // the original non-AA path.
+  if (abs(vPathPosition.x) > 1.0) {
+    discard;
+  }
+#endif
+#endif
+`
+  }
+};
+
+export const dashShaders = {
+  inject: {
+    'vs:#decl': `
+in vec2 instanceDashArrays;
+#ifdef HIGH_PRECISION_DASH
+// [distance from the start of the path, total length of the path], in common space.
+in vec2 instanceDashOffsets;
+#endif
+out vec2 vDashArray;
+out float vDashOffset;
+out float vDashPathLength;
+
+// Also declared in the fragment stage. The vertex stage needs dashAlignMode so that it can
+// reduce the dash phase modulo the same period the fragment stage will test against, and
+// dashUnits to scale the dash array into that period's units.
+layout(std140) uniform pathStyleUniforms {
+  float dashAlignMode;
+  bool dashGapPickable;
+  highp int dashUnits;
+} pathStyle;
 `,
 
     'fs:#decl': `
@@ -270,32 +326,6 @@ float dashPatternCoverage(
     // Fully transparent fragments would still write depth and occlude whatever is behind.
     shouldDiscardDash = shouldDiscardDash || dashCoverage <= 0.0;
   }
-`,
-
-    'fs:#main-end': `
-  // PathLayer computes analytic-edge derivatives in its fragment body. A discard in
-  // #main-start can remove helper invocations and make those derivatives undefined, so all
-  // dash-related termination is deferred until the layer has completed that work.
-  #ifdef ANTIALIASING
-  if (inRoundedDashGap) {
-    // The rounded dash cap and PathLayer silhouette are two geometric constraints on the
-    // same fragment. Intersect their coverage instead of multiplying two edge ramps; at the
-    // cap/body shoulder both ramps are half covered and multiplication would create a dark
-    // quarter-covered notch. Keep the sub-pixel duty cycle separable from the path silhouette.
-    float pathCoverage = smoothedge(0.0, edgePixels);
-    float resolvedCapMultiplier =
-      min(pathCoverage, roundedDashResolvedCoverage) / max(pathCoverage, 1e-6);
-    dashCoverage = mix(
-      resolvedCapMultiplier,
-      roundedDashDutyCycle,
-      roundedDashSubPixelBlend
-    );
-  }
-  #endif
-  if (shouldDiscardDash) {
-    discard;
-  }
-  fragColor.a *= dashCoverage;
 `
   }
 };
@@ -521,49 +551,6 @@ in float instanceOffsets;
     'vs:DECKGL_FILTER_SIZE': `
   float offsetWidth = abs(instanceOffsets * 2.0) + 1.0;
   size *= offsetWidth;
-`,
-    'vs:#main-end': `
-  float offsetWidth = abs(instanceOffsets * 2.0) + 1.0;
-  float offsetDir = sign(instanceOffsets);
-  vPathPosition.x = (vPathPosition.x + offsetDir) * offsetWidth - offsetDir;
-  vPathPosition.y *= offsetWidth;
-  vPathLength *= offsetWidth;
-#ifdef DASH_ENABLED
-  // DECKGL_FILTER_SIZE above widened the stroke by offsetWidth, so these rescalings restore
-  // units of the original half-width. The dash block merges ahead of this one.
-  if (pathStyle.dashUnits != 0) {
-    // Absolute dash units must not inherit the artificial width used to build offset
-    // geometry. Relative 'widths' units intentionally remain tied to the original stroke.
-    vDashArray *= offsetWidth;
-  }
-  vPathBounds *= offsetWidth;
-#ifdef HIGH_PRECISION_DASH
-  vDashPathLength *= offsetWidth;
-  // The dash block reduced the CPU path offset modulo a period expressed in widened-width
-  // units. Multiplying that remainder cannot recover the original phase after wrapping, so
-  // redo the reduction with both the restored path offset and restored justified period.
-  float restoredDashUnitLength = vDashArray.x + vDashArray.y;
-  float restoredDashPeriod = pathStyle.dashAlignMode == 0.0
-    ? restoredDashUnitLength
-    : vDashPathLength /
-      max(round(vDashPathLength / max(restoredDashUnitLength, 0.0001)), 1.0);
-  vDashOffset = restoredDashPeriod > 0.0
-    ? mod(dashOffsetAndLength.x * offsetWidth, restoredDashPeriod)
-    : 0.0;
-#else
-  vDashOffset *= offsetWidth;
-#endif
-#endif
-`,
-    'fs:#main-end': `
-#ifndef ANTIALIASING
-  // With analytic antialiasing, PathLayer evaluates this boundary using the remapped
-  // vPathPosition and retains the complete centered coverage ramp. The hard clip remains for
-  // the original non-AA path.
-  if (abs(vPathPosition.x) > 1.0) {
-    discard;
-  }
-#endif
 `
   }
 };

package/src/utils/projection-utils.ts

@@ -2,8 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {WebMercatorViewport, OrthographicViewport} from '@deck.gl/core';
-import type {Layer, Viewport} from '@deck.gl/core';
+import {WebMercatorViewport, OrthographicViewport, _GlobeViewport} from '@deck.gl/core';
+import type {CoordinateSystem, Layer, ProjectUniforms, Viewport} from '@deck.gl/core';
+import {vec3, vec4} from '@math.gl/core';
+import type {NumericArray} from '@math.gl/core';
+
+/** TILE_SIZE in the project shader module */
+const TILE_SIZE = 512;
+/** GLOBE_RADIUS / EARTH_RADIUS in the project shader module */
+const GLOBE_METERS_TO_COMMON = 256 / 6370972;
 
 /** Bounds in CARTESIAN coordinates */
 export type Bounds = [minX: number, minY: number, maxX: number, maxY: number];
@@ -28,6 +35,127 @@ export function getMercatorReferenceViewport(viewport: Viewport): Viewport {
   return viewport.isGeospatial ? MERCATOR_REFERENCE_VIEWPORT : viewport;
 }
 
+// Flat common space: Mercator (geospatial) or cartesian (OrthographicView). CPU counterparts of
+// project_common_position_to_flat(). Adding a non-flat projection: update the flatten branch in
+// core project.glsl.ts / project.wgsl.ts, isFlatViewport(), and test/render/view-presets.ts.
+
+/** False only for GlobeViewport, whose common space is a sphere. The single globe check in this module. */
+export function isFlatViewport(viewport: Viewport): boolean {
+  return !(viewport instanceof _GlobeViewport);
+}
+
+/** Per-call overrides of the layer's coordinateSystem, coordinateOrigin and modelMatrix */
+export type FlatProjectOptions = {
+  fromCoordinateSystem?: CoordinateSystem;
+  fromCoordinateOrigin?: [number, number, number];
+  modelMatrix?: NumericArray | null;
+};
+
+/**
+ * CPU counterpart of `project_common_position_to_flat(project_position(position))`, relative to
+ * `getFlatCommonOrigin()`. Always pair with the GPU function: a raw `layer.projectPosition()`
+ * disagrees with it under globe or auto-offset.
+ */
+export function projectToFlatCommon(
+  layer: Layer,
+  position: number[],
+  opts: FlatProjectOptions = {}
+): [number, number, number] {
+  // Same resolution as Layer.projectPosition so multi-view setups stay consistent
+  const viewport = getLayerViewport(layer);
+  if (isFlatViewport(viewport)) {
+    return layer.projectPosition(position, opts);
+  }
+  if (getSourceCoordinateSystem(layer, opts) === 'meter-offsets') {
+    return projectGlobeMeterOffsetsToFlatCommon(layer, viewport, position, opts);
+  }
+  return layer.projectPosition(position, {
+    ...opts,
+    viewport: getMercatorReferenceViewport(viewport),
+    autoOffset: false
+  });
+}
+
+/**
+ * Mirrors the shader's GLOBE + METER_OFFSETS path: a linear offset in the tangent plane at the
+ * origin. Do not go through lng/lat; the error grows with the square of the offset (~200 m at 300 km).
+ */
+function projectGlobeMeterOffsetsToFlatCommon(
+  layer: Layer,
+  viewport: Viewport,
+  position: number[],
+  opts: FlatProjectOptions
+): [number, number, number] {
+  const origin = opts.fromCoordinateOrigin ?? layer.props.coordinateOrigin;
+  const modelMatrix = opts.modelMatrix === undefined ? layer.props.modelMatrix : opts.modelMatrix;
+  let [x, y, z = 0] = position;
+  if (modelMatrix) {
+    [x, y, z] = vec4.transformMat4([] as number[], [x, y, z, 1], modelMatrix);
+  }
+  // project.commonOrigin: sphere position of the coordinate origin
+  const originCommon = viewport.projectPosition(origin);
+  // project_get_orientation_matrix(commonOrigin)
+  const uz = vec3.normalize([] as number[], originCommon);
+  const ux = Math.abs(uz[2]) === 1 ? [1, 0, 0] : vec3.normalize([] as number[], [uz[1], -uz[0], 0]);
+  const uy = vec3.cross([] as number[], uz, ux);
+  // enuMatrix * vec3(-x, -y, z) * metersToCommon
+  const displaced = [0, 1, 2].map(
+    i => originCommon[i] + (ux[i] * -x + uy[i] * -y + uz[i] * z) * GLOBE_METERS_TO_COMMON
+  );
+  // project_globe_to_mercator_
+  const lngLatZ = viewport.unprojectPosition(displaced);
+  return MERCATOR_REFERENCE_VIEWPORT.projectPosition(lngLatZ);
+}
+
+/**
+ * Projects `[minX, minY, maxX, maxY]` into flat common bounds. Lng/lat bounds with
+ * `minX - maxX > 180` take the shorter arc across the antimeridian, so `maxX` may exceed TILE_SIZE;
+ * test against them with `project_common_position_to_flat_wrapped()` about the bounds centre.
+ * Otherwise edges are re-ordered, so `[right, top, left, bottom]` input still works.
+ */
+export function projectBoundsToFlatCommon(
+  layer: Layer,
+  bounds: Readonly<[number, number, number, number]>,
+  opts?: FlatProjectOptions
+): Bounds {
+  const a = projectToFlatCommon(layer, [bounds[0], bounds[1], 0], opts);
+  const b = projectToFlatCommon(layer, [bounds[2], bounds[3], 0], opts);
+  if (
+    bounds[0] - bounds[2] > 180 &&
+    getLayerViewport(layer).isGeospatial &&
+    getSourceCoordinateSystem(layer, opts) === 'lnglat'
+  ) {
+    b[0] += TILE_SIZE;
+  }
+  return [Math.min(a[0], b[0]), Math.min(a[1], b[1]), Math.max(a[0], b[0]), Math.max(a[1], b[1])];
+}
+
+function getLayerViewport(layer: Layer): Viewport {
+  return layer.internalState?.viewport || layer.context.viewport;
+}
+
+/** The coordinate system `position` is expressed in, with `default` resolved */
+function getSourceCoordinateSystem(layer: Layer, opts: FlatProjectOptions = {}): CoordinateSystem {
+  const coordinateSystem = opts.fromCoordinateSystem ?? layer.props.coordinateSystem;
+  if (coordinateSystem === 'default') {
+    return getLayerViewport(layer).isGeospatial ? 'lnglat' : 'cartesian';
+  }
+  return coordinateSystem;
+}
+
+/**
+ * Origin of `project_common_position_to_flat()` results: `project.commonOrigin` on flat viewports,
+ * `[0, 0]` under globe, where commonOrigin is a sphere position and must never be re-added.
+ */
+export function getFlatCommonOrigin(
+  projectUniforms: ProjectUniforms,
+  viewport: Viewport
+): [number, number] {
+  return isFlatViewport(viewport)
+    ? [projectUniforms.commonOrigin[0], projectUniforms.commonOrigin[1]]
+    : [0, 0];
+}
+
 /*
  * Compute the union of bounds from multiple layers
  * Returns bounds in CARTESIAN coordinates
@@ -181,6 +309,12 @@ export function getRenderBounds(
     return [0, 0, 1, 1];
   }
 
+  // layerBounds are flat (Mercator) but getViewportBounds() would return sphere coordinates for a
+  // non-flat viewport; the two cannot be intersected. Render the full layer extent instead.
+  if (!isFlatViewport(viewport)) {
+    return layerBounds;
+  }
+
   const viewportBounds = getViewportBounds(viewport, zRange);
   // Expand viewport bounds by 2X. Heurestically chosen to avoid masking
   // errors when mask is partially out of view