@flighthq/render-wgpu 0.3.0-next.906.07cea63 → 0.3.1-next.1041.35b950c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. package/dist/contract.d.ts +7 -1
  2. package/dist/contract.d.ts.map +1 -1
  3. package/dist/contract.js +7 -1
  4. package/dist/contract.js.map +1 -1
  5. package/dist/enableWgpuTextureResolverGuards.d.ts +4 -0
  6. package/dist/enableWgpuTextureResolverGuards.d.ts.map +1 -0
  7. package/dist/enableWgpuTextureResolverGuards.js +8 -0
  8. package/dist/enableWgpuTextureResolverGuards.js.map +1 -0
  9. package/dist/explainWgpuTextureResolution.d.ts +3 -0
  10. package/dist/explainWgpuTextureResolution.d.ts.map +1 -0
  11. package/dist/explainWgpuTextureResolution.js +15 -0
  12. package/dist/explainWgpuTextureResolution.js.map +1 -0
  13. package/dist/index.d.ts +1 -1
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/wgpuBackground.d.ts +2 -0
  18. package/dist/wgpuBackground.d.ts.map +1 -1
  19. package/dist/wgpuBackground.js +30 -2
  20. package/dist/wgpuBackground.js.map +1 -1
  21. package/dist/wgpuCompressedTexture.d.ts +2 -2
  22. package/dist/wgpuCompressedTexture.d.ts.map +1 -1
  23. package/dist/wgpuCompressedTexture.js +52 -13
  24. package/dist/wgpuCompressedTexture.js.map +1 -1
  25. package/dist/wgpuDraw.d.ts +6 -4
  26. package/dist/wgpuDraw.d.ts.map +1 -1
  27. package/dist/wgpuDraw.js +150 -69
  28. package/dist/wgpuDraw.js.map +1 -1
  29. package/dist/wgpuExternalImageSource.d.ts +3 -0
  30. package/dist/wgpuExternalImageSource.d.ts.map +1 -0
  31. package/dist/wgpuExternalImageSource.js +51 -0
  32. package/dist/wgpuExternalImageSource.js.map +1 -0
  33. package/dist/wgpuExternalTexture.d.ts +4 -0
  34. package/dist/wgpuExternalTexture.d.ts.map +1 -0
  35. package/dist/wgpuExternalTexture.js +62 -0
  36. package/dist/wgpuExternalTexture.js.map +1 -0
  37. package/dist/wgpuMaterialRegistry.d.ts.map +1 -1
  38. package/dist/wgpuMaterialRegistry.js +17 -12
  39. package/dist/wgpuMaterialRegistry.js.map +1 -1
  40. package/dist/wgpuMipmap.d.ts.map +1 -1
  41. package/dist/wgpuMipmap.js +11 -9
  42. package/dist/wgpuMipmap.js.map +1 -1
  43. package/dist/wgpuRenderState.d.ts +15 -3
  44. package/dist/wgpuRenderState.d.ts.map +1 -1
  45. package/dist/wgpuRenderState.js +253 -33
  46. package/dist/wgpuRenderState.js.map +1 -1
  47. package/dist/wgpuRenderTarget.d.ts.map +1 -1
  48. package/dist/wgpuRenderTarget.js +2 -0
  49. package/dist/wgpuRenderTarget.js.map +1 -1
  50. package/dist/wgpuRenderTexture.d.ts +15 -0
  51. package/dist/wgpuRenderTexture.d.ts.map +1 -0
  52. package/dist/wgpuRenderTexture.js +130 -0
  53. package/dist/wgpuRenderTexture.js.map +1 -0
  54. package/dist/wgpuRenderTexturePool.d.ts +7 -0
  55. package/dist/wgpuRenderTexturePool.d.ts.map +1 -0
  56. package/dist/wgpuRenderTexturePool.js +86 -0
  57. package/dist/wgpuRenderTexturePool.js.map +1 -0
  58. package/dist/wgpuShader.d.ts.map +1 -1
  59. package/dist/wgpuShader.js +5 -1
  60. package/dist/wgpuShader.js.map +1 -1
  61. package/dist/wgpuSurface.d.ts +2 -2
  62. package/dist/wgpuSurface.d.ts.map +1 -1
  63. package/dist/wgpuSurface.js +61 -13
  64. package/dist/wgpuSurface.js.map +1 -1
  65. package/dist/wgpuTestHelper.d.ts +1 -0
  66. package/dist/wgpuTestHelper.d.ts.map +1 -1
  67. package/dist/wgpuTestHelper.js +125 -8
  68. package/dist/wgpuTestHelper.js.map +1 -1
  69. package/dist/wgpuTextureResolver.d.ts +9 -0
  70. package/dist/wgpuTextureResolver.d.ts.map +1 -0
  71. package/dist/wgpuTextureResolver.js +68 -0
  72. package/dist/wgpuTextureResolver.js.map +1 -0
  73. package/dist/wgpuTextureUpload.d.ts +2 -2
  74. package/dist/wgpuTextureUpload.d.ts.map +1 -1
  75. package/dist/wgpuTextureUpload.js +5 -10
  76. package/dist/wgpuTextureUpload.js.map +1 -1
  77. package/package.json +17 -7
  78. package/src/enableWgpuTextureResolverGuards.test.ts +65 -0
  79. package/src/explainWgpuTextureResolution.test.ts +36 -0
  80. package/src/wgpuBackground.test.ts +34 -1
  81. package/src/wgpuCompressedTexture.test.ts +35 -40
  82. package/src/wgpuDraw.test.ts +180 -62
  83. package/src/wgpuExternalImageSource.test.ts +89 -0
  84. package/src/wgpuExternalTexture.test.ts +35 -0
  85. package/src/wgpuMaterialRegistry.test.ts +44 -3
  86. package/src/wgpuMipmap.test.ts +10 -2
  87. package/src/wgpuRenderState.test.ts +462 -12
  88. package/src/wgpuRenderTarget.test.ts +14 -0
  89. package/src/wgpuRenderTexture.test.ts +165 -0
  90. package/src/wgpuRenderTexturePool.test.ts +146 -0
  91. package/src/wgpuShaderBinding.test.ts +6 -6
  92. package/src/wgpuSurface.test.ts +95 -3
  93. package/src/wgpuTestHelper.test.ts +64 -0
  94. package/src/wgpuTextureResolver.test.ts +212 -0
  95. package/src/wgpuTextureUpload.test.ts +28 -13
