@haiyue/extensions 0.1.0

package/src/animation/AnimationTextRasterizer.ts

@@ -0,0 +1,340 @@
+import type {
+  AnimationText2DComponent,
+  AnimationTextAnimator,
+  AnimationTextDocumentKeyframe,
+  AnimationVectorValueTrack,
+} from '@haiyue/animation-spec';
+
+type TextTexture = HTMLCanvasElement | ImageBitmap;
+
+interface ResolvedTextDocument {
+  text: string;
+  fontFamily: string;
+  fontSize: number;
+  fontWeight: string | number;
+  fontStyle: 'normal' | 'italic';
+  lineHeight: number;
+  tracking: number;
+  textAlign: 'left' | 'center' | 'right';
+  color: readonly [number, number, number, number];
+}
+
+interface GlyphState {
+  x: number;
+  y: number;
+  scaleX: number;
+  scaleY: number;
+  rotation: number;
+  opacity: number;
+  tracking: number;
+  color: [number, number, number, number];
+}
+
+interface SelectorIndexPlan {
+  readonly indices: readonly number[];
+  readonly count: number;
+}
+
+/** Runtime-private deterministic grapheme shaper and Canvas atlas uploader. */
+export class AnimationTextRasterizer {
+  texture: TextTexture | null = null;
+  textureVersion = 0;
+  private readonly canvas: HTMLCanvasElement | null;
+  private time = Number.NaN;
+  private dirty = true;
+  private updating = false;
+  private updateToken = 0;
+  private readonly animated: boolean;
+
+  constructor(readonly component: Readonly<AnimationText2DComponent>) {
+    this.canvas = typeof document === 'undefined' ? null : document.createElement('canvas');
+    this.animated = (component.documents?.length ?? 0) > 1
+      || (component.animators ?? []).some(animator => hasAnimatedAnimator(animator));
+    void this.updateTexture();
+  }
+
+  setTime(time: number): void {
+    if (!this.animated) return;
+    if (this.time === time && !this.dirty) return;
+    this.time = time;
+    this.dirty = true;
+    void this.updateTexture();
+  }
+
+  invalidateFont(): void {
+    this.dirty = true;
+    void this.updateTexture();
+  }
+
+  destroy(): void {
+    this.updateToken++;
+    closeTextTexture(this.texture, this.canvas);
+    this.texture = null;
+  }
+
+  async updateTexture(): Promise<void> {
+    if (!this.dirty || this.updating || !this.canvas) return;
+    const token = ++this.updateToken;
+    this.dirty = false;
+    this.updating = true;
+    try {
+      this.draw(this.canvas, Number.isFinite(this.time) ? this.time : 0);
+      this.texture = this.canvas;
+      this.textureVersion++;
+      if (typeof createImageBitmap !== 'function') return;
+      const bitmap = await createImageBitmap(this.canvas, { colorSpaceConversion: 'none' });
+      if (token !== this.updateToken) { bitmap.close(); return; }
+      const retired = this.texture;
+      this.texture = bitmap;
+      this.textureVersion++;
+      closeTextTexture(retired, this.canvas);
+    } finally {
+      this.updating = false;
+      if (this.dirty) void this.updateTexture();
+    }
+  }
+
+  private draw(canvas: HTMLCanvasElement, time: number): void {
+    const component = this.component;
+    const document = resolveDocument(component, time);
+    const dpr = Math.max(1, Math.min(4, component.resolutionScale ?? 2));
+    const width = Math.max(1, Math.ceil(component.size[0]));
+    const height = Math.max(1, Math.ceil(component.size[1]));
+    canvas.width = Math.max(1, Math.ceil(width * dpr));
+    canvas.height = Math.max(1, Math.ceil(height * dpr));
+    const context = canvas.getContext('2d');
+    if (!context) return;
+    context.setTransform(dpr, 0, 0, dpr, 0, 0);
+    context.clearRect(0, 0, width, height);
+    const background = component.backgroundColor;
+    if (background && background[3] > 0) {
+      context.fillStyle = cssColor(background);
+      context.fillRect(0, 0, width, height);
+    }
+    const padding = Math.max(0, component.padding ?? 0);
+    const contentWidth = Math.max(1, width - padding * 2);
+    const contentHeight = Math.max(1, height - padding * 2);
+    context.font = `${document.fontStyle} ${document.fontWeight} ${document.fontSize}px ${quoteFont(document.fontFamily)}`;
+    context.textBaseline = 'alphabetic';
+    context.textAlign = 'left';
+    const lines = document.text.split(/\r?\n/).map(splitGraphemes);
+    const animators = component.animators ?? [];
+    const selectorPlans = animators.map(animator => createSelectorIndexPlan(lines, animator));
+    const lineHeight = Math.max(1, document.lineHeight);
+    const textHeight = lines.length * lineHeight;
+    let top = padding;
+    const vertical = component.verticalAlign ?? 'middle';
+    if (vertical === 'middle') top += Math.max(0, (contentHeight - textHeight) / 2);
+    else if (vertical === 'bottom') top += Math.max(0, contentHeight - textHeight);
+    let globalIndex = 0;
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex]!;
+      const advances = line.map(glyph => context.measureText(glyph).width);
+      const baseWidth = advances.reduce((sum, advance) => sum + advance, 0) + Math.max(0, line.length - 1) * document.tracking;
+      let x = padding;
+      if (document.textAlign === 'center') x += Math.max(0, (contentWidth - baseWidth) / 2);
+      else if (document.textAlign === 'right') x += Math.max(0, contentWidth - baseWidth);
+      const baseline = top + lineIndex * lineHeight + document.fontSize;
+      for (let glyphIndex = 0; glyphIndex < line.length; glyphIndex++, globalIndex++) {
+        const glyph = line[glyphIndex]!;
+        const advance = advances[glyphIndex] ?? 0;
+        const state = resolveGlyphState(animators, selectorPlans, time, globalIndex, document.color);
+        const centerX = x + advance / 2 + state.x;
+        context.save();
+        context.translate(centerX, baseline + state.y);
+        context.rotate(state.rotation);
+        context.scale(state.scaleX, state.scaleY);
+        context.globalAlpha = state.opacity;
+        context.fillStyle = cssColor(state.color);
+        context.fillText(glyph, -advance / 2, 0);
+        context.restore();
+        x += advance + document.tracking + state.tracking;
+      }
+    }
+  }
+}
+
+function resolveDocument(component: Readonly<AnimationText2DComponent>, time: number): ResolvedTextDocument {
+  let keyframe: Readonly<AnimationTextDocumentKeyframe> | undefined;
+  for (const candidate of component.documents ?? []) {
+    if (candidate.time > time) break;
+    keyframe = candidate;
+  }
+  return {
+    text: keyframe?.text ?? component.text,
+    fontFamily: keyframe?.fontFamily ?? component.fontFamily ?? 'sans-serif',
+    fontSize: keyframe?.fontSize ?? component.fontSize ?? 28,
+    fontWeight: keyframe?.fontWeight ?? component.fontWeight ?? 400,
+    fontStyle: keyframe?.fontStyle ?? component.fontStyle ?? 'normal',
+    lineHeight: keyframe?.lineHeight ?? component.lineHeight ?? (keyframe?.fontSize ?? component.fontSize ?? 28) * 1.2,
+    tracking: keyframe?.tracking ?? component.tracking ?? 0,
+    textAlign: keyframe?.textAlign ?? component.textAlign ?? 'center',
+    color: keyframe?.color ?? component.color,
+  };
+}
+
+function resolveGlyphState(
+  animators: readonly Readonly<AnimationTextAnimator>[],
+  selectorPlans: readonly SelectorIndexPlan[],
+  time: number,
+  index: number,
+  baseColor: readonly [number, number, number, number],
+): GlyphState {
+  const state: GlyphState = { x: 0, y: 0, scaleX: 1, scaleY: 1, rotation: 0, opacity: 1, tracking: 0, color: [...baseColor] };
+  for (let animatorIndex = 0; animatorIndex < animators.length; animatorIndex++) {
+    const animator = animators[animatorIndex]!;
+    const plan = selectorPlans[animatorIndex]!;
+    const weight = selectorWeight(animator, time, plan.indices[index] ?? 0, plan.count);
+    if (Math.abs(weight) < 1e-6) continue;
+    const position = sampled(animator.positionTrack, time, animator.position ?? [0, 0]);
+    const scale = sampled(animator.scaleTrack, time, animator.scale ?? [1, 1]);
+    const rotation = sampled(animator.rotationTrack, time, [animator.rotation ?? 0])[0] ?? 0;
+    const opacity = sampled(animator.opacityTrack, time, [animator.opacity ?? 1])[0] ?? 1;
+    const tracking = sampled(animator.trackingTrack, time, [animator.tracking ?? 0])[0] ?? 0;
+    const color = sampled(animator.fillColorTrack, time, animator.fillColor ?? state.color);
+    state.x += (position[0] ?? 0) * weight;
+    state.y += (position[1] ?? 0) * weight;
+    state.scaleX *= mix(1, scale[0] ?? 1, weight);
+    state.scaleY *= mix(1, scale[1] ?? 1, weight);
+    state.rotation += rotation * weight;
+    state.opacity *= mix(1, opacity, weight);
+    state.tracking += tracking * weight;
+    for (let channel = 0; channel < 4; channel++) state.color[channel] = mix(state.color[channel]!, color[channel] ?? state.color[channel]!, weight);
+  }
+  state.opacity = clamp(state.opacity, 0, 1);
+  return state;
+}
+
+function selectorWeight(animator: Readonly<AnimationTextAnimator>, time: number, index: number, count: number): number {
+  const selector = animator.selector;
+  const units = selector.units ?? 'percent';
+  const coordinate = units === 'index' ? index + 0.5 : (index + 0.5) / Math.max(1, count);
+  const start = sampled(selector.startTrack, time, [selector.start])[0] ?? selector.start;
+  const end = sampled(selector.endTrack, time, [selector.end])[0] ?? selector.end;
+  const offset = sampled(selector.offsetTrack, time, [selector.offset ?? 0])[0] ?? selector.offset ?? 0;
+  const amount = sampled(selector.amountTrack, time, [selector.amount ?? 1])[0] ?? selector.amount ?? 1;
+  const low = Math.min(start + offset, end + offset);
+  const high = Math.max(start + offset, end + offset);
+  const span = Math.max(1e-6, high - low);
+  const progress = clamp((coordinate - low) / span, 0, 1);
+  let weight = coordinate >= low && coordinate <= high ? 1 : 0;
+  switch (selector.shape ?? 'square') {
+    case 'ramp-up': weight = progress; break;
+    case 'ramp-down': weight = 1 - progress; break;
+    case 'triangle': weight = 1 - Math.abs(progress * 2 - 1); break;
+    case 'round': weight = Math.sqrt(Math.max(0, 1 - (progress * 2 - 1) ** 2)); break;
+    case 'smooth': weight = progress * progress * (3 - 2 * progress); break;
+  }
+  if (selector.easing) weight = cubicBezierYForX(weight, ...selector.easing);
+  const smoothness = selector.smoothness ?? 1;
+  if (smoothness < 1) {
+    const width = Math.max(0.01, smoothness);
+    const edge = 0.5 - width * 0.5;
+    weight = clamp((weight - edge) / width, 0, 1);
+  }
+  return clamp(weight * amount, -1, 1);
+}
+
+function createSelectorIndexPlan(
+  lines: readonly (readonly string[])[],
+  animator: Readonly<AnimationTextAnimator>,
+): SelectorIndexPlan {
+  const basedOn = animator.selector.basedOn ?? 'characters';
+  const indices: number[] = [];
+  let group = 0;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+    const line = lines[lineIndex]!;
+    for (let glyphIndex = 0; glyphIndex < line.length; glyphIndex++) {
+      const glyph = line[glyphIndex]!;
+      indices.push(basedOn === 'lines' ? lineIndex : group);
+      if (basedOn === 'characters') group++;
+      else if (basedOn === 'characters-excluding-spaces' && glyph !== ' ') group++;
+      else if (basedOn === 'words' && (glyph === ' ' || glyphIndex === line.length - 1)) group++;
+    }
+  }
+  const count = Math.max(1, basedOn === 'lines' ? lines.length : group);
+  const seed = animator.selector.randomSeed;
+  if (seed === undefined || count < 2) return { indices, count };
+  const permutation = Array.from({ length: count }, (_, index) => index);
+  let randomState = seed >>> 0;
+  for (let index = permutation.length - 1; index > 0; index--) {
+    randomState = deterministicRandom(randomState);
+    const swap = randomState % (index + 1);
+    [permutation[index], permutation[swap]] = [permutation[swap]!, permutation[index]!];
+  }
+  return { indices: indices.map(index => permutation[index] ?? index), count };
+}
+
+function deterministicRandom(state: number): number {
+  let value = state || 0x6d2b79f5;
+  value ^= value << 13;
+  value ^= value >>> 17;
+  value ^= value << 5;
+  return value >>> 0;
+}
+
+function sampled(track: Readonly<AnimationVectorValueTrack> | undefined, time: number, fallback: readonly number[]): readonly number[] {
+  if (!track || track.times.length === 0) return fallback;
+  let frame = 0;
+  while (frame + 1 < track.times.length && track.times[frame + 1]! <= time) frame++;
+  const next = Math.min(frame + 1, track.times.length - 1);
+  let progress = 0;
+  if (next !== frame && track.interpolation !== 'step') {
+    progress = clamp((time - track.times[frame]!) / Math.max(1e-8, track.times[next]! - track.times[frame]!), 0, 1);
+    if (track.interpolation === 'cubic-bezier' && track.easings) {
+      const offset = frame * 4;
+      progress = cubicBezierYForX(progress, track.easings[offset]!, track.easings[offset + 1]!, track.easings[offset + 2]!, track.easings[offset + 3]!);
+    }
+  }
+  const result = new Array<number>(track.valueSize);
+  for (let index = 0; index < track.valueSize; index++) {
+    const from = track.values[frame * track.valueSize + index] ?? 0;
+    result[index] = mix(from, track.values[next * track.valueSize + index] ?? from, progress);
+  }
+  return result;
+}
+
+function splitGraphemes(text: string): string[] {
+  const result: string[] = [];
+  for (const codePoint of Array.from(text)) {
+    if (codePoint === '\u200D' && result.length > 0) {
+      result[result.length - 1] += codePoint;
+    } else if (result.length > 0 && (/\p{Mark}/u.test(codePoint) || codePoint === '\uFE0F' || result[result.length - 1]!.endsWith('\u200D'))) {
+      result[result.length - 1] += codePoint;
+    } else result.push(codePoint);
+  }
+  return result;
+}
+
+function hasAnimatedAnimator(animator: Readonly<AnimationTextAnimator>): boolean {
+  return animator.positionTrack !== undefined || animator.scaleTrack !== undefined || animator.rotationTrack !== undefined
+    || animator.opacityTrack !== undefined || animator.fillColorTrack !== undefined || animator.trackingTrack !== undefined
+    || animator.selector.startTrack !== undefined || animator.selector.endTrack !== undefined
+    || animator.selector.offsetTrack !== undefined || animator.selector.amountTrack !== undefined;
+}
+
+function cubicBezierYForX(x: number, x1: number, y1: number, x2: number, y2: number): number {
+  let low = 0; let high = 1; let t = x;
+  for (let iteration = 0; iteration < 10; iteration++) {
+    const estimate = cubic(t, 0, x1, x2, 1);
+    if (estimate < x) low = t; else high = t;
+    t = (low + high) * 0.5;
+  }
+  return cubic(t, 0, y1, y2, 1);
+}
+
+function cubic(t: number, a: number, b: number, c: number, d: number): number {
+  const inverse = 1 - t;
+  return inverse ** 3 * a + 3 * inverse ** 2 * t * b + 3 * inverse * t ** 2 * c + t ** 3 * d;
+}
+
+function cssColor(color: readonly number[]): string {
+  return `rgba(${Math.round(clamp(color[0] ?? 0, 0, 1) * 255)},${Math.round(clamp(color[1] ?? 0, 0, 1) * 255)},${Math.round(clamp(color[2] ?? 0, 0, 1) * 255)},${clamp(color[3] ?? 1, 0, 1)})`;
+}
+
+function quoteFont(value: string): string { return `"${value.replace(/["\\]/g, '')}"`; }
+function closeTextTexture(texture: TextTexture | null, canvas: HTMLCanvasElement | null): void {
+  if (texture && texture !== canvas && typeof (texture as ImageBitmap).close === 'function') (texture as ImageBitmap).close();
+}
+function mix(a: number, b: number, t: number): number { return a + (b - a) * t; }
+function clamp(value: number, minimum: number, maximum: number): number { return Math.max(minimum, Math.min(maximum, value)); }

