@navaramap/three 0.0.0

package/src/material/enhancer/polygon/polygonBaseEnhancer/state.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_BASE_STATE, updateState } from "./state";
+import type { PolygonBaseProps, PolygonBaseState } from "./types";
+
+/**
+ * Helper to create expected base state by merging with defaults.
+ */
+const createExpectedState = (
+  overrides: Partial<PolygonBaseState> = {},
+): PolygonBaseState => ({
+  ...DEFAULT_BASE_STATE,
+  ...overrides,
+});
+
+describe("polygonBaseEnhancer/state", () => {
+  describe("updateState", () => {
+    type TestCase = {
+      name: string;
+      props: PolygonBaseProps;
+      currentState: PolygonBaseState;
+      expected: PolygonBaseState;
+    };
+
+    const testCases: TestCase[] = [
+      {
+        name: "returns default state when given empty props",
+        props: {},
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState(),
+      },
+      {
+        name: "applies all props",
+        props: {
+          useRTE: true, // ignored - useRTE preserves currentState
+          isTexturized: true,
+          clampToGround: true,
+          pickable: true,
+          minMaxHeight: [10, 100],
+          addExtrudedHeight: 50,
+          addHeight: 20,
+          reflectivity: 0.5,
+          roughness: 0.3,
+        },
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState({
+          // useRTE stays false because updateState preserves currentState.useRTE
+          isTexturized: true,
+          clampToGround: true,
+          pickable: true,
+          minMaxHeight: [10, 100],
+          addExtrudedHeight: 50,
+          addHeight: 20,
+          reflectivity: 0.5,
+          roughness: 0.3,
+        }),
+      },
+      {
+        name: "applies height props only",
+        props: {
+          minMaxHeight: [0, 50],
+          addExtrudedHeight: 25,
+          addHeight: 10,
+        },
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState({
+          minMaxHeight: [0, 50],
+          addExtrudedHeight: 25,
+          addHeight: 10,
+        }),
+      },
+    ];
+
+    it.each(testCases)("$name", ({ props, currentState, expected }) => {
+      const result = updateState(props, currentState);
+      expect(result).toEqual(expected);
+    });
+
+    it("preserves useRTE from currentState (immutable after mount)", () => {
+      const stateWithRTE: PolygonBaseState = {
+        ...DEFAULT_BASE_STATE,
+        useRTE: true,
+      };
+      const result = updateState({ useRTE: false }, stateWithRTE);
+      expect(result.useRTE).toBe(true);
+    });
+
+    it("falls back to currentState for missing props", () => {
+      const currentState: PolygonBaseState = {
+        ...DEFAULT_BASE_STATE,
+        clampToGround: true,
+        pickable: true,
+        addHeight: 42,
+      };
+      const result = updateState({ addExtrudedHeight: 10 }, currentState);
+      expect(result.clampToGround).toBe(true);
+      expect(result.pickable).toBe(true);
+      expect(result.addHeight).toBe(42);
+      expect(result.addExtrudedHeight).toBe(10);
+    });
+  });
+});

package/src/material/enhancer/polygon/polygonBaseEnhancer/state.ts

