@carbonenginejs/runtime-resource 0.12.2 → 0.13.0

package/docs/formats/dxbc/reference/decoded-output.md

@@ -1,122 +1,122 @@
-# Decoded output contract
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/dxbc` JSON output
-Audience: Shader-tool authors and lowering-backend authors
-Summary: Defines the stable top-level JSON fields and the decoder records consumed by shader-lowering packages.
-
-## Top-level result
-
-`CjsDxbcFormat.read(bytes)` returns:
-
-| Field | Meaning |
-| --- | --- |
-| `source` | Caller-provided diagnostic label. |
-| `container` | Container version, declared size, and chunk summaries. |
-| `program` | Shader stage, shader model, chunk tag, and token count, or `null`. |
-| `inputSignature` | Input signature elements, or `null`. |
-| `outputSignature` | Output signature elements, or `null`. |
-| `patchSignature` | Patch-constant signature elements, or `null`. |
-| `instructions` | Decoded instruction records, or `null` when disabled or absent. |
-
-`Inspect` returns a smaller record containing the container/chunk summary,
-stage name, shader model, and input/output element counts.
-
-## Container records
-
-The container summary includes `version`, `totalSize`, and ordered `chunks`.
-Each chunk record includes its four-character code, byte offset, and payload
-size. JSON output omits raw chunk bytes.
-
-## Program records
-
-Program metadata includes:
-
-- `fourCC`: `SHEX` or `SHDR`;
-- numeric and named program type;
-- major and minor shader-model version; and
-- declared program length in 32-bit words.
-
-Recognized program names are pixel, vertex, geometry, hull, domain, and
-compute. An unknown numeric type remains observable as `"unknown"`.
-
-## Signature elements
-
-Each signature element records its semantic name/index, system-value and
-component types, register index, masks, stream, and minimum-precision value
-when that signature layout provides one.
-
-The reader supports the SM4 and SM5 signature chunk layouts used by `ISGN`,
-`ISG1`, `OSGN`, `OSG1`, `OSG5`, `PCSG`, and `PSG1`.
-
-## Instruction records
-
-Each instruction begins with its source token offset, opcode number/name,
-declared length, and decoded control bits. Depending on the opcode, the record
-may also include:
-
-- destination and source operands with component selection and index records;
-- opcode and operand extensions;
-- declaration-specific fields;
-- resource dimensions and return types;
-- sampler, interpolation, precision, topology, or system-value metadata;
-- custom-data payloads; and
-- unprojected declaration words in `tailTokens`.
-
-Executable instructions reject leftover or missing operand words. Declaration
-records may preserve unfamiliar trailing payload words when their instruction
-framing is valid.
-
-### Compute shared memory and synchronization
-
-Compute thread-group shared-memory declarations expose their register and
-complete allocation shape:
-
-| Declaration | Fields |
-| --- | --- |
-| `dcl_thread_group_shared_memory_raw` | `registerIndex`, `byteCount` |
-| `dcl_thread_group_shared_memory_structured` | `registerIndex`, `structureStride`, `structureCount` |
-
-The declaration operand must identify one immediate thread-group shared-memory
-register. Byte counts and structure strides are positive and DWORD-aligned;
-structured element counts are positive. Any additional well-framed declaration
-words remain observable through `tailTokens`.
-
-The `sync` instruction exposes its numeric `syncFlags` mask and a canonical
-bit-order `syncFlagNames` array. The recognized names are
-`threads_in_group`, `thread_group_shared_memory`,
-`thread_group_uav_memory`, and `global_uav_memory`. These control bits are
-separate from arithmetic result controls, so `sync` never reports saturation.
-Unknown bits remain set in the numeric eight-bit mask even though they have no
-entry in the recognized-name array. Reserved operand and opcode-control bits
-are rejected rather than projected onto the canonical records.
-
-## Shader Model 5.1 bindings
-
-SM5.1 resource declarations may include `bindingRange`:
-
-| Field | Meaning |
-| --- | --- |
-| `rangeId` | Class-local binding-range identity. |
-| `lowerBound` / `upperBound` | Declared register bounds. |
-| `unbounded` | Whether the upper bound represents an unbounded range. |
-| `registerCount` | Finite range size, otherwise `null`. |
-| `registerSpace` | D3D register space. |
-
-Executable resource, sampler, UAV, and constant-buffer operands may include a
-`resourceReference` retaining the range identity, index records, and
-non-uniform flag. Range identity remains separate from the actual register
-index needed by an explicit-binding backend.
-
-SM5.0 declarations keep their direct-register shape.
-
-## JSON conversion
-
-Typed arrays become number arrays, arrays are converted recursively, maps
-become plain objects, sets become arrays, and objects with `toJSON` use that
-projection.
-
-## Related documentation
-
-- [Public API reference](api.md)
-- [Architecture and boundaries](../architecture.md)
+# Decoded output contract
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/dxbc` JSON output
+Audience: Shader-tool authors and lowering-backend authors
+Summary: Defines the stable top-level JSON fields and the decoder records consumed by shader-lowering packages.
+
+## Top-level result
+
+`CjsDxbcFormat.read(bytes)` returns:
+
+| Field | Meaning |
+| --- | --- |
+| `source` | Caller-provided diagnostic label. |
+| `container` | Container version, declared size, and chunk summaries. |
+| `program` | Shader stage, shader model, chunk tag, and token count, or `null`. |
+| `inputSignature` | Input signature elements, or `null`. |
+| `outputSignature` | Output signature elements, or `null`. |
+| `patchSignature` | Patch-constant signature elements, or `null`. |
+| `instructions` | Decoded instruction records, or `null` when disabled or absent. |
+
+`Inspect` returns a smaller record containing the container/chunk summary,
+stage name, shader model, and input/output element counts.
+
+## Container records
+
+The container summary includes `version`, `totalSize`, and ordered `chunks`.
+Each chunk record includes its four-character code, byte offset, and payload
+size. JSON output omits raw chunk bytes.
+
+## Program records
+
+Program metadata includes:
+
+- `fourCC`: `SHEX` or `SHDR`;
+- numeric and named program type;
+- major and minor shader-model version; and
+- declared program length in 32-bit words.
+
+Recognized program names are pixel, vertex, geometry, hull, domain, and
+compute. An unknown numeric type remains observable as `"unknown"`.
+
+## Signature elements
+
+Each signature element records its semantic name/index, system-value and
+component types, register index, masks, stream, and minimum-precision value
+when that signature layout provides one.
+
+The reader supports the SM4 and SM5 signature chunk layouts used by `ISGN`,
+`ISG1`, `OSGN`, `OSG1`, `OSG5`, `PCSG`, and `PSG1`.
+
+## Instruction records
+
+Each instruction begins with its source token offset, opcode number/name,
+declared length, and decoded control bits. Depending on the opcode, the record
+may also include:
+
+- destination and source operands with component selection and index records;
+- opcode and operand extensions;
+- declaration-specific fields;
+- resource dimensions and return types;
+- sampler, interpolation, precision, topology, or system-value metadata;
+- custom-data payloads; and
+- unprojected declaration words in `tailTokens`.
+
+Executable instructions reject leftover or missing operand words. Declaration
+records may preserve unfamiliar trailing payload words when their instruction
+framing is valid.
+
+### Compute shared memory and synchronization
+
+Compute thread-group shared-memory declarations expose their register and
+complete allocation shape:
+
+| Declaration | Fields |
+| --- | --- |
+| `dcl_thread_group_shared_memory_raw` | `registerIndex`, `byteCount` |
+| `dcl_thread_group_shared_memory_structured` | `registerIndex`, `structureStride`, `structureCount` |
+
+The declaration operand must identify one immediate thread-group shared-memory
+register. Byte counts and structure strides are positive and DWORD-aligned;
+structured element counts are positive. Any additional well-framed declaration
+words remain observable through `tailTokens`.
+
+The `sync` instruction exposes its numeric `syncFlags` mask and a canonical
+bit-order `syncFlagNames` array. The recognized names are
+`threads_in_group`, `thread_group_shared_memory`,
+`thread_group_uav_memory`, and `global_uav_memory`. These control bits are
+separate from arithmetic result controls, so `sync` never reports saturation.
+Unknown bits remain set in the numeric eight-bit mask even though they have no
+entry in the recognized-name array. Reserved operand and opcode-control bits
+are rejected rather than projected onto the canonical records.
+
+## Shader Model 5.1 bindings
+
+SM5.1 resource declarations may include `bindingRange`:
+
+| Field | Meaning |
+| --- | --- |
+| `rangeId` | Class-local binding-range identity. |
+| `lowerBound` / `upperBound` | Declared register bounds. |
+| `unbounded` | Whether the upper bound represents an unbounded range. |
+| `registerCount` | Finite range size, otherwise `null`. |
+| `registerSpace` | D3D register space. |
+
+Executable resource, sampler, UAV, and constant-buffer operands may include a
+`resourceReference` retaining the range identity, index records, and
+non-uniform flag. Range identity remains separate from the actual register
+index needed by an explicit-binding backend.
+
+SM5.0 declarations keep their direct-register shape.
+
+## JSON conversion
+
+Typed arrays become number arrays, arrays are converted recursively, maps
+become plain objects, sets become arrays, and objects with `toJSON` use that
+projection.
+
+## Related documentation
+
+- [Public API reference](api.md)
+- [Architecture and boundaries](../architecture.md)

