@navaramap/three 0.0.0

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/index.ts

@@ -0,0 +1,134 @@
+import { defaults } from "lodash-es";
+import type { WebGLProgramParametersWithUniforms } from "three";
+import invariant from "tiny-invariant";
+
+import type { MaterialEnhancer } from "../../MaterialEnhancer";
+
+import {
+  AVAILABLE_SHADERS,
+  type SupportedMaterial,
+  updateMaterialProps,
+} from "./material";
+import { createBaseMutates } from "./mutates";
+import { transformShader } from "./shader";
+import { DEFAULT_BASE_PROPS, DEFAULT_BASE_STATE, updateState } from "./state";
+import type {
+  InstancedSpriteBaseMutates,
+  InstancedSpriteBaseProps,
+  InstancedSpriteBaseState,
+} from "./types";
+
+/**
+ * Factory function to create an instancedSprite base enhancer.
+ *
+ * This enhancer handles:
+ * - Scale, center, sizeInMeters, offsetDepth
+ * - Alpha test for billboard mode
+ * - Picking
+ * - RTE (Relative-To-Eye) support for high-precision coordinates
+ * - Billboard mode with texture array
+ *
+ * Supports ShaderMaterial with custom instancedSprite shaders.
+ *
+ * @param material - The Three.js ShaderMaterial to enhance
+ */
+export function createInstancedSpriteBaseEnhancer(
+  material: SupportedMaterial,
+): MaterialEnhancer<
+  SupportedMaterial,
+  InstancedSpriteBaseProps,
+  InstancedSpriteBaseState,
+  InstancedSpriteBaseMutates,
+  typeof AVAILABLE_SHADERS
+> {
+  // Internal state - immutable, always replaced as a whole
+  let state: InstancedSpriteBaseState | null = null;
+  // Internal mutates object (refs are hidden inside)
+  let mutates: InstancedSpriteBaseMutates | null = null;
+
+  return {
+    material,
+    availableShaders: AVAILABLE_SHADERS,
+
+    transformShader: (shader: WebGLProgramParametersWithUniforms): void => {
+      invariant(
+        state && mutates,
+        "mount() must be called before transformShader",
+      );
+      transformShader(shader, state, mutates, material);
+    },
+
+    mount: (props: InstancedSpriteBaseProps): void => {
+      const mergedProps = defaults({}, props, DEFAULT_BASE_PROPS);
+      // Create initial state with immutable fields from props
+      const initialState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: mergedProps.useRTE,
+        billboard: mergedProps.billboard,
+      };
+      state = updateState(mergedProps, initialState);
+      // Create mutates (refs are created inside with default values)
+      mutates = createBaseMutates(
+        mergedProps.useRTE,
+        mergedProps.billboard,
+        mergedProps.rtcCenter,
+      );
+      mutates.update(state);
+
+      // Set texture external ref if provided
+      if (props.texture) {
+        mutates.setTexture(props.texture);
+      }
+
+      updateMaterialProps(material, mergedProps);
+    },
+
+    update: (props: InstancedSpriteBaseProps): void => {
+      invariant(state && mutates, "mount() must be called before update");
+
+      state = updateState(props, state);
+      mutates.update(state);
+
+      if (props.texture) {
+        mutates.setTexture(props.texture);
+      }
+
+      updateMaterialProps(material, props);
+    },
+
+    states: (): InstancedSpriteBaseState => {
+      invariant(state, "mount() must be called before states");
+      return state;
+    },
+
+    mutates: (): InstancedSpriteBaseMutates => {
+      invariant(mutates, "mount() must be called before mutates");
+      return mutates;
+    },
+
+    programCacheKey: (): string => {
+      invariant(state, "mount() must be called before programCacheKey");
+      return JSON.stringify({
+        useRTE: state.useRTE,
+        billboard: state.billboard,
+        userDataDefines: material.userData?.defines ?? undefined,
+      });
+    },
+  };
+}
+
+// Re-export public types
+export type {
+  InstancedSpriteBaseMutates,
+  InstancedSpriteBaseProps,
+  InstancedSpriteBaseState,
+};
+
+// Re-export SupportedMaterial for use by composing enhancers
+export type { SupportedMaterial } from "./material";
+
+// Re-export marker types for composing enhancers
+export {
+  INSTANCED_SPRITE_BASE_SHADER_MARKERS,
+  createInstancedSpriteBaseShaderReplacer,
+} from "./markers";

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/markers.ts

