@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

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

@@ -0,0 +1,133 @@
+/**
+ * Recognises Carbon's local-light resource family from reflection alone.
+ *
+ * Carbon puts local lights in two structured buffers plus an optional profile
+ * texture. On a backend with storage buffers this needs no attention at all —
+ * WebGPU binds them natively and loses nothing. WebGL 2 has no structured
+ * buffers, so the same two resources have to be re-expressed as data textures,
+ * and something has to say which registers they were.
+ *
+ * That "which registers" question is what this module answers, and it is
+ * backend-neutral for the same reason the detail-map recogniser is: it is a fact
+ * about Carbon's resources, not about a shading language. The registers are not
+ * fixed — one permutation binds the family at t11/t12/t13 and another at
+ * t13/t14/t15 — so this is name-driven and must stay that way.
+ *
+ * See docs/contracts/webgl2-texture-budget.md for why the two units matter.
+ */
+
+/** The structured buffers, both required for the family to be recognised. */
+const LIGHT_INDEX_BUFFER = "LightIndexBuffer";
+const LIGHT_DATA_BUFFER = "LightBuffer";
+
+/** The profile texture, which is optional. */
+const LIGHT_PROFILE_ARRAY = "LightProfileArray";
+
+/** Every resource name in the family, for callers that need to strip them. */
+const LOCAL_LIGHT_RESOURCE_NAMES = Object.freeze([LIGHT_INDEX_BUFFER, LIGHT_DATA_BUFFER, LIGHT_PROFILE_ARRAY]);
+
+/** Carbon's resource type code for a structured buffer, as `BoneTransforms` uses. */
+const CARBON_STRUCTURED_BUFFER = 7;
+
+/**
+ * Recognises the local-light family in one stage's reflected resources.
+ *
+ * Both structured buffers are required. The profile array is not: some
+ * permutations never sample it, and a lowering may substitute neutral
+ * attenuation for it. Returning a plan with `profileRegister: null` is a
+ * different statement from returning null, and callers depend on the difference.
+ *
+ * @param {Array<object>} resources Reflected resources, each carrying
+ *   `registerIndex`, `name` and `type`.
+ * @returns {object|null} Frozen plan, or null when the family is absent.
+ */
+function recogniseLocalLightFamily(resources) {
+  const byName = new Map();
+  for (const resource of resources ?? []) {
+    const value = resource?.toJSON?.() ?? resource;
+    const name = value?.name;
+    if (typeof name !== "string" || !LOCAL_LIGHT_RESOURCE_NAMES.includes(name)) continue;
+    if (byName.has(name)) return null;
+    byName.set(name, value);
+  }
+  const index = byName.get(LIGHT_INDEX_BUFFER);
+  const data = byName.get(LIGHT_DATA_BUFFER);
+  if (!index || !data) return null;
+
+  // Both must actually be structured buffers. A same-named 2D texture is not
+  // this family, and lowering it as though it were would misread every light.
+  if (index.type !== CARBON_STRUCTURED_BUFFER || data.type !== CARBON_STRUCTURED_BUFFER) {
+    return null;
+  }
+  if (!Number.isInteger(index.registerIndex) || !Number.isInteger(data.registerIndex)) {
+    return null;
+  }
+  const profile = byName.get(LIGHT_PROFILE_ARRAY);
+  return Object.freeze({
+    indexRegister: index.registerIndex,
+    dataRegister: data.registerIndex,
+    profileRegister: Number.isInteger(profile?.registerIndex) ? profile.registerIndex : null,
+    registers: Object.freeze([index.registerIndex, data.registerIndex, profile?.registerIndex].filter(register => Number.isInteger(register)).sort((a, b) => a - b))
+  });
+}
+
+/**
+ * Removes the local-light resource bindings from a binding manifest.
+ *
+ * Needed when the family is dropped rather than lowered: the emitter no longer
+ * declares those resources, and a consumer that still sees them in the manifest
+ * tries to build textures for resources the shader does not have.
+ *
+ * Mutates in place, matching the manifest's own conventions.
+ *
+ * @param {object} manifestJson Serialized binding manifest.
+ * @returns {object} The same manifest, light resource bindings removed.
+ */
+function stripLocalLightBindings(manifestJson) {
+  for (const stage of manifestJson?.stages ?? []) {
+    stage.bindings = (stage.bindings ?? []).filter(binding => {
+      if (binding?.kind !== "resource") return true;
+      const name = binding.metadataName || binding.carbon?.name;
+      return !LOCAL_LIGHT_RESOURCE_NAMES.includes(name);
+    });
+  }
+  return manifestJson;
+}
+
+/** Transform family recording a profile array replaced by a constant. */
+const LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY = "local-light-profile-neutral";
+
+/**
+ * Builds the resource transform recording that `LightProfileArray` was replaced
+ * by a constant one.
+ *
+ * A transform rather than a binding because nothing is bound: the resource is
+ * gone and its samples are a literal. What has to survive is the *statement*
+ * that it was dropped deliberately, since a described Carbon resource with no
+ * declaration and no record is exactly what the integrity rules treat as lost.
+ *
+ * The single input is the profile register itself. `detail-map-array` lists
+ * several inputs because it merges them into one output; this family has no
+ * output at all, so its input list names only the resource that went away.
+ *
+ * @param {object} plan Recognised local-light family.
+ * @param {string} layoutKey Enclosing pass key.
+ * @returns {object|null} Transform record, or null when there is no profile.
+ */
+function localLightProfileNeutralTransformFor(plan, layoutKey) {
+  if (!Number.isInteger(plan?.profileRegister)) return null;
+  const registerSpace = plan.registerSpace ?? 0;
+  return {
+    id: `${layoutKey}:${LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY}:sampled-resource:${registerSpace}:${plan.profileRegister}`,
+    family: LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY,
+    layoutKey,
+    inputs: [{
+      registerSpace,
+      registerIndex: plan.profileRegister,
+      parameter: LIGHT_PROFILE_ARRAY
+    }]
+  };
+}
+
+export { LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY, LOCAL_LIGHT_RESOURCE_NAMES, localLightProfileNeutralTransformFor, recogniseLocalLightFamily, stripLocalLightBindings };
+//# sourceMappingURL=localLightFamily.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localLightFamily.js","sources":["../../../../../src/formats/hlsl/core/localLightFamily.js"],"sourcesContent":["/**\n * Recognises Carbon's local-light resource family from reflection alone.\n *\n * Carbon puts local lights in two structured buffers plus an optional profile\n * texture. On a backend with storage buffers this needs no attention at all —\n * WebGPU binds them natively and loses nothing. WebGL 2 has no structured\n * buffers, so the same two resources have to be re-expressed as data textures,\n * and something has to say which registers they were.\n *\n * That \"which registers\" question is what this module answers, and it is\n * backend-neutral for the same reason the detail-map recogniser is: it is a fact\n * about Carbon's resources, not about a shading language. The registers are not\n * fixed — one permutation binds the family at t11/t12/t13 and another at\n * t13/t14/t15 — so this is name-driven and must stay that way.\n *\n * See docs/contracts/webgl2-texture-budget.md for why the two units matter.\n */\n\n/** The structured buffers, both required for the family to be recognised. */\nconst LIGHT_INDEX_BUFFER = \"LightIndexBuffer\";\nconst LIGHT_DATA_BUFFER = \"LightBuffer\";\n\n/** The profile texture, which is optional. */\nconst LIGHT_PROFILE_ARRAY = \"LightProfileArray\";\n\n/** Every resource name in the family, for callers that need to strip them. */\nexport const LOCAL_LIGHT_RESOURCE_NAMES = Object.freeze([\n    LIGHT_INDEX_BUFFER,\n    LIGHT_DATA_BUFFER,\n    LIGHT_PROFILE_ARRAY\n]);\n\n/** Carbon's resource type code for a structured buffer, as `BoneTransforms` uses. */\nconst CARBON_STRUCTURED_BUFFER = 7;\n\n/**\n * Recognises the local-light family in one stage's reflected resources.\n *\n * Both structured buffers are required. The profile array is not: some\n * permutations never sample it, and a lowering may substitute neutral\n * attenuation for it. Returning a plan with `profileRegister: null` is a\n * different statement from returning null, and callers depend on the difference.\n *\n * @param {Array<object>} resources Reflected resources, each carrying\n *   `registerIndex`, `name` and `type`.\n * @returns {object|null} Frozen plan, or null when the family is absent.\n */\nexport function recogniseLocalLightFamily(resources)\n{\n    const byName = new Map();\n\n    for (const resource of resources ?? [])\n    {\n        const value = resource?.toJSON?.() ?? resource;\n        const name = value?.name;\n        if (typeof name !== \"string\" || !LOCAL_LIGHT_RESOURCE_NAMES.includes(name)) continue;\n        if (byName.has(name)) return null;\n        byName.set(name, value);\n    }\n\n    const index = byName.get(LIGHT_INDEX_BUFFER);\n    const data = byName.get(LIGHT_DATA_BUFFER);\n    if (!index || !data) return null;\n\n    // Both must actually be structured buffers. A same-named 2D texture is not\n    // this family, and lowering it as though it were would misread every light.\n    if (index.type !== CARBON_STRUCTURED_BUFFER || data.type !== CARBON_STRUCTURED_BUFFER)\n    {\n        return null;\n    }\n    if (!Number.isInteger(index.registerIndex) || !Number.isInteger(data.registerIndex))\n    {\n        return null;\n    }\n\n    const profile = byName.get(LIGHT_PROFILE_ARRAY);\n\n    return Object.freeze({\n        indexRegister: index.registerIndex,\n        dataRegister: data.registerIndex,\n        profileRegister: Number.isInteger(profile?.registerIndex) ? profile.registerIndex : null,\n        registers: Object.freeze(\n            [ index.registerIndex, data.registerIndex, profile?.registerIndex ]\n                .filter((register) => Number.isInteger(register))\n                .sort((a, b) => a - b)\n        )\n    });\n}\n\n/**\n * Removes the local-light resource bindings from a binding manifest.\n *\n * Needed when the family is dropped rather than lowered: the emitter no longer\n * declares those resources, and a consumer that still sees them in the manifest\n * tries to build textures for resources the shader does not have.\n *\n * Mutates in place, matching the manifest's own conventions.\n *\n * @param {object} manifestJson Serialized binding manifest.\n * @returns {object} The same manifest, light resource bindings removed.\n */\nexport function stripLocalLightBindings(manifestJson)\n{\n    for (const stage of manifestJson?.stages ?? [])\n    {\n        stage.bindings = (stage.bindings ?? []).filter((binding) =>\n        {\n            if (binding?.kind !== \"resource\") return true;\n            const name = binding.metadataName || binding.carbon?.name;\n            return !LOCAL_LIGHT_RESOURCE_NAMES.includes(name);\n        });\n    }\n    return manifestJson;\n}\n\n/** Transform family recording a profile array replaced by a constant. */\nexport const LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY = \"local-light-profile-neutral\";\n\n/**\n * Builds the resource transform recording that `LightProfileArray` was replaced\n * by a constant one.\n *\n * A transform rather than a binding because nothing is bound: the resource is\n * gone and its samples are a literal. What has to survive is the *statement*\n * that it was dropped deliberately, since a described Carbon resource with no\n * declaration and no record is exactly what the integrity rules treat as lost.\n *\n * The single input is the profile register itself. `detail-map-array` lists\n * several inputs because it merges them into one output; this family has no\n * output at all, so its input list names only the resource that went away.\n *\n * @param {object} plan Recognised local-light family.\n * @param {string} layoutKey Enclosing pass key.\n * @returns {object|null} Transform record, or null when there is no profile.\n */\nexport function localLightProfileNeutralTransformFor(plan, layoutKey)\n{\n    if (!Number.isInteger(plan?.profileRegister)) return null;\n\n    const registerSpace = plan.registerSpace ?? 0;\n    return {\n        id: `${layoutKey}:${LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY}:sampled-resource:${registerSpace}:${plan.profileRegister}`,\n        family: LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY,\n        layoutKey,\n        inputs: [ {\n            registerSpace,\n            registerIndex: plan.profileRegister,\n            parameter: LIGHT_PROFILE_ARRAY\n        } ]\n    };\n}\n\nexport default recogniseLocalLightFamily;\n"],"names":["LIGHT_INDEX_BUFFER","LIGHT_DATA_BUFFER","LIGHT_PROFILE_ARRAY","LOCAL_LIGHT_RESOURCE_NAMES","Object","freeze","CARBON_STRUCTURED_BUFFER","recogniseLocalLightFamily","resources","byName","Map","resource","value","toJSON","name","includes","has","set","index","get","data","type","Number","isInteger","registerIndex","profile","indexRegister","dataRegister","profileRegister","registers","filter","register","sort","a","b","stripLocalLightBindings","manifestJson","stage","stages","bindings","binding","kind","metadataName","carbon","LOCAL_LIGHT_PROFILE_NEUTRAL_FAMILY","localLightProfileNeutralTransformFor","plan","layoutKey","registerSpace","id","family","inputs","parameter"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA,MAAMA,kBAAkB,GAAG,kBAAkB;AAC7C,MAAMC,iBAAiB,GAAG,aAAa;;AAEvC;AACA,MAAMC,mBAAmB,GAAG,mBAAmB;;AAE/C;AACO,MAAMC,0BAA0B,GAAGC,MAAM,CAACC,MAAM,CAAC,CACpDL,kBAAkB,EAClBC,iBAAiB,EACjBC,mBAAmB,CACtB;;AAED;AACA,MAAMI,wBAAwB,GAAG,CAAC;;AAElC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,yBAAyBA,CAACC,SAAS,EACnD;AACI,EAAA,MAAMC,MAAM,GAAG,IAAIC,GAAG,EAAE;AAExB,EAAA,KAAK,MAAMC,QAAQ,IAAIH,SAAS,IAAI,EAAE,EACtC;IACI,MAAMI,KAAK,GAAGD,QAAQ,EAAEE,MAAM,IAAI,IAAIF,QAAQ;AAC9C,IAAA,MAAMG,IAAI,GAAGF,KAAK,EAAEE,IAAI;AACxB,IAAA,IAAI,OAAOA,IAAI,KAAK,QAAQ,IAAI,CAACX,0BAA0B,CAACY,QAAQ,CAACD,IAAI,CAAC,EAAE;IAC5E,IAAIL,MAAM,CAACO,GAAG,CAACF,IAAI,CAAC,EAAE,OAAO,IAAI;AACjCL,IAAAA,MAAM,CAACQ,GAAG,CAACH,IAAI,EAAEF,KAAK,CAAC;AAC3B,EAAA;AAEA,EAAA,MAAMM,KAAK,GAAGT,MAAM,CAACU,GAAG,CAACnB,kBAAkB,CAAC;AAC5C,EAAA,MAAMoB,IAAI,GAAGX,MAAM,CAACU,GAAG,CAAClB,iBAAiB,CAAC;AAC1C,EAAA,IAAI,CAACiB,KAAK,IAAI,CAACE,IAAI,EAAE,OAAO,IAAI;;AAEhC;AACA;EACA,IAAIF,KAAK,CAACG,IAAI,KAAKf,wBAAwB,IAAIc,IAAI,CAACC,IAAI,KAAKf,wBAAwB,EACrF;AACI,IAAA,OAAO,IAAI;AACf,EAAA;AACA,EAAA,IAAI,CAACgB,MAAM,CAACC,SAAS,CAACL,KAAK,CAACM,aAAa,CAAC,IAAI,CAACF,MAAM,CAACC,SAAS,CAACH,IAAI,CAACI,aAAa,CAAC,EACnF;AACI,IAAA,OAAO,IAAI;AACf,EAAA;AAEA,EAAA,MAAMC,OAAO,GAAGhB,MAAM,CAACU,GAAG,CAACjB,mBAAmB,CAAC;EAE/C,OAAOE,MAAM,CAACC,MAAM,CAAC;IACjBqB,aAAa,EAAER,KAAK,CAACM,aAAa;IAClCG,YAAY,EAAEP,IAAI,CAACI,aAAa;AAChCI,IAAAA,eAAe,EAAEN,MAAM,CAACC,SAAS,CAACE,OAAO,EAAED,aAAa,CAAC,GAAGC,OAAO,CAACD,aAAa,GAAG,IAAI;AACxFK,IAAAA,SAAS,EAAEzB,MAAM,CAACC,MAAM,CACpB,CAAEa,KAAK,CAACM,aAAa,EAAEJ,IAAI,CAACI,aAAa,EAAEC,OAAO,EAAED,aAAa,CAAE,CAC9DM,MAAM,CAAEC,QAAQ,IAAKT,MAAM,CAACC,SAAS,CAACQ,QAAQ,CAAC,CAAC,CAChDC,IAAI,CAAC,CAACC,CAAC,EAAEC,CAAC,KAAKD,CAAC,GAAGC,CAAC,CAC7B;AACJ,GAAC,CAAC;AACN;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,uBAAuBA,CAACC,YAAY,EACpD;EACI,KAAK,MAAMC,KAAK,IAAID,YAAY,EAAEE,MAAM,IAAI,EAAE,EAC9C;AACID,IAAAA,KAAK,CAACE,QAAQ,GAAG,CAACF,KAAK,CAACE,QAAQ,IAAI,EAAE,EAAET,MAAM,CAAEU,OAAO,IACvD;AACI,MAAA,IAAIA,OAAO,EAAEC,IAAI,KAAK,UAAU,EAAE,OAAO,IAAI;MAC7C,MAAM3B,IAAI,GAAG0B,OAAO,CAACE,YAAY,IAAIF,OAAO,CAACG,MAAM,EAAE7B,IAAI;AACzD,MAAA,OAAO,CAACX,0BAA0B,CAACY,QAAQ,CAACD,IAAI,CAAC;AACrD,IAAA,CAAC,CAAC;AACN,EAAA;AACA,EAAA,OAAOsB,YAAY;AACvB;;AAEA;AACO,MAAMQ,kCAAkC,GAAG;;AAElD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,oCAAoCA,CAACC,IAAI,EAAEC,SAAS,EACpE;EACI,IAAI,CAACzB,MAAM,CAACC,SAAS,CAACuB,IAAI,EAAElB,eAAe,CAAC,EAAE,OAAO,IAAI;AAEzD,EAAA,MAAMoB,aAAa,GAAGF,IAAI,CAACE,aAAa,IAAI,CAAC;EAC7C,OAAO;IACHC,EAAE,EAAE,CAAA,EAAGF,SAAS,CAAA,CAAA,EAAIH,kCAAkC,CAAA,kBAAA,EAAqBI,aAAa,CAAA,CAAA,EAAIF,IAAI,CAAClB,eAAe,CAAA,CAAE;AAClHsB,IAAAA,MAAM,EAAEN,kCAAkC;IAC1CG,SAAS;AACTI,IAAAA,MAAM,EAAE,CAAE;MACNH,aAAa;MACbxB,aAAa,EAAEsB,IAAI,CAAClB,eAAe;AACnCwB,MAAAA,SAAS,EAAElD;KACd;GACJ;AACL;;;;"}