Viewer: replace GDI window presentation with a DXGI flip-model swap chain

[chammoru]

Context

Issue #88 exposed horizontal seams that mix adjacent video frames while the Viewer copies a large GDI back buffer into the window. The symptom is most visible with tall/portrait video in a large window on a 4K display and does not appear while paused.

Commit 6a50e71 is the currently verified mitigation: during playback it performs a second GdiFlush() + DwmFlush() after the final window BitBlt(). This stopped the artifact on the affected 4K system, but it deliberately waits for an additional desktop-composition interval. On a 60 Hz display that extra pacing can reduce high-frame-rate presentation throughput and cause playback frame drops.

The long-term fix should stop copying a large, changing GDI surface into a compositor-owned window surface and present completed frames through a DXGI flip-model swap chain instead.

Goal

Use a complete swap-chain buffer as the atomic unit of window presentation so that:

• adjacent video frames cannot be mixed by DWM sampling during a large GDI BitBlt();
• 24, 30, and 60 fps playback can use one synchronized present per displayed frame;
• the double-DwmFlush() mitigation can be removed;
• existing Viewer visuals and interactions remain unchanged.

Non-goals for the first phase

• Rewriting scaling, colour conversion, overlays, or text rendering as GPU shaders.
• Replacing every GDI drawing helper with Direct2D immediately.
• Enabling unsynchronized DXGI_PRESENT_ALLOW_TEARING.
• Changing playback scheduling, decoding, or audio synchronization except where required to integrate presentation.

Proposed architecture

1. Preserve the existing off-screen renderer

Keep the current OnDraw() composition order and GDI helpers for the first phase: canvas background, scaled image, selection rectangles, coordinates, box information, progress/volume UI, and empty state.

Replace the compatible CBitmap back buffer with a top-down 32-bit BGRA DIB section. This provides stable CPU-visible pixels and allows existing GDI operations to continue drawing into the memory DC.

No GDI drawing should target the Viewer HWND once flip-model presentation is active. Microsoft explicitly requires a flip-model HWND not to mix GDI and DXGI updates.

2. Add a D3D11/DXGI presentation backend

Create one presentation backend owned by CViewerView and used only on the UI thread:

• D3D11 device with D3D11_CREATE_DEVICE_BGRA_SUPPORT;
• DXGI factory and one swap chain for the Viewer HWND;
• DXGI_FORMAT_B8G8R8A8_UNORM;
• DXGI_SWAP_EFFECT_FLIP_DISCARD where supported, with FLIP_SEQUENTIAL as the compatibility alternative;
• two or three buffers, sample count 1, windowed mode;
• a CPU-uploadable texture matching the current client size.

The project already targets Windows 10, so DXGI 1.2 flip-model APIs are within the supported platform baseline.

3. Present a completed frame

The playback paint path should be:

1. Adopt the newest queued RGB frame using the current buffer-ownership rules.
2. Render the complete Viewer frame into the BGRA DIB section using the existing off-screen GDI path.
3. Map/update the D3D11 upload texture and copy the complete BGRA image.
4. Copy that texture into the current DXGI back buffer.
5. Call Present(1, 0).
6. Return the previously displayed decoded buffer to the pool only according to the existing stable-buffer lifetime rules.

A swap-chain buffer is not reused until DXGI owns and schedules the completed buffer. This removes the large window-DC BitBlt(), GdiFlush(), and DwmFlush() calls from the normal DXGI path.

4. Resize and lifecycle

• Create device-independent resources once and size-dependent buffers lazily.
• On WM_SIZE, release references to swap-chain buffers, call ResizeBuffers(), and recreate the upload texture/back-buffer references.
• Skip presentation for zero-sized/minimized clients.
• Release all device and swap-chain resources from the view lifecycle on the UI thread.
• Keep printing or non-window OnDraw() targets on the existing GDI path.

5. Device loss and fallback

Handle DXGI_ERROR_DEVICE_REMOVED, DXGI_ERROR_DEVICE_RESET, resize failures, unsupported adapters, Remote Desktop limitations, and initialization failures.

If DXGI cannot be initialized or recovered, fall back to the current verified GDI presentation path including the #88 double-composition-wait mitigation. The fallback should be visible in debug logging so test reports identify which backend was active.

6. Optional Direct2D follow-up

