@forgeax/engine-image 0.1.19 → 0.1.21

package/dist/index.mjs

@@ -19,7 +19,8 @@ var IMAGE_ERROR_EXPECTED = {
   // .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"
 };
 var ImageErrorImpl = class extends Error {
   code;
@@ -273,6 +274,314 @@ async function loadJpeg() {
   return mod.default ?? mod;
 }
 
+// src/to-asset-pack.ts
+function toAssetPack(decoded, meta) {
+  return {
+    schemaVersion: "1.0.0",
+    kind: "external-asset-package",
+    importer: "image",
+    source: "",
+    importSettings: {
+      colorSpace: meta.colorSpace,
+      mipmap: meta.mipmap,
+      addressMode: meta.addressMode,
+      filterMode: meta.filterMode,
+      ...meta.downscaleMaxDimension !== void 0 ? { downscaleMaxDimension: meta.downscaleMaxDimension } : {}
+    },
+    subAssets: [
+      {
+        guid: meta.guid,
+        sourceIndex: 0,
+        kind: "texture"
+      }
+    ]
+  };
+}
+
+// src/pixel-surface.ts
+function invalid(operation, field, value, expected) {
+  return err(
+    imageError({
+      code: "image-surface-invalid",
+      operation,
+      field,
+      value,
+      expected
+    })
+  );
+}
+function finiteNumber(operation, field, value) {
+  if (!Number.isFinite(value)) {
+    return invalid(operation, field, String(value), "a finite number");
+  }
+  return ok(value);
+}
+function positiveDimension(operation, field, value) {
+  if (!Number.isInteger(value) || value <= 0) {
+    return invalid(operation, field, value, "a positive integer");
+  }
+  return ok(value);
+}
+function colorChannels(operation, color) {
+  const channels = Array.isArray(color) ? color : color !== null && typeof color === "object" ? [
+    color.r,
+    color.g,
+    color.b,
+    color.a
+  ] : void 0;
+  if (channels === void 0 || channels.length !== 4) {
+    return invalid(operation, "color", "malformed", "four finite RGBA8 channels");
+  }
+  const normalized = [0, 0, 0, 0];
+  for (let index = 0; index < channels.length; index += 1) {
+    const channel = channels[index];
+    if (channel === void 0 || !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, field, value) {
+  const result = finiteNumber(operation, field, value);
+  return result.ok ? ok(Math.round(result.value)) : result;
+}
+function rectangle(operation, x, y, width, height) {
+  const values = [x, y, width, height];
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+    if (value === void 0 || !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, width, x, y, color) {
+  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, width, height, x, y, rectWidth, rectHeight, color) {
+  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) {
+  let value = state >>> 0;
+  value ^= value << 13;
+  value ^= value >>> 17;
+  value ^= value << 5;
+  return value >>> 0;
+}
+function makeSurface(options) {
+  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 !== void 0 && options.colorSpace !== "srgb" && options.colorSpace !== "linear") {
+    return invalid("create", "colorSpace", String(options.colorSpace), "'srgb' or 'linear'");
+  }
+  if (options.mipmap !== void 0 && 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 = {
+    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(void 0);
+    },
+    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(void 0);
+    },
+    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(void 0);
+    },
+    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(void 0);
+      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(void 0);
+    },
+    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]
+      ]) {
+        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 || 1831565813;
+      const span = max - min;
+      for (let index = 0; index < data.length; index += 4) {
+        state = nextRandom(state);
+        const value = min + state / 4294967296 * 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(void 0);
+    },
+    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);
+}
+function createPixelSurface(options) {
+  return makeSurface(options);
+}
+
 // src/source-key.ts
 function deriveImageSourceKey(role, _locator) {
   const normalizedRole = role.trim();
@@ -338,7 +647,7 @@ function reimportReuseMeta(decoded, existing) {
   }
   return out;
 }
