@carbonenginejs/runtime-resource 0.11.0 → 0.12.0

package/docs/formats/hlsl/guides/reading-effects.md

@@ -0,0 +1,64 @@
+# Reading effects
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` read workflows
+Audience: Users and integrators
+Summary: Shows browser-neutral byte reads, permutation selection, inspection, and Node file workflows.
+
+## Read caller-provided bytes
+
+```js
+import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const response = await fetch("/shaders/effect.sm_hi");
+const bytes = new Uint8Array(await response.arrayBuffer());
+const effect = CjsHlslFormat.read(bytes);
+```
+
+Use `inspect` when only header and technique summary information is needed:
+
+```js
+const summary = CjsHlslFormat.inspect(bytes, {
+    source: "effect.sm_hi"
+});
+```
+
+## Select a permutation
+
+Without a `permutation` option, the reader applies the container's default
+selection rules. Override individual axes by name and value:
+
+```js
+const effect = CjsHlslFormat.read(bytes, {
+    permutation: [
+        { name: "BLEND_MODE", value: "TRANSPARENT" }
+    ]
+});
+```
+
+A `Map` of names to values is also accepted. Unknown axes or invalid values
+are rejected rather than silently ignored.
+
+## Read compact metadata
+
+```js
+const metadata = CjsHlslFormat.read(bytes, {
+    emit: CjsHlslFormat.OUTPUT_METADATA
+});
+```
+
+Metadata output omits embedded bytecode and constant-value bytes. It retains
+the selected options, techniques, passes, stage resources, signatures, and
+render-state records needed for inspection and pipeline planning.
+
+## Read a file in Node
+
+```js
+const effect = await CjsHlslFormat.readFile("effect.sm_hi");
+```
+
+The CLI provides the same metadata workflow:
+
+```sh
+format-hlsl metadata effect.sm_hi effect.json
+```

package/docs/formats/hlsl/reference/advanced-analysis.md

@@ -0,0 +1,66 @@
+# Advanced analysis exports
+
+Status: Experimental
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` advanced named exports
+Audience: Translation-tool authors and maintainers
+Summary: Documents unstable helpers for raw graph analysis and binding-manifest construction.
+
+## Stability
+
+These exports support translation and inspection tooling that needs internal
+effect-model objects. Their shapes may change without a major version bump.
+Use `CjsHlslFormat.read(..., { emit: "json" })` or `"metadata"` for the
+supported data contracts.
+
+## `readEffectAnalysis`
+
+```js
+import { readEffectAnalysis } from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const analysis = readEffectAnalysis(bytes, {
+    source: "effect.sm_hi",
+    permutation: [
+        { name: "BLEND_MODE", value: "TRANSPARENT" }
+    ]
+});
+```
+
+The result contains the loaded effect resource, resolved shader, selected
+option and body-index data, effect description, and a binding manifest when
+an effect description is available.
+
+The returned internal parser-DTO effect resource also has
+`GetShaderByIndex(index)`. It decodes one exact permutation-table slot without
+applying global or local option overrides; it is distinct from the canonical
+runtime-resource method that hydrates and caches `Tr2Shader`. Use the versioned
+portable subpath when the result must cross a package or serialization
+boundary. Its `enumerateUniqueEffectBodies(effectRes)` helper inventories
+first-seen raw body identities without populating the parser's mutable shader
+cache.
+
+## `Tr2EffectBindingManifest`
+
+`Tr2EffectBindingManifest` is an exported advanced class that derives
+register-named constant, resource, sampler, and UAV bindings from an internal
+effect description.
+
+```js
+import {
+    readEffectAnalysis,
+    Tr2EffectBindingManifest
+} from "@carbonenginejs/runtime-resource/formats/hlsl";
+
+const analysis = readEffectAnalysis(bytes);
+analysis.bindingManifest instanceof Tr2EffectBindingManifest;
+```
+
+## Render-context helpers
+
+`Tr2RenderContextEnum` contains the format's stage and render-context numeric
+constants. `tr2ShaderStageName(value)` maps a known stage value to its
+readable name. Both are advanced compatibility helpers rather than a stable
+cross-package enumeration contract.
+
+## Related documentation
+
+- [Portable body reflection](portable-reflection.md)

package/docs/formats/hlsl/reference/api.md