Direct2D is not required for the first phase. After DXGI presentation is proven, Direct2D can render text and vector overlays directly into the DXGI surface, and image scaling can later move to a GPU texture/shader path. Those optimizations should be separate changes so the initial migration remains visually comparable and easy to revert.

Implementation phases

Phase A: backend and guarded integration

• Introduce a small DXGI presenter class with RAII-managed COM resources.
• Add required d3d11.lib and dxgi.lib project dependencies.
• Add the BGRA DIB-section back buffer.
• Integrate DXGI presentation behind a runtime/developer switch.
• Preserve the GDI fallback.

Phase B: validation and default enablement

• Produce a branch artifact.
• Verify the DXGI backend on the Viewer: possible horizontal tearing during video playback after back-buffer reuse #88 4K reproduction system.
• Compare frame cadence and CPU/GPU use against the 6a50e71 build.
• Enable DXGI by default only after all acceptance criteria pass.

Phase C: cleanup

• Remove the double-DwmFlush() workaround from the default DXGI path.
• Retain it only in the GDI fallback.
• Consider Direct2D overlays and GPU scaling as follow-up work based on profiling.

Acceptance criteria

• No horizontal seam on the original Viewer: possible horizontal tearing during video playback after back-buffer reuse #88 tall/portrait 4K reproduction case.
• No seam in large-window and full-screen playback at 24, 30, and 60 fps.
• 60 fps content is not systematically limited to roughly 30 displayed frames per second.
• Pause, resume, end-of-stream, seeking, and playback-rate changes remain correct.
• Image scaling, progress/volume UI, selection rectangles, coordinates, box information, and empty-state rendering match the current Viewer.
• Repeated resize, minimize/restore, full-screen transitions, DPI changes, and movement between monitors do not produce stale frames, flashes, device errors, or crashes.
• DXGI device loss either recovers cleanly or activates the verified GDI fallback.
• Core regression tests pass; Viewer and Comparator Release x64 builds remain clean.
• A final artifact is verified on the affected company 4K system before merging.

References

• Viewer: possible horizontal tearing during video playback after back-buffer reuse #88
• Verified mitigation: 6a50e71cf9b2bf26ec52c29bc4eb89ebfccc2e85
• Microsoft: DXGI flip model
• Microsoft: For best performance, use DXGI flip model
• Microsoft: Direct2D and Direct3D interoperability

[chammoru]

Implementation and local acceptance result / 구현 및 로컬 검증 결과

Draft PR: #92
Branch: agent/issue-90-dxgi-presenter
Commit: 80ad6a27070fed589adcac88db991ff98a40d317
Windows package workflow: https://github.com/chammoru/Q1View/actions/runs/32144807348
Artifact: Q1View-windows-x64 (165,489,176 bytes, expires 2026-11-16)

English

The first implementation phase is complete on the draft branch:

• The Viewer still composes its complete frame with the existing GDI helpers, but now does so in a top-down 32-bit BGRA DIB section.
• A UI-thread-owned D3D11/DXGI presenter uploads that completed image and presents it with an HWND flip-model swap chain (FLIP_DISCARD, with FLIP_SEQUENTIAL compatibility fallback).
• The normal DXGI path no longer performs the HWND BitBlt or either DwmFlush.
• Initialization, resize, upload, or Present failure tears down DXGI and activates the verified Viewer: possible horizontal tearing during video playback after back-buffer reuse #88 GDI path. Q1VIEW_DISABLE_DXGI=1 also selects that fallback for A/B testing.
• Unrotated OpenCV BGR video with no postprocessor now decodes directly into the playback pool buffer. Profiling showed that the old redundant full-frame copy cost about 6 ms per 1080p frame and prevented stable 59.94 fps playback even after the DXGI migration.
• Q1VIEW_TRACE_PLAYBACK=1 enables opt-in backend, displayed/dropped-frame, paint, and decoder timing diagnostics.

Representative file: C0610_main.mp4 (Sony ZV-1F, 1920×1080 HEVC Main, 60000/1001 fps, 11,700 frames, 195.195 s).

Path	Test duration	Displayed frames	Dropped frames	Effective display rate
Verified GDI fallback	30.127 s	793	1,008	26.32 fps
Final DXGI path, complete file	195.197 s	11,675 of 11,699 follow-up frames	24 (0.21%)	59.81 fps

