@carbonenginejs/runtime-trinity 0.6.0 → 0.7.0

package/dist/shader/Tr2Effect.js

@@ -6,7 +6,7 @@ import { Tr2ConstantEffectParameter as _Tr2ConstantEffectPar } from './parameter
 import { Tr2FloatParameter as _Tr2FloatParameter } from './parameter/Tr2FloatParameter.js';
 import { Tr2GeometryBufferParameter as _Tr2GeometryBufferPar } from './parameter/Tr2GeometryBufferParameter.js';
 import { Tr2Matrix4Parameter as _Tr2Matrix4Parameter } from './parameter/Tr2Matrix4Parameter.js';
-import { Tr2EffectConstant as _Tr2EffectConstant } from './reflection/Tr2EffectConstant.js';
+import { Tr2EffectConstant } from '@carbonenginejs/runtime-resource/resource/shader';
 import { Tr2ShaderOption as _Tr2ShaderOption } from './reflection/Tr2ShaderOption.js';
 import { Tr2SamplerOverride as _Tr2SamplerOverride } from './sampler/Tr2SamplerOverride.js';
 import { Tr2Vector2Parameter as _Tr2Vector2Parameter } from './parameter/Tr2Vector2Parameter.js';
@@ -87,6 +87,11 @@ new class extends _identity {
       this.RebuildCachedDataInternal();
       this.insideStartUpdate = wasInsideStartUpdate;
     }
+
+    /**
+     * Overrides the store this effect's TriVariableParameter values resolve
+     * against; passing null restores the fallback to the global store.
+     */
     SetVariableStore(store) {
       this.variableStore = store ?? null;
     }
