@forgeax/engine-image 0.1.19 → 0.1.20

package/src/image-importer.ts

@@ -46,6 +46,7 @@ import { IMPORT_ERROR_HINTS, ImportError } from '@forgeax/engine-types';
 import type { CompressionMode } from './ktx2-encode.js';
 import { encodeTextureToKtx2, resolveEncodeMode } from './ktx2-encode.js';
 import { parseImage } from './parse-image.js';
+import { importTextureSource } from './texture/importer.js';
 
 /** Map a source path / mime hint to the parseImage mime literal. */
 function mimeFromSource(source: string): 'image/png' | 'image/jpeg' | undefined {
@@ -319,13 +320,17 @@ async function importKtx2Source(ctx: ImportContext, bytes: Uint8Array): Promise<
       kind: 'texture',
       payload: {
         kind: 'texture',
-        width: inspection.width,
-        height: inspection.height,
+        shape: {
+          viewDimension: '2d',
+          extent: { width: inspection.width, height: inspection.height },
+        },
         format: colorSpaceToFormat(inspection.colorSpace),
         data: bytes,
         colorSpace: inspection.colorSpace,
-        mipmap: inspection.levelCount > 1,
-        mipLevelCount: inspection.levelCount,
+        mips:
+          inspection.levelCount > 1
+            ? { kind: 'packed', levelCount: inspection.levelCount }
+            : { kind: 'none' },
       },
       refs: [],
       artifacts: {
@@ -481,13 +486,17 @@ async function importBasisSource(ctx: ImportContext, bytes: Uint8Array): Promise
       kind: 'texture',
       payload: {
         kind: 'texture',
-        width: inspection.width,
-        height: inspection.height,
+        shape: {
+          viewDimension: '2d',
+          extent: { width: inspection.width, height: inspection.height },
+        },
         format: colorSpaceToFormat(colorSpace),
         data: bytes,
         colorSpace,
-        mipmap: inspection.levelCount > 1,
-        mipLevelCount: inspection.levelCount,
+        mips:
+          inspection.levelCount > 1
+            ? { kind: 'packed', levelCount: inspection.levelCount }
+            : { kind: 'none' },
       },
       refs: [],
       artifacts: {
@@ -574,6 +583,9 @@ async function maybeEncodeTextureBytes(
 }
 
 async function importImage(ctx: ImportContext): Promise<ImportResult> {
+  if (ctx.source.toLowerCase().endsWith('.texture.json')) {
+    return importTextureSource(ctx);
+  }
   const requiredKind = requiredImageOutputKind(ctx.source);
   if (requiredKind !== undefined) {
     const topologyError = validateImageOutputTopology(ctx, requiredKind);
@@ -730,12 +742,11 @@ async function importImage(ctx: ImportContext): Promise<ImportResult> {
     if (sub.kind !== 'texture') continue;
     const payload: TextureAsset = {
       kind: 'texture',
-      width: dec.width,
-      height: dec.height,
+      shape: { viewDimension: '2d', extent: { width: dec.width, height: dec.height } },
       format: colorSpaceToFormat(colorSpace),
       data: encodedBytes ?? dec.bytes,
       colorSpace,
-      mipmap,
+      mips: mipmap ? { kind: 'generate' } : { kind: 'none' },
     };
     out.push({
       guid: sub.guid,
@@ -825,11 +836,10 @@ export const decodeImageForImport: ImportContext['decodeImage'] = async (
       texture: {
         kind: 'texture' as const,
         data: cookedBytes,
-        width: tex.width,
-        height: tex.height,
+        shape: { viewDimension: '2d', extent: { width: tex.width, height: tex.height } },
         format: colorSpaceToFormat(colorSpace),
         colorSpace,
-        mipmap,
+        mips: mipmap ? { kind: 'generate' as const } : { kind: 'none' as const },
       },
       bytes: cookedBytes,
       mediaType,

package/src/runtime/asset-decoders.ts

@@ -37,11 +37,32 @@ function compressedImageTarget(colorSpace: TextureAsset['colorSpace']): TextureA
   return colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
 }
 
-function validImageSurface(
+function validTextureSurface(
   value: unknown,
-): value is Pick<TextureAsset, 'width' | 'height' | 'format' | 'data' | 'colorSpace'> {
+): value is Pick<TextureAsset, 'shape' | 'format' | 'data' | 'colorSpace' | 'mips'> {
   if (value === null || typeof value !== 'object') return false;
   const candidate = value as Partial<TextureAsset>;
+  const shape = candidate.shape;
+  const extent = shape?.viewDimension === '2d' ? shape.extent : undefined;
+  const mips = candidate.mips;
+  return (
+    extent !== undefined &&
+    validDimensions(extent.width, extent.height) &&
+    mips !== undefined &&
+    (mips.kind === 'none' ||
+      mips.kind === 'generate' ||
+      (mips.kind === 'packed' && Number.isSafeInteger(mips.levelCount) && mips.levelCount > 0)) &&
+    typeof candidate.format === 'string' &&
+    imageBytes(candidate.data) !== undefined &&
+    (candidate.colorSpace === 'srgb' || candidate.colorSpace === 'linear')
+  );
+}
+
+function validEquirectSurface(
+  value: unknown,
+): value is Pick<EquirectAsset, 'width' | 'height' | 'format' | 'data' | 'colorSpace'> {
+  if (value === null || typeof value !== 'object') return false;
+  const candidate = value as Partial<EquirectAsset>;
   return (
     validDimensions(candidate.width ?? 0, candidate.height ?? 0) &&
     typeof candidate.format === 'string' &&
@@ -96,17 +117,24 @@ async function readImageSurface<P extends TextureAsset | EquirectAsset>(
       const mip = transcoded.value.mips[0];
       if (mip === undefined) return invalid(envelope.guid, expected, 'codec:base-mip-missing');
       data = mip.data;
-      return readDecodedSurface(envelope.guid, expected, {
-        ...payload,
-        width: mip.width,
-        height: mip.height,
-        format: target,
-        data,
-      });
+      return readDecodedSurface(
+        envelope.guid,
+        expected,
+        kind,
+        kind === 'texture'
+          ? {
+              ...payload,
+              shape: { viewDimension: '2d', extent: { width: mip.width, height: mip.height } },
+              format: target,
+              data,
+              mips: { kind: 'none' },
+            }
+          : { ...payload, width: mip.width, height: mip.height, format: target, data },
+      );
     }
   }
 
-  return readDecodedSurface(envelope.guid, expected, {
+  return readDecodedSurface(envelope.guid, expected, kind, {
     ...payload,
     ...(data === undefined ? {} : { data }),
   });
@@ -115,9 +143,10 @@ async function readImageSurface<P extends TextureAsset | EquirectAsset>(
 function readDecodedSurface<P extends TextureAsset | EquirectAsset>(
   guid: string,
   expected: string,
+  kind: P['kind'],
   candidate: unknown,
 ): ReturnType<typeof ok<P>> | ReturnType<typeof err<AssetLoadError>> {
-  if (!validImageSurface(candidate)) {
+  if (kind === 'texture' ? !validTextureSurface(candidate) : !validEquirectSurface(candidate)) {
     return invalid(guid, expected, 'image owner validation failed');
   }
   return ok(candidate as P);

package/src/texture/importer.ts

@@ -0,0 +1,198 @@
+import type {
+  ImportContext,
+  ImportedAsset,
+  TextureAsset,
+  TextureError,
+} from '@forgeax/engine-types';
+import { deriveTextureLayout, err, ImportError, ok, type Result } from '@forgeax/engine-types';
+import {
+  parseTextureSourceDescriptor,
+  type TextureSourceDescriptor,
+  type TextureSourceDescriptorError,
+} from './source-descriptor.js';
+
+export interface TextureSourceInput {
+  readonly descriptor: unknown;
+  readonly guid: string;
+  readonly sourceKey: string;
+  readSibling(
+    uri: string,
+  ): Promise<
+    | { readonly ok: true; readonly value: Uint8Array }
+    | { readonly ok: false; readonly error: unknown }
+  >;
+}
+
+export interface TextureSourceReadError {
+  readonly code: 'source-read-failed';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly sourceKey: string;
+    readonly sibling: string;
+    readonly reason: string;
+  };
+}
+
+export type TextureSourceError =
+  | TextureSourceDescriptorError
+  | TextureSourceReadError
+  | TextureError;
+
+export type TextureSourceResult = Result<ImportedAsset<TextureAsset>, TextureSourceError>;
+
+function sourceReadError(input: TextureSourceInput, reason: unknown): TextureSourceReadError {
+  return {
+    code: 'source-read-failed',
+    expected: `readable raw sibling "${input.descriptor && typeof input.descriptor === 'object' && 'rawSibling' in input.descriptor ? input.descriptor.rawSibling : 'rawSibling'}"`,
+    hint: 'repair the raw sibling path or bytes and re-import the same texture GUID',
+    detail: {
+      sourceKey: input.sourceKey,
+      sibling:
+        input.descriptor && typeof input.descriptor === 'object' && 'rawSibling' in input.descriptor
+          ? String(input.descriptor.rawSibling)
+          : 'rawSibling',
+      reason: reason instanceof Error ? reason.message : String(reason),
+    },
+  };
+}
+
+function bodyMediaType(format: GPUTextureFormat): string {
+  return format === 'r8unorm' ? 'application/x-forgeax-r8' : `application/x-forgeax-${format}`;
+}
+
+/** Produce one canonical TextureAsset and body artifact from a descriptor sibling. */
+export async function produceTextureSource(
+  input: TextureSourceInput,
+): Promise<TextureSourceResult> {
+  const descriptorResult = parseTextureSourceDescriptor(input.descriptor);
+  if (!descriptorResult.ok) return descriptorResult;
+  const descriptor = descriptorResult.value;
+  const sibling = await input.readSibling(descriptor.rawSibling);
+  if (!sibling.ok) return err(sourceReadError(input, sibling.error));
+
+  const layout = deriveTextureLayout({
+    shape: descriptor.shape,
+    format: descriptor.format,
+    mips: descriptor.mips,
+    actualByteLength: sibling.value.byteLength,
+    order: 'mip-major,image-major,row-major',
+  });
+  if (!layout.ok) return layout;
+
+  const data = new Uint8Array(sibling.value);
+  return ok({
+    guid: input.guid,
+    kind: 'texture',
+    payload: {
+      kind: 'texture',
+      shape: descriptor.shape,
+      format: descriptor.format,
+      colorSpace: descriptor.colorSpace,
+      mips: descriptor.mips,
+      data,
+    },
+    refs: [],
+    artifacts: {
+      body: {
+        mediaType: bodyMediaType(descriptor.format),
+        assetCodec: { name: descriptor.format, version: '1' },
+        bytes: data,
+      },
+    },
+  });
+}
+
+function sourceValidationError(ctx: ImportContext, error: TextureSourceError): ImportError {
+  const detail = 'detail' in error ? error.detail : { field: 'descriptor', actual: error };
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: error.expected,
+    hint: error.hint,
+    detail: {
+      diagnostics: [
+        {
+          code: `texture-source-${error.code}`,
+          severity: 'error',
+          sourcePath: `${ctx.source}#${'field' in detail ? detail.field : 'rawSibling'}`,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: 'texture-source-descriptor',
+          expected: error.expected,
+          actual: JSON.stringify(detail),
+          hint: error.hint,
+        },
+      ],
+    },
+  });
+}
+
+/** Import a JSON descriptor whose canonical bytes live in one raw sibling. */
+export async function importTextureSource(ctx: ImportContext): Promise<
+  | {
+      readonly ok: true;
+      readonly value: {
+        readonly assets: readonly ImportedAsset[];
+        readonly sourceDependencies: readonly string[];
+      };
+    }
+  | { readonly ok: false; readonly error: ImportError }
+> {
+  const source = await ctx.readSource();
+  if (!source.ok) {
+    const reason = String(source.error);
+    return {
+      ok: false,
+      error: new ImportError({
+        code: 'source-read-failed',
+        expected: `readable texture descriptor at "${ctx.source}"`,
+        hint: 'repair the texture descriptor path and retry the import',
+        detail: { source: ctx.source, reason },
+      }),
+    };
+  }
+
+  let descriptor: unknown;
+  try {
+    descriptor = JSON.parse(new TextDecoder().decode(source.value));
+  } catch (error) {
+    return {
+      ok: false,
+      error: sourceValidationError(ctx, {
+        code: 'texture-source-descriptor-invalid',
+        expected: 'JSON texture source descriptor',
+        hint: 'repair the descriptor JSON and retry the import',
+        detail: {
+          field: 'descriptor',
+          actual: error instanceof Error ? error.message : String(error),
+        },
+      }),
+    };
+  }
+  const subAsset = ctx.subAssets.length === 1 ? ctx.subAssets[0] : undefined;
+  if (subAsset === undefined || subAsset.kind !== 'texture' || subAsset.sourceIndex !== 0) {
+    return {
+      ok: false,
+      error: sourceValidationError(ctx, {
+        code: 'texture-source-descriptor-invalid',
+        expected: 'one texture subAsset at sourceIndex 0',
+        hint: 'repair Meta subAssets and retry the same texture GUID',
+        detail: { field: 'subAssets', actual: ctx.subAssets },
+      }),
+    };
+  }
+  const produced = await produceTextureSource({
+    descriptor,
+    guid: subAsset.guid,
+    sourceKey: subAsset.sourceKey ?? `${ctx.source}:texture`,
+    readSibling: ctx.readSibling,
+  });
+  if (!produced.ok) return { ok: false, error: sourceValidationError(ctx, produced.error) };
+  const parsed = parseTextureSourceDescriptor(descriptor);
+  const sibling = parsed.ok ? parsed.value.rawSibling : ctx.source;
+  return {
+    ok: true,
+    value: { assets: [produced.value], sourceDependencies: [ctx.source, sibling] },
+  };
+}
+
+export type { TextureSourceDescriptor };

package/src/texture/source-descriptor.ts

@@ -0,0 +1,123 @@
+import type { TextureMipPolicy, TextureShape } from '@forgeax/engine-types';
+import {
+  err,
+  ok,
+  type Result,
+  type TextureError,
+  validateTextureShape,
+} from '@forgeax/engine-types';
+
+/** Versioned source-side declaration for one logical sampled texture. */
+export interface TextureSourceDescriptor {
+  readonly schemaVersion: '1';
+  readonly shape: TextureShape;
+  readonly format: GPUTextureFormat;
+  readonly colorSpace: 'srgb' | 'linear';
+  readonly mips: TextureMipPolicy;
+  readonly rawSibling: string;
+}
+
+export interface TextureSourceDescriptorError {
+  readonly code: 'texture-source-descriptor-invalid';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: { readonly field: string; readonly actual: unknown };
+}
+
+export type TextureSourceDescriptorResult = Result<
+  TextureSourceDescriptor,
+  TextureSourceDescriptorError | TextureError
+>;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function positiveInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+function parseShape(value: unknown): TextureShape | undefined {
+  if (!record(value) || !record(value.extent)) return undefined;
+  const extent = value.extent;
+  if (
+    value.viewDimension === '2d' &&
+    positiveInteger(extent.width) &&
+    positiveInteger(extent.height)
+  ) {
+    if (extent.layers === undefined && extent.depth === undefined) {
+      return { viewDimension: '2d', extent: { width: extent.width, height: extent.height } };
+    }
+  }
+  if (
+    value.viewDimension === '2d-array' &&
+    positiveInteger(extent.width) &&
+    positiveInteger(extent.height) &&
+    positiveInteger(extent.layers) &&
+    extent.depth === undefined
+  ) {
+    return {
+      viewDimension: '2d-array',
+      extent: { width: extent.width, height: extent.height, layers: extent.layers },
+    };
+  }
+  if (
+    value.viewDimension === '3d' &&
+    positiveInteger(extent.width) &&
+    positiveInteger(extent.height) &&
+    positiveInteger(extent.depth) &&
+    extent.layers === undefined
+  ) {
+    return {
+      viewDimension: '3d',
+      extent: { width: extent.width, height: extent.height, depth: extent.depth },
+    };
+  }
+  return undefined;
+}
+
+function parseMips(value: unknown): TextureMipPolicy | undefined {
+  if (!record(value)) return undefined;
+  if (value.kind === 'none' || value.kind === 'generate') return { kind: value.kind };
+  if (value.kind === 'packed' && positiveInteger(value.levelCount)) {
+    return { kind: 'packed', levelCount: value.levelCount };
+  }
+  return undefined;
+}
+
+function descriptorError(field: string, actual: unknown): TextureSourceDescriptorError {
+  return {
+    code: 'texture-source-descriptor-invalid',
+    expected: 'version 1 descriptor with shape, format, colorSpace, mips, and rawSibling',
+    hint: 'repair the texture descriptor and re-import the same texture GUID',
+    detail: { field, actual },
+  };
+}
+
+/** Parse and validate source facts before any raw sibling bytes are consumed. */
+export function parseTextureSourceDescriptor(value: unknown): TextureSourceDescriptorResult {
+  if (!record(value)) return err(descriptorError('descriptor', value));
+  if (value.schemaVersion !== '1')
+    return err(descriptorError('schemaVersion', value.schemaVersion));
+  const shape = parseShape(value.shape);
+  if (shape === undefined) return err(descriptorError('shape', value.shape));
+  const mips = parseMips(value.mips);
+  if (mips === undefined) return err(descriptorError('mips', value.mips));
+  if (typeof value.format !== 'string') return err(descriptorError('format', value.format));
+  if (value.colorSpace !== 'srgb' && value.colorSpace !== 'linear') {
+    return err(descriptorError('colorSpace', value.colorSpace));
+  }
+  if (typeof value.rawSibling !== 'string' || value.rawSibling.trim().length === 0) {
+    return err(descriptorError('rawSibling', value.rawSibling));
+  }
+  const shapeResult = validateTextureShape(shape, mips, value.format as GPUTextureFormat);
+  if (!shapeResult.ok) return shapeResult;
+  return ok({
+    schemaVersion: '1',
+    shape,
+    format: value.format as GPUTextureFormat,
+    colorSpace: value.colorSpace,
+    mips,
+    rawSibling: value.rawSibling,
+  });
+}