@navaramap/three 0.0.0

package/src/material/enhancer/model/modelBaseEnhancer/index.ts

@@ -0,0 +1,110 @@
+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 } from "./material";
+import { updateMaterialProps } from "./material";
+import { createBaseMutates } from "./mutates";
+import { transformShader } from "./shader";
+import { DEFAULT_BASE_PROPS, DEFAULT_BASE_STATE, updateState } from "./state";
+import type { ModelBaseMutates, ModelBaseProps, ModelBaseState } from "./types";
+
+/**
+ * Factory function to create a model base enhancer.
+ *
+ * This enhancer handles:
+ * - Basic material properties (color, metalness, roughness, emissive)
+ * - Height (addHeight uniform)
+ * - Picking
+ * - Batch texture support
+ * - SelectiveEffect uniforms (effectIdsMask, uEmissiveIntensity) and emissive/emissiveIntensity material syncing
+ * - Shadow map depth shader
+ *
+ * Supports Standard and Physical materials.
+ *
+ * @param material - The Three.js material to enhance
+ */
+export function createModelBaseEnhancer(
+  material: SupportedMaterial,
+): MaterialEnhancer<
+  SupportedMaterial,
+  ModelBaseProps,
+  ModelBaseState,
+  ModelBaseMutates,
+  typeof AVAILABLE_SHADERS
+> {
+  // Internal state - immutable, always replaced as a whole
+  let state: ModelBaseState | null = null;
+  // Internal mutates object (refs are hidden inside)
+  let mutates: ModelBaseMutates | 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: ModelBaseProps): void => {
+      const mergedProps = defaults({}, props, DEFAULT_BASE_PROPS);
+      state = updateState(mergedProps, DEFAULT_BASE_STATE);
+      // Create mutates (refs are created inside with default values)
+      mutates = createBaseMutates();
+      mutates.update(state);
+      // Handle external refs that are passed through props
+      if (props.batchDataTexture) {
+        mutates.setBatchDataTexture(props.batchDataTexture);
+      }
+      updateMaterialProps(material, mergedProps);
+    },
+
+    update: (props: ModelBaseProps): void => {
+      invariant(state && mutates, "mount() must be called before update");
+      state = updateState(props, state);
+      mutates.update(state);
+      // Handle external refs that are passed through props
+      if (props.batchDataTexture) {
+        mutates.setBatchDataTexture(props.batchDataTexture);
+      }
+      updateMaterialProps(material, props);
+    },
+
+    states: (): ModelBaseState => {
+      invariant(state, "mount() must be called before states");
+      return state;
+    },
+
+    mutates: (): ModelBaseMutates => {
+      invariant(mutates, "mount() must be called before mutates");
+      return mutates;
+    },
+
+    programCacheKey: (): string => {
+      invariant(state, "mount() must be called before programCacheKey");
+      // Return cache key based on state that affects shader defines
+      return JSON.stringify({
+        useBatchTexture: state.useBatchTexture,
+        useBatchColorShow: state.useBatchColorShow,
+      });
+    },
+  };
+}
+
+// Re-export public types
+export type { ModelBaseMutates, ModelBaseProps, ModelBaseState };
+
+// Re-export SupportedMaterial for use by water enhancer
+export type { SupportedMaterial } from "./material";
+
+// Re-export marker types for composing enhancers
+export {
+  MODEL_BASE_SHADER_MARKERS,
+  createModelBaseShaderReplacer,
+} from "./markers";

package/src/material/enhancer/model/modelBaseEnhancer/markers.ts