@@ -0,0 +1,92 @@
+import type { PolygonBaseProps, PolygonBaseState } from "./types";
+
+export const DEFAULT_BASE_PROPS: Required<
+  Omit<
+    PolygonBaseProps,
+    "globeNormalTexture" | "batchDataTexture" | "minMaxHeight"
+  >
+> = {
+  color: 0,
+  opacity: 1,
+  transparent: false,
+  wireframe: false,
+  addExtrudedHeight: 0,
+  addHeight: 0,
+  clampToGround: false,
+  isTexturized: false,
+  pickable: false,
+  effectIdsMask: 0,
+  reflectivity: 0,
+  roughness: 0,
+  emissiveColor: 0,
+  emissiveIntensity: 0,
+  useRTE: false,
+  batchColorEnabled: false,
+  useBatchTexture: false,
+  useBatchColorShow: false,
+  useBatchHeight: false,
+  useBatchExtrudedHeight: false,
+};
+
+/** Default state derived from DEFAULT_BASE_PROPS */
+export const DEFAULT_BASE_STATE: PolygonBaseState = {
+  useRTE: DEFAULT_BASE_PROPS.useRTE,
+  isTexturized: DEFAULT_BASE_PROPS.isTexturized,
+  clampToGround: DEFAULT_BASE_PROPS.clampToGround,
+  pickable: DEFAULT_BASE_PROPS.pickable,
+  emissiveColor: DEFAULT_BASE_PROPS.emissiveColor,
+  emissiveIntensity: DEFAULT_BASE_PROPS.emissiveIntensity,
+  effectIdsMask: 0,
+  minMaxHeight: undefined,
+  addExtrudedHeight: DEFAULT_BASE_PROPS.addExtrudedHeight,
+  addHeight: DEFAULT_BASE_PROPS.addHeight,
+  reflectivity: DEFAULT_BASE_PROPS.reflectivity,
+  roughness: DEFAULT_BASE_PROPS.roughness,
+  batchColorEnabled: DEFAULT_BASE_PROPS.batchColorEnabled,
+  useBatchTexture: DEFAULT_BASE_PROPS.useBatchTexture,
+  useBatchColorShow: DEFAULT_BASE_PROPS.useBatchColorShow,
+  useBatchHeight: DEFAULT_BASE_PROPS.useBatchHeight,
+  useBatchExtrudedHeight: DEFAULT_BASE_PROPS.useBatchExtrudedHeight,
+};
+
+/**
+ * Update immutable state from props.
+ * Props override currentState values; missing props fall back to currentState.
+ * Pass DEFAULT_BASE_STATE as currentState for initial mount.
+ *
+ * @param props - The props to apply
+ * @param currentState - The current state to use as fallback (use DEFAULT_BASE_STATE for mount)
+ */
+export const updateState = (
+  props: PolygonBaseProps,
+  currentState: PolygonBaseState,
+): PolygonBaseState => {
+  const isTexturized = props.isTexturized ?? currentState.isTexturized;
+
+  return {
+    // RTE cannot change after mount - always preserve current value
+    useRTE: currentState.useRTE,
+    isTexturized,
+    clampToGround: props.clampToGround ?? currentState.clampToGround,
+    pickable: props.pickable ?? currentState.pickable,
+    emissiveColor: props.emissiveColor ?? currentState.emissiveColor,
+    emissiveIntensity:
+      props.emissiveIntensity ?? currentState.emissiveIntensity,
+    effectIdsMask: props.effectIdsMask ?? currentState.effectIdsMask,
+    minMaxHeight: props.minMaxHeight ?? currentState.minMaxHeight,
+    addExtrudedHeight:
+      props.addExtrudedHeight ?? currentState.addExtrudedHeight,
+    addHeight: props.addHeight ?? currentState.addHeight,
+    reflectivity: props.reflectivity ?? currentState.reflectivity,
+    roughness: props.roughness ?? currentState.roughness,
+    // Batch flags can only transition from false to true, never back
+    batchColorEnabled:
+      props.batchColorEnabled ?? currentState.batchColorEnabled,
+    useBatchTexture: props.useBatchTexture ?? currentState.useBatchTexture,
+    useBatchColorShow:
+      props.useBatchColorShow ?? currentState.useBatchColorShow,
+    useBatchHeight: props.useBatchHeight ?? currentState.useBatchHeight,
+    useBatchExtrudedHeight:
+      props.useBatchExtrudedHeight ?? currentState.useBatchExtrudedHeight,
+  };
+};

package/src/material/enhancer/polygon/polygonBaseEnhancer/types.ts