-function invalid(guid, expected, reason) {
+function invalid2(guid, expected, reason) {
   return err({
     code: "asset-package-invalid",
     expected,
@@ -360,7 +669,15 @@ function imageBytes(value) {
 function compressedImageTarget(colorSpace) {
   return colorSpace === "srgb" ? "rgba8unorm-srgb" : "rgba8unorm";
 }
-function validImageSurface(value) {
+function validTextureSurface(value) {
+  if (value === null || typeof value !== "object") return false;
+  const candidate = value;
+  const shape = candidate.shape;
+  const extent = shape?.viewDimension === "2d" ? shape.extent : void 0;
+  const mips = candidate.mips;
+  return extent !== void 0 && validDimensions(extent.width, extent.height) && mips !== void 0 && (mips.kind === "none" || mips.kind === "generate" || mips.kind === "packed" && Number.isSafeInteger(mips.levelCount) && mips.levelCount > 0) && typeof candidate.format === "string" && imageBytes(candidate.data) !== void 0 && (candidate.colorSpace === "srgb" || candidate.colorSpace === "linear");
+}
+function validEquirectSurface(value) {
   if (value === null || typeof value !== "object") return false;
   const candidate = value;
   return validDimensions(candidate.width ?? 0, candidate.height ?? 0) && typeof candidate.format === "string" && imageBytes(candidate.data) !== void 0 && (candidate.colorSpace === "srgb" || candidate.colorSpace === "linear");
@@ -369,7 +686,7 @@ async function readImageSurface(input, kind, expected) {
   const { envelope, artifacts } = input;
   const payload = envelope.payload;
   if (payload === null || typeof payload !== "object" || payload.kind !== kind) {
-    return invalid(envelope.guid, expected, `${kind} owner validation failed`);
+    return invalid2(envelope.guid, expected, `${kind} owner validation failed`);
   }
   const body = envelope.artifacts.body ?? envelope.artifacts.atlas;
   let data = imageBytes(payload.data);
@@ -381,35 +698,40 @@ async function readImageSurface(input, kind, expected) {
     if (body.assetCodec?.name === "basis" && body.assetCodec.container !== void 0) {
       const candidate = payload;
       if (candidate.colorSpace !== "srgb" && candidate.colorSpace !== "linear") {
-        return invalid(envelope.guid, expected, `${kind} color space is invalid`);
+        return invalid2(envelope.guid, expected, `${kind} color space is invalid`);
       }
       const target = compressedImageTarget(candidate.colorSpace);
       const transcoded = body.assetCodec.container === "ktx2" ? await parseKtx2(bytes).then(
         (parsed) => parsed.ok ? transcodeKtx2(parsed.value, target) : parsed
       ) : await transcodeBasis(bytes, target);
       if (!transcoded.ok) {
-        return invalid(envelope.guid, expected, `codec:${transcoded.error.code}`);
+        return invalid2(envelope.guid, expected, `codec:${transcoded.error.code}`);
       }
       const mip = transcoded.value.mips[0];
-      if (mip === void 0) return invalid(envelope.guid, expected, "codec:base-mip-missing");
+      if (mip === void 0) return invalid2(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 === void 0 ? {} : { data }
   });
 }
-function readDecodedSurface(guid, expected, candidate) {
-  if (!validImageSurface(candidate)) {
-    return invalid(guid, expected, "image owner validation failed");
+function readDecodedSurface(guid, expected, kind, candidate) {
+  if (kind === "texture" ? !validTextureSurface(candidate) : !validEquirectSurface(candidate)) {
+    return invalid2(guid, expected, "image owner validation failed");
   }
   return ok(candidate);
 }
@@ -440,30 +762,6 @@ var equirectContribution = {
   }
 };
 
-// src/to-asset-pack.ts
-function toAssetPack(decoded, meta) {
-  return {
-    schemaVersion: "1.0.0",
-    kind: "external-asset-package",
-    importer: "image",
-    source: "",
-    importSettings: {
-      colorSpace: meta.colorSpace,
-      mipmap: meta.mipmap,
-      addressMode: meta.addressMode,
-      filterMode: meta.filterMode,
-      ...meta.downscaleMaxDimension !== void 0 ? { downscaleMaxDimension: meta.downscaleMaxDimension } : {}
-    },
-    subAssets: [
-      {
-        guid: meta.guid,
-        sourceIndex: 0,
-        kind: "texture"
-      }
-    ]
-  };
-}
-
-export { IMAGE_ERROR_EXPECTED, ImageErrorImpl, decodeHdr, decodeImageInBrowser, deriveImageSourceKey, equirectContribution, imageError, loadJpeg, loadUpng, reimportReuseMeta, subAssetKey, subAssetKeyEqual, textureContribution, toAssetPack };
+export { IMAGE_ERROR_EXPECTED, ImageErrorImpl, createPixelSurface, decodeHdr, decodeImageInBrowser, deriveImageSourceKey, equirectContribution, imageError, loadJpeg, loadUpng, reimportReuseMeta, subAssetKey, subAssetKeyEqual, textureContribution, toAssetPack };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map