@carbonenginejs/runtime-resource 0.11.1 → 0.12.1

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

@@ -0,0 +1,197 @@
+# Public API reference
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgpu`
+Audience: Shader-tool authors and engine integrators
+Summary: Lists the public WebGPU format profile, byte-oriented helpers, options, and output contracts.
+
+## Import
+
+```js
+import CjsWebgpuFormat, {
+    CjsWebgpuFormat as WebgpuFormat
+} from "@carbonenginejs/runtime-resource/formats/webgpu";
+```
+
+The default and named exports refer to the same class.
+
+## Reusable profile
+
+Construct a profile when several operations share output, source, schema, or
+class-registration options. `permutation` is also reusable by `AnalyzeEffect`
+and `BuildEffect`; current `Read` and `Inspect` derive the translated body or
+Carbon defaults and do not consume that profile field:
+
+```js
+const reader = new WebgpuFormat({
+    emit: "json",
+    source: "res:/graphics/effect.webgpu/example.sm_hi",
+    decodeInstructions: true,
+    permutation: null
+});
+```
+
+| Instance method | Purpose |
+| --- | --- |
+| `SetValues(options)` | Merges reusable profile defaults. |
+| `GetValues(options?)` | Returns effective values with optional overrides. |
+| `SetClasses(classes)` | Registers several package-shape constructors. |
+| `SetClass(type, Class)` | Registers or removes one constructor. |
+| `GetClass(type)` | Returns one registered constructor. |
+| `HasClass(type)` | Reports whether a constructor is registered. |
+| `Read(bytes, options?)` | Reads Carbon-record CEWGPU bytes. |
+| `Inspect(bytes, options?)` | Returns a compact container summary. |
+| `AnalyzeEffect(bytes, options?)` | Analyzes compiled-effect bytes without packaging. |
+| `BuildEffect(bytes, options?)` | Translates a version-15 effect to CEWGPU bytes. |
+| `BuildShaderIr(input, options?)` | Builds validated shader IR from DXBC or decoded input. |
+| `BuildWgsl(input, options?)` | Emits supported shader IR as WGSL. |
+| `BuildWgslBindingPlan(programs, options?)` | Allocates one binding layout across a pass. |
+| `BuildWgslSet(entries)` | Assembles emitted shaders and pass layouts. |
+| `ToJSON(value)` | Converts format output to JSON-compatible data. |
+
+There is no `Build(chunks)` method. The current wire is a Carbon record tree,
+not a generic chunk container.
+
+## Static helpers
+
+| Static helper | Purpose |
+| --- | --- |
+| `isCewgpu(bytes)` | Reports whether bytes have the Carbon-v15 shape. |
+| `read(bytes, options?)` | Reads one container. |
+| `inspect(bytes, options?)` | Inspects one container. |
+| `analyzeEffect(bytes, options?)` | Analyzes one compiled effect. |
+| `buildEffect(bytes, options?)` | Builds CEWGPU bytes from a version-15 effect. |
+| `buildShaderIr(input, options?)` | Builds shader IR. |
+| `buildWgsl(input, options?)` | Emits WGSL. |
+| `buildWgslBindingPlan(programs, options?)` | Allocates a pass binding plan. |
+| `buildWgslSet(entries)` | Builds a portable WGSL set. |
+| `toJSON(value)` | Converts output to JSON-compatible data. |
+
+`isCewgpu` checks the first dword for Carbon version 15. CEWGPU has no private
+magic or payload tag, so this is a shape check rather than backend identity.
+Callers establish identity through the resource path that supplied the bytes.
+
+## Profile options
+
+| Option | Meaning |
+| --- | --- |
+| `emit` | `"json"` by default or `"raw"` for the internal container reader. |
+| `source` | Caller-owned diagnostic label; it is never opened. |
+| `decodeInstructions` | Includes decoded instruction and IR detail during analysis. |
+| `permutation` | Exact `NAME=VALUE` assertions for `AnalyzeEffect` and `BuildEffect`; ignored by current `Read` and `Inspect`. |
+| `schema` | Optional caller schema record retained by the profile. |
+| `classes` | Optional constructor registrations keyed by `CLASS_KEYS`. |
+
+Class registrations are validated and stored for forward compatibility.
+Current JSON reads return plain data rather than hydrated package classes.
+
+Raw output is an internal reader over the same bytes. It is not a second wire
+format and should not be persisted.
+
+## Read result
+
+JSON `Read` returns:
+
+- `format`, Carbon `version`, and `sourcePath`;
+- derived `info` and `metadata`;
+- the complete derived `permutationGraph`;
+- derived `analysis`, `wgsl`, and `backendBodySet`;
+- convenience `stages`, `shaders`, and `layouts` arrays.
+
+These records are computed from the Carbon header, descriptions, WGSL program
+slots, and backend blocks. They are not stored chunks. The old `chunks` field
+is intentionally absent.
+
+`Inspect` reports the source label, Carbon version, compiler-version bytes,
+permutation count, distinct-body count, and resolved stage/shader/layout
+counts.
+
+## Effect analysis
+
+`AnalyzeEffect` accepts supported compiled-effect versions for diagnostic
+analysis. It resolves exact permutation assertions and may include decoded
+DXBC instructions and compiler IR.
+
+`BuildEffect` is narrower: current packaging requires the version-15 record
+layout. The wire retains every permutation row and non-program description
+field that the mapping can represent; non-dynamic sampler names are
+unrecoverable and stage order is canonicalized. Source-stage DXBC and the
+caller's source hash are not retained in the wire. The build result retains
+full portable source reflection, including source program bytes. Compiler IR
+is transient and is neither stored in the wire nor returned by `BuildEffect`.
+
+Unknown, duplicate, or unresolved permutation assertions fail closed.
+
+## Effect-package options
+
+`mode: "selected"` is the default. It translates the resolved body's
+requested complete passes while keeping every permutation row and
+representable non-program description fields in the container.
+
+`mode: "all"` first lowers the resolved selection, so an unsupported resolved
+body aborts the build. After that gate succeeds, unsupported later bodies
+remain in the container with empty program slots and appear as unsupported in
+the in-memory body-set view. `allPermutations: true` is a compatibility
+spelling for all mode.
+
+`selection` can name a technique, pass index, and complete stage list.
+`bindingPolicy.sharedIdentities` may name compatible cross-stage resources
+that are allowed to share one physical binding.
+
+`source` remains a diagnostic label. `sourceIdentity` and `outputPath` are
+returned build provenance; the wire's backend identity still comes from the
+consumer's resource path.
+
+## Build result and qualification
+
+`BuildEffect` returns:
+
+- `bytes`;
+- build-time `info` and `metadata`;
+- `permutationGraph`, portable `reflection`, and `reflectionBlobs`;
+- selected `analysis` and `wgsl`;
+- `backendBodySet` for all mode;
+- an `inspection` obtained by rereading the emitted bytes; and
+- `qualification`.
+
+The richer fields are caller evidence and are not separately stored in the
+container.
+
+`qualification.packageValid` reports structural construction. It does not
+claim that every body translated, that a pipeline was prepared, or that a
+draw succeeded. `backendComplete` and `runtimeComplete` retain those broader
+boundaries.
+
+## Binding-plan and WGSL-set helpers
+
+`BuildWgslBindingPlan` takes the complete program set for one pass.
+Unshared D3D tuples receive stage-qualified `scopeIdentity` values. A tuple is
+shared only when its base identity appears in `sharedIdentities` and the
+declarations are compatible.
+
+`BuildWgslSet` validates shader keys, layouts, numeric slots, and resource
+transforms. Ordinary sets use version 2. A proven physical-resource
+coalescing uses version 3 and carries an explicit transform recipe.
+
+## Static metadata
+
+The class exposes `OUTPUT_JSON`, `OUTPUT_RAW`, `CLASS_KEYS`, `type`,
+`mediaTypes`, `inputTypes`, `outputTypes`, `debugOutputTypes`,
+`implementationStatus`, `format`, `analysisFormat`, and `packageVersion`.
+
+## Errors
+
+Reads fail closed on malformed Carbon records, sparse or misordered
+permutation tables, out-of-range arena references, trailing record bytes, or a
+program-bearing stage WebGPU cannot express.
+
+Builds additionally fail on unsupported source versions, invalid selection,
+unsupported compiler semantics, ambiguous binding plans, non-`main` entry
+points, and malformed backend blocks.
+
+## Related documentation
+
+- [Effect packaging guide](../guides/effect-packaging.md)
+- [CEWGPU effect container](../formats/cewgpu.md)
+- [WGSL compatibility](wgsl-compatibility.md)
+- [Class-purpose catalog](classes/README.md)

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

@@ -0,0 +1,9 @@
+# WebGPU class catalog
+
+Status: Deprecated
+Scope: `@carbonenginejs/runtime-resource/formats/webgpu` maintained classes
+Audience: Users, maintainers, and automated readers
+Summary: Points to the canonical package-wide class catalog after format-package consolidation.
+
+The maintained WebGPU entries now live in the
+[package-wide formats class catalog](../../../../reference/classes/formats.md#webgpu).