@flighthq/render 0.3.0-next.1032.e2b99fc → 0.3.0-next.1162.e90e518

package/dist/renderTarget.d.ts

@@ -1,4 +1,4 @@
-import type { Node2D, MatrixLike, RectangleLike } from '@flighthq/types/contract';
+import type { MatrixLike, Node2D, RectangleLike, RenderTargetAxes, RenderTargetAxisDifference, RenderTargetDescriptor, ResolvedRenderTargetDescriptor } from '@flighthq/types/contract';
 /**
  * Writes into outCacheTransform the transform to pass to the cache resolver so the
  * cached image is placed back at the original scene position.
@@ -14,4 +14,6 @@ export declare function computeRenderTargetSize(bounds: Readonly<RectangleLike>,
  * that the bounds origin lands at (contentX, contentY).
  */
 export declare function computeScene2DRenderTargetTransform(outRenderTransform: MatrixLike, source: Node2D, bounds: Readonly<RectangleLike>, contentX?: number, contentY?: number): void;
+export declare function explainRenderTargetAxes(requested: Readonly<RenderTargetAxes>, effective: Readonly<RenderTargetAxes>): RenderTargetAxisDifference[];
+export declare function resolveRenderTargetDescriptor(descriptor: Readonly<RenderTargetDescriptor>): ResolvedRenderTargetDescriptor;
 //# sourceMappingURL=renderTarget.d.ts.map