@@ -0,0 +1,27 @@
+import { type ShaderMarkers, createShaderReplacer } from "../../ShaderReplacer";
+
+export const MODEL_BASE_SHADER_MARKERS = {
+  vertex: {},
+  fragment: {
+    /** Start of model uniform declarations. */
+    UNIFORM_START: "// NVR_MODEL_BASE_UNIFORM_START",
+    /** End of model uniform declarations. */
+    UNIFORM_END: "// NVR_MODEL_BASE_UNIFORM_END",
+    /** Start of normal computation block. */
+    NORMAL_START: "// NVR_MODEL_BASE_NORMAL_START",
+    /** End of normal computation block. */
+    NORMAL_END: "// NVR_MODEL_BASE_NORMAL_END",
+    /** Start of outgoing light additions block. */
+    OUTGOING_LIGHT_START: "// NVR_MODEL_BASE_OUTGOING_LIGHT_START",
+    /** End of outgoing light additions block. */
+    OUTGOING_LIGHT_END: "// NVR_MODEL_BASE_OUTGOING_LIGHT_END",
+    /** Start of the final normal assignment block (used for MRT output). */
+    FINAL_NORMAL_START: "// NVR_MODEL_BASE_FINAL_NORMAL_START",
+    /** End of the final normal assignment block (used for MRT output). */
+    FINAL_NORMAL_END: "// NVR_MODEL_BASE_FINAL_NORMAL_END",
+  },
+} as const satisfies ShaderMarkers;
+
+export function createModelBaseShaderReplacer(source: string) {
+  return createShaderReplacer<typeof MODEL_BASE_SHADER_MARKERS>(source);
+}

package/src/material/enhancer/model/modelBaseEnhancer/material.test.ts

@@ -0,0 +1,66 @@
+import { MeshStandardMaterial } from "three";
+import { describe, expect, it } from "vitest";
+
+import { updateMaterialProps } from "./material";
+
+describe("modelBaseEnhancer/material", () => {
+  describe("updateMaterialProps", () => {
+    it("should not update properties when props are undefined", () => {
+      const material = new MeshStandardMaterial();
+      material.color.set(0xff0000);
+      material.metalness = 0.5;
+      material.roughness = 0.3;
+
+      updateMaterialProps(material, {});
+      expect(material.color.getHex()).toBe(0xff0000);
+      expect(material.metalness).toBe(0.5);
+      expect(material.roughness).toBe(0.3);
+    });
+
+    it("should update color when provided", () => {
+      const material = new MeshStandardMaterial();
+      updateMaterialProps(material, { color: 0x00ff00 });
+      expect(material.color.getHex()).toBe(0x00ff00);
+    });
+
+    it("should update metalness and roughness when provided", () => {
+      const material = new MeshStandardMaterial();
+      updateMaterialProps(material, { metalness: 0.8, roughness: 0.2 });
+      expect(material.metalness).toBe(0.8);
+      expect(material.roughness).toBe(0.2);
+    });
+
+    it("should update material emissive when provided", () => {
+      const material = new MeshStandardMaterial();
+      updateMaterialProps(material, {
+        emissiveColor: 0xff0000,
+        emissiveIntensity: 0.5,
+      });
+      expect(material.emissive.getHex()).toBe(0xff0000);
+      expect(material.emissiveIntensity).toBe(0.5);
+    });
+
+    it("should update transparent when provided", () => {
+      const material = new MeshStandardMaterial();
+      material.transparent = false;
+
+      updateMaterialProps(material, { transparent: true });
+      expect(material.transparent).toBe(true);
+    });
+
+    it("should update opacity when provided", () => {
+      const material = new MeshStandardMaterial();
+      material.opacity = 1.0;
+      updateMaterialProps(material, { opacity: 0.5 });
+      expect(material.opacity).toBe(0.5);
+    });
+
+    it("should update depthWrite when provided", () => {
+      const material = new MeshStandardMaterial();
+      material.depthWrite = true;
+
+      updateMaterialProps(material, { depthWrite: false });
+      expect(material.depthWrite).toBe(false);
+    });
+  });
+});

package/src/material/enhancer/model/modelBaseEnhancer/material.ts