@@ -0,0 +1,21 @@
+import type { ShaderMarkers } from "../../ShaderReplacer";
+import { createShaderReplacer } from "../../ShaderReplacer";
+
+/**
+ * Shader markers for the instancedSprite base enhancer.
+ * These markers are placed in the shader code to allow composing enhancers to inject their own code.
+ */
+export const INSTANCED_SPRITE_BASE_SHADER_MARKERS = {
+  vertex: {},
+  fragment: {},
+} as const satisfies ShaderMarkers;
+
+/**
+ * Factory function to create a ShaderReplacer restricted to instancedSprite base markers.
+ * Used by composing enhancers to safely modify shaders.
+ */
+export function createInstancedSpriteBaseShaderReplacer(source: string) {
+  return createShaderReplacer<typeof INSTANCED_SPRITE_BASE_SHADER_MARKERS>(
+    source,
+  );
+}

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/material.ts

@@ -0,0 +1,32 @@
+import { ShaderMaterial } from "three";
+
+import type { ShaderName } from "../../MaterialEnhancer";
+
+import type { InstancedSpriteBaseProps } from "./types";
+
+/**
+ * Shaders that the instancedSprite base enhancer supports.
+ * InstancedSprites use ShaderMaterial with custom shaders.
+ */
+export const AVAILABLE_SHADERS = ["shader"] satisfies ShaderName[];
+
+/**
+ * Material types that the instancedSprite base enhancer supports.
+ */
+export type SupportedMaterial = ShaderMaterial;
+
+/**
+ * Update material properties that affect the Three.js material directly.
+ * These properties are not handled by shader uniforms.
+ */
+export function updateMaterialProps(
+  material: SupportedMaterial,
+  props: InstancedSpriteBaseProps,
+): void {
+  if (props.transparent !== undefined) {
+    material.transparent = props.transparent;
+  }
+  if (props.depthTest !== undefined) {
+    material.depthTest = props.depthTest;
+  }
+}

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/mutates.test.ts

