@carbonenginejs/runtime-resource 0.13.0 → 0.15.0

package/dist/format/carbonEffect/carbonEffectResourceTransform.js

@@ -1,197 +1,197 @@
-import { CjsFormatReadError, CjsFormatWriteError } from '../CjsFormatError.js';
-
-/**
- * The resource-transform section, shared by every backend's per-pass block.
- *
- * A resource transform is a recipe for building one backend resource out of
- * several Carbon ones. It is deliberately backend-neutral: `detail-map-array`
- * merges `Detail1Map`, `Detail2Map` and `Detail3Map` into one array texture, and
- * that decision is about the *resources*, not about WGSL or GLSL. Both backends
- * want the identical merge, for different reasons - WebGPU to reduce binding
- * churn, WebGL 2 because the family otherwise needs 17 texture units against a
- * limit of 16 (docs/contracts/webgl2-texture-budget.md).
- *
- * So the section lives here rather than in either backend's block codec, and the
- * two codecs compose it. A transform written by one backend decodes identically
- * under the other.
- */
-
-/**
- * Resource-transform families. The discriminator exists so `kind`,
- * `representation`, `missingLayer` and the output name stay derivable without
- * pinning the format to one recognizer: a second family costs an enum value
- * rather than a format version bump.
- */
-const CARBON_BACKEND_TRANSFORM_FAMILY = Object.freeze(["detail-map-array", "local-light-profile-neutral"]);
-
-/** Constants a `detail-map-array` transform restores rather than storing. */
-const DETAIL_MAP_ARRAY_DEFAULTS = Object.freeze({
-  version: 1,
-  kind: "texture-2d-array",
-  stage: "fragment",
-  representation: "native-or-rgba8",
-  missingLayer: "reject",
-  viewDimension: "2d-array",
-  outputName: "DetailArrayMap"
-});
-
-/**
- * Constants a `local-light-profile-neutral` transform restores rather than
- * storing.
- *
- * Unlike `detail-map-array` this transform has no output resource: its whole
- * content is that an input resource was replaced by a constant. It exists so a
- * described Carbon resource that the backend deliberately dropped is still
- * accounted for - a resource that simply disappears is indistinguishable from
- * one that was lost, and the integrity rules reject that on purpose.
- *
- * `LightProfileArray` is multiplied into a light's attenuation, so the constant
- * is one, not zero. That is the same value the shader's own no-profile path
- * produces, which is why dropping it is neutral rather than dark.
- */
-const LOCAL_LIGHT_PROFILE_NEUTRAL_DEFAULTS = Object.freeze({
-  version: 1,
-  kind: "constant",
-  stage: "fragment",
-  representation: "constant-one",
-  missingLayer: "ignore",
-  viewDimension: null,
-  outputName: null
-});
-
-/**
- * Per-family constant sets, keyed by family name.
- *
- * The reader restores these rather than storing them, so a family that omitted
- * its entry here would silently inherit another family's constants.
- */
-const TRANSFORM_DEFAULTS_BY_FAMILY = Object.freeze({
-  "detail-map-array": DETAIL_MAP_ARRAY_DEFAULTS,
-  "local-light-profile-neutral": LOCAL_LIGHT_PROFILE_NEUTRAL_DEFAULTS
-});
-
-/**
- * Writes a length-prefixed UTF-8 string.
- *
- * @param {object} writer Target byte writer.
- * @param {string} value Text value.
- */
-function writeInlineString(writer, value) {
-  const bytes = new TextEncoder().encode(String(value ?? ""));
-  if (bytes.length > 0xffff) {
-    throw new CjsFormatWriteError("Backend block string exceeds 65535 bytes", {
-      byteLength: bytes.length
-    });
-  }
-  writer.u16(bytes.length);
-  writer.bytes(bytes);
-}
-
-/**
- * Reads a length-prefixed UTF-8 string.
- *
- * @param {object} reader Source byte reader.
- * @returns {string} Decoded text.
- */
-function readInlineString(reader) {
-  const length = reader.readUint16();
-  return new TextDecoder("utf-8", {
-    fatal: false
-  }).decode(reader.readRaw(length));
-}
-
-/**
- * Writes the count-prefixed resource-transform section.
- *
- * @param {object} writer Target byte writer.
- * @param {object[]} transforms Resource transforms.
- */
-function writeTransformSection(writer, transforms) {
-  writer.u8(transforms.length);
-  for (const transform of transforms) {
-    const family = CARBON_BACKEND_TRANSFORM_FAMILY.indexOf(transform.family ?? "detail-map-array");
-    if (family < 0) {
-      throw new CjsFormatWriteError(`Unknown transform family "${transform.family}"`, {
-        family: transform.family
-      });
-    }
-    writer.u8(family);
-    // `id` stays on the wire: a caller may supply it, and it propagates into
-    // the engine binding as `transformId`. Deriving it would foreclose the
-    // caller-supplied plan path to save four bytes.
-    writeInlineString(writer, transform.id);
-    writer.u8(transform.inputs.length);
-    for (const input of transform.inputs) {
-      // Array position is the layer. Safe because `parameter` stays on the
-      // wire, so layer identity remains cross-checkable rather than
-      // asserted by position.
-      writer.u8(input.registerSpace);
-      writer.u8(input.registerIndex);
-      writeInlineString(writer, input.parameter);
-    }
-  }
-}
-
-/**
- * Reads the count-prefixed resource-transform section, restoring derived fields.
- *
- * @param {object} reader Source byte reader.
- * @param {string|null} layoutKey Enclosing pass key, restored onto records.
- * @returns {object[]} Resource transforms.
- */
-function readTransformSection(reader, layoutKey) {
-  const transforms = [];
-  const transformCount = reader.readUint8();
-  for (let index = 0; index < transformCount; index += 1) {
-    const family = CARBON_BACKEND_TRANSFORM_FAMILY[reader.readUint8()];
-    const defaults = TRANSFORM_DEFAULTS_BY_FAMILY[family];
-    if (!defaults) {
-      throw new CjsFormatReadError(`Transform family "${family}" has no restored constants`, {
-        family
-      });
-    }
-    const id = readInlineString(reader);
-    const inputs = [];
-    const inputCount = reader.readUint8();
-    for (let layer = 0; layer < inputCount; layer += 1) {
-      const registerSpace = reader.readUint8();
-      const registerIndex = reader.readUint8();
-      const parameter = readInlineString(reader);
-      const identity = `sampled-resource:${registerSpace}:${registerIndex}`;
-      inputs.push({
-        parameter,
-        layer,
-        // Kept alongside the identity they compose: a consumer checking
-        // the transform against a binding set compares registers, and
-        // re-parsing them back out of the identity string is a second
-        // place for the format of that string to matter.
-        registerSpace,
-        registerIndex,
-        identity,
-        scopeIdentity: `${identity}@${defaults.stage}`
-      });
-    }
-    transforms.push({
-      id,
-      family,
-      version: defaults.version,
-      kind: defaults.kind,
-      stage: defaults.stage,
-      representation: defaults.representation,
-      missingLayer: defaults.missingLayer,
-      layoutKey,
-      inputs,
-      output: {
-        name: defaults.outputName,
-        viewDimension: defaults.viewDimension,
-        layerCount: inputs.length,
-        identity: inputs[0]?.identity ?? null,
-        scopeIdentity: inputs[0]?.scopeIdentity ?? null
-      }
-    });
-  }
-  return transforms;
-}
-
-export { CARBON_BACKEND_TRANSFORM_FAMILY, DETAIL_MAP_ARRAY_DEFAULTS, LOCAL_LIGHT_PROFILE_NEUTRAL_DEFAULTS, readInlineString, readTransformSection, writeInlineString, writeTransformSection };
-//# sourceMappingURL=carbonEffectResourceTransform.js.map
+import { CjsFormatReadError, CjsFormatWriteError } from '../CjsFormatError.js';
+
+/**
+ * The resource-transform section, shared by every backend's per-pass block.
+ *
+ * A resource transform is a recipe for building one backend resource out of
+ * several Carbon ones. It is deliberately backend-neutral: `detail-map-array`
+ * merges `Detail1Map`, `Detail2Map` and `Detail3Map` into one array texture, and
+ * that decision is about the *resources*, not about WGSL or GLSL. Both backends
+ * want the identical merge, for different reasons - WebGPU to reduce binding
+ * churn, WebGL 2 because the family otherwise needs 17 texture units against a
+ * limit of 16 (docs/contracts/webgl2-texture-budget.md).
+ *
+ * So the section lives here rather than in either backend's block codec, and the
+ * two codecs compose it. A transform written by one backend decodes identically
+ * under the other.
+ */
+
+/**
+ * Resource-transform families. The discriminator exists so `kind`,
+ * `representation`, `missingLayer` and the output name stay derivable without
+ * pinning the format to one recognizer: a second family costs an enum value
+ * rather than a format version bump.
+ */
+const CARBON_BACKEND_TRANSFORM_FAMILY = Object.freeze(["detail-map-array", "local-light-profile-neutral"]);
+
+/** Constants a `detail-map-array` transform restores rather than storing. */
+const DETAIL_MAP_ARRAY_DEFAULTS = Object.freeze({
+  version: 1,
+  kind: "texture-2d-array",
+  stage: "fragment",
+  representation: "native-or-rgba8",
+  missingLayer: "reject",
+  viewDimension: "2d-array",
+  outputName: "DetailArrayMap"
+});
+
+/**
+ * Constants a `local-light-profile-neutral` transform restores rather than
+ * storing.
+ *
+ * Unlike `detail-map-array` this transform has no output resource: its whole
+ * content is that an input resource was replaced by a constant. It exists so a
+ * described Carbon resource that the backend deliberately dropped is still
+ * accounted for - a resource that simply disappears is indistinguishable from
+ * one that was lost, and the integrity rules reject that on purpose.
+ *
+ * `LightProfileArray` is multiplied into a light's attenuation, so the constant
+ * is one, not zero. That is the same value the shader's own no-profile path
+ * produces, which is why dropping it is neutral rather than dark.
+ */
+const LOCAL_LIGHT_PROFILE_NEUTRAL_DEFAULTS = Object.freeze({
+  version: 1,
+  kind: "constant",
+  stage: "fragment",
+  representation: "constant-one",
+  missingLayer: "ignore",
+  viewDimension: null,
+  outputName: null
+});
+
+/**
+ * Per-family constant sets, keyed by family name.
+ *
+ * The reader restores these rather than storing them, so a family that omitted
+ * its entry here would silently inherit another family's constants.
+ */
+const TRANSFORM_DEFAULTS_BY_FAMILY = Object.freeze({
+  "detail-map-array": DETAIL_MAP_ARRAY_DEFAULTS,
+  "local-light-profile-neutral": LOCAL_LIGHT_PROFILE_NEUTRAL_DEFAULTS
+});
+
+/**
+ * Writes a length-prefixed UTF-8 string.
+ *
+ * @param {object} writer Target byte writer.
+ * @param {string} value Text value.
+ */
+function writeInlineString(writer, value) {
+  const bytes = new TextEncoder().encode(String(value ?? ""));
+  if (bytes.length > 0xffff) {
+    throw new CjsFormatWriteError("Backend block string exceeds 65535 bytes", {
+      byteLength: bytes.length
+    });
+  }
+  writer.u16(bytes.length);
+  writer.bytes(bytes);
+}
+
+/**
+ * Reads a length-prefixed UTF-8 string.
+ *
+ * @param {object} reader Source byte reader.
+ * @returns {string} Decoded text.
+ */
+function readInlineString(reader) {
+  const length = reader.readUint16();
+  return new TextDecoder("utf-8", {
+    fatal: false
+  }).decode(reader.readRaw(length));
+}
+
+/**
+ * Writes the count-prefixed resource-transform section.
+ *
+ * @param {object} writer Target byte writer.
+ * @param {object[]} transforms Resource transforms.
+ */
+function writeTransformSection(writer, transforms) {
+  writer.u8(transforms.length);
+  for (const transform of transforms) {
+    const family = CARBON_BACKEND_TRANSFORM_FAMILY.indexOf(transform.family ?? "detail-map-array");
+    if (family < 0) {
+      throw new CjsFormatWriteError(`Unknown transform family "${transform.family}"`, {
+        family: transform.family
+      });
+    }
+    writer.u8(family);
+    // `id` stays on the wire: a caller may supply it, and it propagates into
+    // the engine binding as `transformId`. Deriving it would foreclose the
+    // caller-supplied plan path to save four bytes.
+    writeInlineString(writer, transform.id);
+    writer.u8(transform.inputs.length);
+    for (const input of transform.inputs) {
+      // Array position is the layer. Safe because `parameter` stays on the
+      // wire, so layer identity remains cross-checkable rather than
+      // asserted by position.
+      writer.u8(input.registerSpace);
+      writer.u8(input.registerIndex);
+      writeInlineString(writer, input.parameter);
+    }
+  }
+}
+
+/**
+ * Reads the count-prefixed resource-transform section, restoring derived fields.
+ *
+ * @param {object} reader Source byte reader.
+ * @param {string|null} layoutKey Enclosing pass key, restored onto records.
+ * @returns {object[]} Resource transforms.
+ */
+function readTransformSection(reader, layoutKey) {
+  const transforms = [];
+  const transformCount = reader.readUint8();
+  for (let index = 0; index < transformCount; index += 1) {
+    const family = CARBON_BACKEND_TRANSFORM_FAMILY[reader.readUint8()];
+    const defaults = TRANSFORM_DEFAULTS_BY_FAMILY[family];
+    if (!defaults) {
+      throw new CjsFormatReadError(`Transform family "${family}" has no restored constants`, {
+        family
+      });
+    }
+    const id = readInlineString(reader);
+    const inputs = [];
+    const inputCount = reader.readUint8();
+    for (let layer = 0; layer < inputCount; layer += 1) {
+      const registerSpace = reader.readUint8();
+      const registerIndex = reader.readUint8();
+      const parameter = readInlineString(reader);
+      const identity = `sampled-resource:${registerSpace}:${registerIndex}`;
+      inputs.push({
+        parameter,
+        layer,
+        // Kept alongside the identity they compose: a consumer checking
+        // the transform against a binding set compares registers, and
+        // re-parsing them back out of the identity string is a second
+        // place for the format of that string to matter.
+        registerSpace,
+        registerIndex,
+        identity,
+        scopeIdentity: `${identity}@${defaults.stage}`
+      });
+    }
+    transforms.push({
+      id,
+      family,
+      version: defaults.version,
+      kind: defaults.kind,
+      stage: defaults.stage,
+      representation: defaults.representation,
+      missingLayer: defaults.missingLayer,
+      layoutKey,
+      inputs,
+      output: {
+        name: defaults.outputName,
+        viewDimension: defaults.viewDimension,
+        layerCount: inputs.length,
+        identity: inputs[0]?.identity ?? null,
+        scopeIdentity: inputs[0]?.scopeIdentity ?? null
+      }
+    });
+  }
+  return transforms;
+}
+
+export { CARBON_BACKEND_TRANSFORM_FAMILY, DETAIL_MAP_ARRAY_DEFAULTS, LOCAL_LIGHT_PROFILE_NEUTRAL_DEFAULTS, readInlineString, readTransformSection, writeInlineString, writeTransformSection };
+//# sourceMappingURL=carbonEffectResourceTransform.js.map