@@ -0,0 +1,150 @@
+import type { Matrix4, Texture, Vector3 } from "three";
+
+import type { UniformValue } from "../../../types";
+import type { BatchTextureFlags } from "../../batchTexture";
+import type { Mutates } from "../../MaterialEnhancer";
+
+type PolygonBatchTextureFlags = Required<
+  Omit<BatchTextureFlags, "useBatchLineWidth" | "useBatchSize">
+>;
+// Note: opacity is bundled with show in useBatchColorShow
+
+/**
+ * Props for the polygon core enhancer.
+ */
+export type PolygonBaseProps = {
+  // Basic material props
+  color?: number;
+  opacity?: number;
+  transparent?: boolean;
+  wireframe?: boolean;
+
+  // Height/extrusion
+  minMaxHeight?: [number, number];
+  addExtrudedHeight?: number;
+  addHeight?: number;
+
+  // Clamp to ground
+  clampToGround?: boolean;
+  isTexturized?: boolean;
+
+  // Picking
+  pickable?: boolean;
+
+  // Selective Effect
+  effectIdsMask?: number;
+
+  // Reflectivity
+  reflectivity?: number;
+  roughness?: number;
+
+  // Emissive (for selective effects)
+  emissiveColor?: number;
+  emissiveIntensity?: number;
+
+  // External uniforms (passed from CommonUniforms)
+  globeNormalTexture?: UniformValue<Texture | null>;
+
+  // Batch texture
+  batchDataTexture?: UniformValue<Texture | null>;
+
+  // Batch texture state flags - track when batch attributes are being used
+  // When batchColorEnabled is true, material.color is set to white and actual colors come from batch texture
+  batchColorEnabled?: boolean;
+
+  // RTE (Relative To Eye) support
+  useRTE?: boolean;
+} & Partial<PolygonBatchTextureFlags>;
+
+/**
+ * Immutable state for the polygon base enhancer.
+ * This state is always replaced as a whole (never mutated).
+ * Returned directly via states() - refresh after updates.
+ */
+export type PolygonBaseState = Readonly<
+  {
+    useRTE: boolean;
+    isTexturized: boolean;
+    clampToGround: boolean;
+    pickable: boolean;
+    emissiveColor: number;
+    emissiveIntensity: number;
+    effectIdsMask: number;
+    minMaxHeight: [number, number] | undefined;
+    addExtrudedHeight: number;
+    addHeight: number;
+    reflectivity: number;
+    roughness: number;
+    // Batch texture state - when true, material.color is white and colors come from batch texture
+    batchColorEnabled: boolean;
+  } & PolygonBatchTextureFlags
+>;
+
+/**
+ * Mutable references (uniforms) for the polygon base enhancer.
+ *
+ * These are shared references with shader.uniforms and can be mutated directly
+ * for efficient GPU uniform updates without shader recompilation.
+ * Internal type - not exposed externally.
+ */
+export type PolygonBaseRefs = {
+  // Core uniforms
+  uMinMaxHeight: UniformValue<[number, number] | undefined>;
+  uAddExtrudedHeight: UniformValue<number>;
+  uAddHeight: UniformValue<number>;
+  uClampToGround: UniformValue<boolean>;
+  nvr_uPickable: UniformValue<number>;
+  uEffectIdsMask: UniformValue<number>;
+  uEmissiveIntensity: UniformValue<number>;
+  uIsTexturized: UniformValue<boolean>;
+  reflectivity: UniformValue<number>;
+  roughness: UniformValue<number>;
+
+  // Optional uniforms
+  batchDataTexture?: UniformValue<Texture | null>;
+  uGlobeNormal?: UniformValue<Texture | null>;
+
+  // RTE uniforms (only present if useRTE is true)
+  modelViewMatrixRTE?: UniformValue<Matrix4>;
+  u_cameraPositionHigh?: UniformValue<Vector3>;
+  u_cameraPositionLow?: UniformValue<Vector3>;
+};
+
+export type PolygonBaseUniforms = Partial<PolygonBaseRefs>;
+
+/**
+ * Mutation functions for the polygon base enhancer.
+ * Includes `update(state)` to sync refs from state, plus additional methods.
+ */
+export type PolygonBaseMutates = Mutates<
+  PolygonBaseState,
+  PolygonBaseUniforms,
+  {
+    /**
+     * Update RTE (Relative-To-Eye) uniforms for high-precision rendering.
+     * Call this per-frame to update the model-view matrix and camera position.
+     * Does nothing if RTE is not enabled.
+     *
+     * @param modelViewMatrixRTE - The model-view matrix in RTE coordinates
+     * @param cameraPositionHigh - High-precision component of camera position
+     * @param cameraPositionLow - Low-precision component of camera position
+     * @param state - PolygonBaseState
+     */
+    updateRteUniforms: (
+      modelViewMatrixRTE: Matrix4,
+      cameraPositionHigh: Vector3,
+      cameraPositionLow: Vector3,
+      state: PolygonBaseState,
+    ) => void;
+    /**
+     * Set the batch data texture ref.
+     * This is needed because batchDataTexture is an external ref passed via props.
+     */
+    setBatchDataTexture: (texture: UniformValue<Texture | null>) => void;
+    /**
+     * Set the globe normal texture ref.
+     * This is needed because globeNormalTexture is an external ref passed via props.
+     */
+    setGlobeNormalTexture: (texture: UniformValue<Texture | null>) => void;
+  }
+>;

