@forgeax/engine-image 0.1.19 → 0.1.21

package/dist/image-importer.mjs

@@ -1,4 +1,4 @@
-import { err, ok, ImportError, IMPORT_ERROR_HINTS, IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+import { err, ok, ImportError, IMPORT_ERROR_HINTS, deriveTextureLayout, validateTextureShape, IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
 import { parseKtx2, ktx2ColorSpace } from '@forgeax/engine-codec';
 import { basisEncode } from '@forgeax/engine-codec/encode';
 import * as jpeg from 'jpeg-js';
@@ -34,7 +34,8 @@ var init_errors = __esm({
       // .hint after switch (err.code) without parsing the message).
       "atlas-empty-input": "images.length >= 1",
       "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"
+      "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"
     };
     ImageErrorImpl = class extends Error {
       code;
@@ -441,6 +442,208 @@ function parseImage(bytes, mime, opts = {}) {
     mipmap: opts.mipmap ?? true
   });
 }
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positiveInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function parseShape(value) {
+  if (!record(value) || !record(value.extent)) return void 0;
+  const extent = value.extent;
+  if (value.viewDimension === "2d" && positiveInteger(extent.width) && positiveInteger(extent.height)) {
+    if (extent.layers === void 0 && extent.depth === void 0) {
+      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 === void 0) {
+    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 === void 0) {
+    return {
+      viewDimension: "3d",
+      extent: { width: extent.width, height: extent.height, depth: extent.depth }
+    };
+  }
+  return void 0;
+}
+function parseMips(value) {
+  if (!record(value)) return void 0;
+  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 void 0;
+}
+function descriptorError(field, actual) {
+  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 }
+  };
+}
+function parseTextureSourceDescriptor(value) {
+  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 === void 0) return err(descriptorError("shape", value.shape));
+  const mips = parseMips(value.mips);
+  if (mips === void 0) 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);
+  if (!shapeResult.ok) return shapeResult;
+  return ok({
+    schemaVersion: "1",
+    shape,
+    format: value.format,
+    colorSpace: value.colorSpace,
+    mips,
+    rawSibling: value.rawSibling
+  });
+}
+
+// src/texture/importer.ts
+function sourceReadError(input, reason) {
+  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) {
+  return format === "r8unorm" ? "application/x-forgeax-r8" : `application/x-forgeax-${format}`;
+}
+async function produceTextureSource(input) {
+  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, error) {
+  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
+        }
+      ]
+    }
+  });
+}
+async function importTextureSource(ctx) {
+  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;
+  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] : void 0;
+  if (subAsset === void 0 || 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] }
+  };
+}
 
 // src/image-importer.ts
 function mimeFromSource(source) {
@@ -658,13 +861,14 @@ async function importKtx2Source(ctx, bytes) {
       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: {
@@ -813,13 +1017,14 @@ async function importBasisSource(ctx, bytes) {
       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: {
@@ -869,6 +1074,9 @@ async function maybeEncodeTextureBytes(ctx, pixels, width, height, compressionMo
   return { ok: true, value: result.value.ktx2 };
 }
 async function importImage(ctx) {
+  if (ctx.source.toLowerCase().endsWith(".texture.json")) {
+    return importTextureSource(ctx);
+  }
   const requiredKind = requiredImageOutputKind(ctx.source);
   if (requiredKind !== void 0) {
     const topologyError = validateImageOutputTopology(ctx, requiredKind);
@@ -990,12 +1198,11 @@ async function importImage(ctx) {
     if (sub.kind !== "texture") continue;
     const payload = {
       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,
@@ -1062,11 +1269,10 @@ var decodeImageForImport = async (bytes, mimeType, importSettings) => {
       texture: {
         kind: "texture",
         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" } : { kind: "none" }
       },
       bytes: cookedBytes,
       mediaType,