Symptoms

Two UI screens on macOS display broken transparency/alpha blending in Beta 4 that worked correctly in Beta 3:

1. General Challenge Selection Screen (ChallengeLoadScreen):

   • The "Versus" animation overlay (m_overlayVs) between the two general portraits appears opaque/invisible instead of semi-transparent
   • Alpha-blended circular reticle overlays (m_overlayReticleCircleAlphaOuter, m_overlayReticleCircleAlphaInner) do not render with correct transparency

2. Skirmish Loading Screen Minimap:

   • The minimap overlay showing initial unit positions and resource locations renders with incorrect alpha/transparency
   • Visual appearance suggests alpha blending is not being applied or is being reset to opaque

Platform: macOS only (ARM64 Apple Silicon)
Regression: Beta 3 (working) → Beta 4 (broken)
Linux: Confirmed working (no regression)

Root Cause Analysis - Hypothesis

Investigation Areas

1. W3D Shader Manager Alpha Blend State:

   • Check Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DShaderManager.cpp for recent changes to alpha blend enable/disable state (D3DRS_ALPHABLENDENABLE, D3DRS_SRCBLEND, D3DRS_DESTBLEND)
   • Verify blend state is properly restored after each render pass, especially for UI overlays

2. DXVK macOS Render Target / Blend State Persistence:

   • Review DXVK fork branch generalsx-macos-v2.6 for recent changes to render target setup or blend state management
   • Check if MoltenVK translation of Vulkan blend states to Metal is incorrect or incomplete
   • Verify that blend state set via D3D8 wrapper is actually reaching Metal render encoder on macOS

3. UI Gadget Window Rendering Pipeline:

   • The challenge screen and minimap use W3D gadget/window rendering (not 3D scene)
   • Investigate GameWindow / GadgetWindow rendering code for how alpha blending is initialized and maintained
   • Verify that UI render passes properly set and restore blend state (particularly for overlays)

4. Cross-Platform Render Context State Synchronization:

   • Beta 4 may have introduced changes to how render state is cached or reset between render passes
   • macOS Metal backend may not handle implicit state recovery the same way as Windows DirectX or Linux Vulkan
   • Check for any changes to DX8Wrapper or platform-specific render device initialization between Beta 3→4

5. Recent Commits Affecting Rendering (Beta 3→4 timeframe):

   • Fullscreen resolution/backbuffer fixes (April 2026 diary entries)
   • Shader manager initialization or state cache changes
   • W3D display or render device setup changes
   • DXVK version/fork branch updates

Expected Behavior

• General challenge screen: Versus animation and reticle overlays display with semi-transparent alpha blending, allowing visibility of background elements
• Skirmish loading minimap: Overlay elements (position markers, resource indicators) display with correct transparency without obscuring underlying map
• All transparency effects render identically on macOS, Linux, and Windows

Investigation Checklist

• Compare GeneralsX/references/fbraz3-dxvk branch generalsx-macos-v2.6 between current and working beta 3 state (if available)
• Trace ChallengeLoadScreen::init() → activatePieces() render path for blend state management
• Check minimap rendering code (minimap window class, map display rendering) for alpha blend state setup
• Audit W3DShaderManager recent commits for changes to D3DRS_ALPHABLENDENABLE or related blend state
• Verify DXVK render target setup on macOS does not reset blend mode unexpectedly
• Test with local DXVK fork source (-DSAGE_DXVK_USE_LOCAL_FORK=ON) to isolate DXVK-side issues
• Compare Beta 3 and Beta 4 git history for D3D render state / shader changes

Files Likely Involved

• Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DShaderManager.cpp (blend state management)
• Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp (render device setup/reset)
• Core/GameEngine/Source/GameClient/GUI/LoadScreen.cpp (ChallengeLoadScreen rendering)
• Core/GameEngineDevice/Source/dx8wrapper.cpp (D3D8 state wrapper)
• references/fbraz3-dxvk/src/dxvk/ (DXVK blend state pipeline - if macOS-specific issue)

Acceptance Criteria

1. Challenge screen Versus animation and reticles render with visible semi-transparency
2. Skirmish loading minimap overlay elements display with correct alpha blending
3. macOS rendering matches Linux and Windows visual output for transparency effects
4. No regression of other macOS rendering (terrain, units, particle effects, etc.)

Related Issues

• (If applicable) Issue Crash when clicking Load Game/Replay in main menu #52 (macOS save/load regression - recently fixed)
• (If applicable) Issue #XX (fullscreen regression from pillarbox/ultrawide merge)