@@ -1,4 +1,5 @@
1
- import type { ImageResource, TextureContainer, WgpuCompressedTextureSupport } from '@flighthq/types/contract';
1
+ import type { CompressedImage, TextureContainer, WgpuCompressedTextureSupport } from '@flighthq/types/contract';
2
+ import { CompressedImageTextureSourceKind, RegistryEntryState } from '@flighthq/types/contract';
2
3
 
3
4
  import {
4
5
  detectWgpuCompressedTextureSupport,
@@ -8,7 +9,7 @@ import {
8
9
  registerWgpuCompressedTextureUpload,
9
10
  uploadWgpuCompressedTextureContainer,
10
11
  } from './wgpuCompressedTexture';
11
- import { bindWgpuImageResourceTexture } from './wgpuDraw';
12
+ import { bindWgpuCompressedImageTexture } from './wgpuDraw';
12
13
  import { getWgpuRenderStateRuntime } from './wgpuRenderState';
13
14
  import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
14
15
 
@@ -29,6 +30,16 @@ function container(overrides: Partial<TextureContainer> = {}): TextureContainer
29
30
  };
30
31
  }
31
32
 
33
+ function compressedImage(): CompressedImage {
34
+ return {
35
+ compressed: { container: container(), payload: new Uint8Array(8) },
36
+ height: 4,
37
+ kind: CompressedImageTextureSourceKind,
38
+ version: 1,
39
+ width: 4,
40
+ } as unknown as CompressedImage;
41
+ }
42
+
32
43
  describe('detectWgpuCompressedTextureSupport', () => {
33
44
  it('reads the three WebGPU compression features', async () => {
34
45
  const state = await createWgpuRenderStateForTest();
@@ -58,42 +69,45 @@ describe('hasWgpuCompressedTextureFormat', () => {
58
69
  });
59
70
 
60
71
  describe('registerWgpuCompressedTextureDecoder', () => {
61
- it('installs and clears the fallback decoder', async () => {
72
+ it('replaces the decoder policy slot and clears it with null', async () => {
62
73
  const state = await createWgpuRenderStateForTest();
74
+ const runtime = getWgpuRenderStateRuntime(state);
75
+ const before = runtime.registries.compressedTextureDecoder;
63
76
  const decoder = vi.fn(() => new Uint8ClampedArray(64));
64
77
  registerWgpuCompressedTextureDecoder(state, decoder);
65
- expect(getWgpuRenderStateRuntime(state).compressedTextureDecoder).toBe(decoder);
78
+ expect(runtime.registries.compressedTextureDecoder).not.toBe(before);
79
+ expect(runtime.registries.compressedTextureDecoder.entry).toEqual({
80
+ state: RegistryEntryState.Bound,
81
+ value: decoder,
82
+ });
66
83
  registerWgpuCompressedTextureDecoder(state, null);
67
- expect(getWgpuRenderStateRuntime(state).compressedTextureDecoder).toBeNull();
84
+ expect(runtime.registries.compressedTextureDecoder.entry).toBeNull();
68
85
  });
69
86
  });
70
87
 
71
88
  describe('registerWgpuCompressedTextureUpload', () => {
72
- it('installs and clears the ImageResource upload seam', async () => {
89
+ it('replaces the compressed upload policy slot and clears it with null', async () => {
73
90
  const state = await createWgpuRenderStateForTest();
91
+ const runtime = getWgpuRenderStateRuntime(state);
92
+ const before = runtime.registries.compressedTextureUpload;
74
93
  registerWgpuCompressedTextureUpload(state);
75
- expect(getWgpuRenderStateRuntime(state).compressedTextureUpload).toBeTypeOf('function');
94
+ expect(runtime.registries.compressedTextureUpload).not.toBe(before);
95
+ expect(runtime.registries.compressedTextureUpload.entry).toMatchObject({
96
+ state: RegistryEntryState.Bound,
97
+ value: expect.any(Function),
98
+ });
76
99
  registerWgpuCompressedTextureUpload(state, null);
77
- expect(getWgpuRenderStateRuntime(state).compressedTextureUpload).toBeNull();
100
+ expect(runtime.registries.compressedTextureUpload.entry).toBeNull();
78
101
  });
79
102
 
80
- it('lets the normal image binder consume a compressed-only resource', async () => {
103
+ it('lets the compressed-image binder consume its source', async () => {
81
104
  const state = await createWgpuRenderStateForTest();
82
105
  registerWgpuCompressedTextureUpload(state);
83
106
  registerWgpuCompressedTextureDecoder(state, (_format, width, height) => {
84
107
  return new Uint8ClampedArray(width * height * 4);
85
108
  });
86
- const image = {
87
- alphaType: 'straight',
88
- compressed: { container: container(), payload: new Uint8Array(8) },
89
- data: null,
90
- height: 4,
91
- source: null,
92
- version: 1,
93
- width: 4,
94
- } as unknown as ImageResource;
95
109
  const writeTexture = vi.spyOn(state.device.queue, 'writeTexture');
96
- expect(bindWgpuImageResourceTexture(state, image).view).toBeDefined();
110
+ expect(bindWgpuCompressedImageTexture(state, compressedImage())?.view).toBeDefined();
97
111
  expect(writeTexture).toHaveBeenCalledTimes(1);
98
112
  });
99
113
 
@@ -109,18 +123,9 @@ describe('registerWgpuCompressedTextureUpload', () => {
109
123
  }
110
124
  return rgba;
111
125
  });
112
- const image = {
113
- alphaType: 'straight',
114
- compressed: { container: container(), payload: new Uint8Array(8) },
115
- data: null,
116
- height: 4,
117
- source: null,
118
- version: 1,
119
- width: 4,
120
- } as unknown as ImageResource;
121
126
  const writeTexture = vi.spyOn(state.device.queue, 'writeTexture');
122
127
 
123
- const entry = bindWgpuImageResourceTexture(state, image);
128
+ const entry = bindWgpuCompressedImageTexture(state, compressedImage())!;
124
129
 
125
130
  expect(entry.straightAlpha).toBe(false);
126
131
  expect(Array.from(writeTexture.mock.calls[0][1] as Uint8ClampedArray).slice(0, 4)).toEqual([128, 32, 0, 128]);
@@ -130,17 +135,7 @@ describe('registerWgpuCompressedTextureUpload', () => {
130
135
  const state = await createWgpuRenderStateForTest();
131
136
  (state.device.features as Set<GPUFeatureName>).add('texture-compression-bc');
132
137
  registerWgpuCompressedTextureUpload(state);
133
- const image = {
134
- alphaType: 'straight',
135
- compressed: { container: container(), payload: new Uint8Array(8) },
136
- data: null,
137
- height: 4,
138
- source: null,
139
- version: 1,
140
- width: 4,
141
- } as unknown as ImageResource;
142
-
143
- expect(bindWgpuImageResourceTexture(state, image).straightAlpha).toBe(true);
138
+ expect(bindWgpuCompressedImageTexture(state, compressedImage())?.straightAlpha).toBe(true);
144
139
  });
145
140
  });
146
141
 
@@ -1,11 +1,20 @@
1
1
  import { getOrCreateRenderProxy2D, prepareScene2DRender } from '@flighthq/render/contract';
2
- import { createBitmap } from '@flighthq/scene2d/contract';
3
- import type { ImageResource, Texture } from '@flighthq/types/contract';
4
- import { BlendMode } from '@flighthq/types/contract';
2
+ import { createSprite } from '@flighthq/scene2d/contract';
3
+ import { getTextureSource } from '@flighthq/texture/contract';
4
+ import type { Bitmap, CompressedImage, Image, Texture, WgpuTextureEntry } from '@flighthq/types/contract';
5
+ import {
6
+ BitmapTextureSourceKind,
7
+ BlendMode,
8
+ CompressedImageTextureSourceKind,
9
+ ImageTextureSourceKind,
10
+ } from '@flighthq/types/contract';
5
11
 
6
12
  import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
13
+ import { registerWgpuCompressedTextureDecoder, registerWgpuCompressedTextureUpload } from './wgpuCompressedTexture';
7
14
  import {
8
15
  applyWgpuBlendMode,
16
+ bindWgpuBitmapTexture,
17
+ bindWgpuCompressedImageTexture,
9
18
  bindWgpuImageResourceTexture,
10
19
  bindWgpuTexture,
11
20
  bindWgpuVideoTexture,
@@ -28,6 +37,47 @@ beforeAll(() => {
28
37
  installWgpuMock();
29
38
  });
30
39
 
40
+ function requireTextureEntry(entry: WgpuTextureEntry | null): WgpuTextureEntry {
41
+ if (entry === null) throw new Error('Expected a ready WebGPU texture entry');
42
+ return entry;
43
+ }
44
+
45
+ function bitmap(size: number, version: number): Bitmap {
46
+ return {
47
+ alphaType: 'straight',
48
+ colorSpace: 'srgb',
49
+ data: new Uint8ClampedArray(size * size * 4),
50
+ format: 'rgba8unorm',
51
+ height: size,
52
+ kind: BitmapTextureSourceKind,
53
+ version,
54
+ width: size,
55
+ } as unknown as Bitmap;
56
+ }
57
+
58
+ function compressedBc3Image(): CompressedImage {
59
+ return {
60
+ compressed: {
61
+ container: {
62
+ depth: 1,
63
+ faces: 1,
64
+ format: 'bc3',
65
+ height: 4,
66
+ layers: 1,
67
+ levels: [{ byteLength: 16, byteOffset: 0, height: 4, width: 4 }],
68
+ mipLevels: 1,
69
+ supercompression: 'None',
70
+ width: 4,
71
+ },
72
+ payload: new Uint8Array(16),
73
+ },
74
+ height: 4,
75
+ kind: CompressedImageTextureSourceKind,
76
+ version: 1,
77
+ width: 4,
78
+ } as unknown as CompressedImage;
79
+ }
80
+
31
81
  describe('applyWgpuBlendMode', () => {
32
82
  it('updates currentBlendMode on the state', async () => {
33
83
  const state = await createWgpuRenderStateForTest();
@@ -42,27 +92,62 @@ describe('applyWgpuBlendMode', () => {
42
92
  });
43
93
  });
44
94
 
45
- describe('bindWgpuImageResourceTexture', () => {
46
- function dataResource(size: number, version: number): ImageResource {
47
- return {
48
- source: null,
49
- data: new Uint8ClampedArray(size * size * 4),
50
- width: size,
51
- height: size,
52
- version,
53
- alphaType: 'straight',
54
- } as unknown as ImageResource;
55
- }
56
-
57
- it('uploads a data-only ImageResource (a generated Surface) via writeTexture', async () => {
95
+ describe('bindWgpuBitmapTexture', () => {
96
+ it('uploads CPU-readable pixels via writeTexture', async () => {
58
97
  const state = await createWgpuRenderStateForTest();
59
98
  const writeTexture = vi.spyOn(state.device.queue, 'writeTexture');
60
- const entry = bindWgpuImageResourceTexture(state, dataResource(4, 1));
99
+ const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
61
100
  expect(entry.texture).toBeDefined();
62
101
  expect(writeTexture).toHaveBeenCalled();
63
102
  });
64
103
 
65
- it('uploads an element-backed ImageResource via copyExternalImageToTexture', async () => {
104
+ it('caches by resource identity and re-uploads only when the version changes', async () => {
105
+ const state = await createWgpuRenderStateForTest();
106
+ const image = bitmap(2, 1);
107
+ const first = bindWgpuBitmapTexture(state, image);
108
+ expect(bindWgpuBitmapTexture(state, image)).toBe(first);
109
+ const createTexture = vi.spyOn(state.device, 'createTexture');
110
+ image.version = 2;
111
+ bindWgpuBitmapTexture(state, image);
112
+ expect(createTexture).toHaveBeenCalled();
113
+ });
114
+
115
+ it('RETIRES the outgoing texture on a version bump rather than destroying it', async () => {
116
+ const state = await createWgpuRenderStateForTest();
117
+ const image = bitmap(2, 1);
118
+ const outgoing = bindWgpuBitmapTexture(state, image).texture;
119
+
120
+ image.version = 2;
121
+ bindWgpuBitmapTexture(state, image);
122
+
123
+ // A version bump rewrites the cached entry IN PLACE, so a bind group recorded earlier in the frame
124
+ // still points at `outgoing`. The frame's submit is deferred; destroying a texture a recorded command
125
+ // buffer references fails that submit and blanks the whole frame, so it has to wait for post-submit.
126
+ // This guards a hazard with no reproduction of its own — without the test there is nothing to stop
127
+ // the deferral being read as pointless indirection and reverted.
128
+ expect(getWgpuRenderStateRuntime(state).retiredTextures).toContain(outgoing);
129
+ });
130
+ });
131
+
132
+ describe('bindWgpuCompressedImageTexture', () => {
133
+ it('routes through the registered compressed upload seam', async () => {
134
+ const state = await createWgpuRenderStateForTest();
135
+ const decode = vi.fn(() => new Uint8ClampedArray(4 * 4 * 4));
136
+ registerWgpuCompressedTextureUpload(state);
137
+ registerWgpuCompressedTextureDecoder(state, decode);
138
+ const entry = bindWgpuCompressedImageTexture(state, compressedBc3Image());
139
+ expect(entry?.texture).toBeDefined();
140
+ expect(decode).toHaveBeenCalledWith('bc3', 4, 4, expect.any(Uint8Array));
141
+ });
142
+
143
+ it('returns null when no compressed uploader is registered', async () => {
144
+ const state = await createWgpuRenderStateForTest();
145
+ expect(bindWgpuCompressedImageTexture(state, compressedBc3Image())).toBeNull();
146
+ });
147
+ });
148
+
149
+ describe('bindWgpuImageResourceTexture', () => {
150
+ it('uploads a host-backed image via copyExternalImageToTexture', async () => {
66
151
  const state = await createWgpuRenderStateForTest();
67
152
  const copy = vi.spyOn(state.device.queue, 'copyExternalImageToTexture');
68
153
  const canvas = document.createElement('canvas');
@@ -70,25 +155,52 @@ describe('bindWgpuImageResourceTexture', () => {
70
155
  canvas.height = 4;
71
156
  const image = {
72
157
  source: canvas,
73
- data: null,
74
158
  width: 4,
75
159
  height: 4,
160
+ kind: ImageTextureSourceKind,
76
161
  version: 1,
77
- alphaType: 'straight',
78
- } as unknown as ImageResource;
162
+ } as unknown as Image;
79
163
  bindWgpuImageResourceTexture(state, image);
80
164
  expect(copy).toHaveBeenCalled();
81
165
  });
82
166
 
83
- it('caches by resource identity and re-uploads only when the version changes', async () => {
167
+ it('skips an initial upload when the canvas has no pixels', async () => {
84
168
  const state = await createWgpuRenderStateForTest();
85
- const image = dataResource(2, 1);
86
- const first = bindWgpuImageResourceTexture(state, image);
87
- expect(bindWgpuImageResourceTexture(state, image)).toBe(first);
88
- const createTexture = vi.spyOn(state.device, 'createTexture');
169
+ const copy = vi.spyOn(state.device.queue, 'copyExternalImageToTexture');
170
+ const canvas = document.createElement('canvas');
171
+ canvas.width = 0;
172
+ canvas.height = 4;
173
+ const image = {
174
+ source: canvas,
175
+ width: 0,
176
+ height: 4,
177
+ kind: ImageTextureSourceKind,
178
+ version: 1,
179
+ } as unknown as Image;
180
+ expect(bindWgpuImageResourceTexture(state, image)).toBeNull();
181
+ expect(copy).not.toHaveBeenCalled();
182
+ });
183
+
184
+ it('keeps the previous upload when the browser cannot snapshot the current source', async () => {
185
+ const state = await createWgpuRenderStateForTest();
186
+ const copy = vi.spyOn(state.device.queue, 'copyExternalImageToTexture');
187
+ const canvas = document.createElement('canvas');
188
+ canvas.width = 4;
189
+ canvas.height = 4;
190
+ const image = {
191
+ source: canvas,
192
+ width: 4,
193
+ height: 4,
194
+ kind: ImageTextureSourceKind,
195
+ version: 1,
196
+ } as unknown as Image;
197
+ const entry = requireTextureEntry(bindWgpuImageResourceTexture(state, image));
198
+ copy.mockImplementation(() => {
199
+ throw new TypeError('Failed to copy content from external image.');
200
+ });
89
201
  image.version = 2;
90
- bindWgpuImageResourceTexture(state, image);
91
- expect(createTexture).toHaveBeenCalled();
202
+ expect(bindWgpuImageResourceTexture(state, image)).toBe(entry);
203
+ expect(copy).toHaveBeenCalledTimes(2);
92
204
  });
93
205
  });
94
206
 
@@ -98,7 +210,7 @@ describe('bindWgpuTexture', () => {
98
210
  const canvas = document.createElement('canvas');
99
211
  canvas.width = 8;
100
212
  canvas.height = 8;
101
- const entry = bindWgpuTexture(state, canvas);
213
+ const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
102
214
  expect(entry).toBeDefined();
103
215
  expect(entry.texture).toBeDefined();
104
216
  expect(bindWgpuTexture(state, canvas)).toBe(entry);
@@ -130,7 +242,14 @@ describe('bindWgpuTexture', () => {
130
242
 
131
243
  describe('bindWgpuVideoTexture', () => {
132
244
  function videoTexture(version: number, readyState = 4, width = 320, height = 240): Texture {
245
+ const source = document.createElement('video');
246
+ Object.defineProperties(source, {
247
+ readyState: { configurable: true, value: readyState, writable: true },
248
+ videoHeight: { configurable: true, value: height, writable: true },
249
+ videoWidth: { configurable: true, value: width, writable: true },
250
+ });
133
251
  return {
252
+ colorSpace: 'srgb',
134
253
  sampler: {
135
254
  anisotropy: 1,
136
255
  magFilter: 'linear',
@@ -139,18 +258,16 @@ describe('bindWgpuVideoTexture', () => {
139
258
  wrapU: 'clamp-to-edge',
140
259
  wrapV: 'clamp-to-edge',
141
260
  },
142
- storage: {
143
- dimension: '2d',
144
- image: {
145
- source: { readyState, videoHeight: height, videoWidth: width } as HTMLVideoElement,
146
- version,
147
- },
261
+ dimension: '2d',
262
+ source: {
263
+ source,
264
+ version,
148
265
  },
149
266
  version,
150
267
  } as unknown as Texture;
151
268
  }
152
269
 
153
- it('uploads once per backing version and caches the texture by backing identity', async () => {
270
+ it('uploads once per source version and caches the texture by source identity', async () => {
154
271
  const state = await createWgpuRenderStateForTest();
155
272
  const copy = vi.spyOn(state.device.queue, 'copyExternalImageToTexture');
156
273
  const video = videoTexture(1);
@@ -159,7 +276,7 @@ describe('bindWgpuVideoTexture', () => {
159
276
  expect(copy).toHaveBeenCalledTimes(1);
160
277
  expect(bindWgpuVideoTexture(state, video)).toBe(first);
161
278
  expect(copy).toHaveBeenCalledTimes(1);
162
- video.storage.image!.version = 2;
279
+ getTextureSource(video)!.version = 2;
163
280
  expect(bindWgpuVideoTexture(state, video)).toBe(first);
164
281
  expect(copy).toHaveBeenCalledTimes(2);
165
282
  });
@@ -168,7 +285,7 @@ describe('bindWgpuVideoTexture', () => {
168
285
  const state = await createWgpuRenderStateForTest();
169
286
  const video = videoTexture(1, 1, 0, 0);
170
287
  expect(bindWgpuVideoTexture(state, video)).toBeNull();
171
- const element = video.storage.image!.source as HTMLVideoElement;
288
+ const element = (getTextureSource(video) as Image).source as HTMLVideoElement;
172
289
  Object.assign(element, { readyState: 4, videoHeight: 120, videoWidth: 160 });
173
290
  const first = bindWgpuVideoTexture(state, video)!;
174
291
  const destroy = vi.spyOn(first.texture, 'destroy');
@@ -178,6 +295,18 @@ describe('bindWgpuVideoTexture', () => {
178
295
  expect(destroy).toHaveBeenCalled();
179
296
  });
180
297
 
298
+ it('realizes distinct linear and sRGB textures for one video source', async () => {
299
+ const state = await createWgpuRenderStateForTest();
300
+ const createTexture = vi.spyOn(state.device, 'createTexture');
301
+ const video = videoTexture(1);
302
+ const srgb = bindWgpuVideoTexture(state, video);
303
+ expect(createTexture).toHaveBeenLastCalledWith(expect.objectContaining({ format: 'rgba8unorm-srgb' }));
304
+ video.colorSpace = 'linear';
305
+ const linear = bindWgpuVideoTexture(state, video);
306
+ expect(linear).not.toBe(srgb);
307
+ expect(createTexture).toHaveBeenLastCalledWith(expect.objectContaining({ format: 'rgba8unorm' }));
308
+ });
309
+
181
310
  it('destroys and removes an uploaded video texture', async () => {
182
311
  const state = await createWgpuRenderStateForTest();
183
312
  const video = videoTexture(1);
@@ -204,7 +333,7 @@ describe('createWgpuTextureEntry', () => {
204
333
  const canvas = document.createElement('canvas');
205
334
  canvas.width = 4;
206
335
  canvas.height = 4;
207
- const entry = createWgpuTextureEntry(state, 4, 4, canvas);
336
+ const entry = requireTextureEntry(createWgpuTextureEntry(state, 4, 4, canvas));
208
337
  expect(entry.texture).toBeDefined();
209
338
  expect(entry.bindGroup).toBeDefined();
210
339
  });
@@ -220,13 +349,13 @@ describe('drawWgpuQuad', () => {
220
349
  it('does not throw when render pass is open', async () => {
221
350
  const state = await createWgpuRenderStateForTest();
222
351
  renderWgpuBackground(state);
223
- const bitmap = createBitmap();
352
+ const bitmap = createSprite();
224
353
  prepareScene2DRender(state, bitmap);
225
354
  const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
226
355
  const canvas = document.createElement('canvas');
227
356
  canvas.width = 4;
228
357
  canvas.height = 4;
229
- const entry = bindWgpuTexture(state, canvas);
358
+ const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
230
359
  expect(() => drawWgpuQuad(state, renderProxy, entry, 0, 0, 4, 4, 0, 0, 1, 1)).not.toThrow();
231
360
  submitWgpuRenderPass(state);
232
361
  });
@@ -236,13 +365,13 @@ describe('drawWgpuQuadWithTransform', () => {
236
365
  it('does not throw when render pass is open', async () => {
237
366
  const state = await createWgpuRenderStateForTest();
238
367
  renderWgpuBackground(state);
239
- const bitmap = createBitmap();
368
+ const bitmap = createSprite();
240
369
  prepareScene2DRender(state, bitmap);
241
370
  const renderProxy = getOrCreateRenderProxy2D(state, bitmap);
242
371
  const canvas = document.createElement('canvas');
243
372
  canvas.width = 4;
244
373
  canvas.height = 4;
245
- const entry = bindWgpuTexture(state, canvas);
374
+ const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
246
375
  const t = { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 };
247
376
  expect(() => drawWgpuQuadWithTransform(state, renderProxy, t, entry, 0, 0, 4, 4, 0, 0, 1, 1)).not.toThrow();
248
377
  submitWgpuRenderPass(state);
@@ -270,20 +399,9 @@ describe('getWgpuRenderProxyColorScaleBias', () => {
270
399
  });
271
400
 
272
401
  describe('resolveWgpuSmoothingBindGroup', () => {
273
- function dataResource(size: number, version: number): ImageResource {
274
- return {
275
- source: null,
276
- data: new Uint8ClampedArray(size * size * 4),
277
- width: size,
278
- height: size,
279
- version,
280
- alphaType: 'straight',
281
- } as unknown as ImageResource;
282
- }
283
-
284
402
  it('returns the default bind group for a null smoothing (no variant built)', async () => {
285
403
  const state = await createWgpuRenderStateForTest();
286
- const entry = bindWgpuImageResourceTexture(state, dataResource(4, 1));
404
+ const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
287
405
  expect(resolveWgpuSmoothingBindGroup(state, entry, null)).toBe(entry.bindGroup);
288
406
  expect(entry.bindGroupLinear).toBeUndefined();
289
407
  expect(entry.bindGroupNearest).toBeUndefined();
@@ -291,7 +409,7 @@ describe('resolveWgpuSmoothingBindGroup', () => {
291
409
 
292
410
  it('builds and caches distinct LINEAR and NEAREST variants for true/false', async () => {
293
411
  const state = await createWgpuRenderStateForTest();
294
- const entry = bindWgpuImageResourceTexture(state, dataResource(4, 1));
412
+ const entry = bindWgpuBitmapTexture(state, bitmap(4, 1));
295
413
  const createBindGroup = vi.spyOn(state.device, 'createBindGroup');
296
414
 
297
415
  resolveWgpuSmoothingBindGroup(state, entry, true);
@@ -310,13 +428,13 @@ describe('resolveWgpuSmoothingBindGroup', () => {
310
428
 
311
429
  it('drops the cached variants when the texture re-uploads (version bump)', async () => {
312
430
  const state = await createWgpuRenderStateForTest();
313
- const image = dataResource(4, 1);
314
- const entry = bindWgpuImageResourceTexture(state, image);
431
+ const image = bitmap(4, 1);
432
+ const entry = bindWgpuBitmapTexture(state, image);
315
433
  resolveWgpuSmoothingBindGroup(state, entry, true);
316
434
  resolveWgpuSmoothingBindGroup(state, entry, false);
317
435
  expect(entry.bindGroupLinear).toBeDefined();
318
436
  image.version = 2;
319
- bindWgpuImageResourceTexture(state, image);
437
+ bindWgpuBitmapTexture(state, image);
320
438
  expect(entry.bindGroupLinear).toBeUndefined();
321
439
  expect(entry.bindGroupNearest).toBeUndefined();
322
440
  });
@@ -329,7 +447,7 @@ describe('submitWgpuQuadDraw', () => {
329
447
  const canvas = document.createElement('canvas');
330
448
  canvas.width = 4;
331
449
  canvas.height = 4;
332
- const entry = bindWgpuTexture(state, canvas);
450
+ const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
333
451
  expect(() => submitWgpuQuadDraw(state, 0, entry.bindGroup)).not.toThrow();
334
452
  submitWgpuRenderPass(state);
335
453
  });
@@ -339,7 +457,7 @@ describe('submitWgpuQuadDraw', () => {
339
457
  const canvas = document.createElement('canvas');
340
458
  canvas.width = 4;
341
459
  canvas.height = 4;
342
- const entry = bindWgpuTexture(state, canvas);
460
+ const entry = requireTextureEntry(bindWgpuTexture(state, canvas));
343
461
  expect(() => submitWgpuQuadDraw(state, 0, entry.bindGroup)).not.toThrow();
344
462
  });
345
463
  });
@@ -350,7 +468,7 @@ describe('updateWgpuTextureEntry', () => {
350
468
  const canvas = document.createElement('canvas');
351
469
  canvas.width = 4;
352
470
  canvas.height = 4;
353
- const entry = createWgpuTextureEntry(state, 4, 4, canvas);
471
+ const entry = requireTextureEntry(createWgpuTextureEntry(state, 4, 4, canvas));
354
472
  expect(() => updateWgpuTextureEntry(state, entry, canvas)).not.toThrow();
355
473
  });
356
474
  });
@@ -0,0 +1,89 @@
1
+ import { isWgpuExternalImageSourceReady, tryCopyWgpuExternalImageToTexture } from './wgpuExternalImageSource';
2
+ import { createReadyImageElementForTest } from './wgpuTestHelper';
3
+
4
+ describe('isWgpuExternalImageSourceReady', () => {
5
+ it('accepts a dimension-valid canvas without probing or binding its context', () => {
6
+ const canvas = document.createElement('canvas');
7
+ canvas.width = 4;
8
+ canvas.height = 4;
9
+ const getContext = vi.spyOn(canvas, 'getContext');
10
+ expect(isWgpuExternalImageSourceReady(canvas, 4, 4)).toBe(true);
11
+ expect(getContext).not.toHaveBeenCalled();
12
+ });
13
+
14
+ it('accepts a decoded image with enough pixels', () => {
15
+ const image = createReadyImageElementForTest(4, 4);
16
+ expect(isWgpuExternalImageSourceReady(image, 4, 4)).toBe(true);
17
+ });
18
+
19
+ it('rejects zero extents and undersized sources', () => {
20
+ const canvas = document.createElement('canvas');
21
+ canvas.width = 4;
22
+ canvas.height = 4;
23
+ expect(isWgpuExternalImageSourceReady(canvas, 0, 4)).toBe(false);
24
+ expect(isWgpuExternalImageSourceReady(canvas, 5, 4)).toBe(false);
25
+ });
26
+
27
+ it('rejects an undecoded image element', () => {
28
+ const image = document.createElement('img');
29
+ expect(isWgpuExternalImageSourceReady(image, 1, 1)).toBe(false);
30
+ });
31
+
32
+ it('rejects an unrecognized source instead of failing open', () => {
33
+ expect(isWgpuExternalImageSourceReady({} as GPUCopyExternalImageSource, 1, 1)).toBe(false);
34
+ });
35
+ });
36
+
37
+ describe('tryCopyWgpuExternalImageToTexture', () => {
38
+ it('copies a ready source', () => {
39
+ const copyExternalImageToTexture = vi.fn();
40
+ const queue = { copyExternalImageToTexture } as unknown as GPUQueue;
41
+ const texture = {} as GPUTexture;
42
+ const source = createReadyImageElementForTest(4, 4);
43
+ expect(tryCopyWgpuExternalImageToTexture(queue, { source }, { texture }, 4, 4)).toBe(true);
44
+ expect(copyExternalImageToTexture).toHaveBeenCalledWith({ source }, { texture }, [4, 4, 1]);
45
+ });
46
+
47
+ it('fails closed when a canvas has no usable context', () => {
48
+ const canvas = document.createElement('canvas');
49
+ canvas.width = 4;
50
+ canvas.height = 4;
51
+ const copyExternalImageToTexture = vi.fn(() => {
52
+ throw new DOMException('canvas has no rendering context', 'OperationError');
53
+ });
54
+ const queue = { copyExternalImageToTexture } as unknown as GPUQueue;
55
+ expect(tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as GPUTexture }, 4, 4)).toBe(
56
+ false,
57
+ );
58
+ });
59
+
60
+ it('fails closed when the browser cannot snapshot current canvas content', () => {
61
+ const canvas = document.createElement('canvas');
62
+ canvas.width = 4;
63
+ canvas.height = 4;
64
+ const copyExternalImageToTexture = vi.fn(() => {
65
+ throw new TypeError(
66
+ "Failed to execute 'copyExternalImageToTexture' on 'GPUQueue': Failed to copy content from external image.",
67
+ );
68
+ });
69
+ const queue = { copyExternalImageToTexture } as unknown as GPUQueue;
70
+ expect(tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as GPUTexture }, 4, 4)).toBe(
71
+ false,
72
+ );
73
+ });
74
+
75
+ it('rethrows security failures', () => {
76
+ const canvas = document.createElement('canvas');
77
+ canvas.width = 4;
78
+ canvas.height = 4;
79
+ const error = new DOMException('tainted canvas', 'SecurityError');
80
+ const queue = {
81
+ copyExternalImageToTexture: vi.fn(() => {
82
+ throw error;
83
+ }),
84
+ } as unknown as GPUQueue;
85
+ expect(() =>
86
+ tryCopyWgpuExternalImageToTexture(queue, { source: canvas }, { texture: {} as GPUTexture }, 4, 4),
87
+ ).toThrow(error);
88
+ });
89
+ });
@@ -0,0 +1,35 @@
1
+ import { getTextureSourceKind } from '@flighthq/texture/contract';
2
+ import { ExternalTextureSourceKind } from '@flighthq/types/contract';
3
+
4
+ import { createExternalWgpuTexture, disposeExternalWgpuTexture } from './wgpuExternalTexture';
5
+ import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
6
+ import { resolveWgpuTexture } from './wgpuTextureResolver';
7
+
8
+ beforeAll(() => {
9
+ installWgpuMock();
10
+ });
11
+
12
+ describe('createExternalWgpuTexture', () => {
13
+ it('resolves a borrowed handle and forgets it without destroying the allocation', async () => {
14
+ const state = await createWgpuRenderStateForTest();
15
+ const destroy = vi.fn();
16
+ const handle = { createView: vi.fn(() => ({})), destroy } as unknown as GPUTexture;
17
+ const texture = createExternalWgpuTexture(state, handle, { height: 16, width: 32 });
18
+
19
+ expect(getTextureSourceKind(texture)).toBe(ExternalTextureSourceKind);
20
+ expect(resolveWgpuTexture(state, texture)?.texture).toBe(handle);
21
+ expect(disposeExternalWgpuTexture(state, texture)).toBe(true);
22
+ expect(resolveWgpuTexture(state, texture)).toBeNull();
23
+ expect(destroy).not.toHaveBeenCalled();
24
+ });
25
+ });
26
+
27
+ describe('disposeExternalWgpuTexture', () => {
28
+ it('returns false after the borrowed handle has already been forgotten', async () => {
29
+ const state = await createWgpuRenderStateForTest();
30
+ const handle = { createView: () => ({}) } as unknown as GPUTexture;
31
+ const texture = createExternalWgpuTexture(state, handle, { height: 1, width: 1 });
32
+ expect(disposeExternalWgpuTexture(state, texture)).toBe(true);
33
+ expect(disposeExternalWgpuTexture(state, texture)).toBe(false);
34
+ });
35
+ });