@@ -0,0 +1,277 @@
+import { degreeToRadian } from "@navaramap/three_api";
+import { Matrix4, type Texture } from "three";
+import { describe, expect, it, vi } from "vitest";
+
+import type { ShaderUniforms } from "../../MaterialEnhancer";
+
+import { createBaseMutates } from "./mutates";
+import { DEFAULT_BASE_STATE } from "./state";
+import type { InstancedSpriteBaseState } from "./types";
+
+vi.mock("@navaramap/three_api", () => ({
+  degreeToRadian: (degree: number) => (degree * Math.PI) / 180,
+}));
+
+vi.mock("@navaramap/engine-api", () => ({
+  encodePosition: (_x: number, _y: number, _z: number) => ({
+    high: { x: 1000, y: 2000, z: 3000 },
+    low: { x: 0.5, y: 0.25, z: 0.125 },
+  }),
+}));
+
+describe("instancedSpriteBaseEnhancer/mutates", () => {
+  describe("update syncs refs from state", () => {
+    it("should sync core refs from state", () => {
+      const state: InstancedSpriteBaseState = {
+        ...DEFAULT_BASE_STATE,
+        scale: 50,
+        center: [0.5, 0.5],
+        sizeInMeters: false,
+        offsetDepth: false,
+        alphaTest: 0.3,
+        pickable: true,
+        atlasSize: [512, 256] as [number, number],
+      };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uScale?.value).toBe(50);
+      expect(uniforms.uCenter?.value.x).toBe(0.5);
+      expect(uniforms.uCenter?.value.y).toBe(0.5);
+      expect(uniforms.uSizeInMeters?.value).toBe(false);
+      expect(uniforms.uOffsetDepth?.value).toBe(false);
+      expect(uniforms.uAlphaTest?.value).toBe(0.3);
+      expect(uniforms.nvr_uPickable?.value).toBe(1.0);
+      expect(uniforms.uAtlasSize?.value.x).toBe(512);
+      expect(uniforms.uAtlasSize?.value.y).toBe(256);
+    });
+  });
+
+  describe("RTC center", () => {
+    it("should initialize uRTCCenter from constructor args", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false, [10, 20, 30]);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTCCenter?.value.x).toBe(10);
+      expect(uniforms.uRTCCenter?.value.y).toBe(20);
+      expect(uniforms.uRTCCenter?.value.z).toBe(30);
+    });
+  });
+
+  describe("billboard texture ref", () => {
+    it("should assign uTexture to uniforms when billboard=true", () => {
+      const state: InstancedSpriteBaseState = {
+        ...DEFAULT_BASE_STATE,
+        billboard: true,
+      };
+      const mutates = createBaseMutates(false, true);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uTexture).toBeDefined();
+      expect(uniforms.uTexture?.value).toBeNull();
+    });
+
+    it("should not assign uTexture to uniforms when billboard=false", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uTexture).toBeUndefined();
+    });
+
+    it("should update uTexture value without replacing uniform ref", () => {
+      const state: InstancedSpriteBaseState = {
+        ...DEFAULT_BASE_STATE,
+        billboard: true,
+      };
+      const mutates = createBaseMutates(false, true);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+      const initialTextureUniform = uniforms.uTexture;
+      expect(initialTextureUniform).toBeDefined();
+
+      const nextTexture = {
+        image: {
+          width: 1,
+          height: 1,
+          data: new Uint8Array([0, 0, 0, 0]),
+        },
+      } as unknown as Texture;
+
+      mutates.setTexture({ value: nextTexture });
+
+      expect(uniforms.uTexture).toBe(initialTextureUniform);
+      expect(uniforms.uTexture?.value).toBe(nextTexture);
+    });
+  });
+
+  describe("updateRteUniforms", () => {
+    it("should update RTE eye uniforms when useRTE=true", () => {
+      const state: InstancedSpriteBaseState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: true,
+      };
+      const mutates = createBaseMutates(true, false);
+      mutates.update(state);
+
+      // Call updateRteUniforms with some camera position
+      mutates.updateRteUniforms(1000, 2000, 3000, state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      // encodePosition splits into high/low, verify they are set (not zero)
+      const eyeHigh = uniforms.uEyeRTEHigh?.value;
+      const eyeLow = uniforms.uEyeRTELow?.value;
+      expect(eyeHigh).toBeDefined();
+      expect(eyeLow).toBeDefined();
+    });
+
+    it("should do nothing when useRTE=false", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      mutates.updateRteUniforms(1000, 2000, 3000, state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      // Eye uniforms should remain at default (0, 0, 0)
+      expect(uniforms.uEyeRTEHigh?.value.x).toBe(0);
+      expect(uniforms.uEyeRTEHigh?.value.y).toBe(0);
+      expect(uniforms.uEyeRTEHigh?.value.z).toBe(0);
+    });
+  });
+
+  describe("updateRtcUniforms", () => {
+    it("should transform the RTC center into view space when useRTE=false", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      // RTC center at a large ECEF-scale coordinate.
+      const mutates = createBaseMutates(false, false, [6_400_000, 0, 0]);
+      mutates.update(state);
+
+      // View matrix that translates the world by -6,400,000 on X, so the
+      // center lands near the origin (small, precise value) in view space.
+      const viewInverse = new Matrix4().makeTranslation(-6_400_000, 0, 0);
+      mutates.updateRtcUniforms(viewInverse, state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uRTCCenterView?.value.x).toBeCloseTo(0, 3);
+      expect(uniforms.uRTCCenterView?.value.y).toBeCloseTo(0, 3);
+      expect(uniforms.uRTCCenterView?.value.z).toBeCloseTo(0, 3);
+    });
+
+    it("should do nothing when useRTE=true", () => {
+      const state: InstancedSpriteBaseState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: true,
+      };
+      const mutates = createBaseMutates(true, false, [6_400_000, 0, 0]);
+      mutates.update(state);
+
+      mutates.updateRtcUniforms(
+        new Matrix4().makeTranslation(-6_400_000, 0, 0),
+        state,
+      );
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      // Left at the default; the RTC path is not used under RTE.
+      expect(uniforms.uRTCCenterView?.value.x).toBe(0);
+    });
+  });
+
+  describe("updateFarPlane", () => {
+    it("should update uFarPlane value", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      mutates.updateFarPlane(1000);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uFarPlane?.value).toBe(1000);
+    });
+  });
+
+  describe("updateFovRad", () => {
+    it("should update uFovRad value", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      mutates.updateFovRad(degreeToRadian(75));
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uFovRad?.value).toBe(degreeToRadian(75));
+    });
+
+    it("should not replace the uniform ref", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+      const initialRef = uniforms.uFovRad;
+
+      mutates.updateFovRad(degreeToRadian(90));
+
+      expect(uniforms.uFovRad).toBe(initialRef);
+      expect(uniforms.uFovRad?.value).toBe(degreeToRadian(90));
+    });
+  });
+
+  describe("updateScreenHeightPx", () => {
+    it("should update uScreenHeightPx value", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      mutates.updateScreenHeightPx(720);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uScreenHeightPx?.value).toBe(720);
+    });
+
+    it("should not replace the uniform ref", () => {
+      const state: InstancedSpriteBaseState = { ...DEFAULT_BASE_STATE };
+      const mutates = createBaseMutates(false, false);
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+      const initialRef = uniforms.uScreenHeightPx;
+
+      mutates.updateScreenHeightPx(1440);
+
+      expect(uniforms.uScreenHeightPx).toBe(initialRef);
+      expect(uniforms.uScreenHeightPx?.value).toBe(1440);
+    });
+  });
+});

