@flighthq/texture 0.2.1-next.841.373388f → 0.3.0-next.1032.e2b99fc

package/src/texture.test.ts

@@ -1,5 +1,6 @@
-import { createMatrix3, createVector2, inverseMatrix3 } from '@flighthq/geometry';
-import type { ImageResource } from '@flighthq/types';
+import { createMatrix3, createVector2, inverseMatrix3 } from '@flighthq/geometry/contract';
+import type { ImageResource } from '@flighthq/types/contract';
+import { ImageTextureBackingKind, RenderTextureBackingKind } from '@flighthq/types/contract';
 
 import { createSampler, equalsSampler } from './sampler';
 import {
@@ -7,22 +8,25 @@ import {
   copyTexture,
   createTexture,
   equalsTexture,
+  getTextureBackingKind,
   getTextureHeight,
   getTextureInverseUvMatrix,
   getTextureUvMatrix,
   getTextureWidth,
+  hasTextureBacking,
   hasTextureUvTransform,
   isTextureReady,
   resetTextureUvTransform,
   setTextureFlip,
   setTextureImage,
   setTextureUvOffset,
+  setTextureUvFromPixelRect,
   setTextureUvRotation,
   setTextureUvScale,
   transformTextureUv,
 } from './texture';
 
-const fakeImage = { width: 32, height: 64 } as ImageResource;
+const fakeImage = { height: 64, kind: ImageTextureBackingKind, width: 32 } as ImageResource;
 
 // 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) {
@@ -35,7 +39,7 @@ describe('cloneTexture', () => {
   it('shares the image but deep-clones the sampler and uv vectors', () => {
     const source = createTexture({
       colorSpace: 'linear',
-      image: fakeImage,
+      storage: { dimension: '2d', image: fakeImage },
       uvRotation: 0.5,
     });
     source.uvOffset.x = 0.25;
@@ -44,7 +48,8 @@ describe('cloneTexture', () => {
     const copy = cloneTexture(source);
 
     expect(copy).not.toBe(source);
-    expect(copy.image).toBe(fakeImage);
+    expect(copy.storage).not.toBe(source.storage);
+    expect(copy.storage.image).toBe(fakeImage);
     expect(copy.colorSpace).toStrictEqual('linear');
     expect(copy.uvRotation).toStrictEqual(0.5);
     expect(copy.sampler).not.toBe(source.sampler);
@@ -56,34 +61,60 @@ describe('cloneTexture', () => {
     copy.uvOffset.x = 0.9;
     expect(source.uvOffset.x).toStrictEqual(0.25);
   });
+
+  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 copy = cloneTexture(source);
+
+    expect(copy.storage.target).toBe(target);
+    expect(copy.storage).not.toBe(source.storage);
+    expect(copy.sampler).not.toBe(source.sampler);
+  });
 });
 
 describe('copyTexture', () => {
   it('writes every field from source into a distinct out, preserving out entity identities', () => {
-    const source = createTexture({ colorSpace: 'linear', image: fakeImage, uvRotation: 1 });
+    const source = createTexture({
+      colorSpace: 'linear',
+      storage: { dimension: '2d', image: 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.image).toBe(fakeImage);
+    expect(out.storage.image).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', image: fakeImage, uvRotation: 2 });
+    const source = createTexture({
+      colorSpace: 'linear',
+      storage: { dimension: '2d', image: fakeImage },
+      uvRotation: 2,
+    });
     source.uvScale.x = 7;
 
     copyTexture(source, source);
 
     expect(source.colorSpace).toStrictEqual('linear');
-    expect(source.image).toBe(fakeImage);
+    expect(source.storage.image).toBe(fakeImage);
     expect(source.uvRotation).toStrictEqual(2);
     expect(source.uvScale.x).toStrictEqual(7);
   });
@@ -93,8 +124,10 @@ describe('createTexture', () => {
   it('applies the default unbound, srgb, identity-transform state', () => {
     const texture = createTexture();
 
-    expect(texture.image).toBeNull();
+    expect(texture.storage.image).toBeNull();
+    expect(texture.storage.dimension).toStrictEqual('2d');
     expect(texture.colorSpace).toStrictEqual('srgb');
+    expect(texture.version).toStrictEqual(0);
     expect(texture.uvRotation).toStrictEqual(0);
     expect(texture.uvOffset.x).toStrictEqual(0);
     expect(texture.uvOffset.y).toStrictEqual(0);
@@ -114,8 +147,8 @@ describe('createTexture', () => {
 
 describe('equalsTexture', () => {
   it('is true for textures with identical state and same image reference', () => {
-    const a = createTexture({ image: fakeImage, colorSpace: 'linear' });
-    const b = createTexture({ image: fakeImage, colorSpace: 'linear' });
+    const a = createTexture({ colorSpace: 'linear', storage: { dimension: '2d', image: fakeImage } });
+    const b = createTexture({ colorSpace: 'linear', storage: { dimension: '2d', image: fakeImage } });
 
     expect(equalsTexture(a, b)).toBe(true);
     expect(equalsTexture(a, a)).toBe(true);
@@ -123,8 +156,8 @@ describe('equalsTexture', () => {
 
   it('is false when the image reference differs', () => {
     const other = { width: 4, height: 4 } as ImageResource;
-    const a = createTexture({ image: fakeImage });
-    const b = createTexture({ image: other });
+    const a = createTexture({ storage: { dimension: '2d', image: fakeImage } });
+    const b = createTexture({ storage: { dimension: '2d', image: other } });
 
     expect(equalsTexture(a, b)).toBe(false);
   });
@@ -175,9 +208,29 @@ 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({ image: fakeImage });
+    const texture = createTexture({ storage: { dimension: '2d', image: fakeImage } });
 
     expect(getTextureHeight(texture)).toStrictEqual(64);
   });
@@ -187,6 +240,18 @@ describe('getTextureHeight', () => {
 
     expect(getTextureHeight(texture)).toStrictEqual(-1);
   });
+
+  it('returns the render target height when there is no CPU image', () => {
+    const texture = createTexture({
+      storage: {
+        dimension: '2d',
+        image: null,
+        target: { height: 48, kind: RenderTextureBackingKind, width: 96 },
+      },
+    });
+
+    expect(getTextureHeight(texture)).toStrictEqual(48);
+  });
 });
 
 describe('getTextureInverseUvMatrix', () => {
@@ -320,7 +385,7 @@ describe('getTextureUvMatrix', () => {
 
 describe('getTextureWidth', () => {
   it('returns the image width when an image is bound', () => {
-    const texture = createTexture({ image: fakeImage });
+    const texture = createTexture({ storage: { dimension: '2d', image: fakeImage } });
 
     expect(getTextureWidth(texture)).toStrictEqual(32);
   });
@@ -330,6 +395,36 @@ describe('getTextureWidth', () => {
 
     expect(getTextureWidth(texture)).toStrictEqual(-1);
   });
+
+  it('returns the render target width when there is no CPU image', () => {
+    const texture = createTexture({
+      storage: {
+        dimension: '2d',
+        image: null,
+        target: { height: 48, kind: RenderTextureBackingKind, width: 96 },
+      },
+    });
+
+    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);
+    expect(
+      hasTextureBacking(
+        createTexture({
+          storage: {
+            dimension: '2d',
+            image: null,
+            target: { height: 8, kind: RenderTextureBackingKind, width: 8 },
+          },
+        }),
+      ),
+    ).toBe(true);
+  });
 });
 
 describe('hasTextureUvTransform', () => {
@@ -378,14 +473,14 @@ describe('isTextureReady', () => {
 
     expect(isTextureReady(texture)).toBe(false);
 
-    texture.image = fakeImage;
+    texture.storage.image = 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', image: fakeImage });
+    const texture = createTexture({ colorSpace: 'linear', storage: { dimension: '2d', image: fakeImage } });
     const sampler = texture.sampler;
     setTextureUvOffset(texture, 0.4, 0.6);
     setTextureUvRotation(texture, Math.PI);
@@ -399,7 +494,7 @@ describe('resetTextureUvTransform', () => {
     expect(texture.uvScale.x).toStrictEqual(1);
     expect(texture.uvScale.y).toStrictEqual(1);
     expect(texture.colorSpace).toStrictEqual('linear');
-    expect(texture.image).toBe(fakeImage);
+    expect(texture.storage.image).toBe(fakeImage);
     expect(texture.sampler).toBe(sampler);
   });
 });
@@ -418,14 +513,39 @@ describe('setTextureFlip', () => {
 });
 
 describe('setTextureImage', () => {
-  it('binds and clears the image in place', () => {
+  it('binds and clears the image in place and advances the u32 version', () => {
     const texture = createTexture();
 
     setTextureImage(texture, fakeImage);
-    expect(texture.image).toBe(fakeImage);
+    expect(texture.storage.image).toBe(fakeImage);
+    expect(texture.version).toStrictEqual(1);
+
+    setTextureImage(texture, fakeImage);
+    expect(texture.version).toStrictEqual(1);
 
     setTextureImage(texture, null);
-    expect(texture.image).toBeNull();
+    expect(texture.storage.image).toBeNull();
+    expect(texture.version).toStrictEqual(2);
+  });
+});
+
+describe('setTextureUvFromPixelRect', () => {
+  it('normalizes a pixel rectangle against the texture dimensions', () => {
+    const texture = createTexture({
+      storage: { dimension: '2d', image: { height: 100, width: 200 } as ImageResource },
+    });
+    setTextureUvFromPixelRect(texture, 20, 10, 50, 25);
+    expect(texture.uvOffset.x).toBeCloseTo(0.1);
+    expect(texture.uvOffset.y).toBeCloseTo(0.1);
+    expect(texture.uvScale.x).toBeCloseTo(0.25);
+    expect(texture.uvScale.y).toBeCloseTo(0.25);
+  });
+
+  it('sets an empty window when the texture has no dimensions', () => {
+    const texture = createTexture();
+    setTextureUvFromPixelRect(texture, 20, 10, 50, 25);
+    expect(texture.uvOffset).toMatchObject({ x: 0, y: 0 });
+    expect(texture.uvScale).toMatchObject({ x: 0, y: 0 });
   });
 });
 

package/src/videoTexture.test.ts

@@ -1,5 +1,5 @@
-import { createMatrix3, createVector2 } from '@flighthq/geometry';
-import type { VideoResource } from '@flighthq/types';
+import { createMatrix3, createVector2 } from '@flighthq/geometry/contract';
+import type { ImageResource, VideoResource } from '@flighthq/types/contract';
 
 import {
   advanceVideoTexture,
@@ -15,7 +15,7 @@ import {
   setVideoTextureSource,
 } from './videoTexture';
 
-// A minimal element carrier: only the fields the VideoTexture accessors read.
+// A minimal borrowed host element: only the fields the video-backed Texture accessors read.
 function makeVideoResource(readyState = 4, videoWidth = 320, videoHeight = 240): VideoResource {
   return {
     element: { readyState, videoWidth, videoHeight } as unknown as HTMLVideoElement,
@@ -23,26 +23,27 @@ function makeVideoResource(readyState = 4, videoWidth = 320, videoHeight = 240):
 }
 
 describe('advanceVideoTexture', () => {
-  it('bumps frameId and returns the new value', () => {
+  it('bumps the backing and Texture versions and returns the new value', () => {
     const vt = createVideoTexture(makeVideoResource());
-    expect(vt.frameId).toBe(-1);
+    expect(vt.version).toBe(0xffffffff);
     expect(advanceVideoTexture(vt)).toBe(0);
     expect(advanceVideoTexture(vt)).toBe(1);
-    expect(vt.frameId).toBe(1);
+    expect(vt.version).toBe(1);
+    expect(vt.storage.image?.version).toBe(1);
   });
 });
 
 describe('cloneVideoTexture', () => {
-  it('shares the source but deep-clones sampler and uv vectors and resets frameId', () => {
+  it('shares the backing 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.source).toBe(source);
+    expect(clone.storage.image).toBe(vt.storage.image);
     expect(clone.sampler).not.toBe(vt.sampler);
     expect(clone.uvOffset).not.toBe(vt.uvOffset);
     expect(clone.uvOffset.x).toBe(2);
-    expect(clone.frameId).toBe(-1);
+    expect(clone.version).toBe(0);
   });
 });
 
@@ -53,8 +54,8 @@ describe('copyVideoTexture', () => {
     const b = createVideoTexture(makeVideoResource());
     copyVideoTexture(b, a);
     expect(b.colorSpace).toBe('linear');
-    expect(b.frameId).toBe(0);
-    expect(b.source).toBe(a.source);
+    expect(b.version).toBe(0);
+    expect(b.storage.image).toBe(a.storage.image);
     expect(b.uvScale.x).toBe(4);
     copyVideoTexture(a, a);
     expect(a.uvScale.x).toBe(4);
@@ -62,12 +63,12 @@ describe('copyVideoTexture', () => {
 });
 
 describe('createVideoTexture', () => {
-  it('defaults to srgb, identity uv-transform, and frameId -1', () => {
+  it('returns a universal srgb Texture with a borrowed host-image backing', () => {
     const source = makeVideoResource();
     const vt = createVideoTexture(source);
     expect(vt.colorSpace).toBe('srgb');
-    expect(vt.source).toBe(source);
-    expect(vt.frameId).toBe(-1);
+    expect((vt.storage.image as ImageResource).source).toBe(source.element);
+    expect(vt.version).toBe(0xffffffff);
     expect(vt.uvOffset.x).toBe(0);
     expect(vt.uvScale.x).toBe(1);
     expect(vt.uvRotation).toBe(0);
@@ -135,23 +136,24 @@ describe('isVideoTextureFrameReady', () => {
 });
 
 describe('resetVideoTextureFrame', () => {
-  it('sets frameId back to -1', () => {
+  it('sets the shared revision to the u32 pre-first-frame sentinel', () => {
     const vt = createVideoTexture(makeVideoResource());
     advanceVideoTexture(vt);
     advanceVideoTexture(vt);
     resetVideoTextureFrame(vt);
-    expect(vt.frameId).toBe(-1);
+    expect(vt.version).toBe(0xffffffff);
+    expect(vt.storage.image?.version).toBe(0xffffffff);
   });
 });
 
 describe('setVideoTextureSource', () => {
-  it('swaps the source and resets frameId', () => {
+  it('swaps the borrowed host handle and resets the version', () => {
     const vt = createVideoTexture(makeVideoResource());
     advanceVideoTexture(vt);
     const next = makeVideoResource(4, 640, 480);
     setVideoTextureSource(vt, next);
-    expect(vt.source).toBe(next);
-    expect(vt.frameId).toBe(-1);
+    expect((vt.storage.image as ImageResource).source).toBe(next.element);
+    expect(vt.version).toBe(0xffffffff);
     expect(getVideoTextureWidth(vt)).toBe(640);
   });
 });