@@ -0,0 +1,44 @@
+import type { MaterialsFromShaders, ShaderName } from "../../MaterialEnhancer";
+
+import type { ModelBaseProps } from "./types";
+
+// Shaders this enhancer supports
+export const AVAILABLE_SHADERS = [
+  "standard",
+  "physical",
+] satisfies ShaderName[];
+export type SupportedMaterial = MaterialsFromShaders<typeof AVAILABLE_SHADERS>;
+
+/**
+ * Update Three.js material properties from props.
+ * Side effect function - mutates material directly.
+ */
+export const updateMaterialProps = (
+  material: SupportedMaterial,
+  props: ModelBaseProps,
+): void => {
+  if (props.color !== undefined) {
+    material.color.set(props.color);
+  }
+  if (props.metalness !== undefined) {
+    material.metalness = props.metalness;
+  }
+  if (props.roughness !== undefined) {
+    material.roughness = props.roughness;
+  }
+  if (props.emissiveColor !== undefined) {
+    material.emissive.set(props.emissiveColor);
+  }
+  if (props.emissiveIntensity !== undefined) {
+    material.emissiveIntensity = props.emissiveIntensity;
+  }
+  if (props.transparent !== undefined) {
+    material.transparent = props.transparent;
+  }
+  if (props.opacity !== undefined) {
+    material.opacity = props.opacity;
+  }
+  if (props.depthWrite !== undefined) {
+    material.depthWrite = props.depthWrite;
+  }
+};

package/src/material/enhancer/model/modelBaseEnhancer/mutates.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import type { ShaderUniforms } from "../../MaterialEnhancer";
+
+import { createBaseMutates } from "./mutates";
+import { DEFAULT_BASE_STATE } from "./state";
+import type { ModelBaseState } from "./types";
+
+describe("modelBaseEnhancer/mutates", () => {
+  describe("update syncs refs from state", () => {
+    it("should sync pickable ref from state", () => {
+      const state: ModelBaseState = {
+        ...DEFAULT_BASE_STATE,
+        pickable: true,
+      };
+      const mutates = createBaseMutates();
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.nvr_uPickable?.value).toBe(1);
+    });
+
+    it("should set pickable to 0 when false", () => {
+      const state: ModelBaseState = {
+        ...DEFAULT_BASE_STATE,
+        pickable: false,
+      };
+      const mutates = createBaseMutates();
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.nvr_uPickable?.value).toBe(0);
+    });
+  });
+
+  describe("update syncs selective effect uniforms from state", () => {
+    it("should sync effectIdsMask ref from state", () => {
+      const state: ModelBaseState = {
+        ...DEFAULT_BASE_STATE,
+        effectIdsMask: 5, // bits 0 and 2
+      };
+      const mutates = createBaseMutates();
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uEffectIdsMask?.value).toBe(5);
+    });
+
+    it("should sync uEmissiveIntensity ref from state", () => {
+      const state: ModelBaseState = {
+        ...DEFAULT_BASE_STATE,
+        emissiveIntensity: 0.7,
+      };
+      const mutates = createBaseMutates();
+      mutates.update(state);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, state);
+
+      expect(uniforms.uEmissiveIntensity?.value).toBe(0.7);
+    });
+  });
+
+  describe("setBatchDataTexture", () => {
+    it("should assign batch data texture ref", () => {
+      const mutates = createBaseMutates();
+      mutates.update(DEFAULT_BASE_STATE);
+
+      const textureRef = { value: null };
+      mutates.setBatchDataTexture(textureRef);
+
+      const uniforms: ShaderUniforms = {};
+      mutates.updateUniforms(uniforms, DEFAULT_BASE_STATE);
+
+      expect(uniforms.batchDataTexture).toBe(textureRef);
+    });
+  });
+});

package/src/material/enhancer/model/modelBaseEnhancer/mutates.ts

