@carbonenginejs/runtime-resource 0.12.1 → 0.13.0

package/docs/formats/webgl/README.md

@@ -1,57 +1,115 @@
-# WebGL format documentation
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/webgl`
-Audience: Shader-tool authors, runtime integrators, and maintainers
-Summary: Explains CEWG packages, portable reflection, and DXBC-to-GLSL conversion.
-
-## Purpose
-
-`@carbonenginejs/runtime-resource/formats/webgl` reads and builds CEWG packages and converts
-supported compiled Carbon effect stages into GLSL ES 3.00 package data. It
-preserves complete source permutation topology and, for version-15 effects,
-portable reflection for every unique body without creating live shader or GPU
-objects.
-
-## Use this package when
-
-Use `format-webgl` to inspect or build CEWG bytes, translate supported DXBC
-stages, or convert one compiled effect while preserving all source
-permutations and portable reflection. Use runtime and engine packages for live
-shader objects, resource selection, bindings, and draws.
-
-## Where it fits
-
-```text
-compiled effect bytes
-        |
-        +---- format-hlsl ---- portable source reflection
-        +---- format-dxbc ---- decoded shader programs
-        |
-        v
-     format-webgl
-  CEWG + GLSL ES 3.00
-        |
-        +---- runtime-resource ---- selection, cache, Tr2Shader hydration
-        +---- runtime-trinity ----- effect/material facade and parameters
-        `---- WebGL engine -------- programs, bindings, and draws
-```
-
-## Start here
-
-```js
-import { CjsWebglFormat } from "@carbonenginejs/runtime-resource/formats/webgl";
-
-const summary = CjsWebglFormat.inspect(packageBytes);
-const packageData = CjsWebglFormat.read(packageBytes);
-```
-
-## Documentation map
-
-- [Architecture and ownership](architecture.md)
-- [Effect reflection contract](effect-reflection.md)
-- [Constant-buffer layouts](carbon-constant-layouts.md)
-- [Declaration and I/O lowering](decl-io.md)
-- [Structured-memory lowering](memory-structured.md)
-- [Texture sampling](texture-sample.md)
-- [Class-purpose catalog](reference/classes/README.md)
+# WebGL format documentation
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgl`
+Audience: Shader-tool authors, runtime integrators, and maintainers
+Summary: Explains WebGL effect packages, completeness, and DXBC-to-GLSL conversion.
+
+## Purpose
+
+`@carbonenginejs/runtime-resource/formats/webgl` builds effect packages and
+converts supported compiled Carbon effect stages into GLSL ES 3.00 package
+data. It preserves complete source permutation topology without creating live
+shader or GPU objects.
+
+## Use this package when
+
+Use `format-webgl` to inspect or build package bytes, translate supported DXBC
+stages, or convert one compiled effect while preserving all source
+permutations. Use runtime and engine packages for live shader objects, resource
+selection, bindings, and draws.
+
+## Where it fits
+
+```text
+compiled effect bytes
+        |
+        +---- format-hlsl ---- source parsing and permutation analysis
+        +---- format-dxbc ---- decoded shader programs
+        |
+        v
+     format-webgl
+  Carbon container + GLSL ES 3.00
+        |
+        +---- runtime-resource ---- selection, cache, Tr2Shader
+        +---- runtime-trinity ----- effect/material facade and parameters
+        `---- WebGL engine -------- programs, bindings, and draws
+```
+
+The emitted artifact is a shared Carbon v15 container, not a tagged-chunk
+package; the GLSL replaces the DXBC in each stage's program slot. Backend body
+keys deliberately retain the historical `body_<offset>_<size>` form.
+`EFFECT_PERMUTATION_GRAPH_CHUNK` (`PGRF`) still records every Cartesian
+permutation, its option indices, its exact source record, and a
+content-deduplicated body identity.
+
+## Completeness
+
+The build result reports four flags plus a separate qualification:
+
+- `sourceComplete` is true only for version-15 effects.
+- `backendComplete` remains false. Successful translation does not yet prove
+  the engine's physical binding/layout and transform contract.
+- `runtimeComplete` remains false. Live shader objects and GPU handles are
+  outside the format package.
+- `qualification.ok` separately reports whether the selected WebGL programs
+  translated and formed the required raster/compute families. It is returned
+  frozen.
+
+Selected-only or technique/pass/stage-filtered packages still carry complete
+version-15 source coverage, but only their selected backend programs.
+
+Beyond those flags, `glslEffectCompleteness` runs checks that a translation can
+be structurally valid and still be wrong. Two families are worth knowing about:
+
+- `unlowered_local_light_family` — the recognised local-light constants
+  survived into GLSL without being lowered. It is deliberately scoped to that
+  one family: a general "every declared resource is used" rule fires on good
+  builds, because Carbon routinely describes resources a body does not read.
+- `resource_transform_underfilled`, `_layer_gap`, `_carrier_undeclared`, and
+  `_input_still_bound` — a declared resource transform (the detail-map array is
+  the live case) did not complete. Each check is scoped to the stage the
+  transform names, and transform vocabulary is WGSL's: a transform saying
+  `fragment` applies to the WebGL `pixel` stage. Running them across every
+  stage in a pass instead produces 48 false positives.
+
+### Measured link rate
+
+Across all 4,833 shipped compiled effects, **9,319 of 9,321 emitted programs
+compile and link in a real WebGL2 context.** Before the DXBC SM5.1 range-id
+operand fix the rate was near 61%, and the failures were the lesser half of the
+problem: shaders that *did* link were reading constant-buffer rows off the
+register number, and in 56 of 161 multi-dimensional resource operands were
+bound to the wrong texture entirely.
+
+## Tier and permutation policy
+
+For EVE shader work:
+
+- High is `.sm_depth`.
+- Medium is `.sm_hi`.
+- Low is `.sm_lo`.
+- Unpacked Quad V5 evidence must explicitly select `SOPPT_ENABLED`; the
+  default permutation is commonly PPT-off and is not representative.
+
+Always resolve an option tuple against the current source axes. Do not persist
+a permutation index across builds.
+
+## Start here
+
+```js
+import { CjsWebglFormat } from "@carbonenginejs/runtime-resource/formats/webgl";
+
+const summary = CjsWebglFormat.inspect(packageBytes);
+const packageData = CjsWebglFormat.read(packageBytes);
+```
+
+## Documentation map
+
+- [Architecture and ownership](architecture.md)
+- [Carbon compiled-effect container](../carbon-effect-container.md)
+- [Constant-buffer layouts](carbon-constant-layouts.md)
+- [Declaration and I/O lowering](decl-io.md)
+- [Structured-memory lowering](memory-structured.md)
+- [Texture sampling](texture-sample.md)
+- [Class-purpose catalog](reference/classes/README.md)