@@ -95,6 +100,11 @@ new class extends _identity {
     GetVariableStore() {
       return this.variableStore ?? CjsVariableStore.GetGlobalStore();
     }
+
+    /**
+     * The authored constant-parameter list itself, not a copy - callers that
+     * mutate it mutate the effect.
+     */
     GetConstParameters() {
       return this.constParameters;
     }
@@ -193,6 +203,11 @@ new class extends _identity {
     StartUpdate() {
       this.insideStartUpdate = true;
     }
+
+    /**
+     * Attaches every resource to this material, derives actualEffectFilePath from
+     * the authored path, and rebuilds cached shader data.
+     */
     Initialize() {
       for (const resource of this.resources) {
         resource?.OnAddedToMaterial?.(this);
@@ -201,10 +216,18 @@ new class extends _identity {
       this.RebuildCachedDataInternal();
       return true;
     }
+
+    /** Re-runs Initialize after notified fields change; always returns true. */
     OnModified() {
       this.Initialize();
       return true;
     }
+
+    /**
+     * Keeps list membership consistent: a removed entry has its reroute
+     * destination cleared and is detached from the material, an inserted one is
+     * attached, and cached data is rebuilt either way.
+     */
     OnListModified(event, _key, _key2, value) {
       if (value?.SetDestination && String(event).includes("REMOVED")) {
         value.SetDestination(null, 0);
@@ -217,6 +240,13 @@ new class extends _identity {
       }
       this.RebuildCachedDataInternal();
     }
+
+    /**
+     * Re-resolves the shader for the current option set and re-binds every
+     * parameter and resource to it, rebuilding the screen-size LOD texture list on
+     * the way; a no-op while a StartUpdate batch is open. Resolves shader metadata
+     * only - no GPU program is created.
+     */
     RebuildCachedDataInternal() {
       if (this.insideStartUpdate) {
         return;
@@ -238,6 +268,11 @@ new class extends _identity {
         }
       }
     }
+
+    /**
+     * Drops the resolved shader and clears every parameter's and resource's effect
+     * handles by rebuilding them against null.
+     */
     ReleaseCachedData() {
       this.shader = null;
       for (const parameter of this.parameters) {
@@ -248,6 +283,11 @@ new class extends _identity {
       }
       this.lodTextureParameters = [];
     }
+
+    /**
+     * Sets the authored effect path through SetValues so the pipeline rebuild flag
+     * fires; returns whether anything changed.
+     */
     SetEffectPathName(path) {
       return this.SetValues({
         effectFilePath: path ? String(path) : ""
@@ -256,21 +296,43 @@ new class extends _identity {
         returnBoolean: true
       });
     }
+
+    /**
+     * The authored path, not the slash-normalized actualEffectFilePath that
+     * Initialize derives from it.
+     */
     GetEffectPathName() {
       return this.effectFilePath;
     }
+
+    /**
+     * The effect resource the shader is resolved from, or null before one has been
+     * assigned.
+     */
     GetEffectRes() {
       return this.effectResource;
     }
+
+    /** The authored effect name, which is independent of the effect file path. */
     GetName() {
       return this.name;
     }
+
+    /**
+     * Appends a resource parameter, attaches it to this material and rebuilds
+     * cached data; does not check for a duplicate name and always returns true.
+     */
     AddResource(parameter) {
       this.resources.push(parameter);
       parameter?.OnAddedToMaterial?.(this);
       this.RebuildCachedDataInternal();
       return true;
     }
+
+    /**
+     * Creates and attaches a TriTextureParameter for the name, returning false
+     * when a resource already uses that name.
+     */
     AddResourceTexture2D(name, resourcePath = "") {
       if (this.GetResourceByName(name)) {
         return false;
@@ -292,6 +354,12 @@ new class extends _identity {
       }
       return updated;
     }
+
+    /**
+     * Adds a sampler override for the named resource using Carbon's authoring
+     * defaults for the fields not passed in (addressW 1, filter 3, mipFilter 2);
+     * returns false when an override of that name already exists.
+     */
     AddSamplerOverride(name, addressU = 1, addressV = addressU) {
       if (this.HasSamplerOverride(name)) {
         return false;
@@ -307,6 +375,12 @@ new class extends _identity {
       this.RebuildCachedDataInternal();
       return true;
     }
+
+    /**
+     * Adds an authored constant parameter, cloning the value so the caller's
+     * vector is not aliased; returns false when a constant of that name already
+     * exists.
+     */
     AddParameterVector4(name, value = vec4.create()) {
       if (this.HasParameter(name)) {
         return false;
@@ -318,9 +392,19 @@ new class extends _identity {
       this.RebuildCachedDataInternal();
       return true;
     }
+
+    /**
+     * Adds a constant parameter with the scalar splatted across all four
+     * components, matching Carbon's float authoring.
+     */
     AddParameterFloat(name, value = 0) {
       return this.AddParameterVector4(name, vec4.fromValues(value, value, value, value));
     }
+
+    /**
+     * Adds a constant parameter from a colour vector; behaviourally identical to
+     * AddParameterVector4.
+     */
     AddParameterColor(name, value) {
       return this.AddParameterVector4(name, value);
     }
@@ -525,6 +609,12 @@ new class extends _identity {
       }
       return null;
     }
+
+    /**
+     * Removes the named entry from one of the effect's collections, detaching it
+     * from the material first when the list is `resources`; returns whether
+     * anything was removed.
+     */
     #removeNamed(list, name) {
       const existing = CjsParameter.findByName(list, name);
       if (!existing) {
@@ -536,6 +626,13 @@ new class extends _identity {
       list.splice(list.indexOf(existing), 1);
       return true;
     }
+
+    /**
+     * Assigns a dynamic parameter by name, reusing the existing model when its
+     * class claims the value and otherwise creating one and replacing the old
+     * entry; string values route to the texture resource list instead. Throws
+     * TypeError when no registered parameter class can represent the value.
+     */
     #setNamedParameter(name, value) {
       if (typeof value === "string") {
         return this.#setNamedTexture(name, value);
@@ -567,6 +664,12 @@ new class extends _identity {
       }
       return true;
     }
+
+    /**
+     * Points the named texture resource at a res path, creating and attaching a
+     * TriTextureParameter when absent; returns false when the path is already that
+     * value, and throws TypeError for non-string values.
+     */
     #setNamedTexture(name, value) {
       if (typeof value !== "string") {
         throw new TypeError(`Tr2Effect.SetTextures requires res path strings for "${name}".`);
@@ -590,12 +693,34 @@ new class extends _identity {
       parameter?.OnAddedToMaterial?.(this);
       return true;
     }
+
+    /**
+     * Resolves a descriptor's `Type`/`type`/`_type` field to a parameter
+     * constructor, directly or through the schema registry; returns null when no
+     * type field is present and throws TypeError for an unregistered class name.
+     */
+
+    /**
+     * Coerces a number (splatted to all four components), a four-number array, or
+     * a `{ value }` wrapper into a new vec4; returns null when no vec4 can be
+     * read.
+     */
+
+    /**
+     * Empties both the constant and dynamic parameter lists inside one
+     * StartUpdate/EndUpdate batch, so cached data rebuilds once at the end.
+     */
     ClearAllParameters() {
       this.StartUpdate();
       this.constParameters = [];
       this.parameters = [];
       this.EndUpdate();
     }
+
+    /**
+     * Detaches every resource from this material and empties the resource list,
+     * then rebuilds cached data.
+     */
     ClearAllResources() {
       for (const resource of this.resources) {
         resource?.OnRemovedFromMaterial?.(this);
@@ -603,6 +728,12 @@ new class extends _identity {
       this.resources = [];
       this.RebuildCachedDataInternal();
     }
+
+    /**
+     * Sets a shader option, adding it when absent; cached data is rebuilt only
+     * when the value actually changes, since options select the shader
+     * permutation.
+     */
     SetOption(name, value) {
       const existing = CjsParameter.findByName(this.options, name);
       if (existing) {
@@ -618,40 +749,83 @@ new class extends _identity {
       this.options.push(option);
       this.RebuildCachedDataInternal();
     }
+
+    /**
+     * Drops the named option so the shader resolves with its default permutation
+     * again.
+     */
     ResetOption(name) {
       this.options = this.options.filter(option => option?.name !== name);
       this.RebuildCachedDataInternal();
     }
+
+    /** The option's value, or the empty string when the option is not set. */
     GetOption(name) {
       return CjsParameter.findByName(this.options, name)?.value ?? "";
     }
+
+    /**
+     * Looks the name up in the dynamic parameters first, then the resources;
+     * authored constant parameters are not searched.
+     */
     GetParameterByName(name) {
       return this.FindParameterByName(name) ?? this.GetResourceByName(name);
     }
+
+    /**
+     * The dynamic parameter with this shader name, or null; resources and constant
+     * parameters are not consulted.
+     */
     FindParameterByName(name) {
       return this.parameters.find(parameter => CjsParameter.getNamedValue(parameter) === name) ?? null;
     }
+
+    /** The resource parameter with this shader name, or null. */
     GetResourceByName(name) {
       return this.resources.find(parameter => CjsParameter.getNamedValue(parameter) === name) ?? null;
     }
+
+    /** Whether a sampler override is authored for this resource name. */
     HasSamplerOverride(name) {
       return this.samplerOverrides.some(value => value?.name === name);
     }
+
+    /**
+     * Whether an authored constant parameter uses this name; dynamic parameters
+     * and resources do not count.
+     */
     HasParameter(name) {
       return this.constParameters.some(value => value?.name === name);
     }
+
+    /**
+     * Whether any collection - parameters, resources or constant parameters -
+     * already claims the name; the duplicate guard PopulateParameters uses.
+     */
     #hasParameterLike(name) {
       return !!(this.GetParameterByName(name) || this.HasParameter(name));
     }
+
+    /**
+     * Whether the resolved shader both marks the name SasUiVisible and exposes it
+     * as a constant or resource; the predicate PruneParameters filters on.
+     */
     #isShaderParameterVisible(name) {
       if (!name) {
         return false;
       }
       return _Tr2Effect.getBool(this.shader, name, "SasUiVisible", false) && !!(this.shader?.GetConstant?.(name) || this.shader?.GetResource?.(name));
     }
+
+    /** Normalizes an authored effect path's backslashes to forward slashes. */
     static convertEffectPath(path) {
       return String(path).replaceAll("\\", "/");
     }
+
+    /**
+     * Flattens a shader's technique/pass tree into a flat array of stage inputs,
+     * accepting either a GetEffectDescription accessor or a plain `effect` field.
+     */
     static iterateShaderStages(shader) {
       const stages = [];
       const desc = shader?.GetEffectDescription?.() ?? shader?.effect ?? null;
@@ -662,6 +836,11 @@ new class extends _identity {
       }
       return stages;
     }
+
+    /**
+     * Normalizes a stage's resource collection - Map, array of entries, or plain
+     * object - into a flat array of resource descriptions.
+     */
     static iterateResources(values) {
       if (!values) {
         return [];
@@ -674,6 +853,11 @@ new class extends _identity {
       }
       return Object.values(values);
     }
+
+    /**
+     * Reads a boolean shader annotation off a parameter, tolerating Map/array/object annotation containers and the several value field names reflection data uses.
+     * @returns {boolean} defaultValue when the annotation is absent
+     */
     static getBool(shader, parameterName, annotationName, defaultValue = false) {
       const annotations = shader?.GetParameterAnnotations?.(parameterName);
       const values = annotations instanceof Map ? [...annotations.values()] : Array.isArray(annotations) ? annotations : Object.values(annotations ?? {});
@@ -683,11 +867,19 @@ new class extends _identity {
       }
       return Boolean(annotation.boolValue ?? annotation.value ?? annotation.booleanValue ?? defaultValue);
     }
+
+    /**
+     * Builds the parameter model matching a reflected shader constant - float
+     * array, matrix, vector or scalar - seeded with the shader-authored defaults;
+     * a 16-component constant whose name contains `Reflection` becomes an
+     * EnvMapTransform variable parameter instead. Returns null for non-FLOAT
+     * constants, which Carbon does not surface as parameters.
+     */
     static convertEffectConstant(constant, constantValues) {
       // Carbon only populates parameters for FLOAT constants; INT/UINT/BOOL
       // constants are skipped. String types accepted for pre-enum reflection data.
       const constantType = constant?.type;
-      if (constantType !== undefined && constantType !== null && constantType !== _Tr2EffectConstant.Type.FLOAT && constantType !== "FLOAT") {
+      if (constantType !== undefined && constantType !== null && constantType !== Tr2EffectConstant.Type.FLOAT && constantType !== "FLOAT") {
         return null;
       }
       const name = constant.name ?? "";
@@ -741,6 +933,11 @@ new class extends _identity {
       parameter.value = _Tr2Effect.readScalar(constant, constantValues);
       return parameter;
     }
+
+    /**
+     * Builds a TriTextureParameter for texture resources and a
+     * Tr2GeometryBufferParameter for everything else.
+     */
     static convertEffectResource(resource) {
       if (_Tr2Effect.isTextureResource(resource)) {
         const parameter = new _TriTextureParameter();
@@ -751,6 +948,12 @@ new class extends _identity {
       parameter.name = resource.name ?? "";
       return parameter;
     }
+
+    /**
+     * Classifies a reflected resource as a texture: string types containing
+     * TEXTURE but not BUFFER, or numeric types 1..5 (TEXTURE_1D through
+     * TEXTURE_TYPELESS); buffer types start at 6.
+     */
     static isTextureResource(resource) {
       const type = resource?.type;
       if (typeof type === "string") {
@@ -760,6 +963,12 @@ new class extends _identity {
       // Carbon routes TYPELESS to TriTextureParameter too. Buffers start at 6.
       return Number(type) >= 1 && Number(type) <= 5;
     }
+
+    /**
+     * Reads a constant's shader-authored default scalar, preferring an inline
+     * value and otherwise a little-endian float32 at the constant's offset into
+     * the stage's constantValues; 0 when neither is available.
+     */
     static readScalar(constant, values) {
       if (typeof constant.value === "number") {
         return constant.value;
@@ -796,6 +1005,12 @@ new class extends _identity {
       }
       return out;
     }
+
+    /**
+     * Reads the shader-authored default vec4 for one element of a constant out of the stage's constantValues (16 bytes per element), or from the constant's inline value when it has one.
+     * @param element zero-based array element index; ignored when the constant carries an inline value
+     * @returns {vec4} a newly allocated vector; components outside the buffer stay 0
+     */
     static readVector4(constant, values, element) {
       if (constant.value && typeof constant.value.length === "number") {
         return vec4.fromValues(constant.value[0] ?? 0, constant.value[1] ?? 0, constant.value[2] ?? 0, constant.value[3] ?? 0);