@forgeax/engine-image 0.1.20 → 0.1.23

package/src/__tests__/image-importer-conversion-failure.unit.test.ts

@@ -61,6 +61,8 @@ function expectConversionFailure(
         code: diagnosticCode,
         rule: expect.stringMatching(/^image-conversion-/),
         severity: 'error',
+        expected: expect.any(String),
+        hint: expect.any(String),
       }),
     ],
   });
@@ -206,6 +208,25 @@ describe('image importer conversion failure through the public runner', () => {
     expect(state.reads).toBe(6);
   });
 
+  it.each([
+    { colorSpace: 'srgb' as const, format: 'rgba8unorm-srgb' },
+    { colorSpace: 'linear' as const, format: 'rgba8unorm' },
+  ])('publishes a format matching the authored $colorSpace color space', async (input) => {
+    const result = await runImport(
+      meta('valid.png', { colorSpace: input.colorSpace, mipmap: 'none' }),
+      registry(),
+      { readSource: source({ bytes: makePng(1, 1, [1, 2, 3, 255]), reads: 0 }) },
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok || 'skipped' in result.value) return;
+    expect(result.value.pack.assets[0]?.payload).toMatchObject({
+      colorSpace: input.colorSpace,
+      format: input.format,
+      mips: { kind: 'none' },
+    });
+  });
+
   it.skipIf(!pkgBuilt)('repairs raw Basis color-space settings in the same registry', async () => {
     const state = { bytes: await makeRawBasis(), reads: 0 };
     const importerRegistry = registry();

package/src/__tests__/pixel-surface.unit.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { createPixelSurface, toAssetPack } from '../index.js';
+
+const META = {
+  guid: '01928000-7c00-7000-8000-000000000099',
+  colorSpace: 'srgb' as const,
+  mipmap: 'none' as const,
+  addressMode: 'repeat' as const,
+  filterMode: 'nearest' as const,
+};
+
+function surface(width = 4, height = 3) {
+  const result = createPixelSurface({ width, height, colorSpace: 'srgb', mipmap: false });
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('PixelSurface', () => {
+  it('rejects malformed dimensions and channel/seed values through ImageError', () => {
+    const badDimension = createPixelSurface({ width: 0, height: 2 });
+    expect(badDimension.ok).toBe(false);
+    if (!badDimension.ok) {
+      expect(badDimension.error.code).toBe('image-surface-invalid');
+      if (badDimension.error.code === 'image-surface-invalid') {
+        expect(badDimension.error.detail.expected).toContain('positive integer');
+        expect(badDimension.error.detail.code).toBe('image-surface-invalid');
+      }
+    }
+
+    const candidate = surface();
+    const badColor = candidate.setPixel(0, 0, [0, 0, 256, 255]);
+    expect(badColor.ok).toBe(false);
+    if (!badColor.ok && badColor.error.code === 'image-surface-invalid') {
+      expect(badColor.error.detail.operation).toBe('set-pixel');
+    }
+
+    const badSeed = candidate.fillNoise(Number.NaN);
+    expect(badSeed.ok).toBe(false);
+    if (!badSeed.ok && badSeed.error.code === 'image-surface-invalid') {
+      expect(badSeed.error.detail.operation).toBe('noise');
+    }
+  });
+
+  it('rounds coordinates, clips writes, and keeps exact RGBA8 channel order', () => {
+    const candidate = surface();
+    expect(candidate.setPixel(1.4, 1.6, [10, 20, 30, 40]).ok).toBe(true);
+    expect(candidate.data.slice((2 * 4 + 1) * 4, (2 * 4 + 2) * 4)).toEqual(
+      Uint8Array.of(10, 20, 30, 40),
+    );
+    expect(candidate.fillRect(-1.2, -1.2, 3.1, 3.1, [1, 2, 3, 4]).ok).toBe(true);
+    expect(candidate.data.slice(0, 4)).toEqual(Uint8Array.of(1, 2, 3, 4));
+    expect(candidate.fillCircle(3, 2, 1, { r: 9, g: 8, b: 7, a: 6 }).ok).toBe(true);
+    expect(candidate.data.slice((2 * 4 + 3) * 4, (2 * 4 + 4) * 4)).toEqual(
+      Uint8Array.of(9, 8, 7, 6),
+    );
+  });
+
+  it('snapshots overlapping blits before writing', () => {
+    const candidate = surface(4, 1);
+    for (let x = 0; x < 4; x += 1) {
+      expect(candidate.setPixel(x, 0, [x + 1, 0, 0, 255]).ok).toBe(true);
+    }
+    expect(candidate.blit(candidate, 1, 0, { x: 0, y: 0, width: 3, height: 1 }).ok).toBe(true);
+    expect(Array.from(candidate.data.filter((_value, index) => index % 4 === 0))).toEqual([
+      1, 1, 2, 3,
+    ]);
+  });
+
+  it('produces byte-identical seeded noise and a regular TextureAsset/Pack carrier', () => {
+    const first = surface();
+    const second = surface();
+    expect(first.fillNoise(42, { min: 10, max: 200, alpha: 123 }).ok).toBe(true);
+    expect(second.noise(42, { min: 10, max: 200, alpha: 123 }).ok).toBe(true);
+    expect(first.data).toEqual(second.data);
+    expect(first.toTextureAsset()).toMatchObject({
+      kind: 'texture',
+      shape: {
+        viewDimension: '2d',
+        extent: { width: 4, height: 3 },
+      },
+      format: 'rgba8unorm-srgb',
+      colorSpace: 'srgb',
+      mips: { kind: 'none' },
+    });
+    const decoded = first.toDecodedImage();
+    const pack = toAssetPack(decoded, META);
+    expect(pack.subAssets).toEqual([{ guid: META.guid, sourceIndex: 0, kind: 'texture' }]);
+    expect(pack.importSettings.mipmap).toBe('none');
+    const changed = decoded.bytes.slice();
+    changed[0] = (changed[0] ?? 0) ^ 1;
+    expect(changed).not.toEqual(decoded.bytes);
+  });
+});

package/src/errors.ts

@@ -25,6 +25,8 @@ const IMAGE_ERROR_EXPECTED: Readonly<Record<ImageErrorCode, string>> = {
   'atlas-size-exceeded':
     'image width x height <= maxAtlasSize^2 and each image fits in the atlas footprint',
   'atlas-region-mismatch': 'sum(regions[i].w x regions[i].h) <= atlasWidth x atlasHeight',
+  'image-surface-invalid':
+    'PixelSurface dimensions and authoring inputs satisfy the RGBA8 contract',
 };
 
 /** Runtime implementation of the correlated `ImageErrorFor<C>` envelope. */

package/src/image-importer.ts

@@ -32,7 +32,13 @@
 // (a single 2D rgba16float image); the cube-to-cube IBL projection is a runtime
 // GPU pass, not a build-time fold (feat-20260630).
 
-import { type BasisSourceInspection, ktx2ColorSpace, parseKtx2 } from '@forgeax/engine-codec';
+import {
+  type BasisSourceInspection,
+  initBasisTranscoder,
+  inspectBasisSource,
+  ktx2ColorSpace,
+  parseKtx2,
+} from '@forgeax/engine-codec';
 import type {
   EquirectAsset,
   ImageColorSpace,
@@ -219,7 +225,6 @@ async function inspectKtx2Source(
       're-encode the source as one 2D Basis texture',
     );
   }
-  const { initBasisTranscoder } = await import('@forgeax/engine-codec');
   const module = await initBasisTranscoder();
   let file: InstanceType<typeof module.KTX2File>;
   try {
@@ -371,7 +376,6 @@ function basisMetaColorSpace(ctx: ImportContext): ImageColorSpace | ImportError
 async function importBasisSource(ctx: ImportContext, bytes: Uint8Array): Promise<ImportResult> {
   const colorSpace = basisMetaColorSpace(ctx);
   if (colorSpace instanceof ImportError) return { ok: false, error: colorSpace };
-  const { initBasisTranscoder, inspectBasisSource } = await import('@forgeax/engine-codec');
   const module = await initBasisTranscoder();
   if (module.BasisFile === undefined) {
     throw new Error('basis-source-inspection-unavailable: transcoder lacks BasisFile');

package/src/index.ts

@@ -23,6 +23,14 @@ export { decodeHdr } from './hdr-decoder.js';
 export { decodeImageInBrowser } from './image-decoder-browser.js';
 export type { JpegModule, UpngModule } from './image-decoder-node.js';
 export { loadJpeg, loadUpng } from './image-decoder-node.js';
+export {
+  createPixelSurface,
+  type PixelColor,
+  type PixelSurface,
+  type PixelSurfaceNoiseOptions,
+  type PixelSurfaceOptions,
+  type PixelSurfaceRect,
+} from './pixel-surface.js';
 export type {
   EmittedSubAsset,
   ExistingExternalAssetPackage,

package/src/pixel-surface.ts

@@ -0,0 +1,428 @@
+import type {
+  DecodedImage,
+  ImageColorSpace,
+  ImageError,
+  ImageErrorDetailFor,
+  ImageMeta,
+  TextureAsset,
+} from '@forgeax/engine-types';
+import { imageError } from './errors.js';
+import { err, ok, type Result } from './result.js';
+import { type ExternalAssetPackage, toAssetPack } from './to-asset-pack.js';
+
+/** Four finite RGBA8 channels in source order. */
+export type PixelColor =
+  | readonly [number, number, number, number]
+  | Readonly<{ r: number; g: number; b: number; a: number }>;
+
+/** Optional source rectangle for a blit; coordinates are rounded and clipped. */
+export interface PixelSurfaceRect {
+  readonly x?: number;
+  readonly y?: number;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+export interface PixelSurfaceNoiseOptions {
+  /** Inclusive lower channel bound, default 0. */
+  readonly min?: number;
+  /** Inclusive upper channel bound, default 255. */
+  readonly max?: number;
+  /** Alpha written for every generated pixel, default 255. */
+  readonly alpha?: number;
+}
+
+export interface PixelSurfaceOptions {
+  readonly width: number;
+  readonly height: number;
+  readonly colorSpace?: ImageColorSpace;
+  readonly mipmap?: boolean;
+}
+
+export interface PixelSurface {
+  readonly width: number;
+  readonly height: number;
+  readonly colorSpace: ImageColorSpace;
+  readonly mipmap: boolean;
+  /** Tight RGBA8 level-zero bytes in row-major order. */
+  readonly data: Uint8Array;
+
+  setPixel(x: number, y: number, color: PixelColor): Result<void, ImageError>;
+  fillRect(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    color: PixelColor,
+  ): Result<void, ImageError>;
+  fillCircle(cx: number, cy: number, radius: number, color: PixelColor): Result<void, ImageError>;
+  blit(
+    source: PixelSurface,
+    destinationX: number,
+    destinationY: number,
+    sourceRect?: PixelSurfaceRect,
+  ): Result<void, ImageError>;
+  /** Fill RGB channels with deterministic seeded noise and set alpha uniformly. */
+  fillNoise(seed: number, options?: PixelSurfaceNoiseOptions): Result<void, ImageError>;
+  /** Alias kept on the same value for the concise authoring spelling. */
+  noise(seed: number, options?: PixelSurfaceNoiseOptions): Result<void, ImageError>;
+
+  toDecodedImage(): DecodedImage;
+  toTextureAsset(): TextureAsset;
+  toAssetPack(meta: ImageMeta): ExternalAssetPackage;
+}
+
+type SurfaceOperation = ImageErrorDetailFor<'image-surface-invalid'>['operation'];
+
+function invalid(
+  operation: SurfaceOperation,
+  field: string,
+  value: string | number,
+  expected: string,
+): Result<never, ImageError> {
+  return err(
+    imageError({
+      code: 'image-surface-invalid',
+      operation,
+      field,
+      value,
+      expected,
+    }),
+  );
+}
+
+function finiteNumber(
+  operation: SurfaceOperation,
+  field: string,
+  value: number,
+): Result<number, ImageError> {
+  if (!Number.isFinite(value)) {
+    return invalid(operation, field, String(value), 'a finite number');
+  }
+  return ok(value);
+}
+
+function positiveDimension(
+  operation: SurfaceOperation,
+  field: string,
+  value: number,
+): Result<number, ImageError> {
+  if (!Number.isInteger(value) || value <= 0) {
+    return invalid(operation, field, value, 'a positive integer');
+  }
+  return ok(value);
+}
+
+function colorChannels(
+  operation: SurfaceOperation,
+  color: PixelColor,
+): Result<readonly [number, number, number, number], ImageError> {
+  const channels = Array.isArray(color)
+    ? color
+    : color !== null && typeof color === 'object'
+      ? [
+          (color as Readonly<{ r: number; g: number; b: number; a: number }>).r,
+          (color as Readonly<{ r: number; g: number; b: number; a: number }>).g,
+          (color as Readonly<{ r: number; g: number; b: number; a: number }>).b,
+          (color as Readonly<{ r: number; g: number; b: number; a: number }>).a,
+        ]
+      : undefined;
+  if (channels === undefined || channels.length !== 4) {
+    return invalid(operation, 'color', 'malformed', 'four finite RGBA8 channels');
+  }
+  const normalized: [number, number, number, number] = [0, 0, 0, 0];
+  for (let index = 0; index < channels.length; index += 1) {
+    const channel = channels[index];
+    if (channel === undefined || !Number.isFinite(channel) || channel < 0 || channel > 255) {
+      return invalid(
+        operation,
+        `color[${index}]`,
+        channel ?? 'missing',
+        'a finite number in [0, 255]',
+      );
+    }
+    normalized[index] = Math.round(channel);
+  }
+  return ok(normalized);
+}
+
+function rounded(
+  operation: SurfaceOperation,
+  field: string,
+  value: number,
+): Result<number, ImageError> {
+  const result = finiteNumber(operation, field, value);
+  return result.ok ? ok(Math.round(result.value)) : result;
+}
+
+function rectangle(
+  operation: 'fill-rect' | 'blit',
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+): Result<readonly [number, number, number, number], ImageError> {
+  const values: [number, number, number, number] = [x, y, width, height];
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === undefined || !Number.isFinite(value)) {
+      return invalid(
+        operation,
+        ['x', 'y', 'width', 'height'][index] ?? 'rectangle',
+        String(value),
+        'a finite number',
+      );
+    }
+  }
+  if (width <= 0 || height <= 0) {
+    return invalid(
+      operation,
+      width <= 0 ? 'width' : 'height',
+      width <= 0 ? width : height,
+      'a positive number',
+    );
+  }
+  return ok([Math.round(x), Math.round(y), Math.round(width), Math.round(height)]);
+}
+
+function writePixel(
+  data: Uint8Array,
+  width: number,
+  x: number,
+  y: number,
+  color: ArrayLike<number>,
+): void {
+  if (x < 0 || y < 0 || x >= width) return;
+  const offset = (y * width + x) * 4;
+  data[offset] = color[0] ?? 0;
+  data[offset + 1] = color[1] ?? 0;
+  data[offset + 2] = color[2] ?? 0;
+  data[offset + 3] = color[3] ?? 0;
+}
+
+function fillClippedRect(
+  data: Uint8Array,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+  rectWidth: number,
+  rectHeight: number,
+  color: readonly number[],
+): void {
+  const left = Math.max(0, x);
+  const top = Math.max(0, y);
+  const right = Math.min(width, x + rectWidth);
+  const bottom = Math.min(height, y + rectHeight);
+  for (let row = top; row < bottom; row += 1) {
+    for (let column = left; column < right; column += 1) {
+      writePixel(data, width, column, row, color);
+    }
+  }
+}
+
+function nextRandom(state: number): number {
+  // xorshift32 is small, deterministic across runtimes, and has no ambient
+  // state. The seed is normalized once by fillNoise, so zero remains valid.
+  let value = state >>> 0;
+  value ^= value << 13;
+  value ^= value >>> 17;
+  value ^= value << 5;
+  return value >>> 0;
+}
+
+function makeSurface(options: PixelSurfaceOptions): Result<PixelSurface, ImageError> {
+  const width = positiveDimension('create', 'width', options.width);
+  if (!width.ok) return width;
+  const height = positiveDimension('create', 'height', options.height);
+  if (!height.ok) return height;
+  if (
+    options.colorSpace !== undefined &&
+    options.colorSpace !== 'srgb' &&
+    options.colorSpace !== 'linear'
+  ) {
+    return invalid('create', 'colorSpace', String(options.colorSpace), "'srgb' or 'linear'");
+  }
+  if (options.mipmap !== undefined && typeof options.mipmap !== 'boolean') {
+    return invalid('create', 'mipmap', String(options.mipmap), 'a boolean');
+  }
+  const data = new Uint8Array(width.value * height.value * 4);
+  const colorSpace = options.colorSpace ?? 'srgb';
+  const mipmap = options.mipmap ?? false;
+
+  const surface: PixelSurface = {
+    width: width.value,
+    height: height.value,
+    colorSpace,
+    mipmap,
+    data,
+    setPixel(x, y, color) {
+      const px = rounded('set-pixel', 'x', x);
+      if (!px.ok) return px;
+      const py = rounded('set-pixel', 'y', y);
+      if (!py.ok) return py;
+      const normalized = colorChannels('set-pixel', color);
+      if (!normalized.ok) return normalized;
+      writePixel(data, width.value, px.value, py.value, normalized.value);
+      return ok(undefined);
+    },
+    fillRect(x, y, rectWidth, rectHeight, color) {
+      const rect = rectangle('fill-rect', x, y, rectWidth, rectHeight);
+      if (!rect.ok) return rect;
+      const normalized = colorChannels('fill-rect', color);
+      if (!normalized.ok) return normalized;
+      fillClippedRect(
+        data,
+        width.value,
+        height.value,
+        rect.value[0] ?? 0,
+        rect.value[1] ?? 0,
+        rect.value[2] ?? 0,
+        rect.value[3] ?? 0,
+        normalized.value,
+      );
+      return ok(undefined);
+    },
+    fillCircle(cx, cy, radius, color) {
+      const centerX = rounded('fill-circle', 'cx', cx);
+      if (!centerX.ok) return centerX;
+      const centerY = rounded('fill-circle', 'cy', cy);
+      if (!centerY.ok) return centerY;
+      const circleRadius = rounded('fill-circle', 'radius', radius);
+      if (!circleRadius.ok) return circleRadius;
+      if (circleRadius.value <= 0) {
+        return invalid('fill-circle', 'radius', circleRadius.value, 'a positive number');
+      }
+      const normalized = colorChannels('fill-circle', color);
+      if (!normalized.ok) return normalized;
+      const radiusSquared = circleRadius.value * circleRadius.value;
+      const left = Math.max(0, centerX.value - circleRadius.value);
+      const right = Math.min(width.value - 1, centerX.value + circleRadius.value);
+      const top = Math.max(0, centerY.value - circleRadius.value);
+      const bottom = Math.min(height.value - 1, centerY.value + circleRadius.value);
+      for (let row = top; row <= bottom; row += 1) {
+        for (let column = left; column <= right; column += 1) {
+          const dx = column - centerX.value;
+          const dy = row - centerY.value;
+          if (dx * dx + dy * dy <= radiusSquared)
+            writePixel(data, width.value, column, row, normalized.value);
+        }
+      }
+      return ok(undefined);
+    },
+    blit(source, destinationX, destinationY, sourceRect) {
+      const destination = rounded('blit', 'destinationX', destinationX);
+      if (!destination.ok) return destination;
+      const destinationYResult = rounded('blit', 'destinationY', destinationY);
+      if (!destinationYResult.ok) return destinationYResult;
+      if (
+        source === null ||
+        typeof source !== 'object' ||
+        !Number.isInteger(source.width) ||
+        !Number.isInteger(source.height) ||
+        !(source.data instanceof Uint8Array) ||
+        source.data.length !== source.width * source.height * 4
+      ) {
+        return invalid('blit', 'source', 'malformed', 'a valid PixelSurface');
+      }
+      const rect = rectangle(
+        'blit',
+        sourceRect?.x ?? 0,
+        sourceRect?.y ?? 0,
+        sourceRect?.width ?? source.width,
+        sourceRect?.height ?? source.height,
+      );
+      if (!rect.ok) return rect;
+      const sourceX = rect.value[0] ?? 0;
+      const sourceY = rect.value[1] ?? 0;
+      const sourceWidth = rect.value[2] ?? 0;
+      const sourceHeight = rect.value[3] ?? 0;
+      const left = Math.max(0, sourceX);
+      const top = Math.max(0, sourceY);
+      const right = Math.min(source.width, sourceX + sourceWidth);
+      const bottom = Math.min(source.height, sourceY + sourceHeight);
+      if (right <= left || bottom <= top) return ok(undefined);
+      const snapshot = source.data.slice();
+      for (let row = top; row < bottom; row += 1) {
+        for (let column = left; column < right; column += 1) {
+          const targetX = destination.value + column - sourceX;
+          const targetY = destinationYResult.value + row - sourceY;
+          if (targetX < 0 || targetY < 0 || targetX >= width.value || targetY >= height.value)
+            continue;
+          const sourceOffset = (row * source.width + column) * 4;
+          writePixel(
+            data,
+            width.value,
+            targetX,
+            targetY,
+            snapshot.subarray(sourceOffset, sourceOffset + 4),
+          );
+        }
+      }
+      return ok(undefined);
+    },
+    fillNoise(seed, noiseOptions) {
+      if (!Number.isFinite(seed)) return invalid('noise', 'seed', String(seed), 'a finite number');
+      const min = noiseOptions?.min ?? 0;
+      const max = noiseOptions?.max ?? 255;
+      const alpha = noiseOptions?.alpha ?? 255;
+      for (const [field, value] of [
+        ['min', min],
+        ['max', max],
+        ['alpha', alpha],
+      ] as const) {
+        if (!Number.isFinite(value) || value < 0 || value > 255) {
+          return invalid('noise', field, value, 'a finite number in [0, 255]');
+        }
+      }
+      if (min > max) return invalid('noise', 'min', min, 'a value no greater than max');
+      let state = Math.trunc(seed) >>> 0 || 0x6d2b79f5;
+      const span = max - min;
+      for (let index = 0; index < data.length; index += 4) {
+        state = nextRandom(state);
+        const value = min + (state / 0x100000000) * span;
+        const channel = Math.round(value);
+        data[index] = channel;
+        data[index + 1] = channel;
+        data[index + 2] = channel;
+        data[index + 3] = Math.round(alpha);
+      }
+      return ok(undefined);
+    },
+    noise(seed, noiseOptions) {
+      return surface.fillNoise(seed, noiseOptions);
+    },
+    toDecodedImage() {
+      return {
+        bytes: data.slice(),
+        width: width.value,
+        height: height.value,
+        mime: 'image/png',
+        colorSpace,
+        mipmap,
+      };
+    },
+    toTextureAsset() {
+      return {
+        kind: 'texture',
+        shape: {
+          viewDimension: '2d',
+          extent: { width: width.value, height: height.value },
+        },
+        format: colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm',
+        data: data.slice(),
+        colorSpace,
+        mips: mipmap ? { kind: 'generate' } : { kind: 'none' },
+      };
+    },
+    toAssetPack(meta) {
+      return toAssetPack(surface.toDecodedImage(), meta);
+    },
+  };
+  return ok(surface);
+}
+
+/** Create a deterministic, image-owned RGBA8 authoring surface. */
+export function createPixelSurface(options: PixelSurfaceOptions): Result<PixelSurface, ImageError> {
+  return makeSurface(options);
+}