@carbonenginejs/runtime-resource 0.11.0 → 0.12.0

package/docs/formats/hlsl/reference/portable-reflection.md

@@ -0,0 +1,141 @@
+# Portable body reflection
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/hlsl/portable`
+Audience: Backend effect-packager authors
+Summary: Defines exact, handle-free reflection for one compiled effect body.
+
+## Purpose
+
+The ordinary JSON and metadata modes describe one option-selected effect for
+inspection. Backend package builders need a stronger boundary: exact
+permutation-table selection, authored constant defaults, source programs, and
+all reflection fields without renderer handles.
+
+The portable subpath supplies that boundary:
+
+```js
+import {
+    buildEffectBodyReflection,
+    enumerateUniqueEffectBodies,
+    readEffectBodyReflection,
+    validateEffectBodyReflection
+} from "@carbonenginejs/runtime-resource/formats/hlsl/portable";
+
+const document = readEffectBodyReflection(bytes, {
+    source: "effect.sm_depth",
+    permutationIndex: 4
+});
+
+validateEffectBodyReflection(document);
+
+const groups = enumerateUniqueEffectBodies(effectRes);
+const uniqueReflections = groups.map((group) =>
+    buildEffectBodyReflection(effectRes, group.permutationIndex));
+```
+
+`buildEffectBodyReflection(effectRes, permutationIndex)` accepts an already
+loaded raw `Tr2EffectRes`. This avoids reparsing when a backend builder already
+uses `readEffectAnalysis`.
+
+`enumerateUniqueEffectBodies(effectRes)` inspects version-15 source records and
+bytes without decoding. It returns first-occurrence-ordered groups containing
+one canonical `permutationIndex`/`sourceRecord` plus every byte-identical
+variant alias. Exact range aliases are a fast path; distinct ranges are
+fingerprinted and then compared byte-for-byte. The inventory caps the
+Cartesian body table at 65,536 records, rejects partial overlaps, and leaves
+the effect cache and state-manager registries unchanged.
+
+## Contract
+
+Version 1 accepts compiled effect version 15 only. Earlier container versions
+synthesize or normalize several signature fields while reading; rejecting them
+keeps every portable field source-exact.
+
+The root identifies `CJS_EFFECT_BODY_REFLECTION` version 1,
+`mode: "single-body"`, `keyScope: "body-local"`,
+`coverage.bodies: "single"`, the diagnostic source label and
+compiled-effect version/compiler/shared-table/source envelope in `source`, the exact
+`permutationIndex`, and its
+`sourceRecord.offset` / `sourceRecord.byteLength` span. Its effect graph
+preserves:
+
+- ordered parameter annotation groups;
+- ordered techniques, passes, raw render-state pairs, and libraries;
+- every present vertex, pixel, compute, geometry, hull, or domain stage;
+- constant, resource, UAV, dynamic sampler, and stage-annotation metadata;
+- complete pipeline-input, register, static-sampler, and thread-group
+  signatures;
+- exact authored constant-default bytes and declared length; and
+- owned copies of every stage and library source-program payload.
+
+Every source-program record retains its exact shared-table offset. The
+validator requires its complete byte range to remain within
+`source.stringTableByteLength`.
+Stage programs are explicitly `kind: "stage"` and carry their authored stage
+identity. DXR library programs are `kind: "library"` and deliberately carry no
+synthetic compute-stage identity.
+
+Numeric BOOL, INT, and FLOAT annotations retain their exact serialized
+`rawValue`. Sampler floats retain raw IEEE-754 bits. Static sampler border
+colors remain their source enum byte; dynamic sampler border colors remain
+four float bit patterns.
+
+`source.nativeHash` is the compiler-provided v15 hash field, not a package
+content digest. The backend package must independently hash its whole source
+and body payloads.
+
+Version-15 resource and signature counts retain Carbon's authored zero value.
+For heap-view/bindless SRV, UAV, and sampler bindings, `arrayElements: 0` and
+the matching signature `arrayCount: 0` / `registerCount: 0` represent an
+unbounded descriptor range; they are valid source reflection, not an empty or
+malformed binding. Every resource and UAV map entry must reconcile with
+exactly one signature register; signature-only records remain valid.
+
+The compiled body has no authored effect-name field. The caller-supplied
+diagnostic name or path is retained only as `source.label`.
+
+The serializer rejects defaults or constant extents beyond Carbon's 4,096-byte
+stage constant-buffer limit.
+
+## Source truth and realization
+
+The portable document excludes shader, program, render-state, sampler, and
+library handles. It also excludes resource-set descriptions, heap-view arrays,
+backend layouts, masks, sort values, and caches. `runtime-resource` consumes
+the document to hydrate the canonical device-free shader/reflection graph,
+select permutations, and cache shaders. Engines own handles, layouts,
+resource sets, programs, pipelines, and other GPU realization.
+
+Register dynamic classification is not persisted. It depends on per-frame
+reader/engine policy and is not an authored binary field.
+
+Authored constant defaults are separate from the raw model's mutable
+`constantValues`. Carbon-compatible sampler-heap realization may zero-extend
+the latter; it cannot change the portable source prefix.
+
+## Selection and completeness
+
+The parser-internal `GetShaderByIndex(index)` and the portable serializer
+bypass global and local option selection. This is distinct from
+`runtime-resource` `Tr2EffectRes.GetShaderByIndex`, which hydrates and caches a
+canonical shader. The portable serializer performs a fresh non-caching decode
+with a temporary state manager, so mutation of a previously cached raw shader
+cannot change reflection rebuilt from the same owned source bytes.
+This makes a body-table index stable even when an application has global
+effect options.
+
+Version 1 describes one complete listed body. Body-local technique, pass,
+stage, and library keys must be namespaced by a backend package before they are
+flattened across bodies. This document does not claim that a backend package
+contains every permutation body or a program for every body. A backend
+container must reconcile all three of `permutationIndex`,
+`sourceRecord.offset`, and `sourceRecord.byteLength` with its own body identity
+and permutation graph, then reconcile the source byte length and native hash
+before claiming completeness.
+
+## Related documentation
+
+- [JSON and metadata graphs](json-graph.md)
+- [Advanced analysis exports](advanced-analysis.md)
+- [Architecture](../architecture.md)

package/docs/formats/provenance.md

@@ -53,10 +53,10 @@ GR2/GSF reader joined the runtime copies:
 |---|---|---|---|
 | `format-gr2` | `fa64607de7a3a96ed3b1aec5288bf71057642043` (v0.2.0, MIT) | `CjsGr2Format` | `@carbonenginejs/runtime-resource/formats/gr2` |
 
-The copied engine keeps its donor class name (`CjsFormatGr2`, re-exported)
-under `formats/gr2/core/`; `CjsGr2Format` is the runtime-authored contract
-wrapper. Donor license and notice files are kept under
-`format-notices/gr2/`.
+The donor engine was folded into the single public `CjsGr2Format` class, so
+the copied `CjsFormatGr2` name is gone and `formats/gr2/core/` holds only
+role-named helper modules, matching every other format. Donor license and
+notice files are kept under `format-notices/gr2/`.
 
 ## Black definition snapshot
 
@@ -85,6 +85,11 @@ format attribution rather than fork provenance.
 | Wwise soundbank (`.bnk`) | `CjsBnkFormat` | `@carbonenginejs/runtime-resource/formats/bnk` | Original code; chunk layout from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Also carries the SoundbanksInfo JSON helpers (`parseSoundbanksInfo`, `buildSoundbanksCatalog`, `joinSoundbanksInfo`) and `wwiseIdFromName` (FNV-1 32 of the lowercased name, verified against EVE bank/language ids). HIRC entries additionally decode version-stable typed fields (event action lists, action type/target, sound and music-track source ids), pinned by hexdump against bank generator version 150, and the `wwise` static namespace groups the domain toolkit (SoundbanksInfo helpers, id hash, `wwise.eventMediaFromBanks` event → media resolution over inspected banks — graph interpretation for consumers; never used by the resource lifecycle). |
 | Wwise media (`.wem`) | `CjsWemFormat` | `@carbonenginejs/runtime-resource/formats/wem` | Original code; container/codec-tag behavior from public community documentation (ww2ogg, vgmstream, wwiser), no code copied. Includes a Wwise-Vorbis→Ogg repacker (`emit: "ogg"`), an original reimplementation of the ww2ogg algorithm with inline granule computation (no revorb pass needed), and a PTADPCM/16-bit-PCM decoder (`emit: "pcm"` / `toPcm()`, AudioBuffer-ready float32; PTADPCM algorithm from community documentation, verified against EVE media). |
 
+The BNK toolkit also exposes `wwise.sfxNodesFromBanks`: typed, exact-end
+version-150 Random/Sequence, Switch/State, and Layer tails plus event/action
+records and explicit parser diagnostics. It preserves resource facts for
+consumer-owned lowering and is never invoked by the resource lifecycle.
+
 ## Post-fork additions inside copied formats
 
 - `formats/dds` gained original, dependency-free **BC6H and BC7 CPU decoders**

package/docs/formats/webgl/README.md

@@ -0,0 +1,57 @@
+# 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)

package/docs/formats/webgl/architecture.md

@@ -0,0 +1,70 @@
+# 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)

package/docs/formats/webgl/carbon-constant-layouts.md

@@ -0,0 +1,326 @@
+# EVE Carbon/Trinity Shader Constant-Buffer Layout Map
+
+Status: Evolving
+Scope: Carbon/Trinity constant-buffer layouts used by `@carbonenginejs/runtime-resource/formats/webgl`
+Audience: Shader translators, runtime packers, and engine integrators
+Summary: Maps Carbon constant-buffer registers and field layouts for WebGL integration.
+
+> Produced 2026-07-05 from ../carbonengine source (authoritative) for the CEWG
+> per-frame/per-object packer in ccpwgl. All register offsets are in float4
+> (vec4) units. File references are relative to
+> `../carbonengine/trinity/trinity/`.
+
+Scope note: Carbon has **two parallel constant-buffer families**. (a) a
+*generic* Tr2 family in `Tr2ConstantBufferFormats.h`, used by generic Tr2
+renderables; and (b) an *EVE-space* family (`EveSpaceScene::PerFrame*` +
+`EveSpaceObjectVSData/PSData`) used by ships/stations. **ccpwgl's ships mirror
+family (b)**, so that is the primary comparison target.
+
+## 0. Register assignment (shared by all families)
+
+From `Tr2Renderer.cpp:38-43`:
+
+| Register | Purpose | Getter |
+|---|---|---|
+| `b1` | per-frame VS | `GetPerFrameVSStartRegister()` (`Tr2Renderer.cpp:1199`) |
+| `b2` | per-frame PS | `GetPerFramePSStartRegister()` (`:1204`) |
+| `b3` | per-object VS | `GetPerObjectVSStartRegister()` (`:1209`) |
+| `b4` | per-object PS | `GetPerObjectPSStartRegister()` (`:1219`) |
+| `b5` | per-object RT vertex-buffer data | `:1224` |
+| `b6` | per-object VS GUI | `GetPerObjectVSGUIStartRegister()` (`:1214`) |
+
+`b0` is left for effect/material ("custom cb0"); effect constants are handled
+by the material path (`Tr2EffectDescription.cpp`), not these structs. EVE space
+objects reach `b3/b4` through `Tr2Renderer::GetPerObjectStartRegister(shaderType)`
+in `Tr2PersistentPerObjectData.h:122,139`.
+
+---
+
+## 1. EVE-space per-frame layouts (the ccpwgl-relevant path)
+
+### 1a. `EveSpaceScene::PerFrameVSData` -> b1
+
+Struct: `Eve/EveSpaceScene.h:300-327`. Filled: `EveSpaceScene.cpp:3011-3064`
+(`PopulatePerFrameVSData`).
+
+| Field | Type | vec4 off | count | Fed from (EveSpaceScene.cpp) |
+|---|---|---|---|---|
+| ViewInverseTransposeMat | Matrix | 0 | 4 | `GetInverseViewTransform()` (`:3020`) |
+| ViewProjectionMat | Matrix | 4 | 4 | `Transpose(view*reversedProj)` (`:3017-3018`) |
+| ViewMat | Matrix | 8 | 4 | `Transpose(GetViewTransform())` (`:3014`) |
+| ProjectionMat | Matrix | 12 | 4 | `Transpose(GetReversedDepthProjectionTransform())` (`:3015-3016`) |
+| ShadowViewMat | Matrix | 16 | 4 | (populated by shadow path) |
+| ShadowViewProjectionMat | Matrix | 20 | 4 | (shadow path) |
+| EnvMapRotationMat | Matrix | 24 | 4 | `Transpose(RotationMatrix(m_envMapRotation))` (`:3028`) |
+| ViewProjectionLast | Matrix | 28 | 4 | `Transpose(m_viewLast * m_projectionLast*m_jitterMatrix)` (`:3022-3023`) |
+| ViewLast | Matrix | 32 | 4 | `Transpose(m_viewLast)` (`:3024`) |
+| ProjLast | Matrix | 36 | 4 | `Transpose(lastProjection)` (`:3025`) |
+| Sun.DirWorld + unused_pad0 | Vector3+float | 40 | 1 | `-Normalize(m_sunData.DirWorld)` (`:3035`) |
+| Sun.DiffuseColor | Color | 41 | 1 | `m_currentSunColor` (`:3032`) |
+| FogFactors + pad | Vector3+float | 42 | 1 | `(fogEnd/d, 1/d, fogMax)` (`:3045-3050`) |
+| TargetResolution + FovXY | Vector2+Vector2 | 43 | 1 | RT w/h (`:3038-3039`); FovXY from projection+aspect (`:3042-3043`) |
+| ViewportAdjustment | Vector4 | 44 | 1 | device/logical viewport ratios (`:3055-3058`) |
+| Time, Upscaling, ViewportSize | float,float,Vector2 | 45 | 1 | `GetAnimationTime()`, `m_upscalingAmount`, device viewport (`:3059-3063`) |
+
+Total = **46 registers**. `SunData` struct: `EveSpaceScene.h:218-223`
+(Vector3 DirWorld, float pad, Color DiffuseColor).
+
+### 1b. `EveSpaceScene::PerFramePSData` -> b2
+
+Struct: `EveSpaceScene.h:240-294`. Filled: `EveSpaceScene.cpp:3066-3198`
+(`PopulatePerFramePSData`).
+
+| Field | Type | vec4 off | count | Fed from |
+|---|---|---|---|---|
+| ViewInverseTransposeMat | Matrix | 0 | 4 | `GetInverseViewTransform()` (`:3076`) |
+| ViewMat | Matrix | 4 | 4 | `Transpose(GetViewTransform())` (`:3074`) |
+| EnvMapRotationMat | Matrix | 8 | 4 | `Transpose(RotationMatrix(m_envMapRotation))` (`:3079`) |
+| Sun.DirWorld+pad | Vector3+float | 12 | 1 | `-Normalize(sun dir)` (`:3085`) |
+| Sun.DiffuseColor | Color | 13 | 1 | `m_currentSunColor`, `.a=m_defaultDiffuseRoughness` (`:3082-3083`) |
+| AmbientColor + ReflectionIntensity | Vector3+float | 14 | 1 | `m_ambientColor` (`:3086`), `m_currentReflectionIntensity` (`:3088`) |
+| FogColor | Vector4 | 15 | 1 | `(m_fogColor.rgb, m_fogMax)` (`:3089`) |
+| ViewportOffset + ViewportSize | Vector2+Vector2 | 16 | 1 | viewport x/y (`:3105-3106`), device viewport (`:3108-3109`) |
+| TargetResolution + DepthMapSampleCount + Debug | Vector2+f+f | 17 | 1 | RT w/h (`:3095-3096`); DepthMapSampleCount=1 legacy (`:3134`); Debug=`m_perFrameDebug` (`:3190`) |
+| ShadowMapSettings | Vector4 | 18 | 1 | `(1,1,0,0)` (`:3131`) |
+| ShadowCameraRange + ShadowLightness + ShadowQuality | Vec2+f+uint | 19 | 1 | `(1,0)` default (`:3103`), lightness=0 (`:3133`), `1<<m_shadowQuality` (`:3117`) |
+| ProjectionToView + FovXY | Vector2+Vector2 | 20 | 1 | proj `_43,_33` (`:3137-3138`); FovXY (`:3099-3100`) |
+| Time, SceneMipLodBias, Upscaling, GammaBrightness | 4xfloat | 21 | 1 | `GetAnimationTime()` (`:3111`), mip bias (`:3140-3157`), upscaling (`:3112,3152`), `g_eveSpaceSceneGammaBrightness` (`:3092`) |
+| FrameIndex, Jittering, InverseShadowMapAtlasSize, ShadowMapAtlasEntryMinSizeLog2 | uint,uint,f,uint | 22 | 1 | frame counter (`:3114`), jitter!=0 (`:3115`), light-manager atlas (`:3121-3124`) |
+| VolumetricSlices[4] | float[4] | 23 | 1 | hard-coded 1e3..1e6 (`:3192-3195`) |
+| ShadowMapValues[4] | Vector4[4] | 24 | 4 | `shadowMap->m_perSplitData` (`:3161-3164`) |
+| ShadowMatrixVal[16] | Matrix[16] | 28 | 64 | per-split shadow matrices, atlas-tiled 8x2 (`:3171-3184`) |
+| SplitInfo | Vector4 | 92 | 1 | `shadowMap->m_perSplitData.SplitInfo` (`:3185`) |
+| ProjectionInverseMat | Matrix | 93 | 4 | `Inverse(Transpose(reversedProj))` (`:3189`) |
+| CascadeRanges[16] | Vector4[16] | 97 | 16 | `shadowMap->m_perSplitData.CascadeRanges` (`:3166-3169`) |
+| FroxelFogData | FroxelPerFrameData | 113 | 5 | `m_volumetricsRenderer->PopulatePerFrameData` (`:3197`) |
+
+Total = **118 registers**. `SHADOW_FRUSTUM_COUNT = 16` (`Tr2ShadowMap.h:15`).
+`FroxelPerFrameData` (`Tr2VolumetricsRenderer.h:119-135`): FogColor(vec3)+
+BackgroundVisibility, BaseDensity/MaxDistance/MaxDistanceVisibility/
+EnvironmentIntensity, EnvironmentG+3pad, planets[2] (2xSphere=2 vec4)
+= 5 registers.
+
+---
+
+## 2. EVE-space per-object layouts (ships/stations) -> b3 / b4
+
+Structs: `Eve/SpaceObject/EveSpaceObject2.h:99-141`. Copied verbatim into the
+buffers by `EveSpaceObject2::UpdatePerObjectBuffer` (`EveSpaceObject2.cpp:1469-1483`,
+plain `memcpy` of the struct). Bound to b3/b4 via
+`Tr2PerObjectDataWithPersistentBuffers` (`Tr2PersistentPerObjectData.h`).
+`EVE_SPACEOBJECT_CUSTOWMASK_MAX = 2` (`EveSpaceObject2.h:49`);
+`PACKED_COEFFICIENT_COUNT = 7` (`Tr2ShLightingManager.h:51`).
+
+### 2a. `EveSpaceObjectVSData` -> b3
+
+| Field | Type | vec4 off | count | Fed from (EveSpaceObject2.cpp) |
+|---|---|---|---|---|
+| worldTransform | Matrix | 0 | 4 | `Transpose(m_worldTransform)` (`:637`) |
+| worldTransformLast | Matrix | 4 | 4 | `Transpose(m_worldTransform)` prev frame (`:2675`) |
+| invWorldTransform | Matrix | 8 | 4 | `Transpose(m_invWorldTransform)` (`:638`) |
+| shipData | Vector4 | 12 | 1 | `m_spaceObjectShipData` = (boosterGain, activation, dirt, boundingRadius) (`:639`,`734-744`) |
+| clipData | Vector4 | 13 | 1 | `(clipSphereCenter, clipRadiusSq)` (`:758`) |
+| ellpsoidRadii | Vector4 | 14 | 1 | `GetShapeEllipsoid` radius (`:643`) |
+| ellpsoidCenter | Vector4 | 15 | 1 | `GetShapeEllipsoid` center (`:644`) |
+| customMaskMatrix[2] | Matrix[2] | 16 | 8 | `m_customMasks[i]->FillPerObjectData` (`:654-664`) |
+| customMaskData[2] | Vector4[2] | 24 | 2 | custom-mask fill (`:654-664`) |
+| boneOffsets[4] | uint32[4] | 26 | 1 | `[curFrameOffset, prevFrameOffset, boneCount, -]` (`:1440-1444`) |
+| morphTargetVertexDataOffset / AnimationDataOffset / activeMorphTargetsCount / bakedMorphTargetVertexDataOffset | uint32x4 | 27 | 1 | morph-target path |
+| customData | Vector4 | 28 | 1 | copied from PS customData (`:1445`) |
+
+Total = **29 registers**.
+
+**Joints are NOT in this buffer on DX11.** `boneOffsets` (reg 26) index a
+separate `BoneTransforms` ring buffer/SSBO
+(`m_boneOffsets.UploadTransforms(... Float4x3 ...)`, `EveSpaceObject2.cpp:1441`).
+Bones are `Float4x3` (3 vec4 per joint). This is the structured-buffer path
+that `docs/dxbc-lowering/memory-structured.md:131-213` rewrites for WebGL2.
+
+### 2b. `EveSpaceObjectPSData` -> b4
+
+| Field | Type | vec4 off | count | Fed from |
+|---|---|---|---|---|
+| worldTransform | Matrix | 0 | 4 | `m_vsData.worldTransform` (`:646`) |
+| worldTransformLast | Matrix | 4 | 4 | (`:2676`) |
+| invWorldTransform | Matrix | 8 | 4 | (`:647`) |
+| shipData | Vector4 | 12 | 1 | `m_spaceObjectShipData` (`:636`) |
+| clipSphereCenter + clipRadiusSq | Vector3+float | 13 | 1 | (`:755-756`) |
+| clipRadius2Sq, impactDataOffset, clipSphereFactor2, clipSphereFactor | 4xfloat | 14 | 1 | (`:651,760-762`) |
+| shLightingCoefficients[7] | Vector4[7] | 15 | 7 | `UpdateShLighting` / cleared `:1425` |
+| customMaskMaterialIDs[2] | Vector4[2] | 22 | 2 | custom-mask fill |
+| customMaskTargets[2] | Vector4[2] | 24 | 2 | custom-mask fill |
+| customMaskClamps | Vector4 | 26 | 1 | custom-mask fill |
+| screenSize | Vector4 | 27 | 1 | screen size |
+| customData | Vector4 | 28 | 1 | |
+
+Total = **29 registers**.
+
+### 2c. Other EVE per-object buffers
+
+- **Turrets** `EveTurretSet.h:47-70`: `EveTurretSetVSData` = baseCutoffData,
+  turretSetData, shipMatrix, prevShipMatrix, currentBoneOffset/prevBoneOffset/
+  2x unused, then `turretTranslation[N]` + `turretRotation[N]` (per-turret).
+  `EveTurretSetPSData` = shipData, clipData1, clipRadius2Sq+3unused,
+  shLightingCoefficients[7]. Bound at b3/b4 (`EveTurretSet.cpp:3959,3961`).
+- **Missile warhead** (ccpwgl `GLESPerObjectDataEveMissileWarhead`,
+  `Tr2PerObjectData.js:317-337`) mirrors a smaller variant.
+
+---
+
+## 3. Generic Tr2 per-frame / per-object family (`Tr2ConstantBufferFormats.h`)
+
+Used by non-EVE Tr2 renderables. Filled in `Tr2ConstantBufferFormats.cpp` +
+bound at b1/b2/b3/b4. Included for completeness; **not** what ccpwgl ships
+mirror.
+
+- `Tr2PerFrameVSData` (`.h:53-63`): ViewInverseTransposeMat(0-3), sunDirWorld(4),
+  sceneFogColor(5), ViewProjectionMat(6-9), ViewMat(10-13), ProjectionMat(14-17).
+  Filled `Tr2ConstantBufferFormats.cpp:13-29`.
+- `Tr2PerFramePSData` (`.h:73-92`): ViewInverseTransposeMat(0-3),
+  sceneAmbientColor(4), sceneFogColor(5), sunDirWorld(6), sunDiffuseColor(7),
+  sunSpecularColor(8), maxFogAmount/maxFogDistance/minFogDistance/cullDirection(9),
+  ViewProjectionMat(10-13), shScale/shadowCount/invShadowSize/radius(14),
+  viewPort(15), ViewProjInverse(16-19).
+- `Tr2PerObjectVSData` (`.h:35-41`): WorldMat(0-3), boundingCylinderLocalHeight+
+  boundingCylinderLocalXZCenter+boundingCylinderRotation(4).
+- `Tr2PerObjectPSData` (`.h:43-51`): farFadeDistance/nearFadeDistance/padding(0),
+  highlightColor(1), then `Tr2PerObjectPerPixelPointLightData pointLights[8]`
+  (4 regs each, `.h:17-33`) = 32 regs. **<- generic path dynamic lights live in
+  per-object PS constants, 8 point lights max.**
+- Generic VS float buffer capacity is `40*4` floats, PS `80*4` floats
+  (`Tr2PerObjectData.h:67,94`).
+
+**Generic skinned path** (`Tr2PerObjectDataSkinned` / `Tr2PerAreaDataSkinned`,
+`Tr2PerObjectData.cpp:75-193`): here joints ARE inlined into the b3 VS buffer.
+Layout = `[jointMatrices | worldMat | (1 pad reg) | mirrorMatrix]`, total
+`(TR2_MAX_BONES_PER_MESHAREA*3 + 5 + 4)*16` bytes. `TR2_MAX_BONES_PER_MESHAREA
+= 69` (`Tr2PerObjectData.h:98`). Joints are 3 vec4 each (`Float4x3`), packed at
+offset 0; worldMat at reg `69*3=207`, mirrorMatrix at reg `69*3+5=212`
+(`Tr2PerObjectData.cpp:102-103,117-118`).
+
+---
+
+## 4. Drift vs ccpwgl GLES-v8 layouts
+
+ccpwgl per-frame: `../ccpwgl/src/eve/EveSpaceScene.js:1906-1949`, filled
+`:1659-1855`. ccpwgl per-object: `../ccpwgl/src/core/data/Tr2PerObjectData.js:52-105`.
+
+### 4a. Per-frame VS drift (Carbon 1a vs ccpwgl vs, b1)
+
+ccpwgl VS = ViewInverseTransposeMat, ViewProjectionMat, ViewMat, ProjectionMat,
+ShadowViewMat, ShadowViewProjectionMat, EnvMapRotationMat, SunData.DirWorld,
+SunData.DiffuseColor, FogFactors, TargetResolution, ViewportAdjustment,
+MiscSettings = **34 regs**.
+
+| Carbon field (off) | ccpwgl field (off) | Status |
+|---|---|---|
+| ViewInverseTransposeMat..EnvMapRotationMat (0-27) | same (0-27) | OK aligned |
+| **ViewProjectionLast (28-31)** | - | MISSING in ccpwgl |
+| **ViewLast (32-35)** | - | MISSING in ccpwgl |
+| **ProjLast (36-39)** | - | MISSING in ccpwgl |
+| Sun.DirWorld+pad (40) | SunData.DirWorld (28) | semantic match, **-12 reg shift** |
+| Sun.DiffuseColor (41) | SunData.DiffuseColor (29) | (-12) |
+| FogFactors+pad (42) | FogFactors (30) | (-12) |
+| TargetResolution+FovXY (43) | TargetResolution (31) | Carbon packs FovXY in .zw; verify `d.targetResolution` carries fov |
+| ViewportAdjustment (44) | ViewportAdjustment (32) | (-12) |
+| Time,Upscaling,ViewportSize (45) | MiscSettings (33)=time,**unused**,vpW,vpH | `.y` differs: Carbon=Upscaling, ccpwgl=0 |
+
+Net: ccpwgl VS omits the 3 motion-vector matrices (12 regs); every field from
+Sun onward is shifted -12 registers. DX11 shaders reading `cb1[28+]` need the
+Carbon-shaped buffer.
+
+### 4b. Per-frame PS drift (Carbon 1b vs ccpwgl ps, b2)
+
+ccpwgl PS = 13 entries ending at VolumetricSlices = **23 regs** vs Carbon's
+**118**.
+
+| Carbon field (off) | ccpwgl field (off) | Status |
+|---|---|---|
+| ViewInverseTransposeMat/ViewMat/EnvMapRotationMat (0-11) | same (0-11) | OK |
+| Sun.DirWorld (12), Sun.DiffuseColor (13) | SunData.DirWorld (12), .DiffuseColor (13) | OK |
+| AmbientColor+ReflectionIntensity (14) | AmbientColor+**NebulaIntensity** (14) | `.w` semantic differs |
+| FogColor (15) | FogColor (15) | OK |
+| ViewportOffset+ViewportSize (16) | ViewportOffset+ViewportSize (16) | OK |
+| TargetResolution+DepthMapSampleCount+Debug (17) | TargetResolution vec4 (17) | `.z/.w` differ |
+| ShadowMapSettings (18) | ShadowMapSettings (18) | OK |
+| ShadowCameraRange+ShadowLightness+ShadowQuality (19) | ShadowCameraRange vec4 (19) | `.z/.w` differ |
+| ProjectionToView+FovXY (20) | ProjectionToView+FovXY (20) | OK |
+| Time,SceneMipLodBias,Upscaling,GammaBrightness (21) | MiscSettings=time,fogType,fogBlur,contrast (21) | only `.x` matches |
+| **FrameIndex,Jittering,invAtlasSize,atlasMinLog2 (22)** | - | MISSING entirely |
+| VolumetricSlices (23) | VolumetricSlices (22) | **-1 reg shift** |
+| **ShadowMapValues[4] (24-27)** | - | MISSING |
+| **ShadowMatrixVal[16] (28-91)** | - | MISSING (64 regs) |
+| **SplitInfo (92)** | - | MISSING |
+| **ProjectionInverseMat (93-96)** | - | MISSING |
+| **CascadeRanges[16] (97-112)** | - | MISSING |
+| **FroxelFogData (113-117)** | - | MISSING |
+
+Net: aligned through reg ~20, diverges at 21, -1 shift from 23, and the whole
+cascaded-shadow + froxel tail (95 regs) is absent in ccpwgl.
+
+### 4c. Per-object VS drift (Carbon 2a vs ccpwgl vs, b3)
+
+| Carbon field (off) | ccpwgl field (off) | Status |
+|---|---|---|
+| worldTransform..customMaskData[1] (0-25) | WorldMat..CustomMaskData1 (0-25) | OK aligned |
+| **boneOffsets[4] (26)** | - (JointMat starts at 26) | CONFLICT |
+| morph data (27) | (part of JointMat) | CONFLICT |
+| customData (28) | (part of JointMat) | CONFLICT |
+| - (joints in separate SSBO) | **JointMat cb3[26..199], 696 floats = 58 joints** | architecture drift |
+
+In Carbon DX11, cb3[26]=boneOffsets, cb3[27]=morph, cb3[28]=customData, and
+joints live in the separate `BoneTransforms` structured buffer (69 max,
+Float4x3). ccpwgl WebGL2 splices 58 joints inline at cb3[26..199] instead.
+The CEWG path keeps Carbon's shape: cb3 stays 29 regs, joints go to the
+dedicated CewgSb UBO (capacity 69). Bone-count note: Carbon
+TR2_MAX_BONES_PER_MESHAREA=69 vs ccpwgl inline 58 (likely a WebGL uniform
+budget choice, not a Carbon constant).
+
+### 4d. Per-object PS drift (Carbon 2b vs ccpwgl ps, b4)
+
+| Carbon field (off) | ccpwgl field (off) | Status |
+|---|---|---|
+| **worldTransform (0-3)** | - | MISSING in ccpwgl |
+| **worldTransformLast (4-7)** | - | MISSING in ccpwgl |
+| **invWorldTransform (8-11)** | - | MISSING in ccpwgl |
+| shipData (12) | Shipdata (0) | match, **-12 reg** |
+| clipSphereCenter+clipRadiusSq (13) | Clipdata1 (1) | (-12) |
+| clipRadius2Sq,impactDataOffset,clipSphereFactor2,clipSphereFactor (14) | Miscdata (2) | partial semantic overlap |
+| shLightingCoefficients[7] (15-21) | ShLighting 4x7 (3-9) | same 7 vec4 (-12) |
+| customMaskMaterialIDs[2] (22-23) | CustomMaskMaterialID0/1 (10-11) | (-12) |
+| customMaskTargets[2] (24-25) | CustomMaskTarget0/1 (12-13) | (-12) |
+| customMaskClamps (26) | CustomMaskBlending (14) | name differs, same slot |
+| screenSize (27) | Screensize (15) | (-12) |
+| customData (28) | - | MISSING in ccpwgl |
+
+Net: Carbon's per-object PS leads with three matrices (12 regs) ccpwgl lacks —
+every ccpwgl PS field is -12 registers vs the DX11 expectation. Largest
+per-object drift; most likely to break translated pixel shaders if the
+GLES-shaped buffer were reused.
+
+---
+
+## 5. Ambiguities / flags (not guessed — verify before relying on)
+
+1. **Which per-frame family do specific shipped DX11 shaders bind?** EVE ships
+   use `EveSpaceScene::PerFrame*` (b1/b2), but the generic `Tr2PerFrame*`
+   family, `Tr2InteriorScene` per-frame (`Tr2InteriorScene.cpp:644-645`) and
+   shadow-only `Tr2PerFrameShadowPSData` (`Tr2ConstantBufferFormats.h:10-15`)
+   also exist. Confirm per shader family before packing.
+2. **`d.targetResolution` contents:** ccpwgl relies on `device.targetResolution`
+   carrying FovXY in `.zw` (used at `EveSpaceScene.js:1683`). Not verified in
+   `Tw2Device.js`.
+3. **`Tr2PerFrameVSDataDebug`** (`Tr2ConstantBufferFormats.h:66-70`, used
+   `EveSpaceScene.cpp:856`) is a smaller 8-register b1 variant for debug/shadow
+   passes (ViewInverseTransposeMat + ViewProjectionMat only).
+4. **Bone count 69 vs 58**: source of ccpwgl's 58 not found in Carbon; flag for
+   reconciliation.
+5. **Miscdata/customMaskClamps/CustomMaskBlending semantics** only positionally
+   matched; exact float meanings not fully cross-verified.
+6. Effect/material "custom cb0" buffers are per-effect and out of scope of the
+   fixed ABI above.
+
+Primary authoritative files: `Tr2ConstantBufferFormats.h/.cpp`,
+`Tr2PerObjectData.h/.cpp`, `Tr2PersistentPerObjectData.h`,
+`Eve/EveSpaceScene.h/.cpp`, `Eve/SpaceObject/EveSpaceObject2.h/.cpp`,
+`Tr2Renderer.cpp`, `Tr2ShadowMap.h`, `Tr2VolumetricsRenderer.h`.