package/src/material/enhancer/polygon/polygonMaterialEnhancer.ts

@@ -0,0 +1,97 @@
+/**
+ * Polygon Material Enhancer - Composed from Base + Water enhancers
+ *
+ * This module provides the full polygon material functionality by using
+ * the water enhancer factory which internally composes with the base enhancer.
+ */
+
+import type { MaterialEnhancer } from "../MaterialEnhancer";
+
+import {
+  createPolygonBaseEnhancer,
+  type PolygonBaseMutates,
+  type PolygonBaseProps,
+  type PolygonBaseState,
+} from "./polygonBaseEnhancer";
+import {
+  createPolygonWaterEnhancer,
+  type PolygonWaterCombinedMutates,
+  type PolygonWaterCombinedStates,
+  type PolygonWaterProps,
+  type PolygonWaterState,
+  type WaterOnlyProps,
+  type AVAILABLE_SHADERS as WATER_AVAILABLE_SHADERS,
+  type SupportedMaterial as WaterSupportedMaterial,
+} from "./polygonWaterEnhancer";
+
+/**
+ * Combined props for the polygon material enhancer.
+ * Props are explicitly separated into base and water sections for clarity.
+ */
+export type PolygonMaterialProps = {
+  base?: PolygonBaseProps;
+  water?: WaterOnlyProps;
+};
+
+// Shaders this enhancer supports
+type AVAILABLE_SHADERS = typeof WATER_AVAILABLE_SHADERS;
+type SupportedMaterial = WaterSupportedMaterial;
+
+/**
+ * Factory function to create the polygon material enhancer.
+ *
+ * This creates a new enhancer instance with its own internal state.
+ *
+ * @param material - The Three.js material to enhance
+ *
+ * @example
+ * ```typescript
+ * const material = new MeshLambertMaterial();
+ * const enhancer = createPolygonMaterialEnhancer(material);
+ *
+ * // Mount with separated base and water props
+ * enhancer.mount({
+ *   base: { color: 0xff0000, useRTE: true },
+ *   water: { water: true, waterScaleNormal: 0.5 },
+ * });
+ *
+ * // Get state directly via states() - refresh after updates
+ * const { base, water } = enhancer.states();
+ *
+ * // Update RTE uniforms per-frame via mutates()
+ * if (base.useRTE) {
+ *   const { base: baseMutates } = enhancer.mutates();
+ *   baseMutates.updateRteUniforms(modelViewMatrix, cameraHigh, cameraLow);
+ * }
+ *
+ * // Update props (then call states() again to get fresh state)
+ * enhancer.update({ base: { addHeight: 100 } });
+ *
+ * // Use transformShader for onBeforeCompile
+ * material.onBeforeCompile = enhancer.transformShader;
+ * ```
+ */
+export function createPolygonMaterialEnhancer(
+  material: SupportedMaterial,
+): MaterialEnhancer<
+  SupportedMaterial,
+  PolygonMaterialProps,
+  PolygonWaterCombinedStates,
+  PolygonWaterCombinedMutates,
+  AVAILABLE_SHADERS
+> {
+  const baseEnhancer = createPolygonBaseEnhancer(material);
+  return createPolygonWaterEnhancer(baseEnhancer);
+}
+
+// Re-export types for convenience
+export type {
+  PolygonBaseMutates,
+  PolygonBaseProps,
+  PolygonBaseState,
+  PolygonWaterCombinedMutates,
+  PolygonWaterCombinedStates,
+  PolygonWaterProps,
+  PolygonWaterState,
+  WaterOnlyProps,
+};