@@ -0,0 +1,47 @@
+import type { Texture } from "three";
+
+import type { UniformValue } from "../../../types";
+
+import type { ModelBaseMutates, ModelBaseRefs } from "./types";
+
+/**
+ * Default refs with initial values.
+ * These are cloned in createBaseMutates and synced from state via update().
+ */
+const DEFAULT_BASE_REFS: ModelBaseRefs = {
+  nvr_uPickable: { value: 0 },
+  uEffectIdsMask: { value: 0 },
+  uEmissiveIntensity: { value: 0 },
+};
+
+/**
+ * Create mutation functions for the model base enhancer.
+ * Refs are created internally and captured via closure.
+ */
+export const createBaseMutates = (): ModelBaseMutates => {
+  // Clone defaults so each enhancer instance gets independent ref objects
+  const refs = structuredClone(DEFAULT_BASE_REFS) as ModelBaseRefs;
+
+  return {
+    update: (state) => {
+      // Sync refs from state
+      refs.nvr_uPickable.value = state.pickable ? 1 : 0;
+      refs.uEffectIdsMask.value = state.effectIdsMask;
+      refs.uEmissiveIntensity.value = state.emissiveIntensity;
+    },
+    updateUniforms: (uniforms) => {
+      // Assign core uniform refs to shader.uniforms
+      uniforms.nvr_uPickable = refs.nvr_uPickable;
+      uniforms.uEffectIdsMask = refs.uEffectIdsMask;
+      uniforms.uEmissiveIntensity = refs.uEmissiveIntensity;
+
+      // Batch texture
+      if (refs.batchDataTexture) {
+        uniforms.batchDataTexture = refs.batchDataTexture;
+      }
+    },
+    setBatchDataTexture: (texture: UniformValue<Texture | null>): void => {
+      refs.batchDataTexture = texture;
+    },
+  };
+};

package/src/material/enhancer/model/modelBaseEnhancer/shader.test.ts

@@ -0,0 +1,24 @@
+import { testShaderCompatibility } from "../../test-utils/shaderCompatibility";
+
+import { MODEL_BASE_SHADER_MARKERS } from "./markers";
+
+import { createModelBaseEnhancer, type SupportedMaterial } from ".";
+
+testShaderCompatibility(
+  "modelBaseEnhancer",
+  (material) => createModelBaseEnhancer(material as SupportedMaterial),
+  [
+    {
+      name: "Default props",
+      props: {},
+    },
+    {
+      name: "With batch texture",
+      props: {
+        useBatchTexture: true,
+        useBatchColorShow: true,
+      },
+    },
+  ],
+  MODEL_BASE_SHADER_MARKERS,
+);

package/src/material/enhancer/model/modelBaseEnhancer/shader.ts