@@ -0,0 +1,97 @@
+# API reference
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` supported reader API
+Audience: Users and integrators
+Summary: Documents the reader class, options, output modes, and Node adapters.
+
+## Imports
+
+The package root exports `CjsHlslFormat` as both the default and a named
+export:
+
+```js
+import CjsHlslFormat from "@carbonenginejs/runtime-resource/formats/hlsl";
+import { CjsHlslFormat as NamedReader } from "@carbonenginejs/runtime-resource/formats/hlsl";
+```
+
+Additional named exports intended for advanced tooling are documented
+separately in [advanced-analysis.md](advanced-analysis.md).
+
+The versioned `@carbonenginejs/runtime-resource/formats/hlsl/portable` subpath exposes exact
+version-15 body-index reflection plus first-seen exact-byte unique-body
+enumeration for backend packagers. See
+[portable-reflection.md](portable-reflection.md).
+
+## Constructor
+
+```js
+const reader = new CjsHlslFormat({
+    emit: "json",
+    source: "effect.sm_hi",
+    permutation: null,
+    classes: {}
+});
+```
+
+Options are reusable on an instance and can be overridden per call:
+
+- `emit`: `"json"` (default), `"metadata"`, or advanced `"raw"` output.
+- `source`: a caller-supplied label used in diagnostics and output.
+- `permutation`: a `Map` or an array of `{ name, value }` selections.
+- `classes`: constructors used for caller-selected JSON-node projection; this
+  is not canonical runtime shader hydration.
+
+## Instance methods
+
+- `SetValues(options)` updates the reusable profile and returns the reader.
+- `GetValues(options)` returns effective values with optional overrides.
+- `SetClasses(classes)` and `SetClass(type, Class)` configure hydration.
+- `GetClass(type)` and `HasClass(type)` inspect hydration registrations.
+- `Read(input, options)` parses input and emits the configured graph.
+- `Inspect(input, options)` returns header and technique summary data.
+- `ToJSON(value)` converts reader output to JSON-compatible data.
+
+## Static methods
+
+- `CjsHlslFormat.isSupported(input)` performs a header-level support check.
+- `CjsHlslFormat.read(input, options)` performs a one-shot read.
+- `CjsHlslFormat.inspect(input, options)` performs a one-shot inspection.
+- `CjsHlslFormat.toJSON(value)` converts output to JSON-compatible data.
+- `CjsHlslFormat.readFile(path, options)` reads and parses a file in Node.
+
+Inputs may be `Uint8Array`, `ArrayBuffer`, `Buffer`, or `DataView` values.
+Supported container versions are 8 through 15.
+
+## Constants
+
+The class exposes `OUTPUT_JSON`, `OUTPUT_METADATA`, `OUTPUT_RAW`,
+`CLASS_KEYS`, `type`, `mediaTypes`, `inputTypes`, `outputTypes`, and
+`debugOutputTypes`. `inputTypes` contains `sm_hi`, `sm_lo`, and `sm_depth`.
+
+## Output stability
+
+The `json` and `metadata` modes are the supported data contracts described in
+[json-graph.md](json-graph.md). `raw` returns internal parser-DTO
+`Tr2EffectRes` objects, not the canonical runtime-resource class, and may
+change without a major version bump.
+
+## CLI
+
+The package installs a Node CLI that writes metadata JSON:
+
+```sh
+format-hlsl metadata effect.sm_hi
+format-hlsl metadata effect.sm_hi effect.json
+```
+
+When the output path is omitted, the CLI writes `<input-name>.json` in the
+current working directory.
+
+## Related documentation
+
+- [Reading effects](../guides/reading-effects.md)
+- [Hydrating JSON output](../guides/hydrating-json-output.md)
+- [Advanced analysis exports](advanced-analysis.md)
+- [Portable body reflection](portable-reflection.md)
+- [Class catalog](classes/README.md)

package/docs/formats/hlsl/reference/classes/README.md

@@ -0,0 +1,16 @@
+# Class catalog
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` maintained classes
+Audience: Users, maintainers, and automated readers
+Summary: Indexes the one-sentence purpose descriptors for every maintained class in the package.
+
+## Catalog pages
+
+- [Public API classes](public-api.md)
+- [Carbon compatibility classes](carbon-compatibility.md)
+- [Tr2 effect-model classes](tr2-effect-model.md)
+
+Public availability and stability are separate concerns. In particular,
+`Tr2EffectBindingManifest` is exported for advanced tooling but remains an
+experimental surface.

package/docs/formats/hlsl/reference/classes/carbon-compatibility.md

