@carbonenginejs/runtime-resource 0.9.2 → 0.11.0

package/dist/formats/hlsl/core/analysis.js

@@ -0,0 +1,51 @@
+import { normalizeValues, DEFAULT_VALUES, readRaw } from './helpers.js';
+import { resolveSelectedOptions } from './metadata.js';
+import { HlslEffectBindingManifest } from './tr2/shader/HlslEffectBindingManifest.js';
+
+/**
+ * Resolve one permutation to the raw effect/shader/manifest context that
+ * downstream translation tooling needs.
+ *
+ * This is intentionally an advanced helper: it returns internal graph objects
+ * rather than the stable JSON contract exposed by `CjsHlslFormat`.
+ *
+ * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.
+ * @param {object} values Normalized format values.
+ * @returns {{effectRes: object, shader: object|null, selection: object, effectDescription: object|null, bindingManifest: HlslEffectBindingManifest|null}}
+ *   Raw loaded effect data plus the resolved permutation context.
+ */
+function analyzeEffectWithValues(input, values) {
+  const effectRes = readRaw(input, values);
+  const selection = resolveSelectedOptions(effectRes, values.permutation || []);
+  let shader = null;
+  try {
+    shader = effectRes.GetShader(values.permutation || []);
+  } catch {
+    shader = null;
+  }
+  const effectDescription = shader ? shader.GetEffectDescription() : null;
+  const bindingManifest = effectDescription ? HlslEffectBindingManifest.fromEffectDescription(effectDescription) : null;
+  return {
+    effectRes,
+    shader,
+    selection,
+    effectDescription,
+    bindingManifest
+  };
+}
+
+/**
+ * Advanced one-shot helper for tooling that needs one parse plus one binding
+ * manifest build without changing the stable reader emits.
+ *
+ * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.
+ * @param {object} [options] Format values.
+ * @returns {{effectRes: object, shader: object|null, selection: object, effectDescription: object|null, bindingManifest: HlslEffectBindingManifest|null}}
+ *   Raw loaded effect data plus the resolved permutation context.
+ */
+function readEffectAnalysis(input, options = {}) {
+  return analyzeEffectWithValues(input, normalizeValues(DEFAULT_VALUES, options, "readEffectAnalysis"));
+}
+
+export { analyzeEffectWithValues, readEffectAnalysis };
+//# sourceMappingURL=analysis.js.map

package/dist/formats/hlsl/core/analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.js","sources":["../../../../../src/formats/hlsl/core/analysis.js"],"sourcesContent":["import { DEFAULT_VALUES, normalizeValues, readRaw } from \"./helpers.js\";\nimport { resolveSelectedOptions } from \"./metadata.js\";\nimport { HlslEffectBindingManifest } from \"./tr2/shader/HlslEffectBindingManifest.js\";\n\n/**\n * Resolve one permutation to the raw effect/shader/manifest context that\n * downstream translation tooling needs.\n *\n * This is intentionally an advanced helper: it returns internal graph objects\n * rather than the stable JSON contract exposed by `CjsHlslFormat`.\n *\n * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.\n * @param {object} values Normalized format values.\n * @returns {{effectRes: object, shader: object|null, selection: object, effectDescription: object|null, bindingManifest: HlslEffectBindingManifest|null}}\n *   Raw loaded effect data plus the resolved permutation context.\n */\nexport function analyzeEffectWithValues(input, values)\n{\n    const effectRes = readRaw(input, values);\n    const selection = resolveSelectedOptions(effectRes, values.permutation || []);\n\n    let shader = null;\n    try\n    {\n        shader = effectRes.GetShader(values.permutation || []);\n    }\n    catch\n    {\n        shader = null;\n    }\n\n    const effectDescription = shader ? shader.GetEffectDescription() : null;\n    const bindingManifest = effectDescription\n        ? HlslEffectBindingManifest.fromEffectDescription(effectDescription)\n        : null;\n\n    return {\n        effectRes,\n        shader,\n        selection,\n        effectDescription,\n        bindingManifest\n    };\n}\n\n/**\n * Advanced one-shot helper for tooling that needs one parse plus one binding\n * manifest build without changing the stable reader emits.\n *\n * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.\n * @param {object} [options] Format values.\n * @returns {{effectRes: object, shader: object|null, selection: object, effectDescription: object|null, bindingManifest: HlslEffectBindingManifest|null}}\n *   Raw loaded effect data plus the resolved permutation context.\n */\nexport function readEffectAnalysis(input, options = {})\n{\n    return analyzeEffectWithValues(input, normalizeValues(DEFAULT_VALUES, options, \"readEffectAnalysis\"));\n}\n"],"names":["analyzeEffectWithValues","input","values","effectRes","readRaw","selection","resolveSelectedOptions","permutation","shader","GetShader","effectDescription","GetEffectDescription","bindingManifest","HlslEffectBindingManifest","fromEffectDescription","readEffectAnalysis","options","normalizeValues","DEFAULT_VALUES"],"mappings":";;;;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,uBAAuBA,CAACC,KAAK,EAAEC,MAAM,EACrD;AACI,EAAA,MAAMC,SAAS,GAAGC,OAAO,CAACH,KAAK,EAAEC,MAAM,CAAC;EACxC,MAAMG,SAAS,GAAGC,sBAAsB,CAACH,SAAS,EAAED,MAAM,CAACK,WAAW,IAAI,EAAE,CAAC;EAE7E,IAAIC,MAAM,GAAG,IAAI;EACjB,IACA;IACIA,MAAM,GAAGL,SAAS,CAACM,SAAS,CAACP,MAAM,CAACK,WAAW,IAAI,EAAE,CAAC;AAC1D,EAAA,CAAC,CACD,MACA;AACIC,IAAAA,MAAM,GAAG,IAAI;AACjB,EAAA;EAEA,MAAME,iBAAiB,GAAGF,MAAM,GAAGA,MAAM,CAACG,oBAAoB,EAAE,GAAG,IAAI;EACvE,MAAMC,eAAe,GAAGF,iBAAiB,GACnCG,yBAAyB,CAACC,qBAAqB,CAACJ,iBAAiB,CAAC,GAClE,IAAI;EAEV,OAAO;IACHP,SAAS;IACTK,MAAM;IACNH,SAAS;IACTK,iBAAiB;AACjBE,IAAAA;GACH;AACL;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,kBAAkBA,CAACd,KAAK,EAAEe,OAAO,GAAG,EAAE,EACtD;AACI,EAAA,OAAOhB,uBAAuB,CAACC,KAAK,EAAEgB,eAAe,CAACC,cAAc,EAAEF,OAAO,EAAE,oBAAoB,CAAC,CAAC;AACzG;;;;"}

