@mirage-engine/painter 0.4.0 → 1.0.1

package/src/Box/BoxGenerator.ts

@@ -0,0 +1,350 @@
+import * as THREE from "three";
+import { BoxStyles, ShaderHooks } from "../types";
+import {
+  parsePixelValue,
+  parseColor,
+  parseLinearGradient,
+} from "../tools/parser";
+import { BoxShader, BoxChunk } from "../shaders/index";
+
+export function createBoxMaterial(
+  styles: BoxStyles,
+  width: number,
+  height: number,
+  texture: THREE.Texture | null = null,
+  hooks?: ShaderHooks,
+): THREE.ShaderMaterial {
+  const hasTexture = texture !== null || !!styles.imageSrc;
+
+  let customUniformsCode = "";
+  const customUniforms: any = {};
+  
+  if (hooks?.uniforms) {
+    for (const [key, value] of Object.entries(hooks.uniforms)) {
+      if (typeof value === "number") {
+        customUniformsCode += `uniform float ${key};\n`;
+        customUniforms[key] = { value };
+      } else if (Array.isArray(value)) {
+        if (value.length === 2) {
+          customUniformsCode += `uniform vec2 ${key};\n`;
+          customUniforms[key] = { value: new THREE.Vector2(...value) };
+        } else if (value.length === 3) {
+          customUniformsCode += `uniform vec3 ${key};\n`;
+          customUniforms[key] = { value: new THREE.Vector3(...value) };
+        } else if (value.length === 4) {
+          customUniformsCode += `uniform vec4 ${key};\n`;
+          customUniforms[key] = { value: new THREE.Vector4(...value) };
+        }
+      } else {
+        customUniformsCode += `uniform float ${key};\n`;
+        customUniforms[key] = { value };
+      }
+    }
+  }
+
+  const declChunk = (hasTexture ? BoxChunk.declChunk : "") + "\n" + customUniformsCode;
+  const baseUvCode = styles.isTraveler ? BoxChunk.uvChunk : "vec2 resultUv = vUv * uTextureRepeat + uTextureOffset;\n";
+  const uvChunk = hasTexture ? baseUvCode + (hooks?.uvModifier || "") : "";
+  const baseColorChunk = hasTexture ? BoxChunk.baseColorChunk : "";
+  const colorModChunk = hooks?.colorModifier || "";
+
+  const fragmentShader = BoxShader.fragmentShader
+    .replace("#INJECT_DECLARATIONS", declChunk)
+    .replace("#INJECT_UV_MODIFIER", uvChunk)
+    .replace("#INJECT_BASE_COLOR", baseColorChunk)
+    .replace("#INJECT_COLOR_MODIFIER", colorModChunk);
+
+  // uniform setting
+  const parsedBg = parseColor(styles.backgroundColor);
+  const parsedBorder = parseColor(styles.borderColor);
+  const uniforms = {
+    uSize: { value: new THREE.Vector2(width, height) },
+    uBgColor: {
+      value: new THREE.Vector4(
+        parsedBg.color.r,
+        parsedBg.color.g,
+        parsedBg.color.b,
+        parsedBg.alpha,
+      ),
+    },
+    uBorderColor: {
+      value: new THREE.Vector4(
+        parsedBorder.color.r,
+        parsedBorder.color.g,
+        parsedBorder.color.b,
+        parsedBorder.alpha,
+      ),
+    },
+    uBorderRadius: { value: new THREE.Vector4(0, 0, 0, 0) },
+    uBorderWidth: { value: parsePixelValue(styles.borderWidth) },
+    uOpacity: { value: styles.opacity ?? 1.0 },
+    uTexture: { value: null as THREE.Texture | null },
+    uTextureRepeat: { value: new THREE.Vector2(1.0, 1.0) },
+    uTextureOffset: { value: new THREE.Vector2(0.0, 0.0) },
+
+    uGradientCount: { value: 0 },
+    uGradientAngle: { value: 0 },
+    uGradientColors: {
+      value: Array.from({ length: 8 }, () => new THREE.Vector4(0, 0, 0, 0)),
+    },
+    uGradientStops: { value: new Float32Array(8) },
+  };
+  // border radius value initialize
+  setBorderRadius(uniforms.uBorderRadius.value, styles.borderRadius);
+
+  if (hasTexture) {
+    uniforms.uTexture.value = texture;
+  }
+
+  const material = new THREE.ShaderMaterial({
+    uniforms: { ...uniforms, ...customUniforms },
+    vertexShader: BoxShader.vertexShader,
+    fragmentShader: fragmentShader,
+    transparent: true,
+    side: THREE.FrontSide, // for better performance
+  });
+
+  // Initial gradient setup
+  if (styles.backgroundImage) {
+    setBoxUniforms(material, { backgroundImage: styles.backgroundImage });
+  }
+
+  return material;
+}
+
+export function updateBoxMaterial(
+  material: THREE.ShaderMaterial,
+  styles: BoxStyles,
+  width: number,
+  height: number,
+  texture?: THREE.Texture | null,
+) {
+  const parsedBorderWidth = parsePixelValue(styles.borderWidth);
+  setBoxUniforms(material, {
+    width,
+    height,
+    borderRadius: styles.borderRadius,
+    borderWidth: parsedBorderWidth,
+    backgroundColor: styles.backgroundColor,
+    borderColor: styles.borderColor,
+    opacity: styles.opacity,
+    texture,
+    backgroundImage: styles.backgroundImage,
+  });
+}
+
+export interface BoxUniformValues {
+  width?: number;
+  height?: number;
+  borderRadius?: string | number | [number, number, number, number];
+  borderWidth?: number;
+  backgroundColor?: THREE.Color | [number, number, number] | string;
+  borderColor?: THREE.Color | [number, number, number] | string;
+  opacity?: number;
+  bgOpacity?: number;
+  borderOpacity?: number;
+  texture?: THREE.Texture | null;
+  backgroundImage?: string;
+  [key: string]: any;
+}
+
+export function setBoxUniforms(
+  material: THREE.ShaderMaterial,
+  values: BoxUniformValues,
+) {
+  if (values.width !== undefined && values.height !== undefined) {
+    material.uniforms.uSize.value.set(values.width, values.height);
+  }
+  if (values.borderRadius !== undefined) {
+    setBorderRadius(material.uniforms.uBorderRadius.value, values.borderRadius);
+  }
+  if (values.borderWidth !== undefined) {
+    material.uniforms.uBorderWidth.value = values.borderWidth;
+  }
+
+  if (values.backgroundColor !== undefined) {
+    if (Array.isArray(values.backgroundColor)) {
+      const currentAlpha = material.uniforms.uBgColor.value.w;
+      material.uniforms.uBgColor.value.set(
+        values.backgroundColor[0],
+        values.backgroundColor[1],
+        values.backgroundColor[2],
+        currentAlpha,
+      );
+    } else if (typeof values.backgroundColor === "string") {
+      const parsed = parseColor(values.backgroundColor);
+      material.uniforms.uBgColor.value.set(
+        parsed.color.r,
+        parsed.color.g,
+        parsed.color.b,
+        parsed.alpha,
+      );
+    } else {
+      const currentAlpha = material.uniforms.uBgColor.value.w;
+      material.uniforms.uBgColor.value.set(
+        values.backgroundColor.r,
+        values.backgroundColor.g,
+        values.backgroundColor.b,
+        currentAlpha,
+      );
+    }
+  }
+
+  if (values.borderColor !== undefined) {
+    if (Array.isArray(values.borderColor)) {
+      const currentAlpha = material.uniforms.uBorderColor.value.w;
+      material.uniforms.uBorderColor.value.set(
+        values.borderColor[0],
+        values.borderColor[1],
+        values.borderColor[2],
+        currentAlpha,
+      );
+    } else if (typeof values.borderColor === "string") {
+      const parsed = parseColor(values.borderColor);
+      material.uniforms.uBorderColor.value.set(
+        parsed.color.r,
+        parsed.color.g,
+        parsed.color.b,
+        parsed.alpha,
+      );
+    } else {
+      const currentAlpha = material.uniforms.uBorderColor.value.w;
+      material.uniforms.uBorderColor.value.set(
+        values.borderColor.r,
+        values.borderColor.g,
+        values.borderColor.b,
+        currentAlpha,
+      );
+    }
+  }
+
+  if (values.opacity !== undefined) {
+    material.uniforms.uOpacity.value = values.opacity;
+  }
+  if (values.bgOpacity !== undefined) {
+    material.uniforms.uBgColor.value.w = values.bgOpacity;
+  }
+  if (values.borderOpacity !== undefined) {
+    material.uniforms.uBorderColor.value.w = values.borderOpacity;
+  }
+  if (material.uniforms.uTexture && values.texture !== undefined) {
+    material.uniforms.uTexture.value = values.texture;
+  }
+
+  const currentTex = values.texture !== undefined ? values.texture : material.uniforms.uTexture?.value;
+  if (currentTex && (currentTex.image instanceof ImageBitmap || currentTex.image instanceof HTMLImageElement || currentTex.image instanceof HTMLCanvasElement)) {
+    const imgWidth = currentTex.image.width;
+    const imgHeight = currentTex.image.height;
+    const domWidth = values.width ?? material.uniforms.uSize.value.x;
+    const domHeight = values.height ?? material.uniforms.uSize.value.y;
+    
+    if (imgWidth && imgHeight && domWidth && domHeight) {
+      const imageAspect = imgWidth / imgHeight;
+      const domAspect = domWidth / domHeight;
+
+      if (imageAspect > domAspect) {
+        const repeatX = domAspect / imageAspect;
+        material.uniforms.uTextureRepeat.value.set(repeatX, 1);
+        material.uniforms.uTextureOffset.value.set((1 - repeatX) / 2, 0);
+      } else {
+        const repeatY = imageAspect / domAspect;
+        material.uniforms.uTextureRepeat.value.set(1, repeatY);
+        material.uniforms.uTextureOffset.value.set(0, (1 - repeatY) / 2);
+      }
+    }
+  } else if (material.uniforms.uTextureRepeat) {
+    material.uniforms.uTextureRepeat.value.set(1, 1);
+    material.uniforms.uTextureOffset.value.set(0, 0);
+  }
+
+  if (values.backgroundImage !== undefined) {
+    const gradient = parseLinearGradient(values.backgroundImage);
+    if (gradient) {
+      material.uniforms.uGradientCount.value = gradient.stops.length;
+      material.uniforms.uGradientAngle.value = gradient.angle;
+      for (let i = 0; i < 8; i++) {
+        if (i < gradient.stops.length) {
+          const s = gradient.stops[i];
+          material.uniforms.uGradientColors.value[i].set(
+            s.color.r,
+            s.color.g,
+            s.color.b,
+            s.alpha,
+          );
+          // console.log(s.color.r, s.color.g, s.color.b);
+          material.uniforms.uGradientStops.value[i] = s.stop;
+        } else {
+          material.uniforms.uGradientColors.value[i].set(0, 0, 0, 0);
+          material.uniforms.uGradientStops.value[i] = 1.0;
+        }
+      }
+    } else {
+      material.uniforms.uGradientCount.value = 0;
+    }
+  }
+
+  // Update dynamic custom uniforms
+  for (const key of Object.keys(values)) {
+    if (
+      key !== "width" &&
+      key !== "height" &&
+      key !== "borderRadius" &&
+      key !== "borderWidth" &&
+      key !== "backgroundColor" &&
+      key !== "borderColor" &&
+      key !== "opacity" &&
+      key !== "bgOpacity" &&
+      key !== "borderOpacity" &&
+      key !== "texture" &&
+      key !== "backgroundImage"
+    ) {
+      if (material.uniforms[key] !== undefined) {
+        if (
+          material.uniforms[key].value !== undefined &&
+          material.uniforms[key].value !== null &&
+          typeof material.uniforms[key].value.set === "function"
+        ) {
+          if (Array.isArray(values[key])) {
+            material.uniforms[key].value.set(...values[key]);
+          } else if (values[key] !== undefined) {
+            if (values[key].copy) {
+              material.uniforms[key].value.copy(values[key]);
+            } else {
+              material.uniforms[key].value = values[key];
+            }
+          }
+        } else {
+          material.uniforms[key].value = values[key];
+        }
+      }
+    }
+  }
+}
+
+function setBorderRadius(
+  target: THREE.Vector4,
+  radius?: string | number | [number, number, number, number],
+) {
+  if (radius === undefined || radius === null) {
+    target.set(0, 0, 0, 0);
+    return;
+  }
+
+  if (typeof radius === "number") {
+    target.set(radius, radius, radius, radius);
+    return;
+  }
+
+  if (Array.isArray(radius)) {
+    target.set(radius[0], radius[1], radius[2], radius[3]);
+    return;
+  }
+
+  const arr = radius.split("/")[0].trim().split(/\s+/);
+  const tl = parsePixelValue(arr[0]);
+  const tr = parsePixelValue(arr[1] ?? arr[0]);
+  const br = parsePixelValue(arr[2] ?? arr[0]);
+  const bl = parsePixelValue(arr[3] ?? arr[1] ?? arr[0]);
+
+  target.set(tl, tr, br, bl);
+}