package/docs/formats/webgl/architecture.md

@@ -1,70 +1,69 @@
-# Architecture and ownership
-
-Status: Evolving
-Scope: `@carbonenginejs/runtime-resource/formats/webgl`
-Audience: Shader-tool authors, runtime integrators, and maintainers
-Summary: Defines the package's compiler, container, runtime, and engine boundaries.
-
-## Purpose
-
-`format-webgl` is the transformation and package layer between compiled
-Carbon-style effects and WebGL engine realization. It emits portable CEWG data
-and GLSL ES 3.00 without constructing mutable runtime shader classes or WebGL
-objects.
-
-## Dependency direction
-
-```text
-@carbonenginejs/runtime-resource/formats/hlsl
-          |
-          +---- effect parsing and portable reflection
-          |
-          v
-@carbonenginejs/runtime-resource/formats/webgl <---- @carbonenginejs/runtime-resource/formats/dxbc
-          |                              decoded DXBC
-          |
-          +---- CEWG bytes, metadata, reflection, GLSL
-          |
-          +---- runtime-resource ---- package selection + Tr2Shader hydration
-          +---- runtime-trinity ----- effect/material facade + parameters
-          `---- WebGL engine -------- GPU realization
-```
-
-Tools may call the public byte-oriented API, but the format package does not
-import the toolchain. Runtime packages consume immutable package data through
-an explicit adapter boundary.
-
-## Owned responsibilities
-
-- Reading, inspecting, validating, and building CEWG v1 containers.
-- Preserving every source permutation and unique body identity.
-- Packing complete version-15 portable reflection and exact shared bytes.
-- Translating supported DXBC vertex, pixel, and bounded map-style compute
-  stages into GLSL ES 3.00.
-- Preserving backend bodies, stages, programs, manifests, and render states.
-- Rejecting incomplete or inconsistent canonical effect packages.
-
-## Ownership elsewhere
-
-- `format-hlsl` owns compiled-effect parsing and the portable reflection
-  schema.
-- `format-dxbc` owns DXBC decoding.
-- `runtime-resource` owns `Tr2EffectRes`, package bytes, option selection,
-  per-permutation cache identity, canonical `Tr2Shader`, reflection records,
-  sampler setup records, and portable hydration.
-- `runtime-trinity` owns the mutable `Tr2Effect`/`Tr2Material` facade,
-  parameters, authored options, and sampler overrides.
-- The WebGL engine owns program compilation, locations, layouts, resource
-  binding, uploads, draws, and context recovery.
-
-## Completeness boundary
-
-Version-15 CEWG can be source-complete while remaining backend- and
-runtime-incomplete. Successful GLSL translation and compile/link do not prove
-the engine's physical binding/layout contract or a rendered result.
-
-## Related documentation
-
-- [Package documentation](README.md)
-- [Effect reflection contract](effect-reflection.md)
-- [Class-purpose catalog](reference/classes/README.md)
+# Architecture and ownership
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgl`
+Audience: Shader-tool authors, runtime integrators, and maintainers
+Summary: Defines the package's compiler, container, runtime, and engine boundaries.
+
+## Purpose
+
+`format-webgl` is the transformation and package layer between compiled
+Carbon-style effects and WebGL engine realization. It emits Carbon container
+bytes and GLSL ES 3.00 without constructing mutable runtime shader classes or
+WebGL objects.
+
+## Dependency direction
+
+```text
+@carbonenginejs/runtime-resource/formats/hlsl
+          |
+          +---- effect parsing and permutation analysis
+          |
+          v
+@carbonenginejs/runtime-resource/formats/webgl <---- @carbonenginejs/runtime-resource/formats/dxbc
+          |                              decoded DXBC
+          |
+          +---- Carbon container bytes, metadata, GLSL
+          |
+          +---- runtime-resource ---- option selection + Tr2Shader
+          +---- runtime-trinity ----- effect/material facade + parameters
+          `---- WebGL engine -------- GPU realization
+```
+
+Tools may call the public byte-oriented API, but the format package does not
+import the toolchain. Runtime packages read the emitted container bytes
+directly.
+
+## Owned responsibilities
+
+- Building the shared Carbon v15 container for the WebGL backend, with GLSL in
+  each stage's program slot.
+- Preserving every source permutation and unique body identity.
+- Translating supported DXBC vertex, pixel, and bounded map-style compute
+  stages into GLSL ES 3.00.
+- Preserving backend bodies, stages, programs, manifests, and render states.
+- Rejecting incomplete or inconsistent canonical effect packages.
+
+## Ownership elsewhere
+
+- `format-hlsl` owns compiled-effect parsing and permutation analysis.
+- `format-dxbc` owns DXBC decoding.
+- `runtime-resource` owns `Tr2EffectRes`, the container bytes, option
+  selection, per-permutation cache identity, canonical `Tr2Shader`, reflection
+  records, and sampler setup records.
+- `runtime-trinity` owns the mutable `Tr2Effect`/`Tr2Material` facade,
+  parameters, authored options, and sampler overrides.
+- The WebGL engine owns program compilation, locations, layouts, resource
+  binding, uploads, draws, and context recovery.
+
+## Completeness boundary
+
+A version-15 build can be source-complete while remaining backend- and
+runtime-incomplete. Successful GLSL translation and compile/link do not prove
+the engine's physical binding/layout contract or a rendered result.
+
+## Related documentation
+
+- [Package documentation](README.md)
+- [Carbon compiled-effect container](../carbon-effect-container.md)
+- [Class-purpose catalog](reference/classes/README.md)