@@ -0,0 +1,162 @@
+import BatchTextureParsVertex from "@shaders/glsl/chunks/batch_texture_pars_vertex.glsl";
+import BatchTextureVertex from "@shaders/glsl/chunks/batch_texture_vertex.glsl";
+import Pick from "@shaders/glsl/chunks/pick.glsl";
+import ShadowMapDepthFragment from "@shaders/glsl/chunks/shadowmap_depth_fragment.glsl";
+import ShadowMapDepthParsFragment from "@shaders/glsl/chunks/shadowmap_depth_pars_fragment.glsl";
+import ShadowMapDepthParsVertex from "@shaders/glsl/chunks/shadowmap_depth_pars_vertex.glsl";
+import ShadowMapDepthVertex from "@shaders/glsl/chunks/shadowmap_depth_vertex.glsl";
+import ShowFragment from "@shaders/glsl/chunks/show_fragment.glsl";
+import ShowParsFragment from "@shaders/glsl/chunks/show_pars_fragment.glsl";
+import ShowParsVertex from "@shaders/glsl/chunks/show_pars_vertex.glsl";
+import SpecularParsFragment from "@shaders/glsl/chunks/spucular_pars_fragment.glsl";
+import type { WebGLProgramParametersWithUniforms } from "three";
+
+import { createReplacer } from "../../../../utils";
+
+import { MODEL_BASE_SHADER_MARKERS } from "./markers";
+import type { SupportedMaterial } from "./material";
+import type { ModelBaseMutates, ModelBaseState } from "./types";
+
+/**
+ * Transform shader with core model modifications.
+ * Uniform assignment is handled by mutates.updateUniforms().
+ */
+export const transformShader = (
+  shader: WebGLProgramParametersWithUniforms,
+  state: ModelBaseState,
+  mutates: ModelBaseMutates,
+  material: SupportedMaterial,
+): void => {
+  // Set core shader defines
+  shader.defines ??= {};
+  shader.defines.USE_SELECTIVE_EFFECT = 1;
+
+  // TODO: Handle batch texture defines in safe way.
+  // Merge defines from material.userData.defines (includes batch texture row defines)
+  // This is important for batch texture functionality which sets defines like:
+  // - BATCHED_TEXTURE_ROW_COLOR_SHOW, BATCHED_TEXTURE_ROW_HEIGHT, etc.
+  // - USE_BATCH_TEXTURE, USE_BATCH_COLOR_SHOW, USE_BATCH_HEIGHT, etc.
+  if (material.userData.defines) {
+    Object.assign(shader.defines, material.userData.defines);
+  }
+
+  // Assign uniform refs to shader.uniforms via mutates
+  mutates.updateUniforms(shader.uniforms, state);
+
+  // Transform vertex shader
+  shader.vertexShader = createReplacer(shader.vertexShader)
+    .replace(
+      "void main() {",
+      `
+#include <packing>
+
+in float batchId;
+out float nvr_vBatchId;
+out vec3 vPosition;
+
+${ShowParsVertex}
+${BatchTextureParsVertex}
+
+${ShadowMapDepthParsVertex}
+
+void main() {
+  nvr_vBatchId = batchId;
+`,
+    )
+    .replace(
+      "#include <color_vertex>",
+      `
+#include <color_vertex>
+
+${BatchTextureVertex}
+`,
+    )
+    .replace(
+      "#include <clipping_planes_vertex>",
+      `
+#include <clipping_planes_vertex>
+vPosition = (modelMatrix * vec4(transformed, 1.0)).xyz;
+${ShadowMapDepthVertex}
+`,
+    ).source;
+
+  // Transform fragment shader
+  shader.fragmentShader = createReplacer(shader.fragmentShader)
+    .replace(
+      "void main() {",
+      `
+#include <packing>
+
+${MODEL_BASE_SHADER_MARKERS.fragment.UNIFORM_START}
+uniform float nvr_uPickable;
+// uEffectIdsMask is declared by overrideMaterialsForMRT (#ifdef USE_SELECTIVE_EFFECT block)
+${MODEL_BASE_SHADER_MARKERS.fragment.UNIFORM_END}
+
+in float nvr_vBatchId;
+
+${ShowParsFragment}
+
+${Pick}
+
+${ShadowMapDepthParsFragment}
+
+void main() {
+  ${ShowFragment}
+  ${ShadowMapDepthFragment}
+`,
+    )
+    .replace(
+      "#include <color_fragment>",
+      `
+#include <color_fragment>
+
+#ifdef USE_BATCH_COLOR_SHOW
+  diffuseColor.a *= nvr_vOpacity;
+#endif
+`,
+    )
+    .replace(
+      "#include <lights_physical_pars_fragment>",
+      `
+#include <lights_physical_pars_fragment>
+${SpecularParsFragment}
+`,
+    )
+    .replace(
+      "#include <normal_fragment_maps>",
+      `
+${MODEL_BASE_SHADER_MARKERS.fragment.NORMAL_START}
+vec3 origNormal = normal;
+vec3 specular;
+#include <normal_fragment_maps>
+${MODEL_BASE_SHADER_MARKERS.fragment.NORMAL_END}
+`,
+    )
+    .replace(
+      "vec3 outgoingLight = totalDiffuse + totalSpecular + totalEmissiveRadiance;",
+      `
+${MODEL_BASE_SHADER_MARKERS.fragment.OUTGOING_LIGHT_START}
+vec3 outgoingLight = totalDiffuse + totalSpecular + totalEmissiveRadiance;
+${MODEL_BASE_SHADER_MARKERS.fragment.OUTGOING_LIGHT_END}
+`,
+    )
+    .replace(
+      "#include <dithering_fragment>",
+      `
+#include <dithering_fragment>
+if (nvr_uPickable > 0.0 && diffuseColor.a > 0.0) {
+  vec3 pickColor = nvr_batchIdToColor(nvr_vBatchId);
+  gl_FragColor = vec4(pickColor.xyz, 1.0);
+}
+`,
+    )
+    .replace(
+      "normalBuffer = vec4(packNormalToVec2(normal), metalnessFactor, roughnessFactor)",
+      `
+${MODEL_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_START}
+vec3 finalNormal = normal;
+${MODEL_BASE_SHADER_MARKERS.fragment.FINAL_NORMAL_END}
+normalBuffer = vec4(packNormalToVec2(finalNormal), metalnessFactor, roughnessFactor)
+`,
+    ).source;
+};