package/dist/format/compareUtf8.js

@@ -1,36 +1,36 @@
-const textEncoder = new TextEncoder();
-
-/**
- * Compares two strings by their UTF-8 bytes, unsigned.
- *
- * This is `strcmp` order, and it is the only string comparison allowed to decide
- * emitted bytes anywhere in this package.
- *
- * `String.prototype.localeCompare` cannot be used for that job. Without an
- * explicit locale it is implementation- and ICU-dependent, so the same input can
- * order differently across Node builds; it treats case as a minor difference, so
- * `"Z"` sorts *after* `"a"` where bytes put it before; and it gives punctuation
- * variable weight, so `-`, `:` and `@` — which appear in every binding identity we
- * sort — are not ordered by code point. Any of those is enough to make a build
- * unreproducible.
- *
- * Carbon compares the same way, both in its string table (`Blob::operator<`,
- * `StringTable.h:109-122`) and when it sorts annotation keys before writing them
- * (`strcmp`, `EffectData.h:613-616`).
- *
- * @param {string} left First string.
- * @param {string} right Second string.
- * @returns {number} Negative, zero, or positive ordering result.
- */
-function compareUtf8(left, right) {
-  const a = textEncoder.encode(String(left));
-  const b = textEncoder.encode(String(right));
-  const shared = Math.min(a.length, b.length);
-  for (let index = 0; index < shared; index += 1) {
-    if (a[index] !== b[index]) return a[index] - b[index];
-  }
-  return a.length - b.length;
-}
-
-export { compareUtf8 };
-//# sourceMappingURL=compareUtf8.js.map
+const textEncoder = new TextEncoder();
+
+/**
+ * Compares two strings by their UTF-8 bytes, unsigned.
+ *
+ * This is `strcmp` order, and it is the only string comparison allowed to decide
+ * emitted bytes anywhere in this package.
+ *
+ * `String.prototype.localeCompare` cannot be used for that job. Without an
+ * explicit locale it is implementation- and ICU-dependent, so the same input can
+ * order differently across Node builds; it treats case as a minor difference, so
+ * `"Z"` sorts *after* `"a"` where bytes put it before; and it gives punctuation
+ * variable weight, so `-`, `:` and `@` — which appear in every binding identity we
+ * sort — are not ordered by code point. Any of those is enough to make a build
+ * unreproducible.
+ *
+ * Carbon compares the same way, both in its string table (`Blob::operator<`,
+ * `StringTable.h:109-122`) and when it sorts annotation keys before writing them
+ * (`strcmp`, `EffectData.h:613-616`).
+ *
+ * @param {string} left First string.
+ * @param {string} right Second string.
+ * @returns {number} Negative, zero, or positive ordering result.
+ */
+function compareUtf8(left, right) {
+  const a = textEncoder.encode(String(left));
+  const b = textEncoder.encode(String(right));
+  const shared = Math.min(a.length, b.length);
+  for (let index = 0; index < shared; index += 1) {
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return a.length - b.length;
+}
+
+export { compareUtf8 };
+//# sourceMappingURL=compareUtf8.js.map