Full-run averages were 9.999 ms for CPU composition, 2.848 ms for DXGI upload/Present, and 9.653 ms for OpenCV read. EOF occurred at 195.197 s and preserved the correct last frame.

Actual Viewer UI checks passed for exact paused-frame pixel stability, pause/resume, one-frame right/left stepping (returning left reproduced the original paused image byte-for-byte), synchronized playback between two Viewer processes, EOF, repeated resize, minimize/restore, full-screen enter/exit, and the existing GDI fallback. A generated 642×360 59.94 fps H.264 long-GOP video also displayed all 179 follow-up frames with zero drops, validating the direct-decode path with a non-DWORD-aligned source width.

Local Core regression tests passed. Viewer Release x64 was fully rebuilt with 0 warnings/0 errors, Comparator Release x64 built with 0 warnings/0 errors, and all completed PR checks are passing. The Windows Actions artifact contains the signed EXE/ZIP/MSIX test packages.

The issue remains open and PR #92 remains draft because the original #88 tall/portrait seam must still be tested on the affected company 4K display. Please test the default DXGI path first, then optionally launch the same build with Q1VIEW_DISABLE_DXGI=1 for a direct fallback comparison. Also exercise 24/30/59.94 fps playback, large window/full screen, repeated resize, and pause/resume.

한국어

Draft 브랜치에 1차 구현과 로컬 검증을 완료했습니다.

• 기존 GDI 도우미와 합성 순서는 유지하되, 전체 화면을 top-down 32비트 BGRA DIB section에 완성합니다.
• UI 스레드가 소유하는 D3D11/DXGI presenter가 완성된 화면을 업로드하고 HWND flip-model swap chain으로 원자적으로 표시합니다.
• 기본 DXGI 경로에서는 창 DC로의 BitBlt와 두 번의 DwmFlush가 모두 제거됩니다.
• 초기화·리사이즈·업로드·Present가 실패하면 DXGI를 완전히 해제하고 #88에서 검증된 GDI 경로로 돌아갑니다. Q1VIEW_DISABLE_DXGI=1을 사용하면 같은 빌드에서 GDI 경로를 강제로 선택해 비교할 수 있습니다.
• 회전과 별도 후처리가 없는 OpenCV BGR 영상은 playback pool 버퍼로 직접 디코딩합니다. 기존의 불필요한 1080p 전체 프레임 복사가 프레임당 약 6 ms를 소비해 DXGI 적용 후에도 59.94 fps를 방해한다는 프로파일 결과에 따른 최적화입니다.
• Q1VIEW_TRACE_PLAYBACK=1로 backend, 표시/드롭 프레임, paint, decoder 시간을 선택적으로 기록할 수 있습니다.

대표 영상 C0610_main.mp4 전체를 재생한 결과, 195.197초 동안 후속 11,699프레임 중 11,675프레임을 표시했고 24프레임(0.21%)만 드롭하여 실효 표시 속도 약 59.81 fps를 기록했습니다. 같은 빌드의 GDI fallback은 30.127초 동안 793프레임, 약 26.32 fps였습니다. 즉 기존 약 30fps 상한이 제거됐습니다.

일시정지 프레임의 픽셀 고정, pause/resume, 좌우 한 프레임 이동과 원래 프레임으로의 정확한 복귀, 두 Viewer 동기 재생, EOF, 반복 리사이즈, 최소화/복원, 전체화면 진입/복귀, GDI fallback을 실제 Viewer UI로 확인했습니다. 642×360 59.94 fps H.264 long-GOP 테스트 영상도 비정렬 폭의 직접 디코딩 경로에서 후속 179프레임을 드롭 없이 표시했습니다. Core 회귀 테스트와 Viewer/Comparator Release x64 빌드도 모두 통과했습니다.

다만 현재 모니터가 1080p이므로 원래 #88의 세로/고해상도 영상 seam은 최종 판정할 수 없습니다. 회사 4K 시스템에서 Actions 아티팩트의 기본 DXGI 경로로 먼저 재현 장면을 확인하고, 필요하면 Q1VIEW_DISABLE_DXGI=1 GDI fallback과 비교해 주세요. 24/30/59.94 fps, 큰 창/전체화면, 반복 리사이즈, pause/resume도 함께 확인한 뒤 #90을 닫고 PR을 병합하는 것이 안전합니다.