@flighthq/render 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@flighthq/render",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.1.0",
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/materials": "0.1.0",
+    "@flighthq/node": "0.1.0",
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@flighthq/camera": "*",
+    "@flighthq/displayobject": "*",
+    "@flighthq/lighting": "*",
+    "@flighthq/mesh": "*",
+    "@flighthq/scene": "*",
+    "@flighthq/sprite": "*",
+    "typescript": "^5.3.0"
+  },
+  "description": "Renderer registration, render state, render queue, and backend draw contracts",
+  "sideEffects": false
+}

package/src/renderAppearance.test.ts

@@ -0,0 +1,109 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { invalidateNodeAppearance } from '@flighthq/node';
+import { BlendMode } from '@flighthq/types';
+
+import { updateRenderProxyAppearance } from './renderAppearance';
+import { createRenderProxy } from './renderProxy';
+import { createRenderState, getRenderStateRuntime } from './renderState';
+
+describe('updateRenderProxyAppearance', () => {
+  it('returns true on first call (lastAppearanceId starts at -1)', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    expect(updateRenderProxyAppearance(state, data)).toBe(true);
+  });
+
+  it('returns false when appearance has not changed since last call', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    updateRenderProxyAppearance(state, data);
+    expect(updateRenderProxyAppearance(state, data)).toBe(false);
+  });
+
+  it('returns true after invalidateNodeAppearance is called', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    updateRenderProxyAppearance(state, data);
+    invalidateNodeAppearance(obj);
+    expect(updateRenderProxyAppearance(state, data)).toBe(true);
+  });
+
+  it('returns true when parent appearanceFrameId matches currentFrameId', () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 5;
+    const obj = createDisplayObject();
+    const parentObj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    const parentData = createRenderProxy(state, parentObj);
+    updateRenderProxyAppearance(state, data);
+    parentData.appearanceFrameId = getRenderStateRuntime(state).currentFrameId;
+    expect(updateRenderProxyAppearance(state, data, parentData)).toBe(true);
+  });
+
+  it('propagates parent visibility: invisible parent makes child invisible', () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 1;
+    const obj = createDisplayObject();
+    obj.visible = true;
+    const parentObj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    const parentData = createRenderProxy(state, parentObj);
+    parentData.visible = false;
+    parentData.appearanceFrameId = getRenderStateRuntime(state).currentFrameId;
+    updateRenderProxyAppearance(state, data, parentData);
+    expect(data.visible).toBe(false);
+  });
+
+  it('multiplies alpha with parent alpha', () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 1;
+    const obj = createDisplayObject();
+    obj.alpha = 0.5;
+    const parentObj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    const parentData = createRenderProxy(state, parentObj);
+    parentData.visible = true;
+    parentData.alpha = 0.4;
+    parentData.appearanceFrameId = getRenderStateRuntime(state).currentFrameId;
+    updateRenderProxyAppearance(state, data, parentData);
+    expect(data.alpha).toBeCloseTo(0.2);
+  });
+
+  it('uses state renderAlpha when no parent', () => {
+    const state = createRenderState();
+    state.renderAlpha = 0.5;
+    const obj = createDisplayObject();
+    obj.alpha = 0.6;
+    const data = createRenderProxy(state, obj);
+    updateRenderProxyAppearance(state, data);
+    expect(data.alpha).toBeCloseTo(0.3);
+  });
+
+  it('sets appearanceFrameId to currentFrameId after update', () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 7;
+    const obj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    updateRenderProxyAppearance(state, data);
+    expect(data.appearanceFrameId).toBe(7);
+  });
+
+  it("uses the node's own blend mode and does not inherit from the parent", () => {
+    const state = createRenderState();
+    getRenderStateRuntime(state).currentFrameId = 1;
+    const obj = createDisplayObject();
+    obj.blendMode = BlendMode.Screen;
+    const parentObj = createDisplayObject();
+    const data = createRenderProxy(state, obj);
+    const parentData = createRenderProxy(state, parentObj);
+    parentData.blendMode = BlendMode.Multiply;
+    parentData.visible = true;
+    parentData.alpha = 1;
+    parentData.appearanceFrameId = getRenderStateRuntime(state).currentFrameId;
+    updateRenderProxyAppearance(state, data, parentData);
+    expect(data.blendMode).toBe(BlendMode.Screen);
+  });
+});

package/src/renderCache.test.ts