package/docs/formats/gr2.md

@@ -1,160 +1,160 @@
-# Granny GR2 and GSF
-
-Status: Evolving  
-Scope: `@carbonenginejs/runtime-resource/formats/gr2`  
-Audience: Users and integrators  
-Summary: Defines the pure-JavaScript GR2/GSF reader, its output modes, conversion options, graph shape, and class-hydration boundary.
-
-## Purpose
-
-`CjsGr2Format` reads Granny 3D `.gr2` geometry, skeleton, animation, and
-morph-target data, plus Granny State `.gsf` profiles. It runs in Node and the
-browser without `granny2.dll`, native addons, a GPU, or private assets.
-
-The reader owns Granny container parsing, reflected type-tree walking, section
-decompression, JSON projection, optional curve and vertex-channel conversion,
-GSF projection, and caller-class hydration. Resource caching and publication
-remain with `CjsResMan`; GPU realization remains with engine packages.
-
-Supported section compression is None, Oodle1, and the in-project clean-room
-BitKnit2 decoder. Licensing and migration history are recorded in
-[format provenance](provenance.md).
-
-## Import and basic use
-
-Import the runtime-resource wrapper from its explicit format subpath:
-
-```js
-import { CjsGr2Format } from "@carbonenginejs/runtime-resource/formats/gr2";
-
-const graph = CjsGr2Format.read(bytes);
-const summary = CjsGr2Format.inspect(bytes);
-const asynchronousGraph = await CjsGr2Format.readAsync(bytes);
-```
-
-`CjsGr2Format` is the one public class: the reader engine plus the normal
-runtime-resource format metadata and the `isSupported(bytes)` magic probe.
-The barrel exports nothing else.
-
-Register it with `CjsResMan` when GR2/GSF should participate in ordinary
-resource loading:
-
-```js
-import { CjsResMan } from "@carbonenginejs/runtime-resource";
-import { CjsGr2Format } from "@carbonenginejs/runtime-resource/formats/gr2";
-
-const resMan = new CjsResMan().Register({
-  source,
-  formats: [ CjsGr2Format ]
-});
-
-const resource = resMan.GetResource("res:/model/ship.gr2");
-const graph = await resource.Ready();
-```
-
-Concrete formats are not imported or registered by the package root.
-
-## Output modes
-
-`emit` selects the representation:
-
-| Value | Result |
-|---|---|
-| `"json"` | Default stable GR2 graph with plain objects |
-| `"gr2Json"` | Explicit alias for the JSON graph |
-| `"gr2"` | GR2 graph hydrated with caller-supplied classes |
-| `"cmf"` | CMF-shaped graph hydrated with caller-supplied classes |
-| `"raw"` | Low-level reflected `granny_file_info` result |
-
-`"gr2"` and `"cmf"` require a non-empty `classes` map. Classes may also be
-supplied with `"json"`/`"gr2Json"` to hydrate selected JSON nodes while
-leaving omitted nodes as plain objects.
-
-## Conversion options
-
-| Option | Default | Effect |
-|---|---:|---|
-| `decompressCurves` | `false` | Adds decoded `knots`, `controls`, and `dimension` to supported compressed animation curves while retaining the raw curve fields |
-| `unpackTangents` | `false` | Converts packed CCP tangent frames into separate normal, tangent, and binormal channels |
-| `rebuildMissingNormals` | `false` | Generates absent normals from positions and triangle indices |
-| `rebuildMissingTangents` | `false` | Generates absent tangents from positions, normals, UVs, and triangle indices |
-| `rebuildMissingBiNormals` | `false` | Generates absent binormals from normals and tangents |
-| `classes` | `{}` | Maps supported graph node keys to constructors |
-
-Tangent unpacking and missing-channel rebuild options may be functions when a
-caller needs per-mesh policy. Rebuild options fill absent data; they do not
-repair authored channels that are present but incorrect.
-
-A reusable reader profile can hold these defaults:
-
-```js
-const reader = new CjsGr2Format({
-  decompressCurves: true,
-  unpackTangents: true
-});
-
-const first = reader.Read(firstBytes);
-const second = reader.Read(secondBytes);
-```
-
-## JSON graph and hydration
-
-The default graph has this general shape:
-
-```text
-Root
-|-- grannyFileFormatRevision, grannyFileSource
-|-- meshes
-|   |-- boneBindings, morphTargets
-|   |-- vertex: flat numeric channels
-|   `-- indices: triangle index groups
-|-- models
-|   `-- skeleton -> bones
-`-- animations
-    `-- trackGroups -> transformTracks -> curves
-```
-
-Vertex channels include positions, normals, tangents, binormals, UVs, blend
-indices, and blend weights when available. `IndexGroup.faces` is a flat array
-of triangle indices. Sparse morph targets carry `vertexIndices`; native and
-annotation-set morph targets share the same projected shape.
-
-For each registered class key, hydration constructs the class without
-arguments and calls:
-
-```js
-new Class().SetValues(nodeFields);
-```
-
-Constructors must therefore support zero-argument construction and
-`SetValues(values)`. Supported GR2 and CMF keys are exposed through
-`CjsGr2Format.CLASS_KEYS`; use `SetClass`, `SetClasses`, `GetClass`, and
-`HasClass` on reusable reader instances.
-
-`ToJSON(value)` and static `toJSON(value)` convert hydrated output into a
-JSON-compatible value. They do not write a binary `.gr2` file or return JSON
-text.
-
-## Granny State
-
-GSF uses the ordinary Granny container with a GState root schema. The reader
-provides dedicated classification, projection, and inspection:
-
-```js
-if (CjsGr2Format.isGsf(bytes)) {
-  const state = CjsGr2Format.readGsf(bytes);
-  const dependencies = CjsGr2Format.inspectGsf(bytes);
-}
-```
-
-The stable GSF projection contains container revision data, model and
-retarget hints, the state machine, animation slots and sets, referenced
-relative `.gr2` files, token count, editor data, and extended data.
-`readGsfAsync` provides the equivalent promise-facing entry point.
-
-## Related documentation
-
-- [Format subpaths](README.md)
-- [Architecture and boundaries](../architecture.md)
-- [Resource lifecycle](../concepts/resource-lifecycle.md)
-- [Format ownership and provenance](provenance.md)
+# Granny GR2 and GSF
+
+Status: Evolving  
+Scope: `@carbonenginejs/runtime-resource/formats/gr2`  
+Audience: Users and integrators  
+Summary: Defines the pure-JavaScript GR2/GSF reader, its output modes, conversion options, graph shape, and class-hydration boundary.
+
+## Purpose
+
+`CjsGr2Format` reads Granny 3D `.gr2` geometry, skeleton, animation, and
+morph-target data, plus Granny State `.gsf` profiles. It runs in Node and the
+browser without `granny2.dll`, native addons, a GPU, or private assets.
+
+The reader owns Granny container parsing, reflected type-tree walking, section
+decompression, JSON projection, optional curve and vertex-channel conversion,
+GSF projection, and caller-class hydration. Resource caching and publication
+remain with `CjsResMan`; GPU realization remains with engine packages.
+
+Supported section compression is None, Oodle1, and the in-project clean-room
+BitKnit2 decoder. Licensing and migration history are recorded in
+[format provenance](provenance.md).
+
+## Import and basic use
+
+Import the runtime-resource wrapper from its explicit format subpath:
+
+```js
+import { CjsGr2Format } from "@carbonenginejs/runtime-resource/formats/gr2";
+
+const graph = CjsGr2Format.read(bytes);
+const summary = CjsGr2Format.inspect(bytes);
+const asynchronousGraph = await CjsGr2Format.readAsync(bytes);
+```
+
+`CjsGr2Format` is the one public class: the reader engine plus the normal
+runtime-resource format metadata and the `isSupported(bytes)` magic probe.
+The barrel exports nothing else.
+
+Register it with `CjsResMan` when GR2/GSF should participate in ordinary
+resource loading:
+
+```js
+import { CjsResMan } from "@carbonenginejs/runtime-resource";
+import { CjsGr2Format } from "@carbonenginejs/runtime-resource/formats/gr2";
+
+const resMan = new CjsResMan().Register({
+  source,
+  formats: [ CjsGr2Format ]
+});
+
+const resource = resMan.GetResource("res:/model/ship.gr2");
+const graph = await resource.Ready();
+```
+
+Concrete formats are not imported or registered by the package root.
+
+## Output modes
+
+`emit` selects the representation:
+
+| Value | Result |
+|---|---|
+| `"json"` | Default stable GR2 graph with plain objects |
+| `"gr2Json"` | Explicit alias for the JSON graph |
+| `"gr2"` | GR2 graph hydrated with caller-supplied classes |
+| `"cmf"` | CMF-shaped graph hydrated with caller-supplied classes |
+| `"raw"` | Low-level reflected `granny_file_info` result |
+
+`"gr2"` and `"cmf"` require a non-empty `classes` map. Classes may also be
+supplied with `"json"`/`"gr2Json"` to hydrate selected JSON nodes while
+leaving omitted nodes as plain objects.
+
+## Conversion options
+
+| Option | Default | Effect |
+|---|---:|---|
+| `decompressCurves` | `false` | Adds decoded `knots`, `controls`, and `dimension` to supported compressed animation curves while retaining the raw curve fields |
+| `unpackTangents` | `false` | Converts packed CCP tangent frames into separate normal, tangent, and binormal channels |
+| `rebuildMissingNormals` | `false` | Generates absent normals from positions and triangle indices |
+| `rebuildMissingTangents` | `false` | Generates absent tangents from positions, normals, UVs, and triangle indices |
+| `rebuildMissingBiNormals` | `false` | Generates absent binormals from normals and tangents |
+| `classes` | `{}` | Maps supported graph node keys to constructors |
+
+Tangent unpacking and missing-channel rebuild options may be functions when a
+caller needs per-mesh policy. Rebuild options fill absent data; they do not
+repair authored channels that are present but incorrect.
+
+A reusable reader profile can hold these defaults:
+
+```js
+const reader = new CjsGr2Format({
+  decompressCurves: true,
+  unpackTangents: true
+});
+
+const first = reader.Read(firstBytes);
+const second = reader.Read(secondBytes);
+```
+
+## JSON graph and hydration
+
+The default graph has this general shape:
+
+```text
+Root
+|-- grannyFileFormatRevision, grannyFileSource
+|-- meshes
+|   |-- boneBindings, morphTargets
+|   |-- vertex: flat numeric channels
+|   `-- indices: triangle index groups
+|-- models
+|   `-- skeleton -> bones
+`-- animations
+    `-- trackGroups -> transformTracks -> curves
+```
+
+Vertex channels include positions, normals, tangents, binormals, UVs, blend
+indices, and blend weights when available. `IndexGroup.faces` is a flat array
+of triangle indices. Sparse morph targets carry `vertexIndices`; native and
+annotation-set morph targets share the same projected shape.
+
+For each registered class key, hydration constructs the class without
+arguments and calls:
+
+```js
+new Class().SetValues(nodeFields);
+```
+
+Constructors must therefore support zero-argument construction and
+`SetValues(values)`. Supported GR2 and CMF keys are exposed through
+`CjsGr2Format.CLASS_KEYS`; use `SetClass`, `SetClasses`, `GetClass`, and
+`HasClass` on reusable reader instances.
+
+`ToJSON(value)` and static `toJSON(value)` convert hydrated output into a
+JSON-compatible value. They do not write a binary `.gr2` file or return JSON
+text.
+
+## Granny State
+
+GSF uses the ordinary Granny container with a GState root schema. The reader
+provides dedicated classification, projection, and inspection:
+
+```js
+if (CjsGr2Format.isGsf(bytes)) {
+  const state = CjsGr2Format.readGsf(bytes);
+  const dependencies = CjsGr2Format.inspectGsf(bytes);
+}
+```
+
+The stable GSF projection contains container revision data, model and
+retarget hints, the state machine, animation slots and sets, referenced
+relative `.gr2` files, token count, editor data, and extended data.
+`readGsfAsync` provides the equivalent promise-facing entry point.
+
+## Related documentation
+
+- [Format subpaths](README.md)
+- [Architecture and boundaries](../architecture.md)
+- [Resource lifecycle](../concepts/resource-lifecycle.md)
+- [Format ownership and provenance](provenance.md)