Skip to content

MIGRATION.md

Latest commit

 

History

History
118 lines (98 loc) · 5.87 KB

MIGRATION.md

File metadata and controls

118 lines (98 loc) · 5.87 KB
Raw

Migrating from vibranceGUI 2.x

vibranceGUI 2026 (3.0) is a rewrite. Most things just carry over; this page lists what moves automatically and what does not.

Automatic

On first start, the new app looks for the legacy files in %APPDATA%\vibranceGUI (or VIBRANCEGUI_DATA_DIR when set):

  • vibranceGUI.ini — desktop/in-game levels and global flags
  • applicationData.xml — the profile list (name, exe path, in-game level, resolution-change request)

Migration converts legacy NVIDIA levels (0..63 native) to vendor-neutral percent and writes settings.json. The legacy files are left in place — nothing is deleted or overwritten.

Behaviour changes to be aware of

  • Never change resolution is ON by default. Per-game resolution profiles keep working, but they only apply if you untick the global switch and the profile opts in — deliberate, because resolution switching historically caused games to jump monitors (#134).
  • Autostart is not carried over. The old Run registry entry points at the v2 exe path, so v3 reports it as disabled instead of hijacking it; re-enable via Start with Windows.
  • x64 only. There is no 32-bit build; the OS requirement is Windows 10 22H2 / Windows 11 x64.
  • vibranceDLL.dll is gone. The managed code now calls nvapi64.dll / atiadlxx.dll directly. If you still have a vibranceDLL.dll in %APPDATA%\vibranceGUI, you can delete it — v3 never touches it.
  • --force-nvidia / --force-amd flags were kept.

Dropped

  • Gamma / color settings from the 2.5.0 pre-release line are not carried over — the DVC APIs only cover vibrance, and the extra surface wasn't worth the driver risk.
  • vibranceGUI's own installer / updater. The new update check is opt-in and read-only (GitHub Releases query; nothing is downloaded).

Developer section

Architecture map

vibranceGUI.sln (x64 only)
├── src/VibranceGui.Core              net10.0            vendor-neutral domain
│    ├── Profile, AppSettings, ProfileMatcher, LevelPercent
│    ├── ILevelScale (LinearLevelScale, NvidiaLevelScale)
│    ├── Gpu/:  IVibranceBackend, DisplayTarget, BackendError, LevelRange
│    ├── Platform/: IForegroundSource, IProcessExitWatcher, IPowerSessionEvents,
│    │              IAutostartManager, IResolutionSwitcher, HotkeyGesture, IDisplayInfo
│    ├── Settings/: JsonSettingsStore (source-generated JSON), LegacySettingsMigrator,
│    │              ProfileTransfer (import/export)
│    └── Control/: VibranceController, VibranceState, IRecoveryMarker
│         (FileRecoveryMarker = restore-pending.json, InMemoryRecoveryMarker)
├── src/VibranceGui.Gpu.Nvidia        net10.0-windows    NvApi → nvapi64.dll,
│    NvidiaVibranceBackend (scale derived from GetDVCInfoEx range, 0..63 fallback)
├── src/VibranceGui.Gpu.Amd           net10.0-windows    Adl → atiadlxx.dll (ADL2→ADL),
│    AmdVibranceBackend
├── src/VibranceGui.Platform.Win32    net10.0-windows    ProcessInfo, ProcessExitWatcher,
│    Monitors, DisplayInfo(HDR), MessageLoopThread, ForegroundWatcher, HotkeyManager,
│    PowerSessionEvents, AutostartManager, SingleInstance, ResolutionSwitcher,
│    TopLevelWindows, WindowIcon, RotatingFileLoggerProvider
├── src/VibranceGui.App               net10.0-windows    WPF + Fluent dark theme,
│    tray (H.NotifyIcon), MVVM (CommunityToolkit.Mvvm), en/it satellites,
│    Bootstrapper composition root, UpdateChecker
├── tools/VibranceGui.NvProbe                          console diagnostics
└── tests/                            Core / Platform / App test projects

Data flow: ForegroundWatcher (WinEvent, out-of-context) → 150 ms debounce → VibranceController.HandleForeground (on the watcher consumer thread, never the UI thread) → profile match → IVibranceBackend.TrySetLevel per display → state changes surface to the UI via StateChanged/BackendErrorOccurred.

Design decisions

  • WPF + Fluent dark theme — modern look, stays close to the WinForms-era single-window UX, and ThemeMode=Dark (a .NET 9+ experimental API, hence the WPF0001 suppression) gives us the theme for free.
  • No native wrapper DLL — nvapi64.dll is called directly via its nvapi_QueryInterface entry point (undocumented but stable IDs, centralised in NvApi); ADL via NativeLibrary. One less binary to ship and the last .NET Framework / v140_xp blocker disappears.
  • Events + debounce instead of polling — a WinEvent hook delivers foreground changes; a 150 ms channel debounce coalesces bursts and suppresses same-window repeats. This is the #156 mitigation.
  • Level normalisation — the core works in 0..100 percent; each backend converts through ILevelScale. NVIDIA uses the driver-reported Ex range (0..100 on current drivers) and falls back to the legacy 0..63 table; AMD uses the ADL-reported saturation range. Profiles therefore travel across vendors in import/export.
  • Guaranteed restore — every non-desktop write records the touched displays in restore-pending.json; startup heals them. Process exit, suspend, session lock/end, reset and dispose all funnel through the same restore path.
  • Anti-cheat posture — out-of-context WinEvent hook only, PROCESS_QUERY_LIMITED_INFORMATION/SYNCHRONIZE only; no PROCESS_VM_READ, no keyboard/mouse hooks, nothing injected.

NvProbe

tools/VibranceGui.NvProbe is the diagnostic console:

dotnet run --project tools/VibranceGui.NvProbe            # enumerate + read DVC
dotnet run --project tools/VibranceGui.NvProbe -- --test  # +1 step, read-back, restore
dotnet run --project tools/VibranceGui.NvProbe -- --set 80
dotnet run --project tools/VibranceGui.NvProbe -- --amd   # AMD diagnostic only

Exit codes: 0 ok · 1 init failure · 2 --amd without driver · 3 no NVIDIA driver / read-back mismatch.