@@ -0,0 +1,151 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { connectSignal } from '@flighthq/signals';
+
+import {
+  createRenderCache,
+  createRenderCacheAdapter,
+  enableRenderCacheAdapterSignals,
+  getRenderProxyCache,
+  isRenderCache,
+  isRenderCacheAdapter,
+  registerRenderCacheRenderer,
+  RenderCacheKind,
+  useRenderCache,
+} from './renderCache';
+import { createRenderProxy2D } from './renderProxy';
+import { getRenderProxyAdapter } from './renderProxyAdapter';
+import { createRenderState, getRenderStateRuntime } from './renderState';
+
+describe('createRenderCache', () => {
+  it('creates a handle with the render cache kind and a transform', () => {
+    const cache = createRenderCache();
+    expect(cache.kind).toBe(RenderCacheKind);
+    expect(cache.transform).toBeDefined();
+  });
+});
+
+describe('createRenderCacheAdapter', () => {
+  it('adapt returns null and renders normally when no cache is attached', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    const adapter = createRenderCacheAdapter();
+    expect(adapter.adapt(state, obj, data)).toBeNull();
+  });
+
+  it('switches the render node to the cache kind and stops traversal, keeping the source node', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    const cache = createRenderCache();
+    cache.transform.tx = 7;
+    const adapter = createRenderCacheAdapter(cache);
+    const result = adapter.adapt(state, obj, data);
+    expect(result).toBe(false);
+    expect(data.kind).toBe(RenderCacheKind);
+    // Source stays the original node so the appearance/transform passes keep working each frame.
+    expect(data.source).toBe(obj);
+    expect(data.transform2D.tx).toBe(7);
+  });
+
+  it('emits onPrepare when signals are enabled', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const data = createRenderProxy2D(state, obj);
+    const adapter = createRenderCacheAdapter();
+    enableRenderCacheAdapterSignals(adapter);
+    const listener = vi.fn();
+    connectSignal(adapter.signals!.onPrepare, listener);
+    adapter.adapt(state, obj, data);
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('enableRenderCacheAdapterSignals', () => {
+  it('allocates the onPrepare signal', () => {
+    const adapter = createRenderCacheAdapter();
+    expect(adapter.signals).toBeNull();
+    enableRenderCacheAdapterSignals(adapter);
+    expect(adapter.signals).not.toBeNull();
+  });
+
+  it('is idempotent', () => {
+    const adapter = createRenderCacheAdapter();
+    enableRenderCacheAdapterSignals(adapter);
+    const signals = adapter.signals;
+    enableRenderCacheAdapterSignals(adapter);
+    expect(adapter.signals).toBe(signals);
+  });
+});
+
+describe('getRenderProxyCache', () => {
+  it('returns the cache attached to a source, or null when none', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    expect(getRenderProxyCache(state, obj as any)).toBeNull();
+    const cache = createRenderCache();
+    useRenderCache(state, obj as any, cache);
+    expect(getRenderProxyCache(state, obj as any)).toBe(cache);
+  });
+});
+
+describe('isRenderCache', () => {
+  it('returns true for a render cache handle', () => {
+    expect(isRenderCache(createRenderCache())).toBe(true);
+  });
+
+  it('returns false for other kinds and null', () => {
+    expect(isRenderCache({ kind: 'other' })).toBe(false);
+    expect(isRenderCache(null)).toBe(false);
+  });
+});
+
+describe('isRenderCacheAdapter', () => {
+  it('returns true for a render cache adapter', () => {
+    expect(isRenderCacheAdapter(createRenderCacheAdapter())).toBe(true);
+  });
+
+  it('returns false for objects missing adapt or cache, and null', () => {
+    expect(isRenderCacheAdapter({ cache: null })).toBe(false);
+    expect(isRenderCacheAdapter({ adapt: () => null })).toBe(false);
+    expect(isRenderCacheAdapter(null)).toBe(false);
+  });
+});
+
+describe('registerRenderCacheRenderer', () => {
+  it('registers the renderer for the render cache kind', () => {
+    const state = createRenderState();
+    const renderer = { createData: () => null, submit: vi.fn() };
+    registerRenderCacheRenderer(state, renderer as any);
+    expect(getRenderStateRuntime(state).rendererMap.get(RenderCacheKind)).toBe(renderer);
+  });
+});
+
+describe('useRenderCache', () => {
+  it('attaches a cache adapter to the source on the state', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const cache = createRenderCache();
+    const adapter = useRenderCache(state, obj as any, cache);
+    expect(getRenderProxyAdapter(state, obj as any)).toBe(adapter);
+    expect(adapter.cache).toBe(cache);
+  });
+
+  it('reuses an existing cache adapter and swaps the handle', () => {
+    const state = createRenderState();
+    const obj = createDisplayObject();
+    const first = useRenderCache(state, obj as any, createRenderCache());
+    const second = createRenderCache();
+    const adapter = useRenderCache(state, obj as any, second);
+    expect(adapter).toBe(first);
+    expect(adapter.cache).toBe(second);
+  });
+
+  it('isolates attachment between render states', () => {
+    const stateA = createRenderState();
+    const stateB = createRenderState();
+    const obj = createDisplayObject();
+    useRenderCache(stateA, obj as any, createRenderCache());
+    expect(getRenderProxyAdapter(stateB, obj as any)).toBeNull();
+  });
+});

package/src/renderColor.test.ts

@@ -0,0 +1,10 @@
+import { setRenderStateBackgroundColor } from './renderColor';
+import { createRenderState } from './renderState';
+
+describe('setRenderStateBackgroundColor', () => {
+  it('sets the background color on the render state', () => {
+    const state = createRenderState();
+    setRenderStateBackgroundColor(state, 0xff0000ff);
+    expect(state.backgroundColor).toBe(0xff0000ff);
+  });
+});

package/src/renderMaterial.test.ts

@@ -0,0 +1,30 @@
+import { createMaterial } from '@flighthq/materials';
+import type { Renderable } from '@flighthq/types';
+
+import { updateRenderProxyMaterial } from './renderMaterial';
+import { createRenderProxy } from './renderProxy';
+import { createRenderState } from './renderState';
+
+const TestKind = 'Test';
+
+describe('updateRenderProxyMaterial', () => {
+  it('resolves the source material and material data onto the render node', () => {
+    const state = createRenderState();
+    const material = createMaterial(TestKind);
+    const materialData = {};
+    const source = { kind: TestKind, material, materialData } as unknown as Renderable;
+    const data = createRenderProxy(state, source);
+    updateRenderProxyMaterial(state, data);
+    expect(data.material).toBe(material);
+    expect(data.materialData).toBe(materialData);
+  });
+
+  it('resolves to null when the source has no material', () => {
+    const state = createRenderState();
+    const source = { kind: TestKind } as unknown as Renderable;
+    const data = createRenderProxy(state, source);
+    updateRenderProxyMaterial(state, data);
+    expect(data.material).toBeNull();
+    expect(data.materialData).toBeNull();
+  });
+});