package/src/animation/AnimationVisual2D.ts

@@ -0,0 +1,153 @@
+import type { AnimationComposite, AnimationCompositeLayer, AnimationCompositeMode } from '@haiyue/animation-spec';
+import { Component, Geometry2D } from '@haiyue/engine';
+import { UniqueCheckType } from '@haiyue/engine/ecs';
+import type { AssetHandle } from '@haiyue/engine/assets';
+import type { AnimationTextRasterizer } from './AnimationTextRasterizer';
+
+export interface AnimationVisual2DOptions {
+  geometry: Geometry2D;
+  color: readonly [number, number, number, number];
+  instanceId: number;
+  nodeId: string;
+  order: number;
+  sourceOnly?: boolean;
+  composite?: Readonly<AnimationComposite>;
+  texture?: GPUTexture | null;
+  textureHandle?: AssetHandle<GPUTexture> | null;
+  textMaterial?: AnimationTextRasterizer | null;
+  /** Keeps sprites invisible until their asynchronous texture is ready. */
+  requiresTexture?: boolean;
+  uvRect?: readonly [number, number, number, number];
+  gradient?: AnimationVisualGradient | null;
+  effects?: readonly AnimationVisualEffect[];
+}
+
+export interface AnimationVisualGradient {
+  kind: 'linear' | 'radial';
+  start: [number, number];
+  end: [number, number];
+  /** Mutable packed offset,r,g,b,a tuples, bounded to eight stops. */
+  stops: Float32Array;
+  opacity: number;
+}
+
+export type AnimationVisualEffectKind = 'tint' | 'fill' | 'opacity' | 'color-matrix' | 'blur' | 'drop-shadow';
+
+export interface AnimationVisualEffect {
+  readonly kind: AnimationVisualEffectKind;
+  /** Mutable, kind-specific sampled values owned by the animation runtime. */
+  readonly values: Float32Array;
+}
+
+/** Runtime-private render item consumed by Animation2DRenderSystem. */
+export class AnimationVisual2D extends Component {
+  static override UniqueCheckType = UniqueCheckType.SYMBOL | UniqueCheckType.REPLACE;
+  static override UniqueSymbol = Symbol.for('AnimationVisual2D');
+
+  readonly geometry: Geometry2D;
+  readonly instanceId: number;
+  readonly nodeId: string;
+  readonly nodeKey: string;
+  readonly order: number;
+  readonly sourceOnly: boolean;
+  readonly compositeLayers: readonly Readonly<AnimationCompositeLayer>[];
+  readonly compositeKeys: readonly string[];
+  /** Compatibility accessors for single-layer renderer diagnostics. */
+  readonly compositeSource: string | undefined;
+  readonly compositeKey: string | undefined;
+  readonly compositeMode: AnimationCompositeMode | undefined;
+  readonly uvRect: [number, number, number, number];
+  readonly color: [number, number, number, number];
+  texture: GPUTexture | null;
+  textureHandle: AssetHandle<GPUTexture> | null;
+  readonly textMaterial: AnimationTextRasterizer | null;
+  readonly requiresTexture: boolean;
+  gradient: AnimationVisualGradient | null;
+  readonly effects: readonly AnimationVisualEffect[];
+  revision = 0;
+
+  constructor(options: AnimationVisual2DOptions) {
+    super('AnimationVisual2D');
+    this.geometry = options.geometry;
+    this.instanceId = options.instanceId;
+    this.nodeId = options.nodeId;
+    this.nodeKey = `${options.instanceId}:${options.nodeId}`;
+    this.order = options.order;
+    this.sourceOnly = options.sourceOnly ?? false;
+    this.compositeLayers = Object.freeze(options.composite
+      ? ('layers' in options.composite
+        ? options.composite.layers.map(layer => ({ ...layer }))
+        : [{ ...options.composite }])
+      : []);
+    this.compositeKeys = Object.freeze(this.compositeLayers.map(layer => `${options.instanceId}:${layer.source}`));
+    this.compositeSource = this.compositeLayers[0]?.source;
+    this.compositeKey = this.compositeKeys[0];
+    this.compositeMode = this.compositeLayers[0]?.mode;
+    this.uvRect = [...(options.uvRect ?? [0, 0, 1, 1])];
+    this.color = [...options.color];
+    this.texture = options.texture ?? null;
+    this.textureHandle = options.textureHandle ?? null;
+    this.textMaterial = options.textMaterial ?? null;
+    this.requiresTexture = options.requiresTexture ?? false;
+    this.gradient = options.gradient ?? null;
+    this.effects = Object.freeze(options.effects ? [...options.effects] : []);
+  }
+
+  setTexture(texture: GPUTexture | null): void {
+    if (this.texture === texture) return;
+    this.texture = texture;
+    this.revision++;
+  }
+
+  setTextureHandle(handle: AssetHandle<GPUTexture> | null): void {
+    if (this.textureHandle === handle) return;
+    this.textureHandle = handle;
+    this.revision++;
+  }
+
+  setUvRect(value: readonly [number, number, number, number]): void {
+    if (this.uvRect.every((current, index) => current === value[index])) return;
+    this.uvRect[0] = value[0];
+    this.uvRect[1] = value[1];
+    this.uvRect[2] = value[2];
+    this.uvRect[3] = value[3];
+    this.revision++;
+  }
+
+  setCompositeExpansion(index: number, value: number): void {
+    const layer = this.compositeLayers[index];
+    if (!layer || layer.expansion === value) return;
+    (layer as AnimationCompositeLayer).expansion = value;
+    this.revision++;
+  }
+
+  resolveTexture(): GPUTexture | null {
+    if (!this.textureHandle) return this.texture;
+    try { return this.textureHandle.value; } catch { return null; }
+  }
+
+  override clone(): AnimationVisual2D {
+    return new AnimationVisual2D({
+      geometry: this.geometry,
+      color: this.color,
+      instanceId: this.instanceId,
+      nodeId: this.nodeId,
+      order: this.order,
+      sourceOnly: this.sourceOnly,
+      ...(this.compositeLayers.length === 0 ? {} : { composite: { layers: this.compositeLayers } }),
+      texture: this.texture,
+      textureHandle: this.textureHandle,
+      textMaterial: this.textMaterial,
+      requiresTexture: this.requiresTexture,
+      uvRect: this.uvRect,
+      gradient: this.gradient ? {
+        kind: this.gradient.kind,
+        start: [...this.gradient.start],
+        end: [...this.gradient.end],
+        stops: new Float32Array(this.gradient.stops),
+        opacity: this.gradient.opacity,
+      } : null,
+      effects: this.effects.map(effect => ({ kind: effect.kind, values: new Float32Array(effect.values) })),
+    });
+  }
+}