@@ -0,0 +1,66 @@
+# Carbon compatibility classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` package-local compatibility classes
+Audience: Maintainers and automated readers
+Summary: Describes internal utilities and Carbon-shaped compatibility records used by the reader.
+
+<!-- class:CjsBinaryReader -->
+## `CjsBinaryReader`
+
+Little-endian binary reader for Carbon/Trinity compiled effect data.
+
+- Export: None
+- Source: `src/carbon/cjs/CjsBinaryReader.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:CjsEffectReadError -->
+## `CjsEffectReadError`
+
+Error raised when a Carbon/Trinity effect payload cannot be decoded safely.
+
+- Export: None
+- Source: `src/carbon/cjs/CjsEffectReadError.js`
+- Visibility: Internal
+- Kind: Internal implementation
+
+<!-- class:CjsEffectStateManager -->
+## `CjsEffectStateManager`
+
+In-memory JavaScript substitute for Carbon's effect state manager registry.
+
+- Export: None
+- Source: `src/carbon/cjs/CjsEffectStateManager.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsRenderStateSetup -->
+## `CjsRenderStateSetup`
+
+JavaScript mirror of a registered Carbon render-state setup.
+
+- Export: None
+- Source: `src/carbon/cjs/CjsRenderStateSetup.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsResourceSetDescription -->
+## `CjsResourceSetDescription`
+
+JavaScript mirror of Carbon's resource-set descriptor builder.
+
+- Export: None
+- Source: `src/carbon/cjs/CjsResourceSetDescription.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:CjsShaderBytecode -->
+## `CjsShaderBytecode`
+
+JavaScript stand-in for Carbon's shader-bytecode handle payload.
+
+- Export: None
+- Source: `src/carbon/cjs/CjsShaderBytecode.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept

package/docs/formats/hlsl/reference/classes/public-api.md

@@ -0,0 +1,26 @@
+# Public API classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` package-root classes
+Audience: Users, maintainers, and automated readers
+Summary: Describes the supported reader class and the advanced exported binding-manifest class.
+
+<!-- class:CjsHlslFormat -->
+## `CjsHlslFormat`
+
+CarbonEngineJS-facing reader for CCP's Tr2 compiled effect container format (`.sm_hi` / `.sm_lo` / `.sm_depth` bodies).
+
+- Export: `@carbonenginejs/runtime-resource/formats/hlsl`
+- Source: `src/CjsHlslFormat.js`
+- Visibility: Public
+- Kind: CarbonEngineJS
+
+<!-- class:Tr2EffectBindingManifest -->
+## `Tr2EffectBindingManifest`
+
+Carbon-backed binding manifest for register-named shader outputs.
+
+- Export: `@carbonenginejs/runtime-resource/formats/hlsl`
+- Source: `src/core/tr2/shader/Tr2EffectBindingManifest.js`
+- Visibility: Public
+- Kind: Adapted Carbon concept

package/docs/formats/hlsl/reference/classes/tr2-effect-model.md