package/src/material/enhancer/model/modelBaseEnhancer/state.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_BASE_STATE, updateState } from "./state";
+import type { ModelBaseProps, ModelBaseState } from "./types";
+
+/**
+ * Helper to create expected base state by merging with defaults.
+ */
+const createExpectedState = (
+  overrides: Partial<ModelBaseState> = {},
+): ModelBaseState => ({
+  ...DEFAULT_BASE_STATE,
+  ...overrides,
+});
+
+describe("modelBaseEnhancer/state", () => {
+  describe("updateState", () => {
+    type TestCase = {
+      name: string;
+      props: ModelBaseProps;
+      currentState: ModelBaseState;
+      expected: ModelBaseState;
+    };
+
+    const testCases: TestCase[] = [
+      {
+        name: "returns default state when given empty props",
+        props: {},
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState(),
+      },
+      {
+        name: "applies all props",
+        props: {
+          pickable: true,
+          batchColorEnabled: true,
+          useBatchTexture: true,
+          useBatchColorShow: true,
+        },
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState({
+          pickable: true,
+          batchColorEnabled: true,
+          useBatchTexture: true,
+          useBatchColorShow: true,
+        }),
+      },
+      {
+        name: "applies pickable only",
+        props: {
+          pickable: true,
+        },
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState({
+          pickable: true,
+        }),
+      },
+      {
+        name: "applies batch flags only",
+        props: {
+          useBatchTexture: true,
+          useBatchColorShow: true,
+        },
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState({
+          useBatchTexture: true,
+          useBatchColorShow: true,
+        }),
+      },
+      {
+        name: "applies emissive and effectIdsMask",
+        props: {
+          emissiveColor: 0xff0000,
+          emissiveIntensity: 1.5,
+          effectIdsMask: 3,
+        },
+        currentState: DEFAULT_BASE_STATE,
+        expected: createExpectedState({
+          emissiveColor: 0xff0000,
+          emissiveIntensity: 1.5,
+          effectIdsMask: 3,
+        }),
+      },
+    ];
+
+    it.each(testCases)("$name", ({ props, currentState, expected }) => {
+      const result = updateState(props, currentState);
+      expect(result).toEqual(expected);
+    });
+
+    it("falls back to currentState for missing props", () => {
+      const currentState: ModelBaseState = {
+        ...DEFAULT_BASE_STATE,
+        pickable: true,
+        useBatchTexture: true,
+      };
+      const result = updateState({ batchColorEnabled: true }, currentState);
+      expect(result.pickable).toBe(true);
+      expect(result.useBatchTexture).toBe(true);
+      expect(result.batchColorEnabled).toBe(true);
+    });
+  });
+});