package/src/material/enhancer/polygon/polygonWaterEnhancer/index.test.ts

@@ -0,0 +1,72 @@
+import { MeshLambertMaterial } from "three";
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { createPolygonBaseEnhancer } from "../polygonBaseEnhancer";
+
+import { createPolygonWaterEnhancer } from ".";
+
+describe("polygonWaterEnhancer", () => {
+  let enhancer: ReturnType<typeof createPolygonWaterEnhancer>;
+
+  beforeEach(() => {
+    const baseEnhancer = createPolygonBaseEnhancer(new MeshLambertMaterial());
+    enhancer = createPolygonWaterEnhancer(baseEnhancer);
+  });
+
+  describe("lifecycle", () => {
+    it("states() should throw if called before mount", () => {
+      const freshMaterial = new MeshLambertMaterial();
+      const baseEnhancer = createPolygonBaseEnhancer(freshMaterial);
+      const freshEnhancer = createPolygonWaterEnhancer(baseEnhancer);
+
+      expect(() => freshEnhancer.states()).toThrow(
+        "mount() must be called before states",
+      );
+    });
+  });
+
+  describe("programCacheKey", () => {
+    it("should combine base cache key with water-specific state", () => {
+      enhancer.mount({
+        base: { useBatchTexture: true },
+        water: { water: true },
+      });
+
+      const cacheKey = enhancer.programCacheKey();
+
+      // Should contain both base and water cache keys
+      expect(cacheKey).toContain('"useBatchTexture":true');
+      expect(cacheKey).toContain('"useWater":true');
+    });
+
+    it("should return different cache keys when useWater differs", () => {
+      enhancer.mount({ water: { water: false } });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createPolygonWaterEnhancer(
+        createPolygonBaseEnhancer(new MeshLambertMaterial()),
+      );
+      enhancer2.mount({ water: { water: true } });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).not.toBe(cacheKey2);
+    });
+
+    it("should return same cache key for same shader-affecting states with different non-affecting states", () => {
+      enhancer.mount({
+        water: { water: true, waterSpeed: 1.0, shininess: 10 },
+      });
+      const cacheKey1 = enhancer.programCacheKey();
+
+      const enhancer2 = createPolygonWaterEnhancer(
+        createPolygonBaseEnhancer(new MeshLambertMaterial()),
+      );
+      enhancer2.mount({
+        water: { water: true, waterSpeed: 5.0, shininess: 50 },
+      });
+      const cacheKey2 = enhancer2.programCacheKey();
+
+      expect(cacheKey1).toBe(cacheKey2);
+    });
+  });
+});

package/src/material/enhancer/polygon/polygonWaterEnhancer/index.ts

