@carbonenginejs/runtime-resource 0.12.2 → 0.14.0

package/dist/resource/shader/reflection/Tr2Pass.js

@@ -1,11 +1,11 @@
 import { CjsSchema, impl, type } from '@carbonenginejs/runtime-utils/schema';
 import { CjsModel } from '@carbonenginejs/runtime-utils/model';
-import { isPlainObject, isArray, isUint32 } from '@carbonenginejs/runtime-utils/is';
-import { requirePortableStageType } from '../portable.js';
+import { isPlainObject } from '@carbonenginejs/runtime-utils/is';
+import { SHADER_STAGE_COUNT, requireShaderStageType } from './shaderStage.js';
 import { Tr2EffectStageInput } from './Tr2EffectStageInput.js';
+import { recordBytes, toRecordBlob } from './carbonRecordFields.js';
 
 // Source: trinity/trinity/Shader/Tr2EffectDescription.h
-const SHADER_TYPE_COUNT = 6;
 
 /** Reflected effect pass; backend program and state handles remain engine-owned. */
 class Tr2Pass extends CjsModel {
@@ -30,36 +30,44 @@ class Tr2Pass extends CjsModel {
   /** Exact authored render-state pairs retained before an engine creates a state handle. */
   renderStateValues = [];
 
+  /** Optional per-pass backend block, absent in a stock Carbon file. */
+  backendBlock = null;
+
+  /**
+   * Stage types in the order the file stored them.
+   *
+   * `stageInputs` is indexed by stage type, as Carbon's fixed array is, so the
+   * file's ordering is not recoverable from it. That ordering is authored rather
+   * than derivable: measured over 288,528 passes in the shipped corpus, 156 put
+   * geometry before pixel (`0,3,1`) and 12 put it after (`0,1,3`). Any sort loses
+   * one group or the other, so the sequence is kept.
+   */
+  stageOrder = [];
+
   /**
-   * Build one pass from its portable JSON reflection record.
+   * Build one pass from its Carbon v15 description record.
    *
-   * @param {object} value Portable pass record.
+   * Carbon writes only the stages a pass actually uses, but the class keeps a
+   * fixed six-slot array indexed by stage type, so absent stages are filled with
+   * explicit empty slots rather than left as holes. The stage's own type byte
+   * decides where it lands; position in the record does not.
+   *
+   * The optional backend block is retained verbatim and not interpreted here. It
+   * is the one place the container diverges by backend, and deciding what it
+   * means is the engine's job, not the reader's.
+   *
+   * @param {object} record Carbon pass record.
    * @returns {Tr2Pass} Reflected pass.
    */
-  static fromPortable(value) {
-    if (!isPlainObject(value)) {
-      throw new TypeError("Portable effect pass must be an object");
-    }
-    if (!isArray(value.renderStates)) {
-      throw new TypeError("Portable effect render states must be an array");
-    }
-    if (!isArray(value.stages)) {
-      throw new TypeError("Portable effect stages must be an array");
-    }
-    if (value.renderStateCount !== value.renderStates.length || value.stageCount !== value.stages.length) {
-      throw new Error("Portable effect pass counts disagree with its collections");
+  static fromCarbonBinary(record) {
+    if (!isPlainObject(record)) {
+      throw new TypeError("Carbon effect pass record must be an object");
     }
     const pass = new this();
     const renderStateIds = new Set();
-    pass.renderStateValues = value.renderStates.map(entry => {
-      if (!isUint32(entry?.state)) {
-        throw new RangeError("Portable render-state id must fit uint32");
-      }
-      if (!isUint32(entry?.value)) {
-        throw new RangeError("Portable render-state value must fit uint32");
-      }
+    pass.renderStateValues = record.renderStates.map(entry => {
       if (renderStateIds.has(entry.state)) {
-        throw new Error(`Portable render-state id ${entry.state} is duplicated`);
+        throw new Error(`Carbon effect render-state id ${entry.state} is duplicated`);
       }
       renderStateIds.add(entry.state);
       return {
@@ -67,25 +75,72 @@ class Tr2Pass extends CjsModel {
         value: entry.value
       };
     });
-    const stageTypes = new Set();
-    value.stages.forEach(stage => {
-      const stageType = requirePortableStageType(stage?.stageType);
-      if (stageTypes.has(stageType)) {
-        throw new Error(`Portable effect stage type ${stageType} is duplicated`);
-      }
-      stageTypes.add(stageType);
-    });
     pass.stageInputs = Array.from({
-      length: SHADER_TYPE_COUNT
+      length: SHADER_STAGE_COUNT
     }, (_, stageType) => Tr2EffectStageInput.createEmpty(stageType));
     pass.shaderTypeMask = 0;
-    for (const stageValue of value.stages) {
-      const stage = Tr2EffectStageInput.fromPortable(stageValue);
-      pass.stageInputs[stage.stageType] = stage;
-      pass.shaderTypeMask = (pass.shaderTypeMask | 1 << stage.stageType) >>> 0;
+    for (const stageRecord of record.stages) {
+      const stage = Tr2EffectStageInput.fromCarbonBinary(stageRecord);
+      const stageType = requireShaderStageType(stage.stageType);
+      if ((pass.shaderTypeMask & 1 << stageType) !== 0) {
+        throw new Error(`Carbon effect stage type ${stageType} is duplicated`);
+      }
+      pass.stageInputs[stageType] = stage;
+      pass.shaderTypeMask = (pass.shaderTypeMask | 1 << stageType) >>> 0;
     }
+    pass.stageOrder = record.stages.map(stage => stage.type);
+    pass.backendBlock = record.backendBlock ? {
+      bytes: recordBytes(record.backendBlock),
+      size: record.backendBlock.size
+    } : null;
     return pass;
   }
+
+  /**
+   * The populated stages in the order they should be written.
+   *
+   * A retained order wins; anything present but unlisted follows in stage-type
+   * order, so a pass assembled by hand still emits every stage it has.
+   *
+   * @returns {Array<object>} Stages in file order.
+   */
+  #orderedStages() {
+    const present = this.stageInputs.filter(stage => stage?.exists);
+    const ordered = [];
+    for (const stageType of this.stageOrder) {
+      const stage = present.find(entry => entry.stageType === stageType);
+      if (stage && !ordered.includes(stage)) ordered.push(stage);
+    }
+    for (const stage of present) {
+      if (!ordered.includes(stage)) ordered.push(stage);
+    }
+    return ordered;
+  }
+
+  /**
+   * Emit this pass as a Carbon v15 record.
+   *
+   * Only stages that exist are written, in ascending stage type. The class keeps
+   * six slots because Carbon addresses them positionally in memory; the file
+   * stores a count and only the populated ones.
+   *
+   * Render states are sorted by id because Carbon holds them in a `std::map`.
+   *
+   * @returns {object} Carbon pass record.
+   */
+  toCarbonBinary() {
+    const record = {
+      stages: this.#orderedStages().map(stage => stage.toCarbonBinary()),
+      renderStates: this.renderStateValues.map(entry => ({
+        state: entry.state,
+        value: entry.value
+      })).sort((left, right) => left.state - right.state)
+    };
+    if (this.backendBlock) {
+      record.backendBlock = toRecordBlob(this.backendBlock.bytes, this.backendBlock.size);
+    }
+    return record;
+  }
 }
 
 // Declared imperatively rather than with decorators, so this module stays
@@ -103,7 +158,9 @@ CjsSchema.define(Tr2Pass, {
     shaderProgram: type.uint32,
     resourceSetDesc: type.rawStruct("Tr2ResourceSetDescriptionAL"),
     indirectLayout: type.rawStruct("Tr2IndirectDrawBufferLayout"),
-    renderStateValues: [impl.adapted, impl.reason("Carbon stores a renderer-owned render-state handle; the device-free graph retains the authored state/value pairs until an engine realizes them."), type.rawStruct("CjsEffectRenderStateValues")]
+    renderStateValues: [impl.adapted, impl.reason("Carbon stores a renderer-owned render-state handle; the device-free graph retains the authored state/value pairs until an engine realizes them."), type.rawStruct("CjsEffectRenderStateValues")],
+    stageOrder: [impl.custom, impl.reason("Carbon indexes pass stages by type in a fixed array and loses the file's ordering; the device-free graph retains it so a body can be re-emitted as the file that produced it."), type.rawStruct("CjsEffectStageOrder")],
+    backendBlock: [impl.custom, impl.reason("Carbon ends a pass at its render states; CarbonEngineJS containers may append one per-pass block carrying the backend program, which the resource retains uninterpreted for an engine to realize."), type.rawStruct("CjsEffectBackendBlock")]
   }
 });
 

package/dist/resource/shader/reflection/Tr2Pass.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tr2Pass.js","sources":["../../../../../src/resource/shader/reflection/Tr2Pass.js"],"sourcesContent":["// Source: trinity/trinity/Shader/Tr2EffectDescription.h\nimport { CjsSchema, impl, type } from \"@carbonenginejs/runtime-utils/schema\";\nimport { CjsModel } from \"@carbonenginejs/runtime-utils/model\";\nimport {\n  isArray,\n  isPlainObject,\n  isUint32\n} from \"@carbonenginejs/runtime-utils/is\";\nimport { requirePortableStageType } from \"../portable.js\";\nimport { Tr2EffectStageInput } from \"./Tr2EffectStageInput.js\";\n\nconst SHADER_TYPE_COUNT = 6;\n\n/** Reflected effect pass; backend program and state handles remain engine-owned. */\nexport class Tr2Pass extends CjsModel\n{\n\n  /** stageInputs (Tr2EffectStageInput) */\n  stageInputs = [];\n\n  /** renderStates (unsigned int) */\n  renderStates = 0;\n\n  /** shaderTypeMask (unsigned int) */\n  shaderTypeMask = 0;\n\n  /** shaderProgram (unsigned int) */\n  shaderProgram = 0;\n\n  /** resourceSetDesc (Tr2ResourceSetDescriptionAL) */\n  resourceSetDesc = null;\n\n  /** indirectLayout (Tr2IndirectDrawBufferLayout) */\n  indirectLayout = null;\n\n  /** Exact authored render-state pairs retained before an engine creates a state handle. */\n  renderStateValues = [];\n\n  /**\n   * Build one pass from its portable JSON reflection record.\n   *\n   * @param {object} value Portable pass record.\n   * @returns {Tr2Pass} Reflected pass.\n   */\n  static fromPortable(value)\n  {\n    if (!isPlainObject(value))\n    {\n      throw new TypeError(\"Portable effect pass must be an object\");\n    }\n    if (!isArray(value.renderStates))\n    {\n      throw new TypeError(\n        \"Portable effect render states must be an array\"\n      );\n    }\n    if (!isArray(value.stages))\n    {\n      throw new TypeError(\"Portable effect stages must be an array\");\n    }\n    if (value.renderStateCount !== value.renderStates.length\n      || value.stageCount !== value.stages.length)\n    {\n      throw new Error(\n        \"Portable effect pass counts disagree with its collections\"\n      );\n    }\n\n    const pass = new this();\n    const renderStateIds = new Set();\n    pass.renderStateValues = value.renderStates.map(entry =>\n    {\n      if (!isUint32(entry?.state))\n      {\n        throw new RangeError(\"Portable render-state id must fit uint32\");\n      }\n      if (!isUint32(entry?.value))\n      {\n        throw new RangeError(\n          \"Portable render-state value must fit uint32\"\n        );\n      }\n      if (renderStateIds.has(entry.state))\n      {\n        throw new Error(\n          `Portable render-state id ${entry.state} is duplicated`\n        );\n      }\n      renderStateIds.add(entry.state);\n      return {\n        state: entry.state,\n        value: entry.value\n      };\n    });\n\n    const stageTypes = new Set();\n    value.stages.forEach(stage =>\n    {\n      const stageType = requirePortableStageType(stage?.stageType);\n      if (stageTypes.has(stageType))\n      {\n        throw new Error(\n          `Portable effect stage type ${stageType} is duplicated`\n        );\n      }\n      stageTypes.add(stageType);\n    });\n    pass.stageInputs = Array.from(\n      { length: SHADER_TYPE_COUNT },\n      (_, stageType) => Tr2EffectStageInput.createEmpty(stageType)\n    );\n    pass.shaderTypeMask = 0;\n\n    for (const stageValue of value.stages)\n    {\n      const stage = Tr2EffectStageInput.fromPortable(stageValue);\n      pass.stageInputs[stage.stageType] = stage;\n      pass.shaderTypeMask = (\n        pass.shaderTypeMask | (1 << stage.stageType)\n      ) >>> 0;\n    }\n\n    return pass;\n  }\n\n}\n\n// Declared imperatively rather than with decorators, so this module stays\n// plain ESM that loads from source without a transform. The decorator\n// expressions are reused verbatim, so the registered metadata is identical.\n// Statics belong in `methods`: decorateMethod targets the prototype and\n// would register a static as an instance field.\nCjsSchema.define(Tr2Pass, {\n  className: \"Tr2Pass\",\n  family: \"shader\",\n  fields: {\n    stageInputs: type.list(\"Tr2EffectStageInput\"),\n    renderStates: type.uint32,\n    shaderTypeMask: type.uint32,\n    shaderProgram: type.uint32,\n    resourceSetDesc: type.rawStruct(\"Tr2ResourceSetDescriptionAL\"),\n    indirectLayout: type.rawStruct(\"Tr2IndirectDrawBufferLayout\"),\n    renderStateValues: [ impl.adapted, impl.reason(\"Carbon stores a renderer-owned render-state handle; the device-free graph retains the authored state/value pairs until an engine realizes them.\"), type.rawStruct(\"CjsEffectRenderStateValues\") ]\n  }\n});\n"],"names":["SHADER_TYPE_COUNT","Tr2Pass","CjsModel","stageInputs","renderStates","shaderTypeMask","shaderProgram","resourceSetDesc","indirectLayout","renderStateValues","fromPortable","value","isPlainObject","TypeError","isArray","stages","renderStateCount","length","stageCount","Error","pass","renderStateIds","Set","map","entry","isUint32","state","RangeError","has","add","stageTypes","forEach","stage","stageType","requirePortableStageType","Array","from","_","Tr2EffectStageInput","createEmpty","stageValue","CjsSchema","define","className","family","fields","type","list","uint32","rawStruct","impl","adapted","reason"],"mappings":"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"}
+{"version":3,"file":"Tr2Pass.js","sources":["../../../../../src/resource/shader/reflection/Tr2Pass.js"],"sourcesContent":["// Source: trinity/trinity/Shader/Tr2EffectDescription.h\nimport { CjsSchema, impl, type } from \"@carbonenginejs/runtime-utils/schema\";\nimport { CjsModel } from \"@carbonenginejs/runtime-utils/model\";\nimport {\n  isPlainObject\n} from \"@carbonenginejs/runtime-utils/is\";\nimport { requireShaderStageType, SHADER_STAGE_COUNT } from \"./shaderStage.js\";\nimport { Tr2EffectStageInput } from \"./Tr2EffectStageInput.js\";\nimport { recordBytes, toRecordBlob } from \"./carbonRecordFields.js\";\n\n/** Reflected effect pass; backend program and state handles remain engine-owned. */\nexport class Tr2Pass extends CjsModel\n{\n\n  /** stageInputs (Tr2EffectStageInput) */\n  stageInputs = [];\n\n  /** renderStates (unsigned int) */\n  renderStates = 0;\n\n  /** shaderTypeMask (unsigned int) */\n  shaderTypeMask = 0;\n\n  /** shaderProgram (unsigned int) */\n  shaderProgram = 0;\n\n  /** resourceSetDesc (Tr2ResourceSetDescriptionAL) */\n  resourceSetDesc = null;\n\n  /** indirectLayout (Tr2IndirectDrawBufferLayout) */\n  indirectLayout = null;\n\n  /** Exact authored render-state pairs retained before an engine creates a state handle. */\n  renderStateValues = [];\n\n  /** Optional per-pass backend block, absent in a stock Carbon file. */\n  backendBlock = null;\n\n  /**\n   * Stage types in the order the file stored them.\n   *\n   * `stageInputs` is indexed by stage type, as Carbon's fixed array is, so the\n   * file's ordering is not recoverable from it. That ordering is authored rather\n   * than derivable: measured over 288,528 passes in the shipped corpus, 156 put\n   * geometry before pixel (`0,3,1`) and 12 put it after (`0,1,3`). Any sort loses\n   * one group or the other, so the sequence is kept.\n   */\n  stageOrder = [];\n\n  /**\n   * Build one pass from its Carbon v15 description record.\n   *\n   * Carbon writes only the stages a pass actually uses, but the class keeps a\n   * fixed six-slot array indexed by stage type, so absent stages are filled with\n   * explicit empty slots rather than left as holes. The stage's own type byte\n   * decides where it lands; position in the record does not.\n   *\n   * The optional backend block is retained verbatim and not interpreted here. It\n   * is the one place the container diverges by backend, and deciding what it\n   * means is the engine's job, not the reader's.\n   *\n   * @param {object} record Carbon pass record.\n   * @returns {Tr2Pass} Reflected pass.\n   */\n  static fromCarbonBinary(record)\n  {\n    if (!isPlainObject(record))\n    {\n      throw new TypeError(\"Carbon effect pass record must be an object\");\n    }\n\n    const pass = new this();\n    const renderStateIds = new Set();\n    pass.renderStateValues = record.renderStates.map(entry =>\n    {\n      if (renderStateIds.has(entry.state))\n      {\n        throw new Error(\n          `Carbon effect render-state id ${entry.state} is duplicated`\n        );\n      }\n      renderStateIds.add(entry.state);\n      return { state: entry.state, value: entry.value };\n    });\n\n    pass.stageInputs = Array.from(\n      { length: SHADER_STAGE_COUNT },\n      (_, stageType) => Tr2EffectStageInput.createEmpty(stageType)\n    );\n    pass.shaderTypeMask = 0;\n\n    for (const stageRecord of record.stages)\n    {\n      const stage = Tr2EffectStageInput.fromCarbonBinary(stageRecord);\n      const stageType = requireShaderStageType(stage.stageType);\n      if ((pass.shaderTypeMask & (1 << stageType)) !== 0)\n      {\n        throw new Error(\n          `Carbon effect stage type ${stageType} is duplicated`\n        );\n      }\n      pass.stageInputs[stageType] = stage;\n      pass.shaderTypeMask = (pass.shaderTypeMask | (1 << stageType)) >>> 0;\n    }\n\n    pass.stageOrder = record.stages.map(stage => stage.type);\n    pass.backendBlock = record.backendBlock\n      ? { bytes: recordBytes(record.backendBlock), size: record.backendBlock.size }\n      : null;\n\n    return pass;\n  }\n\n\n  /**\n   * The populated stages in the order they should be written.\n   *\n   * A retained order wins; anything present but unlisted follows in stage-type\n   * order, so a pass assembled by hand still emits every stage it has.\n   *\n   * @returns {Array<object>} Stages in file order.\n   */\n  #orderedStages()\n  {\n    const present = this.stageInputs.filter(stage => stage?.exists);\n    const ordered = [];\n    for (const stageType of this.stageOrder)\n    {\n      const stage = present.find(entry => entry.stageType === stageType);\n      if (stage && !ordered.includes(stage)) ordered.push(stage);\n    }\n    for (const stage of present)\n    {\n      if (!ordered.includes(stage)) ordered.push(stage);\n    }\n    return ordered;\n  }\n\n  /**\n   * Emit this pass as a Carbon v15 record.\n   *\n   * Only stages that exist are written, in ascending stage type. The class keeps\n   * six slots because Carbon addresses them positionally in memory; the file\n   * stores a count and only the populated ones.\n   *\n   * Render states are sorted by id because Carbon holds them in a `std::map`.\n   *\n   * @returns {object} Carbon pass record.\n   */\n  toCarbonBinary()\n  {\n    const record = {\n      stages: this.#orderedStages().map(stage => stage.toCarbonBinary()),\n      renderStates: this.renderStateValues\n        .map(entry => ({ state: entry.state, value: entry.value }))\n        .sort((left, right) => left.state - right.state)\n    };\n    if (this.backendBlock)\n    {\n      record.backendBlock = toRecordBlob(\n        this.backendBlock.bytes,\n        this.backendBlock.size\n      );\n    }\n    return record;\n  }\n}\n\n// Declared imperatively rather than with decorators, so this module stays\n// plain ESM that loads from source without a transform. The decorator\n// expressions are reused verbatim, so the registered metadata is identical.\n// Statics belong in `methods`: decorateMethod targets the prototype and\n// would register a static as an instance field.\nCjsSchema.define(Tr2Pass, {\n  className: \"Tr2Pass\",\n  family: \"shader\",\n  fields: {\n    stageInputs: type.list(\"Tr2EffectStageInput\"),\n    renderStates: type.uint32,\n    shaderTypeMask: type.uint32,\n    shaderProgram: type.uint32,\n    resourceSetDesc: type.rawStruct(\"Tr2ResourceSetDescriptionAL\"),\n    indirectLayout: type.rawStruct(\"Tr2IndirectDrawBufferLayout\"),\n    renderStateValues: [ impl.adapted, impl.reason(\"Carbon stores a renderer-owned render-state handle; the device-free graph retains the authored state/value pairs until an engine realizes them.\"), type.rawStruct(\"CjsEffectRenderStateValues\") ],\n    stageOrder: [ impl.custom, impl.reason(\"Carbon indexes pass stages by type in a fixed array and loses the file's ordering; the device-free graph retains it so a body can be re-emitted as the file that produced it.\"), type.rawStruct(\"CjsEffectStageOrder\") ],\n    backendBlock: [ impl.custom, impl.reason(\"Carbon ends a pass at its render states; CarbonEngineJS containers may append one per-pass block carrying the backend program, which the resource retains uninterpreted for an engine to realize.\"), type.rawStruct(\"CjsEffectBackendBlock\") ]\n  }\n});\n"],"names":["Tr2Pass","CjsModel","stageInputs","renderStates","shaderTypeMask","shaderProgram","resourceSetDesc","indirectLayout","renderStateValues","backendBlock","stageOrder","fromCarbonBinary","record","isPlainObject","TypeError","pass","renderStateIds","Set","map","entry","has","state","Error","add","value","Array","from","length","SHADER_STAGE_COUNT","_","stageType","Tr2EffectStageInput","createEmpty","stageRecord","stages","stage","requireShaderStageType","type","bytes","recordBytes","size","#orderedStages","present","filter","exists","ordered","find","includes","push","toCarbonBinary","sort","left","right","toRecordBlob","CjsSchema","define","className","family","fields","list","uint32","rawStruct","impl","adapted","reason","custom"],"mappings":"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"}

package/dist/resource/shader/reflection/carbonRecordFields.js

@@ -0,0 +1,159 @@
+// Shared field accessors for Carbon v15 description records.
+//
+// The record tree is what the one Carbon effect reader emits
+// (`format/carbonEffect/carbonEffectRecords.js`). Each reflection class maps its
+// own record, but three field encodings recur across all of them and are worth
+// naming once rather than open-coding at every call site:
+//
+//   - a string is an arena reference `{offset, value}`, not a string;
+//   - an annotation value is four raw little-endian bytes, because Carbon writes
+//     it through one union member and reads it through another, so the bytes are
+//     the only faithful carrier;
+//   - a blob is `{size, offset, bytes}` with `offset === 0xffffffff` meaning the
+//     reference was never set, which is not the same as an empty payload.
+//
+// Both directions live here, as `recordX` and `toRecordX` pairs. They are held
+// apart by the round trip rather than by separation: records in, classes, records
+// out, compared byte for byte over the shipped corpus, so a mistake that
+// satisfied both sides would have to be an exact inverse of itself.
+
+const rawValueBuffer = new DataView(new ArrayBuffer(4));
+
+/**
+ * Reads the text out of an arena string reference.
+ *
+ * @param {{offset:number,value:string}|null|undefined} ref String reference.
+ * @returns {string} The referenced text, or "" when unset.
+ */
+function recordText(ref) {
+  return String(ref?.value ?? "");
+}
+
+/**
+ * Decodes an annotation record's four raw bytes as the `u32` bit pattern the
+ * reflection classes carry as `rawValue`.
+ *
+ * Carbon stores the value as a `{float,int32_t}` union and the type byte decides
+ * which member is meaningful, so the bits travel untyped and each annotation type
+ * reinterprets them itself. Decoding to a number here — rather than to a float —
+ * is what keeps a value like `-FLT_MAX` exact.
+ *
+ * @param {Uint8Array|null|undefined} bytes Four little-endian bytes.
+ * @returns {number} The unsigned 32-bit pattern those bytes carry.
+ */
+function recordRawValue(bytes) {
+  if (!bytes || bytes.length < 4) return 0;
+  rawValueBuffer.setUint8(0, bytes[0]);
+  rawValueBuffer.setUint8(1, bytes[1]);
+  rawValueBuffer.setUint8(2, bytes[2]);
+  rawValueBuffer.setUint8(3, bytes[3]);
+  return rawValueBuffer.getUint32(0, true);
+}
+
+/**
+ * Re-encodes a record's `float` as the `u32` bit pattern the reflection classes
+ * carry in their `*Raw` sampler fields.
+ *
+ * The container stores sampler LOD and border values as real floats, but the
+ * class keeps the bits, so a value like `-FLT_MAX` survives serialization without
+ * a decimal round trip. Reading the float and re-encoding it here is exact: the
+ * record's value came from a `f32` read, so it is already representable.
+ *
+ * @param {number} value Float value from a sampler record.
+ * @returns {number} The unsigned 32-bit pattern encoding that float.
+ */
+function recordRawBits(value) {
+  rawValueBuffer.setFloat32(0, Number.isFinite(value) ? value : 0, true);
+  return rawValueBuffer.getUint32(0, true);
+}
+
+/**
+ * Wraps text as the arena string reference the writer interns.
+ *
+ * The offset is always 0: the writer assigns real offsets while building the
+ * arena, and any value here would be discarded. Carrying the text is the whole
+ * job.
+ *
+ * @param {string} value Text value.
+ * @returns {{offset:number,value:string}} String reference.
+ */
+function toRecordText(value) {
+  return {
+    offset: 0,
+    value: String(value ?? "")
+  };
+}
+
+/**
+ * Encodes a `u32` bit pattern as an annotation record's four raw bytes.
+ *
+ * The inverse of {@link recordRawValue}, and raw for the same reason: the value
+ * is written through one union member and read through another, so no numeric
+ * conversion may happen on the way out either.
+ *
+ * @param {number} rawValue Unsigned 32-bit pattern.
+ * @returns {Uint8Array} Four little-endian bytes.
+ */
+function toRecordRawValue(rawValue) {
+  const bytes = new Uint8Array(4);
+  rawValueBuffer.setUint32(0, rawValue >>> 0, true);
+  for (let index = 0; index < 4; index += 1) {
+    bytes[index] = rawValueBuffer.getUint8(index);
+  }
+  return bytes;
+}
+
+/**
+ * Decodes a `*Raw` sampler field back to the float the record stores.
+ *
+ * The inverse of {@link recordRawBits}. Assigning the raw `u32` straight across
+ * would write `4286578687.0` where the file says `-3.4028235e38`, and every
+ * structural check in the container would accept it.
+ *
+ * @param {number} bits Raw 32-bit pattern.
+ * @returns {number} The float those bits encode.
+ */
+function toRecordFloat(bits) {
+  rawValueBuffer.setUint32(0, (bits ?? 0) >>> 0, true);
+  return rawValueBuffer.getFloat32(0, true);
+}
+
+/**
+ * Wraps bytes as the record codec's sized blob reference.
+ *
+ * A zero-length blob keeps the offset word the file carried, because the writer
+ * passes it straight through rather than interning anything. That word is
+ * usually `0xffffffff`, but not always — measured across the shipped corpus,
+ * 150 of 4833 files carry a live-looking offset behind a zero size, and
+ * normalizing it changes the bytes and can make two distinct bodies collapse
+ * into one. An empty payload and an absent one are not the same thing.
+ *
+ * @param {Uint8Array} bytes Payload bytes.
+ * @param {number} [declaredSize] Size to declare when tracked separately.
+ * @param {number} [unsetOffset] Offset word to keep when the size is zero.
+ * @returns {{size:number,offset:number,bytes:Uint8Array}} Blob reference.
+ */
+function toRecordBlob(bytes, declaredSize, unsetOffset = 0xffffffff) {
+  const owned = bytes instanceof Uint8Array ? bytes : new Uint8Array(0);
+  const size = declaredSize ?? owned.byteLength;
+  return {
+    size,
+    offset: size === 0 ? unsetOffset >>> 0 : 0,
+    bytes: owned
+  };
+}
+
+/**
+ * Returns a blob reference's payload bytes, or an empty view when the reference
+ * was never set.
+ *
+ * @param {{size:number,offset:number,bytes:Uint8Array}|null|undefined} ref Blob.
+ * @returns {Uint8Array} Owned-by-the-container view over the payload.
+ */
+function recordBytes(ref) {
+  const bytes = ref?.bytes;
+  return bytes instanceof Uint8Array ? bytes : new Uint8Array(0);
+}
+
+export { recordBytes, recordRawBits, recordRawValue, recordText, toRecordBlob, toRecordFloat, toRecordRawValue, toRecordText };
+//# sourceMappingURL=carbonRecordFields.js.map

package/dist/resource/shader/reflection/carbonRecordFields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"carbonRecordFields.js","sources":["../../../../../src/resource/shader/reflection/carbonRecordFields.js"],"sourcesContent":["// Shared field accessors for Carbon v15 description records.\n//\n// The record tree is what the one Carbon effect reader emits\n// (`format/carbonEffect/carbonEffectRecords.js`). Each reflection class maps its\n// own record, but three field encodings recur across all of them and are worth\n// naming once rather than open-coding at every call site:\n//\n//   - a string is an arena reference `{offset, value}`, not a string;\n//   - an annotation value is four raw little-endian bytes, because Carbon writes\n//     it through one union member and reads it through another, so the bytes are\n//     the only faithful carrier;\n//   - a blob is `{size, offset, bytes}` with `offset === 0xffffffff` meaning the\n//     reference was never set, which is not the same as an empty payload.\n//\n// Both directions live here, as `recordX` and `toRecordX` pairs. They are held\n// apart by the round trip rather than by separation: records in, classes, records\n// out, compared byte for byte over the shipped corpus, so a mistake that\n// satisfied both sides would have to be an exact inverse of itself.\n\nconst rawValueBuffer = new DataView(new ArrayBuffer(4));\n\n/**\n * Reads the text out of an arena string reference.\n *\n * @param {{offset:number,value:string}|null|undefined} ref String reference.\n * @returns {string} The referenced text, or \"\" when unset.\n */\nexport function recordText(ref)\n{\n  return String(ref?.value ?? \"\");\n}\n\n/**\n * Decodes an annotation record's four raw bytes as the `u32` bit pattern the\n * reflection classes carry as `rawValue`.\n *\n * Carbon stores the value as a `{float,int32_t}` union and the type byte decides\n * which member is meaningful, so the bits travel untyped and each annotation type\n * reinterprets them itself. Decoding to a number here — rather than to a float —\n * is what keeps a value like `-FLT_MAX` exact.\n *\n * @param {Uint8Array|null|undefined} bytes Four little-endian bytes.\n * @returns {number} The unsigned 32-bit pattern those bytes carry.\n */\nexport function recordRawValue(bytes)\n{\n  if (!bytes || bytes.length < 4) return 0;\n  rawValueBuffer.setUint8(0, bytes[0]);\n  rawValueBuffer.setUint8(1, bytes[1]);\n  rawValueBuffer.setUint8(2, bytes[2]);\n  rawValueBuffer.setUint8(3, bytes[3]);\n  return rawValueBuffer.getUint32(0, true);\n}\n\n/**\n * Re-encodes a record's `float` as the `u32` bit pattern the reflection classes\n * carry in their `*Raw` sampler fields.\n *\n * The container stores sampler LOD and border values as real floats, but the\n * class keeps the bits, so a value like `-FLT_MAX` survives serialization without\n * a decimal round trip. Reading the float and re-encoding it here is exact: the\n * record's value came from a `f32` read, so it is already representable.\n *\n * @param {number} value Float value from a sampler record.\n * @returns {number} The unsigned 32-bit pattern encoding that float.\n */\nexport function recordRawBits(value)\n{\n  rawValueBuffer.setFloat32(0, Number.isFinite(value) ? value : 0, true);\n  return rawValueBuffer.getUint32(0, true);\n}\n\n/**\n * Wraps text as the arena string reference the writer interns.\n *\n * The offset is always 0: the writer assigns real offsets while building the\n * arena, and any value here would be discarded. Carrying the text is the whole\n * job.\n *\n * @param {string} value Text value.\n * @returns {{offset:number,value:string}} String reference.\n */\nexport function toRecordText(value)\n{\n  return { offset: 0, value: String(value ?? \"\") };\n}\n\n/**\n * Encodes a `u32` bit pattern as an annotation record's four raw bytes.\n *\n * The inverse of {@link recordRawValue}, and raw for the same reason: the value\n * is written through one union member and read through another, so no numeric\n * conversion may happen on the way out either.\n *\n * @param {number} rawValue Unsigned 32-bit pattern.\n * @returns {Uint8Array} Four little-endian bytes.\n */\nexport function toRecordRawValue(rawValue)\n{\n  const bytes = new Uint8Array(4);\n  rawValueBuffer.setUint32(0, rawValue >>> 0, true);\n  for (let index = 0; index < 4; index += 1)\n  {\n    bytes[index] = rawValueBuffer.getUint8(index);\n  }\n  return bytes;\n}\n\n/**\n * Decodes a `*Raw` sampler field back to the float the record stores.\n *\n * The inverse of {@link recordRawBits}. Assigning the raw `u32` straight across\n * would write `4286578687.0` where the file says `-3.4028235e38`, and every\n * structural check in the container would accept it.\n *\n * @param {number} bits Raw 32-bit pattern.\n * @returns {number} The float those bits encode.\n */\nexport function toRecordFloat(bits)\n{\n  rawValueBuffer.setUint32(0, (bits ?? 0) >>> 0, true);\n  return rawValueBuffer.getFloat32(0, true);\n}\n\n/**\n * Wraps bytes as the record codec's sized blob reference.\n *\n * A zero-length blob keeps the offset word the file carried, because the writer\n * passes it straight through rather than interning anything. That word is\n * usually `0xffffffff`, but not always — measured across the shipped corpus,\n * 150 of 4833 files carry a live-looking offset behind a zero size, and\n * normalizing it changes the bytes and can make two distinct bodies collapse\n * into one. An empty payload and an absent one are not the same thing.\n *\n * @param {Uint8Array} bytes Payload bytes.\n * @param {number} [declaredSize] Size to declare when tracked separately.\n * @param {number} [unsetOffset] Offset word to keep when the size is zero.\n * @returns {{size:number,offset:number,bytes:Uint8Array}} Blob reference.\n */\nexport function toRecordBlob(bytes, declaredSize, unsetOffset = 0xffffffff)\n{\n  const owned = bytes instanceof Uint8Array ? bytes : new Uint8Array(0);\n  const size = declaredSize ?? owned.byteLength;\n  return { size, offset: size === 0 ? (unsetOffset >>> 0) : 0, bytes: owned };\n}\n\n/**\n * Returns a blob reference's payload bytes, or an empty view when the reference\n * was never set.\n *\n * @param {{size:number,offset:number,bytes:Uint8Array}|null|undefined} ref Blob.\n * @returns {Uint8Array} Owned-by-the-container view over the payload.\n */\nexport function recordBytes(ref)\n{\n  const bytes = ref?.bytes;\n  return bytes instanceof Uint8Array ? bytes : new Uint8Array(0);\n}\n"],"names":["rawValueBuffer","DataView","ArrayBuffer","recordText","ref","String","value","recordRawValue","bytes","length","setUint8","getUint32","recordRawBits","setFloat32","Number","isFinite","toRecordText","offset","toRecordRawValue","rawValue","Uint8Array","setUint32","index","getUint8","toRecordFloat","bits","getFloat32","toRecordBlob","declaredSize","unsetOffset","owned","size","byteLength","recordBytes"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,MAAMA,cAAc,GAAG,IAAIC,QAAQ,CAAC,IAAIC,WAAW,CAAC,CAAC,CAAC,CAAC;;AAEvD;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,UAAUA,CAACC,GAAG,EAC9B;AACE,EAAA,OAAOC,MAAM,CAACD,GAAG,EAAEE,KAAK,IAAI,EAAE,CAAC;AACjC;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,cAAcA,CAACC,KAAK,EACpC;EACE,IAAI,CAACA,KAAK,IAAIA,KAAK,CAACC,MAAM,GAAG,CAAC,EAAE,OAAO,CAAC;EACxCT,cAAc,CAACU,QAAQ,CAAC,CAAC,EAAEF,KAAK,CAAC,CAAC,CAAC,CAAC;EACpCR,cAAc,CAACU,QAAQ,CAAC,CAAC,EAAEF,KAAK,CAAC,CAAC,CAAC,CAAC;EACpCR,cAAc,CAACU,QAAQ,CAAC,CAAC,EAAEF,KAAK,CAAC,CAAC,CAAC,CAAC;EACpCR,cAAc,CAACU,QAAQ,CAAC,CAAC,EAAEF,KAAK,CAAC,CAAC,CAAC,CAAC;AACpC,EAAA,OAAOR,cAAc,CAACW,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC;AAC1C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,aAAaA,CAACN,KAAK,EACnC;AACEN,EAAAA,cAAc,CAACa,UAAU,CAAC,CAAC,EAAEC,MAAM,CAACC,QAAQ,CAACT,KAAK,CAAC,GAAGA,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC;AACtE,EAAA,OAAON,cAAc,CAACW,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC;AAC1C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASK,YAAYA,CAACV,KAAK,EAClC;EACE,OAAO;AAAEW,IAAAA,MAAM,EAAE,CAAC;AAAEX,IAAAA,KAAK,EAAED,MAAM,CAACC,KAAK,IAAI,EAAE;GAAG;AAClD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASY,gBAAgBA,CAACC,QAAQ,EACzC;AACE,EAAA,MAAMX,KAAK,GAAG,IAAIY,UAAU,CAAC,CAAC,CAAC;EAC/BpB,cAAc,CAACqB,SAAS,CAAC,CAAC,EAAEF,QAAQ,KAAK,CAAC,EAAE,IAAI,CAAC;AACjD,EAAA,KAAK,IAAIG,KAAK,GAAG,CAAC,EAAEA,KAAK,GAAG,CAAC,EAAEA,KAAK,IAAI,CAAC,EACzC;IACEd,KAAK,CAACc,KAAK,CAAC,GAAGtB,cAAc,CAACuB,QAAQ,CAACD,KAAK,CAAC;AAC/C,EAAA;AACA,EAAA,OAAOd,KAAK;AACd;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASgB,aAAaA,CAACC,IAAI,EAClC;AACEzB,EAAAA,cAAc,CAACqB,SAAS,CAAC,CAAC,EAAE,CAACI,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC;AACpD,EAAA,OAAOzB,cAAc,CAAC0B,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC;AAC3C;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,YAAYA,CAACnB,KAAK,EAAEoB,YAAY,EAAEC,WAAW,GAAG,UAAU,EAC1E;AACE,EAAA,MAAMC,KAAK,GAAGtB,KAAK,YAAYY,UAAU,GAAGZ,KAAK,GAAG,IAAIY,UAAU,CAAC,CAAC,CAAC;AACrE,EAAA,MAAMW,IAAI,GAAGH,YAAY,IAAIE,KAAK,CAACE,UAAU;EAC7C,OAAO;IAAED,IAAI;IAAEd,MAAM,EAAEc,IAAI,KAAK,CAAC,GAAIF,WAAW,KAAK,CAAC,GAAI,CAAC;AAAErB,IAAAA,KAAK,EAAEsB;GAAO;AAC7E;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,WAAWA,CAAC7B,GAAG,EAC/B;AACE,EAAA,MAAMI,KAAK,GAAGJ,GAAG,EAAEI,KAAK;EACxB,OAAOA,KAAK,YAAYY,UAAU,GAAGZ,KAAK,GAAG,IAAIY,UAAU,CAAC,CAAC,CAAC;AAChE;;;;"}

package/dist/resource/shader/reflection/shaderStage.js

@@ -0,0 +1,22 @@
+/** Number of shader stages Carbon's fixed-width stage array holds. */
+const SHADER_STAGE_COUNT = 6;
+
+/**
+ * Require one of Carbon's six authored shader-stage indices.
+ *
+ * Carbon addresses stages positionally through a fixed-width array on the pass
+ * (`Tr2EffectDescription.h`), so a stage type is an index into that array and
+ * nothing outside `[0, 5]` addresses anything.
+ *
+ * @param {number} value Candidate stage type.
+ * @returns {number} The validated stage type.
+ */
+function requireShaderStageType(value) {
+  if (!Number.isSafeInteger(value) || value < 0 || value >= SHADER_STAGE_COUNT) {
+    throw new RangeError(`Shader stage type must be in [0, ${SHADER_STAGE_COUNT - 1}]`);
+  }
+  return value;
+}
+
+export { SHADER_STAGE_COUNT, requireShaderStageType };
+//# sourceMappingURL=shaderStage.js.map

package/dist/resource/shader/reflection/shaderStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shaderStage.js","sources":["../../../../../src/resource/shader/reflection/shaderStage.js"],"sourcesContent":["/** Number of shader stages Carbon's fixed-width stage array holds. */\nexport const SHADER_STAGE_COUNT = 6;\n\n/**\n * Require one of Carbon's six authored shader-stage indices.\n *\n * Carbon addresses stages positionally through a fixed-width array on the pass\n * (`Tr2EffectDescription.h`), so a stage type is an index into that array and\n * nothing outside `[0, 5]` addresses anything.\n *\n * @param {number} value Candidate stage type.\n * @returns {number} The validated stage type.\n */\nexport function requireShaderStageType(value)\n{\n  if (!Number.isSafeInteger(value) || value < 0 || value >= SHADER_STAGE_COUNT)\n  {\n    throw new RangeError(\n      `Shader stage type must be in [0, ${SHADER_STAGE_COUNT - 1}]`\n    );\n  }\n  return value;\n}\n"],"names":["SHADER_STAGE_COUNT","requireShaderStageType","value","Number","isSafeInteger","RangeError"],"mappings":"AAAA;AACO,MAAMA,kBAAkB,GAAG;;AAElC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,sBAAsBA,CAACC,KAAK,EAC5C;AACE,EAAA,IAAI,CAACC,MAAM,CAACC,aAAa,CAACF,KAAK,CAAC,IAAIA,KAAK,GAAG,CAAC,IAAIA,KAAK,IAAIF,kBAAkB,EAC5E;IACE,MAAM,IAAIK,UAAU,CAClB,CAAA,iCAAA,EAAoCL,kBAAkB,GAAG,CAAC,GAC5D,CAAC;AACH,EAAA;AACA,EAAA,OAAOE,KAAK;AACd;;;;"}

package/dist/resource/shader/sampler/Tr2SamplerSetup.js

@@ -1,7 +1,7 @@
 import { CjsSchema, impl, type } from '@carbonenginejs/runtime-utils/schema';
 import { CjsModel } from '@carbonenginejs/runtime-utils/model';
 import { isPlainObject } from '@carbonenginejs/runtime-utils/is';
-import { cloneCarbonValue } from '@carbonenginejs/runtime-utils/types';
+import { recordText, recordRawBits, toRecordFloat, toRecordText } from '../reflection/carbonRecordFields.js';
 
 // Source: trinity/trinity/Shader/Tr2EffectDescription.h
 
@@ -39,22 +39,80 @@ class Tr2SamplerSetup extends CjsModel {
   }
 
   /**
-   * Build one sampler from its portable JSON reflection record.
+   * Build one dynamic sampler from its Carbon v15 description record.
    *
-   * @param {object} value Portable sampler record.
+   * The name is kept whatever `isDynamic` says. Carbon nulls a non-dynamic
+   * sampler's name while reading (`Tr2EffectDescription.cpp:430-433`), but that
+   * is a runtime decision made on the way to a device — the file still carries
+   * the string, and this graph has to be able to re-emit the file it came from.
+   * Dropping it loses arena content: measured across the shipped corpus, this
+   * single rule accounted for every non-byte-identical re-emission.
+   *
+   * A consumer that wants Carbon's runtime view asks for it: the name is
+   * meaningful only when `isDynamic`.
+   *
+   * @param {object} record Carbon sampler record.
    * @returns {Tr2SamplerSetup} Reflected sampler.
    */
-  static fromPortable(value) {
-    if (!isPlainObject(value)) {
-      throw new TypeError("Portable effect sampler must be an object");
+  static fromCarbonBinary(record) {
+    if (!isPlainObject(record)) {
+      throw new TypeError("Carbon effect sampler record must be an object");
     }
     const sampler = new this();
-    sampler.hasName = value.name !== null;
-    sampler.name = sampler.hasName ? String(value.name ?? "") : "";
-    sampler.sampler = cloneCarbonValue(value.descriptor);
-    sampler.isDynamic = !!value.isDynamic;
+    sampler.isDynamic = !!record.isDynamic;
+    sampler.name = recordText(record.name);
+    sampler.hasName = sampler.name !== "";
+    sampler.sampler = {
+      comparison: !!record.comparison,
+      minFilter: record.minFilter,
+      magFilter: record.magFilter,
+      mipFilter: record.mipFilter,
+      addressU: record.addressU,
+      addressV: record.addressV,
+      addressW: record.addressW,
+      mipLODBiasRaw: recordRawBits(record.mipLODBias),
+      maxAnisotropy: record.maxAnisotropy,
+      comparisonFunc: record.comparisonFunc,
+      borderColorRaw: (record.borderColor ?? []).map(recordRawBits),
+      minLODRaw: recordRawBits(record.minLOD),
+      maxLODRaw: recordRawBits(record.maxLOD)
+    };
     return sampler;
   }
+
+  /**
+   * Emit this sampler as a Carbon v15 record.
+   *
+   * The name is written whether or not it is meaningful: Carbon's writer always
+   * emits the field, and the string it emits is the one the compiler authored,
+   * not the one Carbon's reader keeps.
+   *
+   * @param {number} registerIndex Register this sampler is bound at.
+   * @returns {object} Carbon sampler record.
+   */
+  toCarbonBinary(registerIndex) {
+    const descriptor = this.sampler ?? {};
+    return {
+      registerIndex,
+      name: toRecordText(this.name),
+      comparison: descriptor.comparison ? 1 : 0,
+      minFilter: descriptor.minFilter,
+      magFilter: descriptor.magFilter,
+      mipFilter: descriptor.mipFilter,
+      addressU: descriptor.addressU,
+      addressV: descriptor.addressV,
+      addressW: descriptor.addressW,
+      mipLODBias: toRecordFloat(descriptor.mipLODBiasRaw),
+      maxAnisotropy: descriptor.maxAnisotropy,
+      comparisonFunc: descriptor.comparisonFunc,
+      // On one line deliberately: the raw-field guard requires the
+      // reinterpretation to be visible on the same line as the raw access.
+      borderColor: (descriptor.borderColorRaw ?? [0, 0, 0, 0]).slice(0, 4).map(toRecordFloat),
+      minLOD: toRecordFloat(descriptor.minLODRaw),
+      maxLOD: toRecordFloat(descriptor.maxLODRaw),
+      isDynamic: this.isDynamic ? 1 : 0
+    };
+  }
 }
 
 // Declared imperatively rather than with decorators, so this module stays

package/dist/resource/shader/sampler/Tr2SamplerSetup.js.map

@@ -1 +1 @@
-{"version":3,"file":"Tr2SamplerSetup.js","sources":["../../../../../src/resource/shader/sampler/Tr2SamplerSetup.js"],"sourcesContent":["// Source: trinity/trinity/Shader/Tr2EffectDescription.h\nimport { CjsSchema, impl, type } from \"@carbonenginejs/runtime-utils/schema\";\nimport { CjsModel } from \"@carbonenginejs/runtime-utils/model\";\nimport { isPlainObject } from \"@carbonenginejs/runtime-utils/is\";\nimport { cloneCarbonValue } from \"@carbonenginejs/runtime-utils/types\";\n\n/** Reflected sampler name and complete device-free sampler descriptor. */\nexport class Tr2SamplerSetup extends CjsModel\n{\n\n  /** name (const char*) */\n  name = \"\";\n\n  /** Whether the source sampler carried a name rather than authored null. */\n  hasName = false;\n\n  /** sampler (Tr2SamplerStateAL) */\n  sampler = null;\n\n  /** Whether the sampler occupies a dynamic register rather than static signature state. */\n  isDynamic = false;\n\n  /**\n   * Construct a canonical sampler record from JS/JSON model values.\n   *\n   * @param {object} values Canonical model values.\n   * @param {object} options CjsModel import options.\n   * @returns {Tr2SamplerSetup} Hydrated sampler.\n   */\n  static from(values = {}, options = {})\n  {\n    let normalized = values;\n    if (values && Object.hasOwn(values, \"name\")\n      && !Object.hasOwn(values, \"hasName\"))\n    {\n      normalized = {\n        ...values,\n        hasName: values.name !== null,\n        name: values.name === null ? \"\" : values.name\n      };\n    }\n    return super.from(normalized, options);\n  }\n\n  /**\n   * Build one sampler from its portable JSON reflection record.\n   *\n   * @param {object} value Portable sampler record.\n   * @returns {Tr2SamplerSetup} Reflected sampler.\n   */\n  static fromPortable(value)\n  {\n    if (!isPlainObject(value))\n    {\n      throw new TypeError(\"Portable effect sampler must be an object\");\n    }\n    const sampler = new this();\n    sampler.hasName = value.name !== null;\n    sampler.name = sampler.hasName ? String(value.name ?? \"\") : \"\";\n    sampler.sampler = cloneCarbonValue(value.descriptor);\n    sampler.isDynamic = !!value.isDynamic;\n    return sampler;\n  }\n\n}\n\n// Declared imperatively rather than with decorators, so this module stays\n// plain ESM that loads from source without a transform. The decorator\n// expressions are reused verbatim, so the registered metadata is identical.\n// Statics belong in `methods`: decorateMethod targets the prototype and\n// would register a static as an instance field.\nCjsSchema.define(Tr2SamplerSetup, {\n  className: \"Tr2SamplerSetup\",\n  family: \"shader\",\n  fields: {\n    name: type.string,\n    hasName: [ impl.adapted, impl.reason(\"The schema string field cannot distinguish an authored null sampler name from an empty name; portable reflection must retain that distinction for static sampler records.\"), type.boolean ],\n    sampler: type.rawStruct(\"Tr2SamplerStateAL\"),\n    isDynamic: [ impl.adapted, impl.reason(\"The portable effect contract distinguishes dynamic and static sampler declarations before an engine creates sampler state.\"), type.boolean ]\n  }\n});\n"],"names":["Tr2SamplerSetup","CjsModel","name","hasName","sampler","isDynamic","from","values","options","normalized","Object","hasOwn","fromPortable","value","isPlainObject","TypeError","String","cloneCarbonValue","descriptor","CjsSchema","define","className","family","fields","type","string","impl","adapted","reason","boolean","rawStruct"],"mappings":";;;;;AAAA;;AAMA;AACO,MAAMA,eAAe,SAASC,QAAQ,CAC7C;AAEE;AACAC,EAAAA,IAAI,GAAG,EAAE;;AAET;AACAC,EAAAA,OAAO,GAAG,KAAK;;AAEf;AACAC,EAAAA,OAAO,GAAG,IAAI;;AAEd;AACAC,EAAAA,SAAS,GAAG,KAAK;;AAEjB;AACF;AACA;AACA;AACA;AACA;AACA;EACE,OAAOC,IAAIA,CAACC,MAAM,GAAG,EAAE,EAAEC,OAAO,GAAG,EAAE,EACrC;IACE,IAAIC,UAAU,GAAGF,MAAM;IACvB,IAAIA,MAAM,IAAIG,MAAM,CAACC,MAAM,CAACJ,MAAM,EAAE,MAAM,CAAC,IACtC,CAACG,MAAM,CAACC,MAAM,CAACJ,MAAM,EAAE,SAAS,CAAC,EACtC;AACEE,MAAAA,UAAU,GAAG;AACX,QAAA,GAAGF,MAAM;AACTJ,QAAAA,OAAO,EAAEI,MAAM,CAACL,IAAI,KAAK,IAAI;QAC7BA,IAAI,EAAEK,MAAM,CAACL,IAAI,KAAK,IAAI,GAAG,EAAE,GAAGK,MAAM,CAACL;OAC1C;AACH,IAAA;AACA,IAAA,OAAO,KAAK,CAACI,IAAI,CAACG,UAAU,EAAED,OAAO,CAAC;AACxC,EAAA;;AAEA;AACF;AACA;AACA;AACA;AACA;EACE,OAAOI,YAAYA,CAACC,KAAK,EACzB;AACE,IAAA,IAAI,CAACC,aAAa,CAACD,KAAK,CAAC,EACzB;AACE,MAAA,MAAM,IAAIE,SAAS,CAAC,2CAA2C,CAAC;AAClE,IAAA;AACA,IAAA,MAAMX,OAAO,GAAG,IAAI,IAAI,EAAE;AAC1BA,IAAAA,OAAO,CAACD,OAAO,GAAGU,KAAK,CAACX,IAAI,KAAK,IAAI;AACrCE,IAAAA,OAAO,CAACF,IAAI,GAAGE,OAAO,CAACD,OAAO,GAAGa,MAAM,CAACH,KAAK,CAACX,IAAI,IAAI,EAAE,CAAC,GAAG,EAAE;IAC9DE,OAAO,CAACA,OAAO,GAAGa,gBAAgB,CAACJ,KAAK,CAACK,UAAU,CAAC;AACpDd,IAAAA,OAAO,CAACC,SAAS,GAAG,CAAC,CAACQ,KAAK,CAACR,SAAS;AACrC,IAAA,OAAOD,OAAO;AAChB,EAAA;AAEF;;AAEA;AACA;AACA;AACA;AACA;AACAe,SAAS,CAACC,MAAM,CAACpB,eAAe,EAAE;AAChCqB,EAAAA,SAAS,EAAE,iBAAiB;AAC5BC,EAAAA,MAAM,EAAE,QAAQ;AAChBC,EAAAA,MAAM,EAAE;IACNrB,IAAI,EAAEsB,IAAI,CAACC,MAAM;AACjBtB,IAAAA,OAAO,EAAE,CAAEuB,IAAI,CAACC,OAAO,EAAED,IAAI,CAACE,MAAM,CAAC,2KAA2K,CAAC,EAAEJ,IAAI,CAACK,OAAO,CAAE;AACjOzB,IAAAA,OAAO,EAAEoB,IAAI,CAACM,SAAS,CAAC,mBAAmB,CAAC;AAC5CzB,IAAAA,SAAS,EAAE,CAAEqB,IAAI,CAACC,OAAO,EAAED,IAAI,CAACE,MAAM,CAAC,4HAA4H,CAAC,EAAEJ,IAAI,CAACK,OAAO;AACpL;AACF,CAAC,CAAC;;;;"}
+{"version":3,"file":"Tr2SamplerSetup.js","sources":["../../../../../src/resource/shader/sampler/Tr2SamplerSetup.js"],"sourcesContent":["// Source: trinity/trinity/Shader/Tr2EffectDescription.h\nimport { CjsSchema, impl, type } from \"@carbonenginejs/runtime-utils/schema\";\nimport { CjsModel } from \"@carbonenginejs/runtime-utils/model\";\nimport { isPlainObject } from \"@carbonenginejs/runtime-utils/is\";\nimport {\n  recordRawBits,\n  recordText,\n  toRecordFloat,\n  toRecordText\n} from \"../reflection/carbonRecordFields.js\";\n\n/** Reflected sampler name and complete device-free sampler descriptor. */\nexport class Tr2SamplerSetup extends CjsModel\n{\n\n  /** name (const char*) */\n  name = \"\";\n\n  /** Whether the source sampler carried a name rather than authored null. */\n  hasName = false;\n\n  /** sampler (Tr2SamplerStateAL) */\n  sampler = null;\n\n  /** Whether the sampler occupies a dynamic register rather than static signature state. */\n  isDynamic = false;\n\n  /**\n   * Construct a canonical sampler record from JS/JSON model values.\n   *\n   * @param {object} values Canonical model values.\n   * @param {object} options CjsModel import options.\n   * @returns {Tr2SamplerSetup} Hydrated sampler.\n   */\n  static from(values = {}, options = {})\n  {\n    let normalized = values;\n    if (values && Object.hasOwn(values, \"name\")\n      && !Object.hasOwn(values, \"hasName\"))\n    {\n      normalized = {\n        ...values,\n        hasName: values.name !== null,\n        name: values.name === null ? \"\" : values.name\n      };\n    }\n    return super.from(normalized, options);\n  }\n\n  /**\n   * Build one dynamic sampler from its Carbon v15 description record.\n   *\n   * The name is kept whatever `isDynamic` says. Carbon nulls a non-dynamic\n   * sampler's name while reading (`Tr2EffectDescription.cpp:430-433`), but that\n   * is a runtime decision made on the way to a device — the file still carries\n   * the string, and this graph has to be able to re-emit the file it came from.\n   * Dropping it loses arena content: measured across the shipped corpus, this\n   * single rule accounted for every non-byte-identical re-emission.\n   *\n   * A consumer that wants Carbon's runtime view asks for it: the name is\n   * meaningful only when `isDynamic`.\n   *\n   * @param {object} record Carbon sampler record.\n   * @returns {Tr2SamplerSetup} Reflected sampler.\n   */\n  static fromCarbonBinary(record)\n  {\n    if (!isPlainObject(record))\n    {\n      throw new TypeError(\"Carbon effect sampler record must be an object\");\n    }\n\n    const sampler = new this();\n    sampler.isDynamic = !!record.isDynamic;\n    sampler.name = recordText(record.name);\n    sampler.hasName = sampler.name !== \"\";\n    sampler.sampler = {\n      comparison: !!record.comparison,\n      minFilter: record.minFilter,\n      magFilter: record.magFilter,\n      mipFilter: record.mipFilter,\n      addressU: record.addressU,\n      addressV: record.addressV,\n      addressW: record.addressW,\n      mipLODBiasRaw: recordRawBits(record.mipLODBias),\n      maxAnisotropy: record.maxAnisotropy,\n      comparisonFunc: record.comparisonFunc,\n      borderColorRaw: (record.borderColor ?? []).map(recordRawBits),\n      minLODRaw: recordRawBits(record.minLOD),\n      maxLODRaw: recordRawBits(record.maxLOD)\n    };\n    return sampler;\n  }\n\n\n  /**\n   * Emit this sampler as a Carbon v15 record.\n   *\n   * The name is written whether or not it is meaningful: Carbon's writer always\n   * emits the field, and the string it emits is the one the compiler authored,\n   * not the one Carbon's reader keeps.\n   *\n   * @param {number} registerIndex Register this sampler is bound at.\n   * @returns {object} Carbon sampler record.\n   */\n  toCarbonBinary(registerIndex)\n  {\n    const descriptor = this.sampler ?? {};\n    return {\n      registerIndex,\n      name: toRecordText(this.name),\n      comparison: descriptor.comparison ? 1 : 0,\n      minFilter: descriptor.minFilter,\n      magFilter: descriptor.magFilter,\n      mipFilter: descriptor.mipFilter,\n      addressU: descriptor.addressU,\n      addressV: descriptor.addressV,\n      addressW: descriptor.addressW,\n      mipLODBias: toRecordFloat(descriptor.mipLODBiasRaw),\n      maxAnisotropy: descriptor.maxAnisotropy,\n      comparisonFunc: descriptor.comparisonFunc,\n      // On one line deliberately: the raw-field guard requires the\n      // reinterpretation to be visible on the same line as the raw access.\n      borderColor: (descriptor.borderColorRaw ?? [ 0, 0, 0, 0 ]).slice(0, 4).map(toRecordFloat),\n      minLOD: toRecordFloat(descriptor.minLODRaw),\n      maxLOD: toRecordFloat(descriptor.maxLODRaw),\n      isDynamic: this.isDynamic ? 1 : 0\n    };\n  }\n\n}\n\n// Declared imperatively rather than with decorators, so this module stays\n// plain ESM that loads from source without a transform. The decorator\n// expressions are reused verbatim, so the registered metadata is identical.\n// Statics belong in `methods`: decorateMethod targets the prototype and\n// would register a static as an instance field.\nCjsSchema.define(Tr2SamplerSetup, {\n  className: \"Tr2SamplerSetup\",\n  family: \"shader\",\n  fields: {\n    name: type.string,\n    hasName: [ impl.adapted, impl.reason(\"The schema string field cannot distinguish an authored null sampler name from an empty name; portable reflection must retain that distinction for static sampler records.\"), type.boolean ],\n    sampler: type.rawStruct(\"Tr2SamplerStateAL\"),\n    isDynamic: [ impl.adapted, impl.reason(\"The portable effect contract distinguishes dynamic and static sampler declarations before an engine creates sampler state.\"), type.boolean ]\n  }\n});\n"],"names":["Tr2SamplerSetup","CjsModel","name","hasName","sampler","isDynamic","from","values","options","normalized","Object","hasOwn","fromCarbonBinary","record","isPlainObject","TypeError","recordText","comparison","minFilter","magFilter","mipFilter","addressU","addressV","addressW","mipLODBiasRaw","recordRawBits","mipLODBias","maxAnisotropy","comparisonFunc","borderColorRaw","borderColor","map","minLODRaw","minLOD","maxLODRaw","maxLOD","toCarbonBinary","registerIndex","descriptor","toRecordText","toRecordFloat","slice","CjsSchema","define","className","family","fields","type","string","impl","adapted","reason","boolean","rawStruct"],"mappings":"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"}

package/dist/worker/CjsResManMainThreadLoader.js

@@ -33,10 +33,11 @@ class CjsResManMainThreadLoader {
    * @param {object} descriptor Registered format descriptor.
    * @param {*} input Reader input.
    * @param {object} [formatOptions={}] Normalized format options.
+   * @param {object|null} [context=null] Normalized resource path context.
    * @returns {Promise<*>} Format result.
    */
-  ReadFormat(descriptor, input, formatOptions = {}) {
-    return readFormatOnCurrentThread(descriptor, input, formatOptions);
+  ReadFormat(descriptor, input, formatOptions = {}, context = null) {
+    return readFormatOnCurrentThread(descriptor, input, formatOptions, context);
   }
 
   /**
@@ -55,25 +56,26 @@ class CjsResManMainThreadLoader {
  * @param {object} descriptor Registered format descriptor.
  * @param {*} input Reader input.
  * @param {object} formatOptions Normalized format options.
+ * @param {object|null} context Normalized resource path context.
  * @returns {Promise<*>} Reader result.
  */
-function readFormatOnCurrentThread(descriptor, input, formatOptions = {}) {
+function readFormatOnCurrentThread(descriptor, input, formatOptions = {}, context = null) {
   const Format = descriptor?.Format;
   if (typeof Format !== "function") {
     throw new TypeError("Resource format descriptor requires a Format class.");
   }
   if (typeof Format.readAsync === "function") {
-    return Format.readAsync(input, formatOptions);
+    return Format.readAsync(input, formatOptions, context);
   }
   if (typeof Format.read === "function") {
-    return Format.read(input, formatOptions);
+    return Format.read(input, formatOptions, context);
   }
   const reader = new Format(formatOptions);
   if (typeof reader.ReadAsync === "function") {
-    return reader.ReadAsync(input, formatOptions);
+    return reader.ReadAsync(input, formatOptions, context);
   }
   if (typeof reader.Read === "function") {
-    return reader.Read(input, formatOptions);
+    return reader.Read(input, formatOptions, context);
   }
   throw new TypeError(`${Format.name} does not expose a read operation.`);
 }