package/dist/renderTarget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderTarget.d.ts","sourceRoot":"","sources":["../src/renderTarget.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,iBAAiB,EAAE,UAAU,EAC7B,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,QAAQ,GAAE,MAAU,EACpB,QAAQ,GAAE,MAAU,GACnB,IAAI,CAON;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,OAAO,GAAE,MAAU,EACnB,QAAQ,GAAE,MAAU,EACpB,SAAS,GAAE,MAAU,GACpB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKnC;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,kBAAkB,EAAE,UAAU,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,QAAQ,GAAE,MAAU,EACpB,QAAQ,GAAE,MAAU,GACnB,IAAI,CAUN"}
+{"version":3,"file":"renderTarget.d.ts","sourceRoot":"","sources":["../src/renderTarget.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,aAAa,EACb,gBAAgB,EAChB,0BAA0B,EAC1B,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,0BAA0B,CAAC;AAElC;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,iBAAiB,EAAE,UAAU,EAC7B,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,QAAQ,GAAE,MAAU,EACpB,QAAQ,GAAE,MAAU,GACnB,IAAI,CAON;AAED,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,OAAO,GAAE,MAAU,EACnB,QAAQ,GAAE,MAAU,EACpB,SAAS,GAAE,MAAU,GACpB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKnC;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,kBAAkB,EAAE,UAAU,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,EAC/B,QAAQ,GAAE,MAAU,EACpB,QAAQ,GAAE,MAAU,GACnB,IAAI,CAUN;AAID,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EACrC,SAAS,EAAE,QAAQ,CAAC,gBAAgB,CAAC,GACpC,0BAA0B,EAAE,CAa9B;AAKD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GAC3C,8BAA8B,CAsBhC"}

package/dist/renderTarget.js

@@ -34,6 +34,54 @@ export function computeScene2DRenderTargetTransform(outRenderTransform, source,
     _tempTranslation.ty = contentY - bounds.y;
     multiplyMatrix(outRenderTransform, _tempTranslation, _tempInvLocal);
 }
+// Returns plain-data axis differences in a stable order. Backends retain the requested and effective
+// shapes, then use this common comparison so every explain* surface reports substitutions uniformly.
+export function explainRenderTargetAxes(requested, effective) {
+    const differences = [];
+    for (const axis of _renderTargetAxisOrder) {
+        const requestedValue = requested[axis];
+        const effectiveValue = effective[axis];
+        const equal = Array.isArray(requestedValue) && Array.isArray(effectiveValue)
+            ? requestedValue.length === effectiveValue.length &&
+                requestedValue.every((value, index) => value === effectiveValue[index])
+            : requestedValue === effectiveValue;
+        if (!equal)
+            differences.push({ axis, effective: effectiveValue, requested: requestedValue });
+    }
+    return differences;
+}
+// Resolves every substrate-independent default and normalization once. Backend realizations start
+// here and apply only device capability substitutions (for example GL MAX_SAMPLES or float-render
+// support), so Canvas/GL/WGPU cannot independently reinterpret the descriptor's optional axes.
+export function resolveRenderTargetDescriptor(descriptor) {
+    const width = Math.max(1, Math.ceil(descriptor.width));
+    const height = Math.max(1, Math.ceil(descriptor.height));
+    const colorAttachments = Math.max(1, Math.ceil(descriptor.colorAttachments ?? 1));
+    const defaultFormat = descriptor.format ?? 'rgba8';
+    const colorFormats = Array.from({ length: colorAttachments }, (_, index) => descriptor.colorFormats?.[index] ?? defaultFormat);
+    return {
+        width,
+        height,
+        format: colorFormats[0],
+        colorAttachments,
+        colorFormats,
+        sampleCount: Math.max(1, Math.ceil(descriptor.sampleCount ?? 1)),
+        depth: descriptor.depth ?? 'none',
+        colorSpace: descriptor.colorSpace ?? 'srgb',
+        clearColors: descriptor.clearColors ? [...descriptor.clearColors] : [],
+        clearDepth: descriptor.clearDepth ?? 1,
+    };
+}
 const _tempInvLocal = createMatrix();
 const _tempTranslation = createMatrix();
+const _renderTargetAxisOrder = [
+    'width',
+    'height',
+    'format',
+    'colorAttachments',
+    'colorFormats',
+    'sampleCount',
+    'depth',
+    'colorSpace',
+];
 //# sourceMappingURL=renderTarget.js.map

package/dist/renderTarget.js.map

@@ -1 +1 @@
-{"version":3,"file":"renderTarget.js","sourceRoot":"","sources":["../src/renderTarget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,iBAA6B,EAC7B,MAA+B,EAC/B,WAAmB,CAAC,EACpB,WAAmB,CAAC;IAEpB,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC;IACxB,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC;IACxB,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC;IACxB,iBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC;IACxB,iBAAiB,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC;IAC3C,iBAAiB,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAA+B,EAC/B,UAAkB,CAAC,EACnB,WAAmB,CAAC,EACpB,YAAoB,CAAC;IAErB,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC;QAChE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mCAAmC,CACjD,kBAA8B,EAC9B,MAAc,EACd,MAA+B,EAC/B,WAAmB,CAAC,EACpB,WAAmB,CAAC;IAEpB,MAAM,cAAc,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAClD,aAAa,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC7C,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC;IACvB,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC;IACvB,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC;IACvB,gBAAgB,CAAC,CAAC,GAAG,CAAC,CAAC;IACvB,gBAAgB,CAAC,EAAE,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC;IAC1C,gBAAgB,CAAC,EAAE,GAAG,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC;IAC1C,cAAc,CAAC,kBAAkB,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,aAAa,GAAG,YAAY,EAAE,CAAC;AACrC,MAAM,gBAAgB,GAAG,YAAY,EAAE,CAAC"}
+{"version":3,"file":"renderTarget.js","sourceRoot":"","sources":["../src/renderTarget.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/render",
-  "version": "0.3.0-next.1032.e2b99fc",
+  "version": "0.3.0-next.1162.e90e518",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,15 +36,15 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/color": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/entity": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/geometry": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/log": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/materials": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/mesh": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/node": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/signals": "0.3.0-next.1032.e2b99fc",
-    "@flighthq/types": "0.3.0-next.1032.e2b99fc"
+    "@flighthq/color": "0.3.0-next.1162.e90e518",
+    "@flighthq/entity": "0.3.0-next.1162.e90e518",
+    "@flighthq/geometry": "0.3.0-next.1162.e90e518",
+    "@flighthq/log": "0.3.0-next.1162.e90e518",
+    "@flighthq/materials": "0.3.0-next.1162.e90e518",
+    "@flighthq/mesh": "0.3.0-next.1162.e90e518",
+    "@flighthq/node": "0.3.0-next.1162.e90e518",
+    "@flighthq/signals": "0.3.0-next.1162.e90e518",
+    "@flighthq/types": "0.3.0-next.1162.e90e518"
   },
   "devDependencies": {
     "@flighthq/adjustments": "*",

package/src/renderTarget.test.ts

@@ -2,9 +2,11 @@ import { createMatrix, createRectangle } from '@flighthq/geometry/contract';
 import { createDisplayObject } from '@flighthq/scene2d/contract';
 
 import {
-  computeScene2DRenderTargetTransform,
   computeRenderCacheTransform,
   computeRenderTargetSize,
+  computeScene2DRenderTargetTransform,
+  explainRenderTargetAxes,
+  resolveRenderTargetDescriptor,
 } from './renderTarget';
 
 describe('computeRenderCacheTransform', () => {
@@ -82,3 +84,88 @@ describe('computeScene2DRenderTargetTransform', () => {
     expect(() => computeScene2DRenderTargetTransform(out, obj, bounds)).not.toThrow();
   });
 });
+
+describe('resolveRenderTargetDescriptor', () => {
+  it('resolves every optional target axis and clear policy', () => {
+    expect(resolveRenderTargetDescriptor({ width: 64, height: 48 })).toEqual({
+      width: 64,
+      height: 48,
+      format: 'rgba8',
+      colorAttachments: 1,
+      colorFormats: ['rgba8'],
+      sampleCount: 1,
+      depth: 'none',
+      colorSpace: 'srgb',
+      clearColors: [],
+      clearDepth: 1,
+    });
+  });
+
+  describe('explainRenderTargetAxes', () => {
+    it('reports every changed axis in stable descriptor order', () => {
+      const requested = resolveRenderTargetDescriptor({
+        width: 64,
+        height: 48,
+        format: 'rgba16f',
+        colorAttachments: 2,
+        sampleCount: 8,
+        depth: 'depth-stencil-sampled',
+      });
+      const effective = {
+        ...requested,
+        format: 'rgba8' as const,
+        colorFormats: ['rgba8', 'rgba8'] as const,
+        sampleCount: 4,
+        depth: 'depth-stencil' as const,
+      };
+
+      expect(explainRenderTargetAxes(requested, effective)).toEqual([
+        { axis: 'format', effective: 'rgba8', requested: 'rgba16f' },
+        { axis: 'colorFormats', effective: ['rgba8', 'rgba8'], requested: ['rgba16f', 'rgba16f'] },
+        { axis: 'sampleCount', effective: 4, requested: 8 },
+        { axis: 'depth', effective: 'depth-stencil', requested: 'depth-stencil-sampled' },
+      ]);
+    });
+
+    it('returns no differences for identical canonical axes', () => {
+      const axes = resolveRenderTargetDescriptor({ width: 64, height: 48 });
+      expect(explainRenderTargetAxes(axes, { ...axes, colorFormats: [...axes.colorFormats] })).toEqual([]);
+    });
+  });
+
+  it('normalizes dimensions, attachment count, and sample count once', () => {
+    expect(
+      resolveRenderTargetDescriptor({
+        width: 10.2,
+        height: 0,
+        colorAttachments: 1.2,
+        sampleCount: 3.1,
+      }),
+    ).toMatchObject({
+      width: 11,
+      height: 1,
+      colorAttachments: 2,
+      sampleCount: 4,
+    });
+  });
+
+  it('expands heterogeneous color formats across every requested attachment', () => {
+    const resolved = resolveRenderTargetDescriptor({
+      width: 64,
+      height: 48,
+      format: 'rgba16f',
+      colorAttachments: 3,
+      colorFormats: ['rgba8', 'rgba32f'],
+    });
+
+    expect(resolved.format).toBe('rgba8');
+    expect(resolved.colorFormats).toEqual(['rgba8', 'rgba32f', 'rgba16f']);
+  });
+
+  it('copies caller-owned clear arrays', () => {
+    const clearColors = [0xff0000ff];
+    const resolved = resolveRenderTargetDescriptor({ width: 64, height: 48, clearColors });
+    clearColors[0] = 0;
+    expect(resolved.clearColors).toEqual([0xff0000ff]);
+  });
+});