diff --git a/docs/ISSUES.md b/docs/ISSUES.md index aa44567d..0e951a27 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -9207,7 +9207,11 @@ the full 6,558-pass / 5-skip suite remains green. ## #226 — Retail building/EnvCell detail-texture overlay is not rendered -**Status:** IMPLEMENTED + CONNECTED-VISUAL-VERIFIED 2026-08-21 +**Status:** IMPLEMENTED + CONNECTED-VISUAL-VERIFIED 2026-08-21; re-ported to +the single-pass path 2026-08-22 by Campaign VM VM1 after VM2's live cdb read +found retail hardware never takes the two-pass fallback this issue originally +ported (see +[`docs/research/2026-08-22-vm2-retail-detail-path-cdb.md`](research/2026-08-22-vm2-retail-detail-path-cdb.md)). **Severity:** LOW **Filed:** 2026-07-20 **Component:** rendering / building and environment materials @@ -9224,8 +9228,12 @@ mechanisms. `bb5acab9` ported the behavior that produced the observed mismatch: `TexMerge::CopyAndTile`/`Merge` pass each source's authored base tiling into the terrain composition. #226 now resolves Dereth category 1/2 detail surfaces, uploads their authored texture/tiling with retail wrap/linear sampling, and -replays building and EnvCell built-mesh subsets with the exact -`DESTCOLOR + INVSRCALPHA` blend. This includes opaque, ClipMap, straight-alpha, +replays building and EnvCell built-mesh subsets with retail's single-pass +detail combine (VM1/VM2, 2026-08-22): `SRCALPHA + INVSRCALPHA` compositing +`lerp(base * diffuse, detail.rgb, detail.a * diffuseAlpha)`, matching the +`bCanDoSinglePassDetailing = 1` path real hardware runs — not the two-pass +`DESTCOLOR + INVSRCALPHA` fallback the port originally reproduced. This +includes opaque, ClipMap, straight-alpha, additive, and inverse-alpha material subsets; transparent base/detail commands remain adjacent in acdream's authoritative shared alpha order with depth writes disabled (retail bypasses delayed alpha while detail is installed; retaining @@ -9253,10 +9261,12 @@ its evidence source is **Acceptance:** Toggling the existing “Building Detail Textures” checkbox visibly changes nearby building and interior surfaces without a restart. -Enabled detail is full through 10 m positive view depth, fades linearly to an -exact no-op at 50 m, and preserves retail's measured slight brightening. -Disabling it submits no detail replay and preserves the already-accepted base -render. Landscape, ordinary objects, physics, and collision remain unchanged. +There is no distance fade (VM1/VM2: retail's `get_alpha_for_z` is unreachable +for built meshes; attenuation is the sampler's linear mip chain), and the +single-pass combine darkens the live category texture by roughly 10% on +mid-tones rather than brightening it. Disabling it submits no detail replay +and preserves the already-accepted base render. Landscape, ordinary objects, +physics, and collision remain unchanged. The automated gates cover the setting gate, data/blend/fade contract, built-mesh subset eligibility, opaque command filtering and A2C coverage, transparent depth/order seam, Vulkan descriptor diff --git a/docs/architecture/retail-divergence-register.md b/docs/architecture/retail-divergence-register.md index 79801d23..f647244c 100644 --- a/docs/architecture/retail-divergence-register.md +++ b/docs/architecture/retail-divergence-register.md @@ -457,7 +457,7 @@ AP-94..AP-112 for the confirmed retail-UI completion gaps. | TS-49 | Hidden-object availability is bridged through `TargetManager.NotifyVoyeurOfEventAndClear(ExitWorld)` because acdream has not ported retail's DetectionManager. Retail `CObjCell::hide_object` sends `LeftDetection` to detection voyeurs; acdream instead withholds Hidden hosts from ordinary `GetObjectA` relationship creation and uses the existing non-Ok target update to tear down MoveTo/Sticky consumers and clear watched-role subscriptions while preserving the hidden object's own watcher role. | `src/AcDream.App/Physics/EntityPhysicsHost.cs` (`NotifyHidden`); `src/AcDream.App/Physics/LiveEntityMotionRuntimeController.cs` (`ResolvePhysicsHost`); `src/AcDream.Core/Physics/Motion/TargetManager.cs` (`NotifyVoyeurOfEventAndClear`) | The current movement consumers already share TargetManager's status fan-out; the bridge prevents pursuit of an unavailable object without inventing a second partial detection database. | Plugins or future systems listening specifically for retail detection enter/leave events receive no `LeftDetection`; only movement/sticky target consumers observe the equivalent availability loss. | `CObjCell::hide_object @ 0x0052BE30`; retire by porting DetectionManager/CObjCell detection-voyeur delivery and routing Hidden through `LeftDetection` | | TS-50 | `AnimationDone` executes semantically at each owner's retail `CPhysicsObj::process_hooks` boundary, but all other animation hooks are retained in `AnimationHookFrameQueue` until final root/part/equipped-child pose publication. Retail executes the complete hook stream before transition and the Target/Movement/PartArray/Position manager tail because its current CPartArray pose already exists in-place. Static owners correctly reach `process_hooks` only after their root, parts, and children are current. | `src/AcDream.App/Rendering/Vfx/AnimationHookFrameQueue.cs`; `src/AcDream.App/Rendering/RetailStaticAnimatingObjectScheduler.cs`; shared frame drain in `src/AcDream.App/Update/LiveObjectFrameController.cs` (`LiveEffectFrameController`) | The modern renderer publishes immutable effect-pose snapshots after all root/child composition; deferred visual sinks avoid attaching particles/lights/audio to the previous pose. Semantic `AnimationDone` is split out and exact, so motion completion and manager behavior are not delayed. Pose-owner lifetime tokens prevent deferred hooks from crossing delete/local-ID reuse. | A non-AnimationDone hook with same-quantum semantic consequences (notably `CallPES`, default-script chaining, audio/particle creation relative to a transition) runs later than retail and can observe post-tail state or start one render frame late. | `CPhysicsObj::process_hooks @ 0x00511550`; `CPhysicsObj::UpdatePositionInternal @ 0x00512C30`; `CPhysicsObj::animate_static_object @ 0x00513DF0`; retire by publishing the current per-object/child pose before hook routing or splitting semantic and presentation sinks without changing authored hook order | | TS-51 | Particle and PhysicsScript tails advance once per render frame after the complete ordinary/static object worksets. Retail advances each ordinary object's ParticleManager then ScriptManager inside every admitted `UpdateObjectInternal` quantum; `animate_static_object` instead advances that static owner's ScriptManager then ParticleManager and only then `process_hooks`, using its whole admitted elapsed interval. acdream's shared tail is Particle → Script after static hook capture. | `src/AcDream.App/Update/LiveObjectFrameController.cs` (`LiveObjectFrameController` + `LiveEffectFrameController` shared `_particles.Tick` / `_scripts.Tick` tail); `src/AcDream.App/Rendering/RetailStaticAnimatingObjectScheduler.cs` | The current managers are shared presentation/runtime owners rather than per-object manager instances. R6 makes root motion, animation, object clocks, workset membership, and ordinary manager order faithful without pretending the shared tails have per-owner timing or static-tail order. Splitting ownership safely requires a later effect-lifetime slice. | A render fragment below retail's minimum object quantum can advance an effect while its owner waits; a catch-up frame advances an owner's root through several quanta but its effect tail only once; static hooks can route before their script/particle managers and static default scripts/particles use render elapsed in Particle → Script order rather than `animate_static_object` elapsed/discard and Script → Particle → hooks timing. | `CPhysicsObj::UpdateObjectInternal @ 0x005156B0`; `CPhysicsObj::animate_static_object @ 0x00513DF0`; retire by giving live/static owners incarnation-bound particle/script managers and ticking each manager in the owning object quantum/order | -| ~~TS-52~~ | **RETIRED 2026-08-21 (#226).** The row's landscape premise was wrong: the reachable Sept-2013 `ChangeRegion` caller passes zero LANDSCAPE detail surfaces and enables the building/environment categories. acdream now resolves those authored category detail textures and tiling, replays eligible building-shell and EnvCell subsets with retail's `DESTCOLOR + INVSRCALPHA` blend and 10–50 m viewer-depth fade, and consumes the existing Building Detail Textures preference. The earlier experimental landscape array remains correctly reverted; there is no missing user-visible landscape pass to track. | `src/AcDream.App/Rendering/TerrainAtlas.cs`; `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.Rhi.cs`; `src/AcDream.App/Rendering/Wb/EnvCellRenderer.Rhi.cs`; `src/AcDream.App/Rendering/Shaders/mesh_detail.vert`; `src/AcDream.App/Rendering/Shaders/mesh_detail.frag` | Retired on measured caller/category evidence and the connected on/off/restored visual gate. | None; disabling the preference submits no detail replay, while enabling it visibly changes nearby building/EnvCell surfaces. Landscape remains unchanged, matching the reachable retail caller. | `docs/research/2026-08-21-retail-building-detail-texturing-pseudocode.md`; `LScape::ChangeRegion`; `SmartBox::SetDetailTexturing`; issue #226 | +| ~~TS-52~~ | **RETIRED 2026-08-21 (#226); re-ported 2026-08-22 (Campaign VM VM1/VM2).** The row's landscape premise was wrong: the reachable Sept-2013 `ChangeRegion` caller passes zero LANDSCAPE detail surfaces and enables the building/environment categories. acdream now resolves those authored category detail textures and tiling, and replays eligible building-shell and EnvCell subsets with retail's **single-pass** detail combine — `SRCALPHA + INVSRCALPHA` compositing `lerp(base·diffuse, detail.rgb, detail.a·diffuseAlpha)` — which VM2's live cdb read proved is the path real hardware runs (`m_caps.bCanDoSinglePassDetailing = 1`), not the two-pass `DESTCOLOR + INVSRCALPHA` fallback this row originally described. There is no viewer-depth fade: retail's `get_alpha_for_z` is unreachable for built meshes (`noFadeDetail = 1`); attenuation is the sampler's linear mip chain. acdream consumes the existing Building Detail Textures preference. The earlier experimental landscape array remains correctly reverted; there is no missing user-visible landscape pass to track. | `src/AcDream.App/Rendering/TerrainAtlas.cs`; `src/AcDream.App/Rendering/Wb/WbDrawDispatcher.Rhi.cs`; `src/AcDream.App/Rendering/Wb/EnvCellRenderer.Rhi.cs`; `src/AcDream.App/Rendering/Shaders/mesh_detail.vert`; `src/AcDream.App/Rendering/Shaders/mesh_detail.frag` | Retired on measured caller/category evidence and the connected on/off/restored visual gate; blend/fade re-ported on VM2's live cdb evidence. | None; disabling the preference submits no detail replay, while enabling it visibly changes nearby building/EnvCell surfaces (a mild darkening, not the earlier-assumed brightening). Landscape remains unchanged, matching the reachable retail caller. | `docs/research/2026-08-21-retail-building-detail-texturing-pseudocode.md`; `docs/research/2026-08-22-vm2-retail-detail-path-cdb.md`; `LScape::ChangeRegion`; `SmartBox::SetDetailTexturing`; issue #226 | | TS-53 | acdream advances retained UI time on the draw seam and local teleport/UI-camera presentation after its SmartBox-shaped object → inbound network → CommandInterpreter barrier. Retail `Client::UseTime` calls `UIElementManager::UseTime` first, whose global time message reaches `gmSmartBoxUI::UseTime`, and publishes player-camera work from the physics/player callback rather than one post-network camera tail. Slices 6–7 preserve the accepted host order as ownership-only extractions. | `src/AcDream.App/Update/UpdateFrameOrchestrator.cs` (post-live-frame teleport/camera phases); `src/AcDream.App/Rendering/PrivatePresentationRenderer.cs` (`RetainedGameplayUiFrame.Render`); `docs/plans/2026-07-21-gamewindow-slice-6-update-frame-orchestration.md`; `docs/plans/2026-07-22-gamewindow-slice-7-render-frame-orchestration.md` | Current retained UI, portal transit, reveal, camera, and connected movement traces are accepted; changing cross-subsystem host order while extracting ownership would combine a behavior change with the structural cutover. | Retained UI, teleport, and camera presentation can observe same-frame object/inbound/player state one host update earlier or later than retail at transition boundaries; a future exact host-order port must prove UI, input, reveal, and camera consequences together. | `Client::UseTime @ 0x00411C40`; `UIElementManager::UseTime`; `gmSmartBoxUI::UseTime @ 0x004D6E30`; `CPhysics::UseTime @ 0x00509950`; retire only with a focused host-order port and connected portal/camera comparison | | ~~TS-54~~ | **RETIRED 2026-08-08 (Campaign A slice A4).** The AdminEnvirons stingers now play. `UiSoundController.PlayEnvironCue` maps the change type through `EnvironSoundCueMap` — an EXPLICIT table read case-by-case out of `CPlayerSystem::Handle_Admin__Environs` @ `0x0055DE20` (`0x0055E0C6..0x0055E2C7`), not an offset: codes `0x65..0x72` sit 0x11 below their SoundType but `0x73`/`0x74` have no case at all, so `0x75` lands on `UI_Squeal` (0x84) where arithmetic would give 0x86, and the switch ends at `0x7B`/`UI_Thunder6` with no `0x7C` case. All 21 cases are pinned by conformance tests. The bank itself is no longer a blocker either: the UI sound table's DID is resolved by walking the dats' EnumIDMap chain (`UiSoundTableResolver`, master → slot-7 map → `0x2000004B`), which is how retail finds it — `GetUISoundTable` holds no literal. | retired | — | — | `CPlayerSystem::Handle_Admin__Environs @ 0x0055DE20`; `SoundManager::PlaySoundFromCenter @ 0x00550950`; `ClientUISystem::GetUISoundTable @ 0x00563FB0`; `docs/research/2026-08-08-audio-retail-music-absence.md` §5 | | TS-55 | AdminEnvirons fog values remain a color-only `WeatherSystem.Override` approximation. Retail values 1..5 install authored ambient color/level plus fog color/max; value 6 also forces transition/min/max and blanks radar; Clear restores all override fields and radar; `0x270F` installs a separate authored override. | `src/AcDream.App/World/WorldEnvironmentController.cs` (`ApplyAdminEnvirons`); `src/AcDream.Core/World/WeatherState.cs` (`EnvironOverrideColor`) | Preserves the already accepted enum bridge while Slice 8 moves ownership; porting the complete environment/radar presentation is a separate behavior change requiring focused visual gates. | Forced-fog hue, density, scene ambient, and radar blanking differ from retail; `0x270F` is ignored. | `CPlayerSystem::Handle_Admin__Environs @ 0x0055DE20` (`0x0055DE2B..0x0055E344`) | diff --git a/docs/research/2026-08-21-retail-building-detail-texturing-pseudocode.md b/docs/research/2026-08-21-retail-building-detail-texturing-pseudocode.md index b8f1cb98..0bf362d9 100644 --- a/docs/research/2026-08-21-retail-building-detail-texturing-pseudocode.md +++ b/docs/research/2026-08-21-retail-building-detail-texturing-pseudocode.md @@ -1,7 +1,14 @@ # Retail building and environment detail texturing — #226 port note -**Date:** 2026-08-21 -**Status:** IMPLEMENTED + CONNECTED-VISUAL-VERIFIED +**Date:** 2026-08-21 · **Amended:** 2026-08-22 (Campaign VM, VM1) +**Status:** IMPLEMENTED + CONNECTED-VISUAL-VERIFIED; re-ported to retail's +single-pass detail combine by VM1 after +[VM2's live cdb read](2026-08-22-vm2-retail-detail-path-cdb.md) proved real +hardware never takes the two-pass framebuffer fallback this note originally +described. The "Exact two-pass pseudocode" and "Brightening decision" +sections below are corrected in place; everything about the reachable +setting/caller chain, the authored source data, and material coverage is +unchanged and still applies. This note is the implementation handoff requested by #226. The measurements below come from the already-completed @@ -59,11 +66,17 @@ magnification, and mip filtering. Detail UV is `baseUv * tiling`. The port therefore uploads each live category as a one-layer RGBA8 texture array with a full mip chain and the existing repeat/linear world sampler. -## Exact two-pass pseudocode +## Exact single-pass pseudocode -Retail has both a single-pass multitexture route and a two-pass fallback. The -Vulkan port uses the fallback because it preserves the already-accepted base -pass byte-for-byte and expresses the retail framebuffer blend directly. +Retail has both a single-pass multitexture route and a two-pass framebuffer +fallback for adapters that cannot advertise `D3DTEXOPCAPS_PREMODULATE`. +[VM2's live cdb read](2026-08-22-vm2-retail-detail-path-cdb.md) on the +PDB-paired retail client found `m_caps.bCanDoSinglePassDetailing = 1` and the +file-static `trysinglepass = 1` on real (AMD) hardware, so +`D3DPolyRender::RenderMeshSubset` (`0x0059ca10`) never falls back for built +meshes — every loaded `CGfxObj` sets `use_built_mesh = 1` +(`CGfxObj::InitLoad` `0x005346b0`). The port below matches the path players +actually saw. ```text enabled = DisplaySettings.BuildingDetailTextures // existing setting; no new option @@ -83,31 +96,47 @@ for each replayed fragment: reject ordinary objects / landscape / scenery accept opaque, ClipMap, alpha, additive and inverse-alpha subsets - zMetres = positive_view_space_depth_in_metres - fade = clamp((50 m - zMetres) / (50 m - 10 m), 0, 1) - // full through 10 m; linear 10–50 m; exactly zero at/after 50 m + // No distance term. ACRender::get_alpha_for_z (0x006b6230) is only + // evaluated in D3DPolyRender::DrawPolyInternal (0x0059d7c0, the + // immediate-polygon path) and only when the static noFadeDetail + // (0x00820e38, initialised to 1) is 0 — unreachable for built meshes. + // Attenuation is the LINEAR mip chain converging to the texture mean. detail = sample(categoryTexture, baseUv * categoryTiling) - src.rgb = detail.rgb * fade - src.a = detail.a * fade + diffuseAlpha = base_subset_diffuse_alpha // 1 for opaque; the + // translucency-fade multiplier + // for a fading subset + // (tmpmaterial.Diffuse.a in + // RenderMeshSubset) + + // D3DPolyRender::SetSurface (0x0059c4d0) texture-stage setup: + // stage 0 colour = MODULATE(TEXTURE, DIFFUSE) = base.rgb * diffuse.rgb + // stage 0 alpha = PREMODULATE(DIFFUSE, DIFFUSE) = diffuseAlpha * detail.a + // stage 1 colour = BLENDCURRENTALPHA(TEXTURE, CURRENT) = lerp(current.rgb, detail.rgb, stage0.a) + src.rgb = detail.rgb + src.a = detail.a * diffuseAlpha depth test = EQUAL opaque; LESS_OR_EQUAL transparent depth write = preserve base class // ON opaque; OFF transparent alpha-to-coverage = OFF // detail alpha is blend input blend op = ADD - source = DEST_COLOR + source = SRC_ALPHA destination = ONE_MINUS_SRC_ALPHA ``` -Scaling **both** RGB and alpha by the fade is load-bearing. The resulting -framebuffer multiplier is: +The pixel this produces is `lerp(base * diffuse, detail.rgb, detail.a * +diffuseAlpha)` — a blend **toward** the detail colour by +`detail.a * diffuseAlpha`: ```text -factor = 1 + fade * (detail.rgb - detail.a) +result = base * (1 - detail.a * diffuseAlpha) + detail.rgb * (detail.a * diffuseAlpha) ``` -Thus fade zero is an exact no-op and the full-strength neutral point is -`detail.rgb == detail.a` channel-by-channel. It is not 0.5 gray. +`detail.a * diffuseAlpha == 0` is an exact no-op (fully-transparent detail +texel, or a translucency fade that has reached zero). At `detail.a * +diffuseAlpha == 1` the result is exactly the detail colour. There is no +"neutral gray" point — this is a lerp, not the fallback's multiplicative +`1 + fade * (detail.rgb - detail.a)` factor. ### Built-mesh material coverage and order @@ -147,19 +176,22 @@ change base coverage/blend/depth behavior; it avoids making the checkbox reorder the default transparent scene. The connected acceptance matrix must still exercise overlapping transparent building/EnvCell surfaces. -## Brightening decision +## Darkening, not brightening -The port keeps retail's `DEST_COLOR + ONE_MINUS_SRC_ALPHA` verbatim. The -findings measured factors **1.177**, **1.204**, and **1.033** for the three -Dereth textures; the live Dereth building/environment category uses the -1.033-factor texture. That slight brightening is intentional retail parity, -not an acceptance failure. - -Changing the destination factor to `ZERO` would be a visual correction rather -than a port. Exposing both behaviors behind one retail checkbox would also -make the option ambiguous. If a roughening-corrected material is wanted later, -it belongs as an explicitly named opt-in enhancement/shader-pack policy with a -registered divergence. It is not part of #226. +The earlier version of this note read the two-pass fallback's `DEST_COLOR + +ONE_MINUS_SRC_ALPHA` as retail's blend and reported the findings doc's +**1.177**, **1.204**, and **1.033** framebuffer-multiplier measurements for +the three Dereth textures as intentional retail brightening. VM2 showed that +factor formula belongs to the fallback only, which real hardware does not +run. The single-pass lerp above has the opposite sign: with the live +Dereth building/environment category texture (mean rgb 0.165, mean alpha +0.132) and opaque diffuse (`diffuseAlpha = 1`), the combine is +`≈ 0.868 × base + 0.022` — a mild **darkening** of roughly 10% on mid-tones, +not a brightening. This is retail's actual on-screen behavior on the +hardware the game shipped on; it is not a visual correction and carries no +opt-out. See +[`RetailDetailTextureContract`](../../src/AcDream.App/Rendering/RetailDetailTextureContract.cs) +and the VM2 note for the exact numbers. ## What the reverted experiment got wrong @@ -201,10 +233,15 @@ current Vulkan-only RHI. - Opaque object replay submits only command runs containing a building; mixed commands are filtered per instance. Depth equality inherits the base pass's per-sample ClipMap coverage without applying A2C to detail alpha. -- Detail is full through positive view depth 10 m, fades linearly over 10–50 - m, and is an exact no-op at and beyond 50 m. +- There is no distance fade (VM1, VM2): `noFadeDetail` gates + `get_alpha_for_z` to the immediate-polygon path only, which built meshes + never reach. Attenuation is the sampler's linear mip chain converging to + the texture mean; a building reads the same well past 50 m as it does at + 10 m, not a hard step. - Category source, 256 x 256 size, tiling 4, repeat addressing, and linear mip sampling match the measured Dereth data. -- The retail 1.033 live-category brightening is expected. There is no - `dst=ZERO` correction mode hidden behind the retail checkbox. +- The retail single-pass combine darkens the live category texture by + roughly 10% on mid-tones (VM2); this is expected. There is no + `dst=ZERO` correction mode and no brightening two-pass fallback hidden + behind the retail checkbox. - Physics, collision, walkability, and geometry are untouched. diff --git a/src/AcDream.App/Rendering/Gpu/GpuEnums.cs b/src/AcDream.App/Rendering/Gpu/GpuEnums.cs index d4396d9d..444daa9e 100644 --- a/src/AcDream.App/Rendering/Gpu/GpuEnums.cs +++ b/src/AcDream.App/Rendering/Gpu/GpuEnums.cs @@ -137,10 +137,13 @@ internal enum GpuBlendMode InverseAlpha, /// - /// Retail building/EnvCell detail overlay: - /// DstColor, OneMinusSrcAlpha. This intentionally preserves the - /// retail client's measured brightening; it is not a conventional - /// modulate/roughening blend. + /// Retail building/EnvCell detail overlay: SrcAlpha, + /// OneMinusSrcAlpha. VM2's live cdb read proved retail hardware runs + /// the single-pass texture-stage combine (D3DPolyRender::SetSurface + /// 0x0059c4d0), a lerp toward the detail colour by + /// detail.a * diffuse.a — a mild darkening on the live Dereth + /// category texture, not the two-pass DstColor fallback's + /// brightening. /// RetailDetail, } diff --git a/src/AcDream.App/Rendering/Gpu/Vk/VulkanViewportMapping.cs b/src/AcDream.App/Rendering/Gpu/Vk/VulkanViewportMapping.cs index d736a9ef..5e4a5819 100644 --- a/src/AcDream.App/Rendering/Gpu/Vk/VulkanViewportMapping.cs +++ b/src/AcDream.App/Rendering/Gpu/Vk/VulkanViewportMapping.cs @@ -175,9 +175,12 @@ internal static class VulkanViewportMapping GpuBlendMode.Additive => (BlendFactor.SrcAlpha, BlendFactor.One), // Retail's third mode, found at slice V4c in WbDrawDispatcher.ApplyRetailBlend. GpuBlendMode.InverseAlpha => (BlendFactor.OneMinusSrcAlpha, BlendFactor.SrcAlpha), - // ACRender::SetDetailSurfaceInternal with DrawBuilding/DrawEnvCell's - // category state: D3DBLEND_DESTCOLOR + D3DBLEND_INVSRCALPHA. - GpuBlendMode.RetailDetail => (BlendFactor.DstColor, BlendFactor.OneMinusSrcAlpha), + // VM2 (live cdb read, 2026-08-22): real hardware runs the single-pass + // texture-stage detail combine, not the two-pass DESTCOLOR fallback. + // D3DPolyRender::SetSurface's stage-1 BLENDCURRENTALPHA is a lerp + // toward the detail colour by detail.a * diffuse.a, which is the + // ordinary straight-alpha-over factor pair. + GpuBlendMode.RetailDetail => (BlendFactor.SrcAlpha, BlendFactor.OneMinusSrcAlpha), GpuBlendMode.None => (BlendFactor.One, BlendFactor.Zero), _ => throw new ArgumentOutOfRangeException(nameof(blend), blend, "Unknown blend mode."), }; diff --git a/src/AcDream.App/Rendering/RetailDetailTextureContract.cs b/src/AcDream.App/Rendering/RetailDetailTextureContract.cs index 613fbb8f..c647d5ab 100644 --- a/src/AcDream.App/Rendering/RetailDetailTextureContract.cs +++ b/src/AcDream.App/Rendering/RetailDetailTextureContract.cs @@ -5,15 +5,39 @@ namespace AcDream.App.Rendering; /// /// Testable CPU statement of retail's detail-pass gate and pixel math. The -/// production pixels are produced by mesh_detail; keeping these facts in -/// one small contract makes the setting, distance units, neutral point, and -/// intentional brightening independently assertable without a GPU. +/// production pixels are produced by mesh_detail; keeping these facts +/// in one small contract makes the setting and the combine independently +/// assertable without a GPU. +/// +/// VM2 (2026-08-22, live cdb read on the PDB-paired retail client, +/// docs/research/2026-08-22-vm2-retail-detail-path-cdb.md) settled +/// which of retail's two detail paths real hardware runs. Retail's +/// RenderDevice::render_device.m_caps.bCanDoSinglePassDetailing reads +/// 1 and the file-static trysinglepass reads 1, so +/// D3DPolyRender::RenderMeshSubset (0x0059ca10) never falls back to +/// the two-pass framebuffer blend the earlier #226 port reproduced; it takes +/// the single-pass texture-stage combine set up in +/// D3DPolyRender::SetSurface (0x0059c4d0): +/// lerp(base * diffuse, detail.rgb, detail.a * diffuse.a) — a blend +/// TOWARD the detail colour by detail.a * diffuse.a, not the +/// fallback's dest * (detail.rgb + 1 - detail.a). Built meshes light +/// with tmpmaterial.Diffuse.a = 1 for opaque subsets +/// (RenderMeshSubset), so on the live Dereth category texture (mean +/// rgb 0.165, mean alpha 0.132) the combine is a mild darkening +/// (≈ 0.868 * base + 0.022), the opposite sign of the fallback's +/// brightening. +/// +/// There is no distance fade on this path. Retail's +/// ACRender::get_alpha_for_z (0x006b6230) is only evaluated in +/// D3DPolyRender::DrawPolyInternal (0x0059d7c0, the immediate-polygon +/// path) and only when the static noFadeDetail (0x00820e38, +/// initialised to 1) is 0. Every loaded CGfxObj sets +/// use_built_mesh=1 (CGfxObj::InitLoad 0x005346b0), so buildings +/// and EnvCells never reach that function — their attenuation is the LINEAR +/// mip chain converging to the texture mean, not a scripted ramp. /// internal static class RetailDetailTextureContract { - internal const float FullDetailDistanceMetres = 10f; - internal const float ZeroDetailDistanceMetres = 50f; - internal static bool ShouldRender( bool settingEnabled, TerrainAtlas.RetailDetailTextureBinding binding) => @@ -29,19 +53,28 @@ internal static class RetailDetailTextureContract internal static GpuCompareOp DetailDepthCompare(bool transparent) => transparent ? GpuCompareOp.LessOrEqual : GpuCompareOp.Equal; - internal static float FadeForPositiveViewDepthMetres(float depthMetres) => - Math.Clamp( - (ZeroDetailDistanceMetres - depthMetres) - / (ZeroDetailDistanceMetres - FullDetailDistanceMetres), - 0f, - 1f); + /// + /// The exact pixel mesh_detail composites onto the existing + /// framebuffer colour: retail's single-pass stage-1 + /// BLENDCURRENTALPHA(TEXTURE, CURRENT), a lerp from + /// toward 's RGB by + /// detail.a * opacity. is the base + /// subset's diffuse alpha — 1 for an opaque subset, the translucency-fade + /// multiplier for a fading one — mirrored from the shader's + /// instanceAlpha[instanceIndex] read. + /// + internal static Vector3 Expected(Vector3 baseColour, Vector4 detail, float opacity) => + Vector3.Lerp( + baseColour, + new Vector3(detail.X, detail.Y, detail.Z), + detail.W * opacity); /// - /// Effective multiplier on the existing framebuffer after the shader - /// scales both detail RGB and alpha by fade and the pipeline applies - /// DstColor + OneMinusSrcAlpha. + /// True when the combine above is an exact no-op — either the detail + /// texel is fully transparent or the base subset's own diffuse alpha (the + /// translucency fade) has reached zero. Neutral is detail.a * opacity + /// == 0, not any particular colour equality. /// - internal static Vector3 FramebufferFactor(Vector4 detail, float fade) => - Vector3.One + fade * (new Vector3(detail.X, detail.Y, detail.Z) - - new Vector3(detail.W)); + internal static bool IsNeutral(Vector4 detail, float opacity) => + detail.W * opacity == 0f; } diff --git a/src/AcDream.App/Rendering/Shaders/mesh_detail.frag b/src/AcDream.App/Rendering/Shaders/mesh_detail.frag index 0ce6f64d..7a0ec49b 100644 --- a/src/AcDream.App/Rendering/Shaders/mesh_detail.frag +++ b/src/AcDream.App/Rendering/Shaders/mesh_detail.frag @@ -3,7 +3,7 @@ in vec2 vBaseUv; in vec2 vDetailUv; -in float vDetailFade; +in float vDetailOpacity; in flat uint vBaseTextureIndex; in flat uint vBaseTextureLayer; in flat uint vBatchFlags; @@ -13,6 +13,31 @@ uniform uint uTextureIndexA; // category detail texture, layer 0 out vec4 FragColor; +// VM2 (2026-08-22, live cdb read on the PDB-paired retail client, GUID +// 9e847e2f-777c-4bd9-886c-22256bb87f32): retail's RenderDevice reports +// m_caps.bCanDoSinglePassDetailing = 1 and the file-static trysinglepass = 1, +// so real hardware never takes the two-pass framebuffer fallback this shader +// used to reproduce. It takes the single-pass texture-stage combine set up +// in D3DPolyRender::SetSurface (0x0059c4d0) and consumed per built-mesh +// material subset by D3DPolyRender::RenderMeshSubset (0x0059ca10): +// +// stage 0 colour = MODULATE(TEXTURE, DIFFUSE) = base.rgb * diffuse.rgb +// stage 0 alpha = PREMODULATE(DIFFUSE, DIFFUSE) = diffuse.a * detail.a +// stage 1 colour = BLENDCURRENTALPHA(TEXTURE, CURRENT) = lerp(current.rgb, detail.rgb, stage0.a) +// +// i.e. the pixel retail draws is lerp(base * diffuse, detail.rgb, detail.a * +// diffuse.a) — a blend TOWARD the detail colour by detail.a * diffuse.a, not +// a "dest * (detail + 1 - alpha)" brightening. RenderMeshSubset lights every +// built mesh with tmpmaterial.Diffuse.a = 1 (opaque subsets), so +// vDetailOpacity below is exactly that diffuse.a — 1 for opaque, the +// translucency-fade multiplier for a fading subset. The pipeline blend +// (VulkanViewportMapping.BlendFactorsOf(GpuBlendMode.RetailDetail)) expresses +// the same lerp as SrcAlpha + OneMinusSrcAlpha over the existing base pixel, +// so this fragment outputs the raw (non-premultiplied) detail colour with +// that combined alpha and lets the fixed-function blend unit do the +// base*(1-a) + detail*a lerp. See +// docs/research/2026-08-22-vm2-retail-detail-path-cdb.md. + void main() { // Object command replays may contain ordinary instances; only building // shells survive. Bit 0 means this command came through retail's built-mesh @@ -20,8 +45,6 @@ void main() { // curr_detail_surface for every built-mesh material subset. if (vDetailCategory == 0u || (vBatchFlags & 1u) == 0u) discard; - if (vDetailFade <= 0.0) - discard; vec4 base = ACDREAM_SAMPLE_ARRAY( vBaseTextureIndex, @@ -33,10 +56,5 @@ void main() { uTextureIndexA, vec3(vDetailUv, 0.0)); - // Pipeline blend is retail's DstColor + OneMinusSrcAlpha. Scaling both - // source colour and alpha makes fade=0 exactly neutral while fade=1 keeps - // retail's measured factor: dest * (detail.rgb + 1 - detail.a). - FragColor = vec4( - detail.rgb * vDetailFade, - detail.a * vDetailFade); + FragColor = vec4(detail.rgb, detail.a * vDetailOpacity); } diff --git a/src/AcDream.App/Rendering/Shaders/mesh_detail.vert b/src/AcDream.App/Rendering/Shaders/mesh_detail.vert index c71e2e54..ad43ece2 100644 --- a/src/AcDream.App/Rendering/Shaders/mesh_detail.vert +++ b/src/AcDream.App/Rendering/Shaders/mesh_detail.vert @@ -44,6 +44,18 @@ layout(std430, binding = 9) readonly buffer InstanceDetailCategoryBuf { uint instanceDetailCategory[]; }; +// #188 per-instance opacity multiplier, identical binding and indexing to +// mesh_modern.vert's InstanceAlphaBuf (binding 7). VM2's cdb read proved +// retail's built-mesh detail combine is a single-pass texture-stage blend +// whose stage-0 alpha is PREMODULATE(DIFFUSE, DIFFUSE) = diffuse.a * +// detail.a (D3DPolyRender::SetSurface 0x0059c4d0) — the base subset's own +// diffuse alpha gates how much detail shows through, exactly like the base +// pass's translucency-fade multiplier already does for mesh_modern. 1.0 for +// every opaque subset; <1.0 while a TransparentPartHook fade is in flight. +layout(std430, binding = 7) readonly buffer InstanceAlphaBuf { + float instanceAlpha[]; +}; + out gl_PerVertex { vec4 gl_Position; float gl_ClipDistance[8]; @@ -57,7 +69,7 @@ uniform float uParamB; // 1 = require building instance, 0 = EnvCell category out vec2 vBaseUv; out vec2 vDetailUv; -out float vDetailFade; +out float vDetailOpacity; out flat uint vBaseTextureIndex; out flat uint vBaseTextureLayer; out flat uint vBatchFlags; @@ -76,11 +88,14 @@ void main() { for (uint i = clip.count; i < 8u; ++i) gl_ClipDistance[i] = 1.0; - // System.Numerics' perspective projection used by every gameplay camera - // makes clip.w the positive view-space depth. Retail get_alpha_for_z uses - // that same metric in metres: 255 through 10 m, linearly to 0 at 50 m. - float positiveViewDepthMetres = gl_Position.w; - vDetailFade = clamp((50.0 - positiveViewDepthMetres) / 40.0, 0.0, 1.0); + // No distance term: VM2 found the fade only exists in + // D3DPolyRender::DrawPolyInternal (0x0059d7c0, the immediate-polygon + // path) and only when the static noFadeDetail (0x00820e38, initialised + // to 1) is 0. Every loaded CGfxObj sets use_built_mesh=1 + // (CGfxObj::InitLoad 0x005346b0), so buildings/EnvCells never reach that + // function; their attenuation is the LINEAR mip chain converging to the + // texture mean, which the existing sampler already provides. + vDetailOpacity = instanceAlpha[instanceIndex]; vBaseUv = aTexCoord; vDetailUv = aTexCoord * uParamA; diff --git a/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.frag.spv b/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.frag.spv index 75674e4a..95f1748a 100644 Binary files a/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.frag.spv and b/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.frag.spv differ diff --git a/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.vert.spv b/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.vert.spv index 8a7e5999..033db8b4 100644 Binary files a/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.vert.spv and b/src/AcDream.App/Rendering/Shaders/spv/mesh_detail.vert.spv differ diff --git a/src/AcDream.App/Rendering/Shaders/spv/shaders.manifest.json b/src/AcDream.App/Rendering/Shaders/spv/shaders.manifest.json index 7184bd38..ed1abf25 100644 --- a/src/AcDream.App/Rendering/Shaders/spv/shaders.manifest.json +++ b/src/AcDream.App/Rendering/Shaders/spv/shaders.manifest.json @@ -231,12 +231,12 @@ "stages": [ { "stage": "vert", - "sourceSha256": "0273312da9fefb5084d3aee120f33c542e1adcfb846e6c7b3fc2b068c1348fb3", + "sourceSha256": "c955bdce56199ef2057dbaf0dc1d1f75ececac49047f57685b09b63117e921da", "compiled": true }, { "stage": "frag", - "sourceSha256": "1fbc3ffb12d260cbe0d111551f28c69f15754ba5e5e11fe3ec43747bebef4883", + "sourceSha256": "c02dd48647352a87c183fe925a9590b70731c677dd942bcea71ac6ad63ff486d", "compiled": true } ] diff --git a/tests/AcDream.App.Tests/Rendering/Gpu/Vk/VulkanViewportMappingTests.cs b/tests/AcDream.App.Tests/Rendering/Gpu/Vk/VulkanViewportMappingTests.cs index 77582eb7..29bb1219 100644 --- a/tests/AcDream.App.Tests/Rendering/Gpu/Vk/VulkanViewportMappingTests.cs +++ b/tests/AcDream.App.Tests/Rendering/Gpu/Vk/VulkanViewportMappingTests.cs @@ -146,8 +146,11 @@ public sealed class VulkanViewportMappingTests Assert.Equal( (BlendFactor.OneMinusSrcAlpha, BlendFactor.SrcAlpha), VulkanViewportMapping.BlendFactorsOf(GpuBlendMode.InverseAlpha)); + // VM2 (2026-08-22): real hardware runs the single-pass detail combine, + // a lerp expressed as the ordinary straight-alpha-over factor pair — + // not the two-pass DstColor fallback. Assert.Equal( - (BlendFactor.DstColor, BlendFactor.OneMinusSrcAlpha), + (BlendFactor.SrcAlpha, BlendFactor.OneMinusSrcAlpha), VulkanViewportMapping.BlendFactorsOf(GpuBlendMode.RetailDetail)); } diff --git a/tests/AcDream.App.Tests/Rendering/RetailDetailTextureContractTests.cs b/tests/AcDream.App.Tests/Rendering/RetailDetailTextureContractTests.cs index 8b488724..1e4bd303 100644 --- a/tests/AcDream.App.Tests/Rendering/RetailDetailTextureContractTests.cs +++ b/tests/AcDream.App.Tests/Rendering/RetailDetailTextureContractTests.cs @@ -34,57 +34,73 @@ public sealed class RetailDetailTextureContractTests } [Theory] - [InlineData(0f, 1f)] - [InlineData(10f, 1f)] - [InlineData(30f, 0.5f)] - [InlineData(50f, 0f)] - [InlineData(80f, 0f)] - public void DistanceFadeUsesPositiveViewDepthInMetres( - float depthMetres, - float expected) + [InlineData(0.1f, 0.2f, 0.3f)] + [InlineData(0.0f, 0.0f, 0.0f)] + [InlineData(1.0f, 1.0f, 1.0f)] + [InlineData(0.5f, 0.9f, 0.05f)] + public void ZeroDetailAlphaIsExactNoOp(float r, float g, float b) { + var baseColour = new Vector3(r, g, b); + var transparentDetail = new Vector4(0.9f, 0.1f, 0.7f, 0f); + Assert.Equal( - expected, - RetailDetailTextureContract.FadeForPositiveViewDepthMetres(depthMetres), - precision: 5); + baseColour, + RetailDetailTextureContract.Expected(baseColour, transparentDetail, opacity: 1f)); + Assert.True(RetailDetailTextureContract.IsNeutral(transparentDetail, opacity: 1f)); } [Fact] - public void FadeZeroIsExactNoOpAndNeutralRgbEqualsAlpha() - { - var brighteningSample = new Vector4(0.459f, 0.459f, 0.459f, 0.282f); - Assert.Equal( - Vector3.One, - RetailDetailTextureContract.FramebufferFactor(brighteningSample, fade: 0f)); - - var neutral = new Vector4(0.4f, 0.4f, 0.4f, 0.4f); - Vector3 neutralFactor = RetailDetailTextureContract.FramebufferFactor(neutral, fade: 1f); - Assert.Equal(1f, neutralFactor.X, precision: 5); - Assert.Equal(1f, neutralFactor.Y, precision: 5); - Assert.Equal(1f, neutralFactor.Z, precision: 5); - } - - [Fact] - public void RetailBlendPreservesMeasuredBrightening() - { - var measured = new Vector4(0.459f, 0.459f, 0.459f, 0.282f); - Vector3 factor = RetailDetailTextureContract.FramebufferFactor(measured, fade: 1f); - - Assert.Equal(1.177f, factor.X, precision: 5); - Assert.Equal(1.177f, factor.Y, precision: 5); - Assert.Equal(1.177f, factor.Z, precision: 5); - } - - [Fact] - public void EnabledDerethCategoryTextureKeepsItsMeasuredBrightening() + public void ZeroOpacityIsExactNoOp() { + var baseColour = new Vector3(0.5f, 0.5f, 0.5f); var derethCategory = new Vector4(0.165f, 0.165f, 0.165f, 0.132f); - Vector3 factor = RetailDetailTextureContract.FramebufferFactor( - derethCategory, - fade: 1f); - Assert.Equal(1.033f, factor.X, precision: 5); - Assert.Equal(1.033f, factor.Y, precision: 5); - Assert.Equal(1.033f, factor.Z, precision: 5); + // opacity 0 models a translucency fade that has finished disappearing: + // even a fully-opaque detail texel contributes nothing. + Assert.Equal( + baseColour, + RetailDetailTextureContract.Expected(baseColour, derethCategory, opacity: 0f)); + Assert.True(RetailDetailTextureContract.IsNeutral(derethCategory, opacity: 0f)); + } + + [Fact] + public void LiveDerethCategoryTextureDarkensMidtones() + { + // Live category texture 0x06006D58 (VM2), opaque diffuse (opacity 1). + var detail = new Vector4(0.165f, 0.165f, 0.161f, 0.132f); + var baseColour = new Vector3(0.5f, 0.5f, 0.5f); + + Vector3 result = RetailDetailTextureContract.Expected(baseColour, detail, opacity: 1f); + + Assert.True(result.X < baseColour.X); + Assert.True(result.Y < baseColour.Y); + Assert.True(result.Z < baseColour.Z); + + // lerp(base, detail.rgb, 0.132) ~= 0.868 * base + 0.0218 per channel — + // the mild darkening VM2 measured, not the two-pass fallback's + // brightening. Compared as an absolute difference (not xunit's + // decimal-rounding `precision` parameter, which would flip a channel + // sitting on a rounding boundary) against the stated 1e-3 tolerance. + float approx = 0.868f * baseColour.X + 0.0218f; // same for every channel: baseColour is uniform + Assert.True(MathF.Abs(result.X - approx) < 1e-3f, $"R off by {result.X - approx}"); + Assert.True(MathF.Abs(result.Y - approx) < 1e-3f, $"G off by {result.Y - approx}"); + Assert.True(MathF.Abs(result.Z - approx) < 1e-3f, $"B off by {result.Z - approx}"); + Assert.False(RetailDetailTextureContract.IsNeutral(detail, opacity: 1f)); + } + + [Fact] + public void FullAlphaReplacesBaseWithDetailColour() + { + var baseColour = new Vector3(0.9f, 0.1f, 0.4f); + var detail = new Vector4(0.2f, 0.3f, 0.4f, 1f); + + Vector3 result = RetailDetailTextureContract.Expected(baseColour, detail, opacity: 1f); + + // Tolerance rather than bit-exact equality: Lerp's `a + (b - a) * t` + // form is not guaranteed to cancel `a` perfectly at t=1 in floating + // point for arbitrary inputs. + Assert.True(MathF.Abs(result.X - detail.X) < 1e-6f); + Assert.True(MathF.Abs(result.Y - detail.Y) < 1e-6f); + Assert.True(MathF.Abs(result.Z - detail.Z) < 1e-6f); } }