package/src/material/enhancer/instancedSprite/instancedSpriteBaseEnhancer/mutates.ts

@@ -0,0 +1,151 @@
+import { encodePosition } from "@navaramap/engine-api";
+import {
+  type Matrix4,
+  type Texture,
+  Vector2 as ThreeVector2,
+  Vector3 as ThreeVector3,
+} from "three";
+
+import type { UniformValue } from "../../../types";
+
+import type {
+  InstancedSpriteBaseMutates,
+  InstancedSpriteBaseRefs,
+  InstancedSpriteBaseState,
+} from "./types";
+
+/**
+ * Create mutation functions for the instancedSprite base enhancer.
+ * Refs are created internally and captured via closure.
+ *
+ * @param _useRTE - Whether RTE is enabled (reserved for API consistency)
+ * @param billboard - Whether billboard mode is enabled (determines if texture ref is created)
+ * @param rtcCenter - The RTC center position [x, y, z]
+ */
+export const createBaseMutates = (
+  _useRTE: boolean,
+  billboard: boolean,
+  rtcCenter?: [number, number, number],
+): InstancedSpriteBaseMutates => {
+  const refs: InstancedSpriteBaseRefs = {
+    uRTCCenter: {
+      value: new ThreeVector3(
+        rtcCenter?.[0] ?? 0,
+        rtcCenter?.[1] ?? 0,
+        rtcCenter?.[2] ?? 0,
+      ),
+    },
+    uRTCCenterView: { value: new ThreeVector3(0, 0, 0) },
+    uEyeRTELow: { value: new ThreeVector3(0, 0, 0) },
+    uEyeRTEHigh: { value: new ThreeVector3(0, 0, 0) },
+    uScale: { value: 100.0 },
+    uCenter: { value: new ThreeVector2(0, 0) },
+    uSizeInMeters: { value: true },
+    uOffsetDepth: { value: true },
+    uAlphaTest: { value: 0.0 },
+    uFarPlane: { value: 0.0 },
+    uAtlasSize: { value: new ThreeVector2(1, 1) },
+    nvr_uPickable: { value: 0.0 },
+    uEffectIdsMask: { value: 0 },
+    uEmissiveColor: { value: new ThreeVector3(0, 0, 0) },
+    uEmissiveIntensity: { value: 0 },
+    uFovRad: { value: 1.0 },
+    uScreenHeightPx: { value: 1080 },
+  };
+
+  // Conditionally create texture ref for billboard mode
+  if (billboard) {
+    refs.uTexture = { value: null };
+  }
+
+  return {
+    update: (state: InstancedSpriteBaseState) => {
+      refs.uScale.value = state.scale;
+      refs.uCenter.value.set(state.center[0], state.center[1]);
+      refs.uSizeInMeters.value = state.sizeInMeters;
+      refs.uOffsetDepth.value = state.offsetDepth;
+      refs.uAlphaTest.value = state.alphaTest;
+      refs.uAtlasSize.value.set(state.atlasSize[0], state.atlasSize[1]);
+      refs.nvr_uPickable.value = state.pickable ? 1.0 : 0.0;
+      refs.uEffectIdsMask.value = state.effectIdsMask;
+      const c = state.emissiveColor;
+      refs.uEmissiveColor.value.set(
+        ((c >> 16) & 0xff) / 255,
+        ((c >> 8) & 0xff) / 255,
+        (c & 0xff) / 255,
+      );
+      refs.uEmissiveIntensity.value = state.emissiveIntensity;
+    },
+
+    updateUniforms: (uniforms) => {
+      uniforms.uRTCCenter = refs.uRTCCenter;
+      uniforms.uRTCCenterView = refs.uRTCCenterView;
+      uniforms.uEyeRTELow = refs.uEyeRTELow;
+      uniforms.uEyeRTEHigh = refs.uEyeRTEHigh;
+      uniforms.uScale = refs.uScale;
+      uniforms.uCenter = refs.uCenter;
+      uniforms.uSizeInMeters = refs.uSizeInMeters;
+      uniforms.uOffsetDepth = refs.uOffsetDepth;
+      uniforms.uAlphaTest = refs.uAlphaTest;
+      uniforms.uFarPlane = refs.uFarPlane;
+      uniforms.uAtlasSize = refs.uAtlasSize;
+      uniforms.uFovRad = refs.uFovRad;
+      uniforms.uScreenHeightPx = refs.uScreenHeightPx;
+      uniforms.nvr_uPickable = refs.nvr_uPickable;
+      uniforms.uEffectIdsMask = refs.uEffectIdsMask;
+      uniforms.uEmissiveColor = refs.uEmissiveColor;
+      uniforms.uEmissiveIntensity = refs.uEmissiveIntensity;
+
+      if (refs.uTexture) {
+        uniforms.uTexture = refs.uTexture;
+      }
+    },
+
+    updateRteUniforms: (
+      cameraX: number,
+      cameraY: number,
+      cameraZ: number,
+      state: InstancedSpriteBaseState,
+    ) => {
+      if (!state.useRTE) return;
+      const encoded = encodePosition(cameraX, cameraY, cameraZ);
+      refs.uEyeRTELow.value.set(encoded.low.x, encoded.low.y, encoded.low.z);
+      refs.uEyeRTEHigh.value.set(
+        encoded.high.x,
+        encoded.high.y,
+        encoded.high.z,
+      );
+    },
+
+    updateRtcUniforms: (
+      viewMatrix: Matrix4,
+      state: InstancedSpriteBaseState,
+    ) => {
+      if (state.useRTE) return;
+      // Transform the RTC center into view space here (JS numbers are float64),
+      // so the shader receives a small, precise value instead of doing
+      // `viewMatrix * uRTCCenter` where both operands are ~6.4e6 in float32.
+      refs.uRTCCenterView.value
+        .copy(refs.uRTCCenter.value)
+        .applyMatrix4(viewMatrix);
+    },
+
+    updateFarPlane: (far: number) => {
+      refs.uFarPlane.value = far;
+    },
+
+    updateFovRad: (fovRad: number) => {
+      refs.uFovRad.value = fovRad;
+    },
+
+    updateScreenHeightPx: (height: number) => {
+      refs.uScreenHeightPx.value = height;
+    },
+
+    setTexture: (texture: UniformValue<Texture | null>) => {
+      if (refs.uTexture) {
+        refs.uTexture.value = texture.value;
+      }
+    },
+  };
+};