package/dist/formats/hlsl/core/helpers.js

@@ -0,0 +1,270 @@
+import { HlslEffectReadError } from './HlslEffectReadError.js';
+import { resolveSelectedOptions, emitEffectMetadata } from './metadata.js';
+import { HlslEffectRes } from './tr2/resources/HlslEffectRes.js';
+import { CLASS_KEYS, emitEffectJson } from './json.js';
+
+/**
+ * Internal read-pipeline glue for CjsHlslFormat.
+ *
+ * Keeps the public class file small: input normalization, option/classes
+ * normalization, the shared read path used by both the instance and the
+ * static one-shots, and JSON conversion live here. The actual Tr2 effect
+ * container parser lives under src/core/tr2 (internal parsing machinery,
+ * not part of this package's public surface); this module wires bytes into
+ * that graph and, for `emit: "json"`, converts it via src/core/json.js into
+ * the documented plain-data shape.
+ */
+
+const OUTPUT_JSON = "json";
+const OUTPUT_RAW = "raw";
+const OUTPUT_METADATA = "metadata";
+const DEFAULT_VALUES = Object.freeze({
+  emit: OUTPUT_JSON,
+  source: "memory",
+  permutation: null,
+  classes: Object.freeze({})
+});
+const VALID_EMITS = new Set([OUTPUT_JSON, OUTPUT_RAW, OUTPUT_METADATA]);
+const OPTION_KEYS = new Set(["emit", "source", "permutation", "classes"]);
+
+/**
+ * Validate a `classes` node key against {@link CLASS_KEYS}.
+ *
+ * @param {string} key Candidate node key.
+ * @param {string} [readerName] Reader name used in the thrown error.
+ */
+function validateClassKey(key, readerName = "CjsHlslFormat") {
+  if (!CLASS_KEYS.includes(key)) {
+    throw new Error(`${readerName}: unknown class key ${JSON.stringify(key)}; expected one of ${CLASS_KEYS.join(", ")}`);
+  }
+}
+
+/**
+ * Validate a single `classes` entry: a known key mapped to a constructor.
+ *
+ * @param {string} key Node key.
+ * @param {Function} Class Candidate constructor.
+ * @param {string} [readerName] Reader name used in thrown errors.
+ */
+function validateClass(key, Class, readerName = "CjsHlslFormat") {
+  validateClassKey(key, readerName);
+  if (typeof Class !== "function") {
+    throw new TypeError(`${readerName}: class ${JSON.stringify(key)} must be a constructor`);
+  }
+}
+
+/**
+ * Merge and validate a `classes` map over a base map.
+ *
+ * @param {object} base Current classes map.
+ * @param {object} classes Incoming classes map to merge in.
+ * @param {string} readerName Reader name used in thrown errors.
+ * @returns {object} Merged, validated classes map.
+ */
+function mergeClasses(base, classes, readerName) {
+  if (!classes || typeof classes !== "object") {
+    throw new TypeError(`${readerName}: classes option must be an object`);
+  }
+  const next = {
+    ...base
+  };
+  for (const [key, Class] of Object.entries(classes)) {
+    if (Class === null || Class === undefined) {
+      delete next[key];
+      continue;
+    }
+    validateClass(key, Class, readerName);
+    next[key] = Class;
+  }
+  return next;
+}
+
+/**
+ * Merge format values over a base set and validate them.
+ *
+ * @param {object} base Current values.
+ * @param {object} [options] Values to merge in.
+ * @param {string} [readerName] Reader name used in error messages.
+ * @returns {object} A validated copy of the merged values.
+ */
+function normalizeValues(base, options = {}, readerName = "CjsHlslFormat") {
+  if (!options || typeof options !== "object") {
+    throw new TypeError(`${readerName}: options must be an object`);
+  }
+  for (const key of Object.keys(options)) {
+    if (!OPTION_KEYS.has(key)) {
+      throw new TypeError(`${readerName}: unknown option ${JSON.stringify(key)}`);
+    }
+  }
+  const values = {
+    ...base,
+    ...options
+  };
+  if (!VALID_EMITS.has(values.emit)) {
+    throw new TypeError(`${readerName}: emit must be one of ${Array.from(VALID_EMITS, emit => JSON.stringify(emit)).join(", ")}, got ${JSON.stringify(values.emit)}`);
+  }
+  if (typeof values.source !== "string" || !values.source) {
+    values.source = DEFAULT_VALUES.source;
+  }
+  values.classes = Object.prototype.hasOwnProperty.call(options, "classes") ? mergeClasses(base.classes || {}, options.classes, readerName) : {
+    ...(base.classes || {})
+  };
+  return {
+    emit: values.emit,
+    source: values.source,
+    permutation: values.permutation ?? null,
+    classes: values.classes
+  };
+}
+
+/**
+ * Normalize caller input into a Uint8Array of Tr2 effect bytes.
+ *
+ * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Candidate payload.
+ * @returns {Uint8Array} The payload bytes.
+ */
+function toBytes(input) {
+  if (input instanceof Uint8Array) return input;
+  if (typeof ArrayBuffer !== "undefined" && input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+  throw new TypeError("CjsHlslFormat: input must be Tr2 effect bytes (Uint8Array, Buffer, DataView or ArrayBuffer)");
+}
+
+/**
+ * The shared read path used by the instance Read, Inspect, and the static
+ * one-shots: normalizes input bytes and loads a HlslEffectRes graph. This is
+ * internal parsing machinery — the documented public contract is the plain
+ * JSON shape produced by {@link readWithValues}, not this raw graph.
+ *
+ * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.
+ * @param {object} values Normalized format values.
+ * @returns {HlslEffectRes} The loaded effect resource graph.
+ */
+function readRaw(input, values) {
+  const bytes = toBytes(input);
+  const effect = new HlslEffectRes();
+  const ok = effect.DoLoad(bytes, {
+    source: values.source
+  });
+  if (!ok) {
+    throw new HlslEffectReadError(effect.loadError ? effect.loadError.message : "Failed to read Tr2 effect resource", {
+      source: values.source,
+      cause: effect.loadError || null
+    });
+  }
+  return effect;
+}
+
+/**
+ * Resolves one permutation's HlslShader from a loaded effect, tolerating
+ * bodies that fail to decode (returns null instead of throwing).
+ *
+ * @param {HlslEffectRes} effect Loaded effect resource graph.
+ * @param {object} values Normalized format values.
+ * @returns {object|null} Resolved HlslShader, or null.
+ */
+function resolveShader(effect, values) {
+  try {
+    return effect.GetShader(values.permutation || []);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Shared read entry honouring the emit mode.
+ *
+ * `emit: "raw"` returns the live HlslEffectRes instance — internal,
+ * unstable, and not schema-guaranteed across versions. `emit: "json"`
+ * (the default) returns the documented plain-data effect graph, honouring
+ * `values.classes`.
+ *
+ * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.
+ * @param {object} values Normalized format values.
+ * @returns {HlslEffectRes|object} The raw HlslEffectRes instance, or the documented JSON graph.
+ */
+function readWithValues(input, values) {
+  const effect = readRaw(input, values);
+  if (values.emit === OUTPUT_RAW) return effect;
+  const shader = resolveShader(effect, values);
+  if (values.emit === OUTPUT_METADATA) {
+    const selection = resolveSelectedOptions(effect, values.permutation || []);
+    return emitEffectMetadata(effect, shader, selection);
+  }
+  return emitEffectJson(effect, shader, {
+    classes: values.classes
+  });
+}
+
+/**
+ * Cheap inspection: effect header facts plus the default permutation's
+ * technique names and stage counts, without a full JSON conversion of the
+ * decoded graph.
+ *
+ * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.
+ * @param {object} values Normalized format values.
+ * @returns {object} Plain summary data.
+ */
+function inspectWithValues(input, values) {
+  const effect = readRaw(input, values);
+  const summary = {
+    source: values.source,
+    version: effect.m_version,
+    compilerVersion: effect.m_compilerVersion,
+    isGood: effect.IsGood(),
+    permutationCount: effect.m_permutations.length,
+    bodyCount: effect.m_offsetCount,
+    effectName: null,
+    techniques: []
+  };
+  try {
+    const shader = effect.GetShader(values.permutation || []);
+    if (shader) {
+      const description = shader.GetEffectDescription();
+      summary.effectName = description.effectName || null;
+      summary.techniques = description.techniques.map(technique => ({
+        name: technique.name,
+        passCount: technique.passes.length,
+        stageCounts: technique.passes.map(pass => pass.stageInputs.filter(stage => stage && stage.m_exists).length)
+      }));
+    }
+  } catch (error) {
+    summary.inspectError = {
+      name: error.name,
+      message: error.message
+    };
+  }
+  return summary;
+}
+
+/**
+ * Deep-convert a value to plain JSON-compatible data. Typed arrays become
+ * plain number arrays; Maps/Sets become objects/arrays; class instances
+ * with toJSON are honoured.
+ *
+ * @param {any} value Value to convert.
+ * @returns {any} Plain data.
+ */
+function toJsonValue(value) {
+  if (value === null || value === undefined) return value ?? null;
+  if (typeof value === "number" || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "bigint") return value.toString();
+  if (ArrayBuffer.isView(value)) return Array.from(value);
+  if (Array.isArray(value)) return value.map(toJsonValue);
+  if (value instanceof Map) {
+    const out = {};
+    for (const [key, entry] of value) out[key] = toJsonValue(entry);
+    return out;
+  }
+  if (value instanceof Set) return Array.from(value, toJsonValue);
+  if (typeof value === "object") {
+    if (typeof value.toJSON === "function") return toJsonValue(value.toJSON());
+    const out = {};
+    for (const key of Object.keys(value)) out[key] = toJsonValue(value[key]);
+    return out;
+  }
+  return null;
+}
+
+export { CLASS_KEYS, DEFAULT_VALUES, HlslEffectReadError, OUTPUT_JSON, OUTPUT_METADATA, OUTPUT_RAW, inspectWithValues, normalizeValues, readRaw, readWithValues, toBytes, toJsonValue, validateClass, validateClassKey };
+//# sourceMappingURL=helpers.js.map

package/dist/formats/hlsl/core/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sources":["../../../../../src/formats/hlsl/core/helpers.js"],"sourcesContent":["/**\n * Internal read-pipeline glue for CjsHlslFormat.\n *\n * Keeps the public class file small: input normalization, option/classes\n * normalization, the shared read path used by both the instance and the\n * static one-shots, and JSON conversion live here. The actual Tr2 effect\n * container parser lives under src/core/tr2 (internal parsing machinery,\n * not part of this package's public surface); this module wires bytes into\n * that graph and, for `emit: \"json\"`, converts it via src/core/json.js into\n * the documented plain-data shape.\n */\n\nimport { HlslEffectReadError } from \"./HlslEffectReadError.js\";\nimport {\n    emitEffectMetadata,\n    resolveSelectedOptions\n} from \"./metadata.js\";\nimport { HlslEffectRes } from \"./tr2/resources/HlslEffectRes.js\";\nimport { CLASS_KEYS, emitEffectJson } from \"./json.js\";\n\nexport const OUTPUT_JSON = \"json\";\nexport const OUTPUT_RAW = \"raw\";\nexport const OUTPUT_METADATA = \"metadata\";\n\nexport const DEFAULT_VALUES = Object.freeze({\n    emit: OUTPUT_JSON,\n    source: \"memory\",\n    permutation: null,\n    classes: Object.freeze({})\n});\n\nconst VALID_EMITS = new Set([ OUTPUT_JSON, OUTPUT_RAW, OUTPUT_METADATA ]);\nconst OPTION_KEYS = new Set([ \"emit\", \"source\", \"permutation\", \"classes\" ]);\n\n/**\n * Validate a `classes` node key against {@link CLASS_KEYS}.\n *\n * @param {string} key Candidate node key.\n * @param {string} [readerName] Reader name used in the thrown error.\n */\nexport function validateClassKey(key, readerName = \"CjsHlslFormat\")\n{\n    if (!CLASS_KEYS.includes(key))\n    {\n        throw new Error(`${readerName}: unknown class key ${JSON.stringify(key)}; expected one of ${CLASS_KEYS.join(\", \")}`);\n    }\n}\n\n/**\n * Validate a single `classes` entry: a known key mapped to a constructor.\n *\n * @param {string} key Node key.\n * @param {Function} Class Candidate constructor.\n * @param {string} [readerName] Reader name used in thrown errors.\n */\nexport function validateClass(key, Class, readerName = \"CjsHlslFormat\")\n{\n    validateClassKey(key, readerName);\n    if (typeof Class !== \"function\")\n    {\n        throw new TypeError(`${readerName}: class ${JSON.stringify(key)} must be a constructor`);\n    }\n}\n\n/**\n * Merge and validate a `classes` map over a base map.\n *\n * @param {object} base Current classes map.\n * @param {object} classes Incoming classes map to merge in.\n * @param {string} readerName Reader name used in thrown errors.\n * @returns {object} Merged, validated classes map.\n */\nfunction mergeClasses(base, classes, readerName)\n{\n    if (!classes || typeof classes !== \"object\")\n    {\n        throw new TypeError(`${readerName}: classes option must be an object`);\n    }\n\n    const next = { ...base };\n    for (const [ key, Class ] of Object.entries(classes))\n    {\n        if (Class === null || Class === undefined)\n        {\n            delete next[key];\n            continue;\n        }\n        validateClass(key, Class, readerName);\n        next[key] = Class;\n    }\n    return next;\n}\n\n/**\n * Merge format values over a base set and validate them.\n *\n * @param {object} base Current values.\n * @param {object} [options] Values to merge in.\n * @param {string} [readerName] Reader name used in error messages.\n * @returns {object} A validated copy of the merged values.\n */\nexport function normalizeValues(base, options = {}, readerName = \"CjsHlslFormat\")\n{\n    if (!options || typeof options !== \"object\")\n    {\n        throw new TypeError(`${readerName}: options must be an object`);\n    }\n    for (const key of Object.keys(options))\n    {\n        if (!OPTION_KEYS.has(key))\n        {\n            throw new TypeError(`${readerName}: unknown option ${JSON.stringify(key)}`);\n        }\n    }\n\n    const values = { ...base, ...options };\n\n    if (!VALID_EMITS.has(values.emit))\n    {\n        throw new TypeError(`${readerName}: emit must be one of ${Array.from(VALID_EMITS, (emit) => JSON.stringify(emit)).join(\", \")}, got ${JSON.stringify(values.emit)}`);\n    }\n    if (typeof values.source !== \"string\" || !values.source)\n    {\n        values.source = DEFAULT_VALUES.source;\n    }\n    values.classes = Object.prototype.hasOwnProperty.call(options, \"classes\")\n        ? mergeClasses(base.classes || {}, options.classes, readerName)\n        : { ...(base.classes || {}) };\n\n    return {\n        emit: values.emit,\n        source: values.source,\n        permutation: values.permutation ?? null,\n        classes: values.classes\n    };\n}\n\n/**\n * Normalize caller input into a Uint8Array of Tr2 effect bytes.\n *\n * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Candidate payload.\n * @returns {Uint8Array} The payload bytes.\n */\nexport function toBytes(input)\n{\n    if (input instanceof Uint8Array) return input;\n    if (typeof ArrayBuffer !== \"undefined\" && input instanceof ArrayBuffer) return new Uint8Array(input);\n    if (ArrayBuffer.isView(input)) return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);\n    throw new TypeError(\"CjsHlslFormat: input must be Tr2 effect bytes (Uint8Array, Buffer, DataView or ArrayBuffer)\");\n}\n\n/**\n * The shared read path used by the instance Read, Inspect, and the static\n * one-shots: normalizes input bytes and loads a HlslEffectRes graph. This is\n * internal parsing machinery — the documented public contract is the plain\n * JSON shape produced by {@link readWithValues}, not this raw graph.\n *\n * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.\n * @param {object} values Normalized format values.\n * @returns {HlslEffectRes} The loaded effect resource graph.\n */\nexport function readRaw(input, values)\n{\n    const bytes = toBytes(input);\n    const effect = new HlslEffectRes();\n    const ok = effect.DoLoad(bytes, { source: values.source });\n\n    if (!ok)\n    {\n        throw new HlslEffectReadError(\n            effect.loadError ? effect.loadError.message : \"Failed to read Tr2 effect resource\",\n            {\n                source: values.source,\n                cause: effect.loadError || null\n            }\n        );\n    }\n\n    return effect;\n}\n\n/**\n * Resolves one permutation's HlslShader from a loaded effect, tolerating\n * bodies that fail to decode (returns null instead of throwing).\n *\n * @param {HlslEffectRes} effect Loaded effect resource graph.\n * @param {object} values Normalized format values.\n * @returns {object|null} Resolved HlslShader, or null.\n */\nfunction resolveShader(effect, values)\n{\n    try\n    {\n        return effect.GetShader(values.permutation || []);\n    }\n    catch\n    {\n        return null;\n    }\n}\n\n/**\n * Shared read entry honouring the emit mode.\n *\n * `emit: \"raw\"` returns the live HlslEffectRes instance — internal,\n * unstable, and not schema-guaranteed across versions. `emit: \"json\"`\n * (the default) returns the documented plain-data effect graph, honouring\n * `values.classes`.\n *\n * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.\n * @param {object} values Normalized format values.\n * @returns {HlslEffectRes|object} The raw HlslEffectRes instance, or the documented JSON graph.\n */\nexport function readWithValues(input, values)\n{\n    const effect = readRaw(input, values);\n    if (values.emit === OUTPUT_RAW) return effect;\n\n    const shader = resolveShader(effect, values);\n    if (values.emit === OUTPUT_METADATA)\n    {\n        const selection = resolveSelectedOptions(effect, values.permutation || []);\n        return emitEffectMetadata(effect, shader, selection);\n    }\n\n    return emitEffectJson(effect, shader, { classes: values.classes });\n}\n\n/**\n * Cheap inspection: effect header facts plus the default permutation's\n * technique names and stage counts, without a full JSON conversion of the\n * decoded graph.\n *\n * @param {Uint8Array|ArrayBuffer|Buffer|DataView} input Tr2 effect payload.\n * @param {object} values Normalized format values.\n * @returns {object} Plain summary data.\n */\nexport function inspectWithValues(input, values)\n{\n    const effect = readRaw(input, values);\n\n    const summary = {\n        source: values.source,\n        version: effect.m_version,\n        compilerVersion: effect.m_compilerVersion,\n        isGood: effect.IsGood(),\n        permutationCount: effect.m_permutations.length,\n        bodyCount: effect.m_offsetCount,\n        effectName: null,\n        techniques: []\n    };\n\n    try\n    {\n        const shader = effect.GetShader(values.permutation || []);\n        if (shader)\n        {\n            const description = shader.GetEffectDescription();\n            summary.effectName = description.effectName || null;\n            summary.techniques = description.techniques.map((technique) => ({\n                name: technique.name,\n                passCount: technique.passes.length,\n                stageCounts: technique.passes.map(\n                    (pass) => pass.stageInputs.filter((stage) => stage && stage.m_exists).length\n                )\n            }));\n        }\n    }\n    catch (error)\n    {\n        summary.inspectError = { name: error.name, message: error.message };\n    }\n\n    return summary;\n}\n\n/**\n * Deep-convert a value to plain JSON-compatible data. Typed arrays become\n * plain number arrays; Maps/Sets become objects/arrays; class instances\n * with toJSON are honoured.\n *\n * @param {any} value Value to convert.\n * @returns {any} Plain data.\n */\nexport function toJsonValue(value)\n{\n    if (value === null || value === undefined) return value ?? null;\n    if (typeof value === \"number\" || typeof value === \"string\" || typeof value === \"boolean\") return value;\n    if (typeof value === \"bigint\") return value.toString();\n    if (ArrayBuffer.isView(value)) return Array.from(value);\n    if (Array.isArray(value)) return value.map(toJsonValue);\n    if (value instanceof Map)\n    {\n        const out = {};\n        for (const [ key, entry ] of value) out[key] = toJsonValue(entry);\n        return out;\n    }\n    if (value instanceof Set) return Array.from(value, toJsonValue);\n    if (typeof value === \"object\")\n    {\n        if (typeof value.toJSON === \"function\") return toJsonValue(value.toJSON());\n        const out = {};\n        for (const key of Object.keys(value)) out[key] = toJsonValue(value[key]);\n        return out;\n    }\n    return null;\n}\n\nexport { HlslEffectReadError };\nexport { CLASS_KEYS };\n"],"names":["OUTPUT_JSON","OUTPUT_RAW","OUTPUT_METADATA","DEFAULT_VALUES","Object","freeze","emit","source","permutation","classes","VALID_EMITS","Set","OPTION_KEYS","validateClassKey","key","readerName","CLASS_KEYS","includes","Error","JSON","stringify","join","validateClass","Class","TypeError","mergeClasses","base","next","entries","undefined","normalizeValues","options","keys","has","values","Array","from","prototype","hasOwnProperty","call","toBytes","input","Uint8Array","ArrayBuffer","isView","buffer","byteOffset","byteLength","readRaw","bytes","effect","HlslEffectRes","ok","DoLoad","HlslEffectReadError","loadError","message","cause","resolveShader","GetShader","readWithValues","shader","selection","resolveSelectedOptions","emitEffectMetadata","emitEffectJson","inspectWithValues","summary","version","m_version","compilerVersion","m_compilerVersion","isGood","IsGood","permutationCount","m_permutations","length","bodyCount","m_offsetCount","effectName","techniques","description","GetEffectDescription","map","technique","name","passCount","passes","stageCounts","pass","stageInputs","filter","stage","m_exists","error","inspectError","toJsonValue","value","toString","isArray","Map","out","entry","toJSON"],"mappings":"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"}

package/dist/formats/hlsl/core/json.js

@@ -0,0 +1,284 @@
+import { hlslShaderStageName } from './tr2/HlslRenderContextEnum.js';
+
+/**
+ * Tr2 effect JSON emitter.
+ *
+ * Converts the internal HlslEffectRes/HlslShader graph (src/core/tr2, internal
+ * parsing machinery — not part of this package's public surface) into the
+ * plain, documented JSON shape that IS the public contract of this reader.
+ *
+ * `emitEffectJson(effect, shader, options)` returns a plain object whose key
+ * order mirrors the reader schema below. When `options.classes` is given,
+ * matching node kinds are instantiated and populated as class instances
+ * instead of plain object literals — an opt-in alternative to walking the
+ * returned JSON into application-specific classes by hand.
+ */
+
+
+/**
+ * Node keys accepted by {@link emitEffectJson}'s `options.classes` map.
+ *
+ * Each key names one node shape in the emitted effect graph; the mapped
+ * constructor is instantiated with `new` and populated with that node's
+ * usual fields instead of a plain object literal.
+ *
+ * This is a first-pass hydration surface: it covers the top-level effect
+ * graph (the header, the default-permutation effect description, its
+ * techniques/passes/stage inputs, and per-stage constants/resources/
+ * samplers/bytecode). Nested detail that has no dedicated class key yet
+ * (shader libraries, parameter annotations, pipeline-input/register
+ * signatures) is still emitted as plain, JSON-compatible data.
+ */
+const CLASS_KEYS = Object.freeze(["Root", "Permutation", "EffectDescription", "Technique", "Pass", "StageInput", "Constant", "Resource", "Sampler", "ShaderBytecode"]);
+
+/**
+ * Instantiate and populate a node class, or return the plain props unchanged.
+ *
+ * @param {object} classes Opt-in node class map.
+ * @param {string} key Node key to look up in `classes`.
+ * @param {object} props Fields to populate onto the instance.
+ * @returns {object} A populated class instance, or `props` when no
+ * constructor is registered for `key`.
+ */
+function build(classes, key, props) {
+  const Ctor = classes[key];
+  return Ctor ? Object.assign(new Ctor(), props) : props;
+}
+
+/**
+ * Emit one HlslShaderPermutation node.
+ *
+ * @param {object} permutation Decoded permutation axis.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted permutation record.
+ */
+function emitPermutation(permutation, classes) {
+  return build(classes, "Permutation", {
+    name: permutation.name,
+    options: permutation.options.slice(),
+    defaultOption: permutation.defaultOption,
+    description: permutation.description,
+    type: permutation.type
+  });
+}
+
+/**
+ * Emit one HlslShaderBytecode node. Bytes are included as a plain number
+ * array (opaque payload; this package does not decode DXBC/HLSL bytecode).
+ *
+ * @param {object|null} bytecode Captured shader bytecode, or null.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object|null} Emitted bytecode record, or null.
+ */
+function emitShaderBytecode(bytecode, classes) {
+  if (!bytecode) return null;
+  return build(classes, "ShaderBytecode", {
+    stageType: bytecode.stageType,
+    stageName: bytecode.stageName,
+    shaderSize: bytecode.shaderSize,
+    stringTableOffset: bytecode.stringTableOffset,
+    effectName: bytecode.effectName,
+    bytes: Array.from(bytecode.bytes)
+  });
+}
+
+/**
+ * Emit one HlslEffectConstant node.
+ *
+ * @param {object} constant Decoded constant-buffer field metadata.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted constant record.
+ */
+function emitConstant(constant, classes) {
+  return build(classes, "Constant", {
+    name: constant.name,
+    offset: constant.offset,
+    size: constant.size,
+    type: constant.type,
+    dimension: constant.dimension,
+    elements: constant.elements,
+    isSRGB: constant.isSRGB,
+    isAutoregister: constant.isAutoregister
+  });
+}
+
+/**
+ * Emit one HlslEffectResource (SRV or UAV) node.
+ *
+ * @param {number} registerIndex Shader register index.
+ * @param {object} resource Decoded resource metadata.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted resource record.
+ */
+function emitResource(registerIndex, resource, classes) {
+  return build(classes, "Resource", {
+    registerIndex,
+    name: resource.name,
+    type: resource.type,
+    arrayElements: resource.arrayElements,
+    isSRGB: resource.isSRGB,
+    isAutoregister: resource.isAutoregister
+  });
+}
+
+/**
+ * Emit one HlslSamplerSetup node.
+ *
+ * @param {number} registerIndex Shader register index.
+ * @param {object} samplerSetup Decoded sampler setup (name + descriptor).
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted sampler record.
+ */
+function emitSampler(registerIndex, samplerSetup, classes) {
+  const sampler = samplerSetup.sampler || {};
+  return build(classes, "Sampler", {
+    registerIndex,
+    name: samplerSetup.name,
+    isDynamic: !!sampler.isDynamic,
+    comparison: !!sampler.comparison,
+    minFilter: sampler.minFilter,
+    magFilter: sampler.magFilter,
+    mipFilter: sampler.mipFilter,
+    addressU: sampler.addressU,
+    addressV: sampler.addressV,
+    addressW: sampler.addressW,
+    mipLODBias: sampler.mipLODBias,
+    maxAnisotropy: sampler.maxAnisotropy,
+    comparisonFunc: sampler.comparisonFunc,
+    borderColor: (sampler.borderColor || []).slice(),
+    minLOD: sampler.minLOD,
+    maxLOD: sampler.maxLOD
+  });
+}
+
+/**
+ * Emit one HlslEffectStageInput node, or null for stages absent from a pass.
+ *
+ * @param {object|undefined} stageInput Decoded stage input, if present.
+ * @param {number} stageType Trinity shader stage enum value.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object|null} Emitted stage-input record, or null.
+ */
+function emitStageInput(stageInput, stageType, classes) {
+  if (!stageInput || !stageInput.m_exists) return null;
+  const signature = stageInput.signature || {};
+  return build(classes, "StageInput", {
+    stageType,
+    stageName: hlslShaderStageName(stageType),
+    constants: (stageInput.constants || []).map(constant => emitConstant(constant, classes)),
+    resources: Array.from(stageInput.resources || [], ([registerIndex, resource]) => emitResource(registerIndex, resource, classes)),
+    samplers: Array.from(stageInput.samplers || [], ([registerIndex, sampler]) => emitSampler(registerIndex, sampler, classes)),
+    uavs: Array.from(stageInput.uavs || [], ([registerIndex, resource]) => emitResource(registerIndex, resource, classes)),
+    bytecode: emitShaderBytecode(stageInput.cjsShaderBytecode, classes),
+    signature: {
+      pipelineInputs: (signature.pipelineInputs || []).map(entry => ({
+        ...entry
+      })),
+      registers: (signature.registers || []).map(entry => ({
+        ...entry
+      })),
+      threadGroupSize: signature.threadGroupSize ? {
+        ...signature.threadGroupSize
+      } : null
+    }
+  });
+}
+
+/**
+ * Emit one HlslPass node.
+ *
+ * @param {object} pass Decoded technique pass.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted pass record.
+ */
+function emitPass(pass, classes) {
+  return build(classes, "Pass", {
+    shaderTypeMask: pass.shaderTypeMask,
+    stageInputs: pass.stageInputs.map((stageInput, stageType) => emitStageInput(stageInput, stageType, classes)),
+    renderStates: pass.cjsRenderStateSetup ? pass.cjsRenderStateSetup.toJSON() : []
+  });
+}
+
+/**
+ * Emit one HlslEffectTechnique node.
+ *
+ * @param {object} technique Decoded technique.
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted technique record.
+ */
+function emitTechnique(technique, classes) {
+  return build(classes, "Technique", {
+    name: technique.name,
+    shaderTypeMask: technique.shaderTypeMask,
+    passes: technique.passes.map(pass => emitPass(pass, classes)),
+    // Shader-library (v14+ ray tracing) metadata has no dedicated class
+    // key yet; emitted as plain, JSON-compatible data.
+    libraries: technique.libraries.map(library => library?.toJSON?.() ?? library)
+  });
+}
+
+/**
+ * Serializes a map of parameter names to annotation arrays as plain data.
+ *
+ * @param {Map<string, object[]>} annotations Annotation map.
+ * @returns {object[]} JSON-safe annotation groups.
+ */
+function emitAnnotations(annotations) {
+  return Array.from(annotations.entries(), ([name, entries]) => ({
+    name,
+    annotations: entries.map(entry => entry?.toJSON?.() ?? entry)
+  }));
+}
+
+/**
+ * Emit one HlslEffectDescription node: one resolved permutation's decoded
+ * techniques, passes, and stage metadata.
+ *
+ * @param {object} description Decoded effect description (`HlslShader.GetEffectDescription()`).
+ * @param {object} classes Opt-in node class map.
+ * @returns {object} Emitted effect-description record.
+ */
+function emitEffectDescription(description, classes) {
+  return build(classes, "EffectDescription", {
+    version: description.version,
+    effectName: description.effectName,
+    techniques: description.techniques.map(technique => emitTechnique(technique, classes)),
+    annotations: emitAnnotations(description.annotations),
+    readError: description.readError ? {
+      name: description.readError.name,
+      message: description.readError.message
+    } : null
+  });
+}
+
+/**
+ * Convert a loaded HlslEffectRes (and, when resolvable, its default- or
+ * selected-permutation HlslShader) into the documented plain JSON shape.
+ *
+ * @param {object} effect Loaded HlslEffectRes instance.
+ * @param {object|null} shader Resolved HlslShader for one permutation, or null.
+ * @param {object} [options] Emission options.
+ * @param {object} [options.classes] Opt-in node class map. See {@link CLASS_KEYS}.
+ * @returns {object} Plain JSON-compatible effect graph, or a populated
+ * `classes.Root` instance when provided.
+ */
+function emitEffectJson(effect, shader, options = {}) {
+  const {
+    classes = {}
+  } = options;
+  return build(classes, "Root", {
+    version: effect.m_version,
+    compilerVersion: effect.m_compilerVersion,
+    sourcePath: effect.sourcePath,
+    bodyCount: effect.m_offsetCount,
+    permutations: effect.m_permutations.map(permutation => emitPermutation(permutation, classes)),
+    effect: shader ? emitEffectDescription(shader.GetEffectDescription(), classes) : null,
+    loadError: effect.loadError ? {
+      name: effect.loadError.name,
+      message: effect.loadError.message
+    } : null
+  });
+}
+
+export { CLASS_KEYS, emitEffectJson };
+//# sourceMappingURL=json.js.map