@@ -0,0 +1,150 @@
+# Tr2 effect-model classes
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` internal Tr2 graph
+Audience: Maintainers and automated readers
+Summary: Describes internal parser DTOs for resource, permutation, effect, pass, and stage metadata; these are not canonical runtime-resource classes.
+
+Every same-named `Tr2*` entry in this catalog is package-internal binary parser
+state. Canonical device-free runtime `Tr2EffectRes`, `Tr2Shader`, and reflection
+identity belong to `@carbonenginejs/runtime-resource`.
+
+<!-- class:Tr2EffectRes -->
+## `Tr2EffectRes`
+
+Carbon/Trinity effect resource reader for compiled shader metadata.
+
+- Export: None
+- Source: `src/core/tr2/resources/Tr2EffectRes.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2ShaderPermutation -->
+## `Tr2ShaderPermutation`
+
+Trinity shader permutation axis and option metadata.
+
+- Export: None
+- Source: `src/core/tr2/resources/Tr2ShaderPermutation.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectConstant -->
+## `Tr2EffectConstant`
+
+Constant-buffer parameter metadata read from a Trinity effect body.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectConstant.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectDescription -->
+## `Tr2EffectDescription`
+
+Trinity effect-description body decoded from one compiled permutation record.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectDescription.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectLibrary -->
+## `Tr2EffectLibrary`
+
+Ray-tracing shader library metadata from v14+ Trinity effects.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectLibrary.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectParameterAnnotation -->
+## `Tr2EffectParameterAnnotation`
+
+Parameter annotation value attached to a Trinity effect parameter.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectParameterAnnotation.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectResource -->
+## `Tr2EffectResource`
+
+Shader resource or UAV metadata read from a Trinity effect body.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectResource.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectStageInput -->
+## `Tr2EffectStageInput`
+
+Decoded per-stage input metadata for constants, resources, samplers, and signatures.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectStageInput.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2EffectTechnique -->
+## `Tr2EffectTechnique`
+
+Trinity effect technique containing passes and optional shader libraries.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2EffectTechnique.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2Pass -->
+## `Tr2Pass`
+
+Trinity effect pass containing shader stages, resource metadata, and render state.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2Pass.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2SamplerDescription -->
+## `Tr2SamplerDescription`
+
+Trinity sampler descriptor read from compiled effect metadata.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2SamplerDescription.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2SamplerSetup -->
+## `Tr2SamplerSetup`
+
+Trinity sampler binding that pairs a metadata name with a sampler descriptor.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2SamplerSetup.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2Shader -->
+## `Tr2Shader`
+
+Trinity shader wrapper around a decoded `Tr2EffectDescription`.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2Shader.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept
+
+<!-- class:Tr2ShaderOption -->
+## `Tr2ShaderOption`
+
+Name/value shader permutation option used during effect lookup.
+
+- Export: None
+- Source: `src/core/tr2/shader/Tr2ShaderOption.js`
+- Visibility: Internal
+- Kind: Adapted Carbon concept

package/docs/formats/hlsl/reference/json-graph.md

@@ -0,0 +1,100 @@
+# JSON and metadata graphs
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl` emitted data
+Audience: Users and integrators
+Summary: Documents the default JSON graph, compact metadata graph, and permutation selection.
+
+## Default JSON graph
+
+`emit: "json"` is the default:
+
+```text
+Root
+|- version, compilerVersion, sourcePath, bodyCount, loadError
+|- permutations: Permutation[]
+`- effect: EffectDescription | null
+   |- version, effectName, annotations, readError
+   `- techniques: Technique[]
+      `- passes: Pass[]
+         |- renderStates: { key, value }[]
+         `- stageInputs: (StageInput | null)[]
+            |- constants: Constant[]
+            |- resources: Resource[]
+            |- uavs: Resource[]
+            |- samplers: Sampler[]
+            |- signature
+            `- bytecode: ShaderBytecode | null
+```
+
+Bytecode values are opaque payloads. A compatible bytecode-format package
+must decode their instruction streams.
+
+## Permutation selection
+
+By default, `effect` represents the container's default option set. Select
+another compiled body with an array or `Map`:
+
+```js
+const effect = CjsHlslFormat.read(bytes, {
+    permutation: [
+        { name: "BLEND_MODE", value: "TRANSPARENT" }
+    ]
+});
+```
+
+## Metadata graph
+
+`emit: "metadata"` returns compact inspection data without bytecode,
+constant-value bytes, or runtime handles:
+
+```text
+MetadataRoot
+|- version, compilerVersion, sourcePath, bodyCount, loadError
+|- permutations: Permutation[]
+|- bodyIndex
+|- selectedOptions: Option[]
+`- effect: MetadataEffect | null
+   `- techniques: Technique[]
+      `- passes: Pass[]
+         |- renderStates: RenderState[]
+         `- stageInputs: (StageInput | null)[]
+            |- constantValueSize
+            |- constants: Constant[]
+            |- resources: Resource[]
+            |- uavs: Resource[]
+            |- samplers: Sampler[]
+            |- annotations
+            `- signature
+```
+
+Each render-state record retains its numeric `key` and `value`. Known state
+types can also include readable or typed fields such as `name`, `valueName`,
+`valueFloat`, `valueHex`, or `valueFlags`.
+
+## Raw graph
+
+`emit: "raw"` returns the internal parser-DTO `Tr2EffectRes` graph. It is not
+the canonical runtime-resource class. It allows advanced callers to resolve
+multiple permutations after one parse, but it is not a stable or
+serialization-safe schema.
+
+Raw stage and library inputs retain authored `sourceConstantValueSize` /
+`sourceConstantValues` separately from Carbon-compatible mutable constant
+buffers. Libraries retain their source `cjsShaderBytecode` directly. Use
+`@carbonenginejs/runtime-resource/formats/hlsl/portable` to copy those facts into a validated
+handle-free contract.
+
+## Compatibility and failures
+
+The reader supports compiled effect versions 8 through 15. The root or
+selected effect can contain format-defined error fields when a compiled body
+cannot be decoded. Invalid input reads and unsupported layout decisions throw
+rather than being filled with guessed values.
+
+## Related documentation
+
+- [API reference](api.md)
+- [Advanced analysis exports](advanced-analysis.md)
+- [Portable body reflection](portable-reflection.md)
+- [Reading effects](../guides/reading-effects.md)