package/src/Painter.ts

@@ -1,36 +1,40 @@
 import * as THREE from "three";
-import { BoxStyles, TextStyles, ShaderHooks} from "./types";
-import { createBoxMaterial, updateBoxMaterial } from "./BoxGenerator";
-import { createTextTexture } from "./TextGenerator";
+import { BoxStyles, TextStyles, ShaderHooks } from "./types";
+import {
+  createBoxMaterial,
+  updateBoxMaterial,
+  setBoxUniforms,
+  BoxUniformValues,
+} from "./Box/BoxGenerator";
+import { TextGenerator } from "./Text/TextGenerator";
 
 export const Painter = {
   create(
     type: "BOX" | "TEXT",
-    styles: any,
+    styles: BoxStyles | TextStyles,
     content: string,
     width: number,
     height: number,
     quality: number = 2,
     texture: THREE.Texture | null = null,
-    shaderHooks?: ShaderHooks
+    shaderHooks?: ShaderHooks,
   ): THREE.Material {
     if (type === "BOX") {
-      return createBoxMaterial(styles as BoxStyles, width, height, texture, shaderHooks);
+      return createBoxMaterial(
+        styles as BoxStyles,
+        width,
+        height,
+        texture,
+        shaderHooks,
+      );
     } else if (type === "TEXT") {
-      const texture = createTextTexture(
+      return new TextGenerator(
         content || "",
         styles as TextStyles,
         width,
         height,
         quality,
       );
-
-      return new THREE.MeshBasicMaterial({
-        map: texture,
-        transparent: true,
-        side: THREE.FrontSide,
-        color: 0xffffff,
-      });
     }
 
     return new THREE.MeshBasicMaterial({ visible: false });
@@ -39,12 +43,12 @@ export const Painter = {
   update(
     material: THREE.Material,
     type: "BOX" | "TEXT",
-    styles: any,
+    styles: BoxStyles | TextStyles,
     content: string,
     width: number,
     height: number,
     quality: number = 2,
-    texture?: THREE.Texture | null
+    texture?: THREE.Texture | null,
   ) {
     if (type === "BOX") {
       updateBoxMaterial(
@@ -52,25 +56,24 @@ export const Painter = {
         styles as BoxStyles,
         width,
         height,
-        texture
+        texture,
       );
     } else if (type === "TEXT") {
-      const basicMat = material as THREE.MeshBasicMaterial;
-
-      if (basicMat.map) {
-        basicMat.map.dispose();
-      }
-
-      const newTexture = createTextTexture(
+      const textMat = material as TextGenerator;
+      textMat.updateText(
         content || "",
         styles as TextStyles,
         width,
         height,
         quality,
       );
-
-      basicMat.map = newTexture;
-      basicMat.needsUpdate = true;
     }
   },
+
+  forceUpdateUniforms(
+    material: THREE.ShaderMaterial,
+    values: BoxUniformValues,
+  ) {
+    setBoxUniforms(material, values);
+  },
 };

package/src/Text/FontMetricsManager.ts

@@ -0,0 +1,62 @@
+export class FontMetricsManager {
+  private static cache: Map<string, number> = new Map();
+
+  /**
+   * Calculates or retrieves the exact alphabetic baseline (in pixels) for the given font.
+   * @param font CSS font shorthand string (e.g., "400 16px Inter")
+   * @returns Baseline Y offset in pixels
+   */
+  static getBaseline(font: string): number {
+    if (this.cache.has(font)) {
+      return this.cache.get(font)!;
+    }
+
+    const baseline = this.calculateBaselineFromDOM(font);
+    this.cache.set(font, baseline);
+    return baseline;
+  }
+
+  private static calculateBaselineFromDOM(font: string): number {
+    // Return 0 when running in a non‑DOM environment (e.g., server‑side rendering)
+    if (typeof document === "undefined") return 0;
+
+    const container = document.createElement("div");
+    const span = document.createElement("span");
+    const img = document.createElement("img"); // 1×1 transparent pixel
+
+    // Hide the helper elements and apply the target font
+    container.style.visibility = "hidden";
+    container.style.position = "absolute";
+    container.style.top = "0px";
+    container.style.left = "0px";
+    container.style.font = font;
+
+    // Reset padding/margin/border to isolate pure font metrics
+    container.style.margin = "0";
+    container.style.padding = "0";
+    container.style.border = "none";
+    span.style.margin = "0";
+    span.style.padding = "0";
+    span.style.border = "none";
+    span.style.lineHeight = "normal"; // Prevent line‑height interference
+
+    // Align the 1×1 image to the baseline of the span
+    img.width = 1;
+    img.height = 1;
+    img.style.verticalAlign = "baseline";
+
+    // Assemble the DOM structure
+    span.appendChild(document.createTextNode("Hidden Text"));
+    container.appendChild(span);
+    container.appendChild(img);
+
+    document.body.appendChild(container);
+
+    // Measure the distance from the top of the span to the top of the baseline‑aligned image
+    const baseline = img.offsetTop - span.offsetTop;
+
+    document.body.removeChild(container);
+
+    return baseline;
+  }
+}

package/src/Text/TextGenerator.ts

@@ -0,0 +1,123 @@
+import * as THREE from "three";
+import { TextStyles } from "../types";
+import { FontMetricsManager } from "./FontMetricsManager";
+
+export class TextGenerator extends THREE.MeshBasicMaterial {
+  private canvas: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D;
+  private qualityFactor: number;
+
+  constructor(text: string, styles: TextStyles, rectWidth: number, rectHeight: number, qualityFactor: number = 2) {
+    super({
+      transparent: true,
+      side: THREE.FrontSide,
+      color: 0xffffff,
+    });
+
+    this.canvas = document.createElement("canvas");
+    this.ctx = this.canvas.getContext("2d")!;
+
+    if (!this.ctx) {
+      throw new Error("[Mirage] Failed to create canvas context");
+    }
+
+    this.qualityFactor = qualityFactor;
+
+    this.map = new THREE.CanvasTexture(this.canvas);
+    this.map.colorSpace = THREE.LinearSRGBColorSpace;
+    this.map.minFilter = THREE.LinearFilter;
+    this.map.magFilter = THREE.LinearFilter;
+
+    this.updateText(text, styles, rectWidth, rectHeight);
+  }
+
+  private wrapText(text: string, maxWidth: number): string[] {
+    const forcedLines = text.split("\n");
+    const resultLines: string[] = [];
+
+    forcedLines.forEach((line) => {
+      const words = line.match(/[^\s\-]+\-?|\-|\s+/g) || [];
+
+      if (words.length === 0) {
+        resultLines.push("");
+        return;
+      }
+
+      let currentLine = words[0];
+
+      for (let i = 1; i < words.length; i++) {
+        const word = words[i];
+        const width = this.ctx.measureText(currentLine + word).width;
+
+        if (width <= maxWidth + 2) {
+          currentLine += word;
+        } else {
+          if (currentLine) resultLines.push(currentLine);
+          currentLine = word.trimStart();
+        }
+      }
+
+      if (currentLine) {
+        resultLines.push(currentLine);
+      }
+    });
+
+    return resultLines;
+  }
+
+  public updateText(text: string, styles: TextStyles, rectWidth: number, rectHeight: number, qualityFactor?: number) {
+    if (qualityFactor !== undefined) {
+      this.qualityFactor = qualityFactor;
+    }
+
+    const pixelRatio = window.devicePixelRatio || 1;
+    const scale = pixelRatio * this.qualityFactor;
+
+    const newCanvasWidth = rectWidth * scale;
+    const newCanvasHeight = rectHeight * scale;
+
+    if (this.canvas.width !== newCanvasWidth || this.canvas.height !== newCanvasHeight) {
+      this.canvas.width = newCanvasWidth;
+      this.canvas.height = newCanvasHeight;
+    } else {
+      this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+    }
+
+    // Reset transform and apply scale
+    this.ctx.setTransform(scale, 0, 0, scale, 0, 0);
+
+    this.ctx.font = styles.font;
+    this.ctx.fillStyle = styles.color;
+    this.ctx.textBaseline = "alphabetic";
+    this.ctx.globalAlpha = 1;
+
+    const lines = this.wrapText(text, rectWidth);
+    const lineHeight = styles.lineHeight;
+    const baseline = FontMetricsManager.getBaseline(styles.font);
+
+    lines.forEach((line, index) => {
+      const y = index * lineHeight + baseline;
+
+      let x = 0;
+      if (styles.textAlign === "center") {
+        x = rectWidth / 2;
+      } else if (styles.textAlign === "right") {
+        x = rectWidth;
+      }
+      
+      this.ctx.textAlign = styles.textAlign as CanvasTextAlign;
+      this.ctx.fillText(line, x, y);
+    });
+
+    if (this.map) {
+      this.map.needsUpdate = true;
+    }
+  }
+
+  public dispose() {
+    if (this.map) {
+      this.map.dispose();
+    }
+    super.dispose();
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,4 @@
+declare module "*?raw" {
+  const content: string;
+  export default content;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
-export * from "./TextGenerator";
+export * from "./Text/TextGenerator";
 export * from "./types";
-export * from "./BoxGenerator";
-export * from "./Painter";
+export * from "./Box/BoxGenerator";
+export * from "./Painter";
+export * from "./tools/parser";