@@ -0,0 +1,164 @@
+import { defaults } from "lodash-es";
+import type { WebGLProgramParametersWithUniforms } from "three";
+import invariant from "tiny-invariant";
+
+import type { MaterialEnhancer } from "../../MaterialEnhancer";
+import type {
+  PolygonBaseMutates,
+  PolygonBaseProps,
+  PolygonBaseState,
+  SupportedMaterial,
+} from "../polygonBaseEnhancer";
+
+import {
+  AVAILABLE_SHADERS,
+  type SupportedMaterial as WaterSupportedMaterial,
+} from "./material";
+import { applyWaterMaterialConfig } from "./material";
+import { createWaterMutates } from "./mutates";
+import { transformWaterShader } from "./shader";
+import {
+  DEFAULT_WATER_PROPS,
+  DEFAULT_WATER_STATE,
+  updateWaterState,
+} from "./state";
+import type {
+  PolygonWaterCombinedMutates,
+  PolygonWaterCombinedStates,
+  PolygonWaterProps,
+  PolygonWaterState,
+  WaterMutates,
+  WaterOnlyProps,
+} from "./types";
+
+/**
+ * Factory function to create a polygon water enhancer.
+ *
+ * @param baseEnhancer - The base polygon enhancer to compose with (material is obtained from this)
+ * @returns A new MaterialEnhancer with combined base + water functionality
+ */
+export function createPolygonWaterEnhancer(
+  baseEnhancer: MaterialEnhancer<
+    SupportedMaterial,
+    PolygonBaseProps,
+    PolygonBaseState,
+    PolygonBaseMutates,
+    typeof AVAILABLE_SHADERS
+  >,
+): MaterialEnhancer<
+  WaterSupportedMaterial,
+  PolygonWaterProps,
+  PolygonWaterCombinedStates,
+  PolygonWaterCombinedMutates,
+  typeof AVAILABLE_SHADERS
+> {
+  const { material } = baseEnhancer;
+  // Internal state - immutable, always replaced as a whole
+  let state: PolygonWaterState | null = null;
+  // Internal mutates object (refs are hidden inside)
+  let mutates: WaterMutates | null = null;
+
+  return {
+    material: material as WaterSupportedMaterial,
+    availableShaders: AVAILABLE_SHADERS,
+
+    transformShader: (shader: WebGLProgramParametersWithUniforms): void => {
+      invariant(
+        state && mutates,
+        "mount() must be called before transformShader",
+      );
+      // First apply base transformations
+      baseEnhancer.transformShader(shader);
+      // Then apply water transformations
+      transformWaterShader(shader, state, mutates);
+    },
+
+    mount: (props: PolygonWaterProps): void => {
+      // Mount base enhancer first with base props
+      baseEnhancer.mount(props.base ?? {});
+
+      // Initialize water state and mutates with water props
+      const waterProps = props.water ?? {};
+      const mergedWaterProps = defaults({}, waterProps, DEFAULT_WATER_PROPS);
+      state = updateWaterState(mergedWaterProps, DEFAULT_WATER_STATE);
+      // Create mutates (refs are created inside with default values)
+      mutates = createWaterMutates();
+      mutates.update(state);
+      // Handle external ref (timeUniform identity doesn't change after mount)
+      if (waterProps.timeUniform) {
+        mutates.setTimeUniform(waterProps.timeUniform);
+      }
+
+      // Apply material configuration (side effect)
+      const { isTexturized } = baseEnhancer.states();
+      applyWaterMaterialConfig(
+        material as WaterSupportedMaterial,
+        state,
+        isTexturized,
+        false,
+      );
+    },
+
+    update: (props: PolygonWaterProps): void => {
+      // Update base enhancer first with base props
+      if (props.base) {
+        baseEnhancer.update(props.base);
+      }
+
+      invariant(state && mutates, "mount() must be called before update");
+
+      // Update water state and refs with water props
+      if (props.water) {
+        const prevUseWater = state.useWater;
+        state = updateWaterState(props.water, state);
+        mutates.update(state);
+        // Handle external ref (timeUniform identity doesn't change, only set once)
+        if (props.water.timeUniform) {
+          mutates.setTimeUniform(props.water.timeUniform);
+        }
+
+        // Apply material configuration (side effect)
+        const { isTexturized } = baseEnhancer.states();
+        applyWaterMaterialConfig(material, state, isTexturized, prevUseWater);
+      }
+    },
+
+    states: (): PolygonWaterCombinedStates => {
+      invariant(state, "mount() must be called before states");
+      return {
+        base: baseEnhancer.states(),
+        water: state,
+      };
+    },
+
+    mutates: (): PolygonWaterCombinedMutates => {
+      invariant(mutates, "mount() must be called before mutates");
+      return {
+        base: baseEnhancer.mutates(),
+        water: mutates,
+      };
+    },
+
+    programCacheKey: (): string => {
+      invariant(state, "mount() must be called before programCacheKey");
+      // Combine base cache key with water-specific state
+      return (
+        baseEnhancer.programCacheKey() +
+        JSON.stringify({
+          useWater: state.useWater,
+        })
+      );
+    },
+  };
+}
+
+// Re-export public types
+export type {
+  PolygonWaterCombinedMutates,
+  PolygonWaterCombinedStates,
+  PolygonWaterProps,
+  PolygonWaterState,
+  WaterOnlyProps,
+  AVAILABLE_SHADERS,
+  SupportedMaterial,
+};