@flighthq/texture 0.3.0-next.1032.e2b99fc → 0.3.0-next.1220.6982c21

package/src/texture.test.ts

@@ -1,6 +1,7 @@
+import { createEntity } from '@flighthq/entity/contract';
 import { createMatrix3, createVector2, inverseMatrix3 } from '@flighthq/geometry/contract';
-import type { ImageResource } from '@flighthq/types/contract';
-import { ImageTextureBackingKind, RenderTextureBackingKind } from '@flighthq/types/contract';
+import type { Image, RenderTarget, Texture2D } from '@flighthq/types/contract';
+import { ImageTextureSourceKind, RenderTargetTextureSourceKind } from '@flighthq/types/contract';
 
 import { createSampler, equalsSampler } from './sampler';
 import {
@@ -8,17 +9,18 @@ import {
   copyTexture,
   createTexture,
   equalsTexture,
-  getTextureBackingKind,
+  getTextureSource,
+  getTextureSourceKind,
   getTextureHeight,
   getTextureInverseUvMatrix,
   getTextureUvMatrix,
   getTextureWidth,
-  hasTextureBacking,
+  hasTextureSource,
   hasTextureUvTransform,
   isTextureReady,
   resetTextureUvTransform,
   setTextureFlip,
-  setTextureImage,
+  setTextureSource,
   setTextureUvOffset,
   setTextureUvFromPixelRect,
   setTextureUvRotation,
@@ -26,7 +28,16 @@ import {
   transformTextureUv,
 } from './texture';
 
-const fakeImage = { height: 64, kind: ImageTextureBackingKind, width: 32 } as ImageResource;
+const fakeImage = { height: 64, kind: ImageTextureSourceKind, width: 32 } as Image;
+
+function makeRenderTarget(width: number, height: number): RenderTarget {
+  return createEntity({
+    height,
+    kind: RenderTargetTextureSourceKind,
+    version: 0,
+    width,
+  }) as RenderTarget;
+}
 
 // Applies a column-major 3×3 uv matrix to (u, v, 1), writing the transformed coordinate into out.
 function multiplyMatrix3Uv(out: { x: number; y: number }, matrix: { m: ArrayLike<number> }, u: number, v: number) {
@@ -39,7 +50,8 @@ describe('cloneTexture', () => {
   it('shares the image but deep-clones the sampler and uv vectors', () => {
     const source = createTexture({
       colorSpace: 'linear',
-      storage: { dimension: '2d', image: fakeImage },
+      dimension: '2d',
+      source: fakeImage,
       uvRotation: 0.5,
     });
     source.uvOffset.x = 0.25;
@@ -48,8 +60,8 @@ describe('cloneTexture', () => {
     const copy = cloneTexture(source);
 
     expect(copy).not.toBe(source);
-    expect(copy.storage).not.toBe(source.storage);
-    expect(copy.storage.image).toBe(fakeImage);
+    expect(copy.dimension).toBe('2d');
+    expect(getTextureSource(copy)).toBe(fakeImage);
     expect(copy.colorSpace).toStrictEqual('linear');
     expect(copy.uvRotation).toStrictEqual(0.5);
     expect(copy.sampler).not.toBe(source.sampler);
@@ -63,18 +75,13 @@ describe('cloneTexture', () => {
   });
 
   it('preserves a render-target descriptor while cloning sampling state', () => {
-    const target = {
-      colorSpace: 'linear' as const,
-      height: 32,
-      kind: RenderTextureBackingKind,
-      width: 64,
-    };
-    const source = createTexture({ storage: { dimension: '2d', image: null, target } });
+    const target = makeRenderTarget(64, 32);
+    target.colorSpace = 'linear';
+    const source = createTexture({ dimension: '2d', source: target });
 
     const copy = cloneTexture(source);
 
-    expect(copy.storage.target).toBe(target);
-    expect(copy.storage).not.toBe(source.storage);
+    expect(getTextureSource(copy)).toBe(target);
     expect(copy.sampler).not.toBe(source.sampler);
   });
 });
@@ -83,30 +90,30 @@ describe('copyTexture', () => {
   it('writes every field from source into a distinct out, preserving out entity identities', () => {
     const source = createTexture({
       colorSpace: 'linear',
-      storage: { dimension: '2d', image: fakeImage },
+      dimension: '2d',
+      source: fakeImage,
       uvRotation: 1,
     });
     source.uvScale.x = 4;
     const out = createTexture();
     const outSampler = out.sampler;
     const outOffset = out.uvOffset;
-    const outStorage = out.storage;
 
     copyTexture(out, source);
 
-    expect(out.storage.image).toBe(fakeImage);
+    expect(getTextureSource(out)).toBe(fakeImage);
     expect(out.colorSpace).toStrictEqual('linear');
     expect(out.uvRotation).toStrictEqual(1);
     expect(out.uvScale.x).toStrictEqual(4);
     expect(out.sampler).toBe(outSampler);
-    expect(out.storage).toBe(outStorage);
     expect(out.uvOffset).toBe(outOffset);
   });
 
   it('is safe when out aliases source', () => {
     const source = createTexture({
       colorSpace: 'linear',
-      storage: { dimension: '2d', image: fakeImage },
+      dimension: '2d',
+      source: fakeImage,
       uvRotation: 2,
     });
     source.uvScale.x = 7;
@@ -114,18 +121,30 @@ describe('copyTexture', () => {
     copyTexture(source, source);
 
     expect(source.colorSpace).toStrictEqual('linear');
-    expect(source.storage.image).toBe(fakeImage);
+    expect(getTextureSource(source)).toBe(fakeImage);
     expect(source.uvRotation).toStrictEqual(2);
     expect(source.uvScale.x).toStrictEqual(7);
   });
+
+  it('refuses to change the creation-time dimension', () => {
+    const out = createTexture();
+    const cube = createTexture({ dimension: 'cube' });
+
+    expect(() => copyTexture(out, cube)).toThrow('copyTexture requires matching dimensions');
+    expect(out.dimension).toBe('2d');
+    expect(out.source).toBeNull();
+  });
 });
 
 describe('createTexture', () => {
-  it('applies the default unbound, srgb, identity-transform state', () => {
+  it('creates a flat Texture2D with the default unbound, srgb, identity-transform state', () => {
     const texture = createTexture();
 
-    expect(texture.storage.image).toBeNull();
-    expect(texture.storage.dimension).toStrictEqual('2d');
+    expectTypeOf(texture).toEqualTypeOf<Texture2D>();
+    expect(texture).not.toHaveProperty('storage');
+    expect(texture.dimension).toStrictEqual('2d');
+    expect(texture.source).toBeNull();
+    expect(getTextureSource(texture)).toBeNull();
     expect(texture.colorSpace).toStrictEqual('srgb');
     expect(texture.version).toStrictEqual(0);
     expect(texture.uvRotation).toStrictEqual(0);
@@ -147,17 +166,17 @@ describe('createTexture', () => {
 
 describe('equalsTexture', () => {
   it('is true for textures with identical state and same image reference', () => {
-    const a = createTexture({ colorSpace: 'linear', storage: { dimension: '2d', image: fakeImage } });
-    const b = createTexture({ colorSpace: 'linear', storage: { dimension: '2d', image: fakeImage } });
+    const a = createTexture({ colorSpace: 'linear', dimension: '2d', source: fakeImage });
+    const b = createTexture({ colorSpace: 'linear', dimension: '2d', source: fakeImage });
 
     expect(equalsTexture(a, b)).toBe(true);
     expect(equalsTexture(a, a)).toBe(true);
   });
 
   it('is false when the image reference differs', () => {
-    const other = { width: 4, height: 4 } as ImageResource;
-    const a = createTexture({ storage: { dimension: '2d', image: fakeImage } });
-    const b = createTexture({ storage: { dimension: '2d', image: other } });
+    const other = { width: 4, height: 4 } as Image;
+    const a = createTexture({ dimension: '2d', source: fakeImage });
+    const b = createTexture({ dimension: '2d', source: other });
 
     expect(equalsTexture(a, b)).toBe(false);
   });
@@ -208,29 +227,9 @@ describe('equalsTexture', () => {
   });
 });
 
-describe('getTextureBackingKind', () => {
-  it('reads the key from the active image or target backing', () => {
-    expect(getTextureBackingKind(createTexture())).toBeNull();
-    expect(getTextureBackingKind(createTexture({ storage: { dimension: '2d', image: fakeImage } }))).toBe(
-      ImageTextureBackingKind,
-    );
-    expect(
-      getTextureBackingKind(
-        createTexture({
-          storage: {
-            dimension: '2d',
-            image: null,
-            target: { height: 8, kind: RenderTextureBackingKind, width: 8 },
-          },
-        }),
-      ),
-    ).toBe(RenderTextureBackingKind);
-  });
-});
-
 describe('getTextureHeight', () => {
   it('returns the image height when an image is bound', () => {
-    const texture = createTexture({ storage: { dimension: '2d', image: fakeImage } });
+    const texture = createTexture({ dimension: '2d', source: fakeImage });
 
     expect(getTextureHeight(texture)).toStrictEqual(64);
   });
@@ -241,13 +240,10 @@ describe('getTextureHeight', () => {
     expect(getTextureHeight(texture)).toStrictEqual(-1);
   });
 
-  it('returns the render target height when there is no CPU image', () => {
+  it('returns the render-target source height', () => {
     const texture = createTexture({
-      storage: {
-        dimension: '2d',
-        image: null,
-        target: { height: 48, kind: RenderTextureBackingKind, width: 96 },
-      },
+      dimension: '2d',
+      source: makeRenderTarget(96, 48),
     });
 
     expect(getTextureHeight(texture)).toStrictEqual(48);
@@ -289,6 +285,36 @@ describe('getTextureInverseUvMatrix', () => {
   });
 });
 
+describe('getTextureSource', () => {
+  it('returns the direct source and the first bound source in a layered texture', () => {
+    const direct = createTexture({ dimension: '2d', source: fakeImage });
+    const layered = createTexture({ dimension: '2d-array', sources: [null, fakeImage] });
+
+    expect(getTextureSource(direct)).toBe(fakeImage);
+    expect(getTextureSource(layered)).toBe(fakeImage);
+  });
+
+  it('returns null when every source slot is unbound', () => {
+    expect(getTextureSource(createTexture())).toBeNull();
+    expect(getTextureSource(createTexture({ dimension: '2d-array', sources: [null] }))).toBeNull();
+  });
+});
+
+describe('getTextureSourceKind', () => {
+  it('reads the key from the active source', () => {
+    expect(getTextureSourceKind(createTexture())).toBeNull();
+    expect(getTextureSourceKind(createTexture({ dimension: '2d', source: fakeImage }))).toBe(ImageTextureSourceKind);
+    expect(
+      getTextureSourceKind(
+        createTexture({
+          dimension: '2d',
+          source: makeRenderTarget(8, 8),
+        }),
+      ),
+    ).toBe(RenderTargetTextureSourceKind);
+  });
+});
+
 describe('getTextureUvMatrix', () => {
   it('produces the identity matrix for the default uv transform', () => {
     const texture = createTexture();
@@ -385,7 +411,7 @@ describe('getTextureUvMatrix', () => {
 
 describe('getTextureWidth', () => {
   it('returns the image width when an image is bound', () => {
-    const texture = createTexture({ storage: { dimension: '2d', image: fakeImage } });
+    const texture = createTexture({ dimension: '2d', source: fakeImage });
 
     expect(getTextureWidth(texture)).toStrictEqual(32);
   });
@@ -396,31 +422,25 @@ describe('getTextureWidth', () => {
     expect(getTextureWidth(texture)).toStrictEqual(-1);
   });
 
-  it('returns the render target width when there is no CPU image', () => {
+  it('returns the render-target source width', () => {
     const texture = createTexture({
-      storage: {
-        dimension: '2d',
-        image: null,
-        target: { height: 48, kind: RenderTextureBackingKind, width: 96 },
-      },
+      dimension: '2d',
+      source: makeRenderTarget(96, 48),
     });
 
     expect(getTextureWidth(texture)).toStrictEqual(96);
   });
 });
 
-describe('hasTextureBacking', () => {
-  it('detects image and target backings without duplicating their discriminant', () => {
-    expect(hasTextureBacking(createTexture())).toBe(false);
-    expect(hasTextureBacking(createTexture({ storage: { dimension: '2d', image: fakeImage } }))).toBe(true);
+describe('hasTextureSource', () => {
+  it('detects CPU and GPU sources through the same field', () => {
+    expect(hasTextureSource(createTexture())).toBe(false);
+    expect(hasTextureSource(createTexture({ dimension: '2d', source: fakeImage }))).toBe(true);
     expect(
-      hasTextureBacking(
+      hasTextureSource(
         createTexture({
-          storage: {
-            dimension: '2d',
-            image: null,
-            target: { height: 8, kind: RenderTextureBackingKind, width: 8 },
-          },
+          dimension: '2d',
+          source: makeRenderTarget(8, 8),
         }),
       ),
     ).toBe(true);
@@ -473,14 +493,14 @@ describe('isTextureReady', () => {
 
     expect(isTextureReady(texture)).toBe(false);
 
-    texture.storage.image = fakeImage;
+    setTextureSource(texture, fakeImage);
     expect(isTextureReady(texture)).toBe(true);
   });
 });
 
 describe('resetTextureUvTransform', () => {
   it('restores the identity transform while leaving image, color space, and sampler untouched', () => {
-    const texture = createTexture({ colorSpace: 'linear', storage: { dimension: '2d', image: fakeImage } });
+    const texture = createTexture({ colorSpace: 'linear', dimension: '2d', source: fakeImage });
     const sampler = texture.sampler;
     setTextureUvOffset(texture, 0.4, 0.6);
     setTextureUvRotation(texture, Math.PI);
@@ -494,7 +514,7 @@ describe('resetTextureUvTransform', () => {
     expect(texture.uvScale.x).toStrictEqual(1);
     expect(texture.uvScale.y).toStrictEqual(1);
     expect(texture.colorSpace).toStrictEqual('linear');
-    expect(texture.storage.image).toBe(fakeImage);
+    expect(getTextureSource(texture)).toBe(fakeImage);
     expect(texture.sampler).toBe(sampler);
   });
 });
@@ -512,19 +532,19 @@ describe('setTextureFlip', () => {
   });
 });
 
-describe('setTextureImage', () => {
+describe('setTextureSource', () => {
   it('binds and clears the image in place and advances the u32 version', () => {
     const texture = createTexture();
 
-    setTextureImage(texture, fakeImage);
-    expect(texture.storage.image).toBe(fakeImage);
+    setTextureSource(texture, fakeImage);
+    expect(getTextureSource(texture)).toBe(fakeImage);
     expect(texture.version).toStrictEqual(1);
 
-    setTextureImage(texture, fakeImage);
+    setTextureSource(texture, fakeImage);
     expect(texture.version).toStrictEqual(1);
 
-    setTextureImage(texture, null);
-    expect(texture.storage.image).toBeNull();
+    setTextureSource(texture, null);
+    expect(getTextureSource(texture)).toBeNull();
     expect(texture.version).toStrictEqual(2);
   });
 });
@@ -532,7 +552,8 @@ describe('setTextureImage', () => {
 describe('setTextureUvFromPixelRect', () => {
   it('normalizes a pixel rectangle against the texture dimensions', () => {
     const texture = createTexture({
-      storage: { dimension: '2d', image: { height: 100, width: 200 } as ImageResource },
+      dimension: '2d',
+      source: { height: 100, width: 200 } as Image,
     });
     setTextureUvFromPixelRect(texture, 20, 10, 50, 25);
     expect(texture.uvOffset.x).toBeCloseTo(0.1);

package/src/videoTexture.test.ts

@@ -1,6 +1,7 @@
 import { createMatrix3, createVector2 } from '@flighthq/geometry/contract';
-import type { ImageResource, VideoResource } from '@flighthq/types/contract';
+import type { Image, VideoResource } from '@flighthq/types/contract';
 
+import { getTextureSource } from './texture';
 import {
   advanceVideoTexture,
   cloneVideoTexture,
@@ -19,27 +20,28 @@ import {
 function makeVideoResource(readyState = 4, videoWidth = 320, videoHeight = 240): VideoResource {
   return {
     element: { readyState, videoWidth, videoHeight } as unknown as HTMLVideoElement,
+    objectUrl: null,
   };
 }
 
 describe('advanceVideoTexture', () => {
-  it('bumps the backing and Texture versions and returns the new value', () => {
+  it('bumps the source and Texture versions and returns the new value', () => {
     const vt = createVideoTexture(makeVideoResource());
     expect(vt.version).toBe(0xffffffff);
     expect(advanceVideoTexture(vt)).toBe(0);
     expect(advanceVideoTexture(vt)).toBe(1);
     expect(vt.version).toBe(1);
-    expect(vt.storage.image?.version).toBe(1);
+    expect(getTextureSource(vt)?.version).toBe(1);
   });
 });
 
 describe('cloneVideoTexture', () => {
-  it('shares the backing but deep-clones sampler and uv vectors', () => {
+  it('shares the source but deep-clones sampler and uv vectors', () => {
     const source = makeVideoResource();
     const vt = createVideoTexture(source, { uvOffset: createVector2(2, 3) });
     advanceVideoTexture(vt);
     const clone = cloneVideoTexture(vt);
-    expect(clone.storage.image).toBe(vt.storage.image);
+    expect(getTextureSource(clone)).toBe(getTextureSource(vt));
     expect(clone.sampler).not.toBe(vt.sampler);
     expect(clone.uvOffset).not.toBe(vt.uvOffset);
     expect(clone.uvOffset.x).toBe(2);
@@ -55,7 +57,7 @@ describe('copyVideoTexture', () => {
     copyVideoTexture(b, a);
     expect(b.colorSpace).toBe('linear');
     expect(b.version).toBe(0);
-    expect(b.storage.image).toBe(a.storage.image);
+    expect(getTextureSource(b)).toBe(getTextureSource(a));
     expect(b.uvScale.x).toBe(4);
     copyVideoTexture(a, a);
     expect(a.uvScale.x).toBe(4);
@@ -63,11 +65,11 @@ describe('copyVideoTexture', () => {
 });
 
 describe('createVideoTexture', () => {
-  it('returns a universal srgb Texture with a borrowed host-image backing', () => {
+  it('returns a universal srgb Texture with a borrowed host-image source', () => {
     const source = makeVideoResource();
     const vt = createVideoTexture(source);
     expect(vt.colorSpace).toBe('srgb');
-    expect((vt.storage.image as ImageResource).source).toBe(source.element);
+    expect((getTextureSource(vt) as Image).source).toBe(source.element);
     expect(vt.version).toBe(0xffffffff);
     expect(vt.uvOffset.x).toBe(0);
     expect(vt.uvScale.x).toBe(1);
@@ -79,7 +81,7 @@ describe('getVideoTextureHeight', () => {
   it('returns the element videoHeight when a frame is decoded, else -1', () => {
     expect(getVideoTextureHeight(createVideoTexture(makeVideoResource(4, 320, 240)))).toBe(240);
     expect(getVideoTextureHeight(createVideoTexture(makeVideoResource(0, 0, 0)))).toBe(-1);
-    expect(getVideoTextureHeight(createVideoTexture({ element: null }))).toBe(-1);
+    expect(getVideoTextureHeight(createVideoTexture({ element: null, objectUrl: null }))).toBe(-1);
   });
 });
 
@@ -122,7 +124,7 @@ describe('getVideoTextureWidth', () => {
   it('returns the element videoWidth when a frame is decoded, else -1', () => {
     expect(getVideoTextureWidth(createVideoTexture(makeVideoResource(4, 320, 240)))).toBe(320);
     expect(getVideoTextureWidth(createVideoTexture(makeVideoResource(0, 0, 0)))).toBe(-1);
-    expect(getVideoTextureWidth(createVideoTexture({ element: null }))).toBe(-1);
+    expect(getVideoTextureWidth(createVideoTexture({ element: null, objectUrl: null }))).toBe(-1);
   });
 });
 
@@ -131,7 +133,7 @@ describe('isVideoTextureFrameReady', () => {
     expect(isVideoTextureFrameReady(createVideoTexture(makeVideoResource(4, 320, 240)))).toBe(true);
     expect(isVideoTextureFrameReady(createVideoTexture(makeVideoResource(1, 320, 240)))).toBe(false);
     expect(isVideoTextureFrameReady(createVideoTexture(makeVideoResource(4, 0, 0)))).toBe(false);
-    expect(isVideoTextureFrameReady(createVideoTexture({ element: null }))).toBe(false);
+    expect(isVideoTextureFrameReady(createVideoTexture({ element: null, objectUrl: null }))).toBe(false);
   });
 });
 
@@ -142,7 +144,7 @@ describe('resetVideoTextureFrame', () => {
     advanceVideoTexture(vt);
     resetVideoTextureFrame(vt);
     expect(vt.version).toBe(0xffffffff);
-    expect(vt.storage.image?.version).toBe(0xffffffff);
+    expect(getTextureSource(vt)?.version).toBe(0xffffffff);
   });
 });
 
@@ -152,7 +154,7 @@ describe('setVideoTextureSource', () => {
     advanceVideoTexture(vt);
     const next = makeVideoResource(4, 640, 480);
     setVideoTextureSource(vt, next);
-    expect((vt.storage.image as ImageResource).source).toBe(next.element);
+    expect((getTextureSource(vt) as Image).source).toBe(next.element);
     expect(vt.version).toBe(0xffffffff);
     expect(getVideoTextureWidth(vt)).toBe(640);
   });

package/src/voxelGrid.test.ts

@@ -0,0 +1,37 @@
+import { createEntity } from '@flighthq/entity/contract';
+import type { VoxelGrid } from '@flighthq/types/contract';
+import { VoxelGridTextureSourceKind } from '@flighthq/types/contract';
+
+import { invalidateVoxelGrid } from './voxelGrid';
+
+function voxelGrid(version: number): VoxelGrid {
+  return createEntity({
+    data: new Uint8Array(32),
+    depth: 2,
+    format: 'rgba8unorm' as const,
+    height: 2,
+    kind: VoxelGridTextureSourceKind,
+    version,
+    width: 2,
+  }) as VoxelGrid;
+}
+
+describe('invalidateVoxelGrid', () => {
+  it('advances the shared content version without replacing voxel bytes', () => {
+    const grid = voxelGrid(0);
+    const data = grid.data;
+
+    invalidateVoxelGrid(grid);
+
+    expect(grid.version).toBe(1);
+    expect(grid.data).toBe(data);
+  });
+
+  it('wraps the content version as u32', () => {
+    const grid = voxelGrid(0xffffffff);
+
+    invalidateVoxelGrid(grid);
+
+    expect(grid.version).toBe(0);
+  });
+});