@carbonenginejs/runtime 0.1.0-alpha.2 → 0.1.0-alpha.4

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

@@ -1,17 +1,23 @@
 # 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 Carbon WebGL
-> 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
+Status: Evolving
+Scope: Carbon/Trinity constant-buffer layouts used by `@carbonenginejs/runtime/resource/formats/webgl`
+Audience: Shader translators, runtime packers, and engine integrators
+Summary: Routes constant-buffer layout ownership and records family/register distinctions and legacy GLES compatibility limits.
+
+Origin: a 2026-07-05 native-source comparison for the ccpwgl packer. The
+[original field/filler tables](https://github.com/carbonenginejs/runtime/blob/ede6c17c372c6582fa2a70f72a508e589945537c/docs/resource/formats/webgl/carbon-constant-layouts.md) retain that dated evidence;
+this page does not requalify today's CCPWGL implementation. Native file references
+are relative to `trinity/trinity/`; offsets below are float4 (vec4) registers.
+Runtime lookup offsets are floats, not registers.
+
+Use the [canonical constant-data contract](../../../trinity/architecture.md#constant-data-ownership)
+and [per-frame/per-object public entries](../../../trinity/reference/api.md#current-subpaths),
+not a second backend layout. Source declarations own field order, widths and
+encodings; this summary does not prove which family a shader consumes.
+
+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.
@@ -37,127 +43,49 @@ 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). See the
-[historical WebGL2 `cb3` rewrite and its recorded August 2 `std140` UBO replacement](memory-structured.md#glsl-lowering--b-webgl2-cb3-joint-matrix-rewrite-contract-the-shipping-path).
+
+### 1a. `EveSpaceScene::PerFrameVSData` -> b1
+
+**46 registers.** The `EveSpaceScenePerFrame.vs` declaration in
+[CjsPerFrameLayouts](../../../../src/trinity/core/rawData/CjsPerFrameLayouts.js)
+owns the fields and native citations. Ten matrices lead the block, including
+the previous view/projection data; the remaining fields begin at register 40.
+
+### 1b. `EveSpaceScene::PerFramePSData` -> b2
+
+**118 registers**, owned by `EveSpaceScenePerFrame.ps` in the same catalog.
+The shadow/froxel tail starts at register 24: four shadow values, sixteen
+matrices, split info, inverse projection, sixteen cascade ranges, then five
+froxel registers. Integer fields retain their declared encodings; matching
+float-lane counts is not enough. Original producer assignments remain in the
+dated tables linked above, not a second maintained field inventory.
+
+---
+
+## 2. EVE-space per-object layouts (ships/stations) -> b3 / b4
+
+[CjsEveSpaceObjectLayout](../../../../src/trinity/core/rawData/layouts/CjsEveSpaceObjectLayout.js)
+owns the persistent VS/PS pair, native citations, field defaults and encodings.
+Carbon uploads these structs by copy and binds them through
+`Tr2PerObjectDataWithPersistentBuffers`; do not substitute the generic family.
+
+### 2a. `EveSpaceObjectVSData` -> b3
+
+**29 registers.** `boneOffsets` occupies register 26, morph data 27 and
+`customData` 28. **DX11 EVE joints are not inline:** those offsets index the
+separate `BoneTransforms` ring/structured buffer. Each joint is `Float4x3`
+(three vec4); native upload evidence is `EveSpaceObject2.cpp:1441`.
+See the [historical WebGL2 `cb3` rewrite and its recorded August 2 `std140` UBO replacement](memory-structured.md#glsl-lowering--b-webgl2-cb3-joint-matrix-rewrite-contract-the-shipping-path).
 
 ### 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,
+**29 registers.** Three world-transform matrices lead the block; ship/clip
+values, seven SH coefficient vectors, custom masks, screen size and custom data
+follow. The catalog, not the legacy GLES PS field order, defines this layout.
+
+### 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,
@@ -199,108 +127,46 @@ 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 Carbon WebGL path keeps Carbon's shape: cb3 stays 29 regs, joints go to the
-dedicated CjsSb 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)
+
+## 4. Drift vs ccpwgl GLES-v8 layouts
+
+These are **recorded legacy comparisons**, not current CCPWGL defects or a
+reason to rewrite valid GLES buffers. Use the correct family for each shader.
+The [July comparison](https://github.com/carbonenginejs/runtime/blob/ede6c17c372c6582fa2a70f72a508e589945537c/docs/resource/formats/webgl/carbon-constant-layouts.md#4-drift-vs-ccpwgl-gles-v8-layouts)
+retains exact old producer paths, field offsets and semantic mismatches.
+
+### 4a. Per-frame VS drift (Carbon 1a vs ccpwgl vs, b1)
+
+Legacy GLES used 34 registers versus EVE DX11's 46. Its missing three history
+matrices shift fields from Sun onward by −12 registers. `MiscSettings.y`
+was unused rather than Upscaling; TargetResolution's FovXY lanes remain a flag below.
+
+### 4b. Per-frame PS drift (Carbon 1b vs ccpwgl ps, b2)
+
+Legacy GLES used 23 registers versus 118. Some aligned lanes have different
+semantics (NebulaIntensity/ReflectionIntensity and the target, shadow and misc
+settings). The frame-index register is absent, shifting VolumetricSlices by −1;
+the 94-register shadow/froxel tail is absent (95 fewer registers overall).
+Equal positions do not prove equal values.
+
+### 4c. Per-object VS drift (Carbon 2a vs ccpwgl vs, b3)
+
+Legacy `JointMat` at registers 26–199 (696 floats, 58 joints) conflicts with
+DX11's bone-offset/morph/custom slots. The recorded Carbon WebGL replacement
+keeps the 29-register EVE block and uses a separate CjsSb UBO (capacity 69);
+the memory-structured link above owns that distinction. The origin of 58 versus
+69 is unresolved, not an inferred native limit.
+
+### 4d. Per-object PS drift (Carbon 2b vs ccpwgl ps, b4)
+
+Legacy GLES lacks the three leading matrices, shifting its fields by −12
+registers, and omits customData. Miscdata and mask-field semantic equivalence
+was incomplete. Reusing that buffer for DX11 pixel shaders is not valid merely
+because the later field names resemble each other.
+
+---
+
+## 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*`