---
phase: 05-native-addon-and-dwm-capture
plan: 02
subsystem: native-addon
tags: [native, cpp, dwm-shared-surface, capture, async-worker, d3d11]
dependency_graph:
  requires: [native-addon-binary, d3d11-device-singleton, png-encoder]
  provides: [dwm-capture-pipeline, captureWindow-implementation]
  affects: [05-03-PLAN]
tech_stack:
  - { name: "DwmGetDxSharedSurface", role: "DWM shared surface capture (from user32.dll)" }
  - { name: "D3D11", role: "Texture copy and staging readback" }
  - { name: "stb_image_write", role: "BGRA-to-RGBA + PNG encoding" }
  - { name: "Napi::AsyncWorker", role: "Off-main-thread capture execution" }
---

# Plan 05-02 Summary: DWM Shared Surface Capture Pipeline

## What was built

Implemented the DwmGetDxSharedSurface capture pipeline — the same API used by OBS Studio and AutoHotKey for flicker-free, occlusion-immune window capture. Originally planned as Windows.Graphics.Capture (WGC), pivoted by user decision to avoid WGC's yellow capture border and reduce implementation complexity.

## Key files

### Created
- `native/src/capture.cpp` — Full pipeline: DwmGetDxSharedSurface lookup from user32.dll, shared surface handle → D3D11 OpenSharedResource → staging texture CopyResource → Map → BGRA-to-PNG encoding. SEH wrapper for crash protection.
- `native/src/capture.h` — CaptureWorker class declaration (Napi::AsyncWorker subclass)

### Modified
- `native/src/addon.cpp` — CaptureWindow wired to dispatch CaptureWorker, isAvailable checks both D3D11 and DwmGetDxSharedSurface presence
- `native/CMakeLists.txt` — Dropped to C++17 (no WinRT needed), removed windowsapp.lib dependency

## Deviations

- **API pivot (user decision):** Replaced WGC with DwmGetDxSharedSurface. User preferred the proven OBS/AHK approach — no yellow border, simpler code, battle-tested stability.
- **C++17 instead of C++20:** DwmGetDxSharedSurface doesn't use WinRT, so no coroutine headers needed.
- **No COM/WinRT initialization:** DwmGetDxSharedSurface is a plain Win32 function, no RoInitialize needed per thread.

## Verification

- Addon compiles and loads successfully
- `isAvailable()` returns true (D3D11 + DwmGetDxSharedSurface both present)
- `captureWindow(hwnd)` on Notepad++ returns valid 241KB PNG (1179x1218)
- Invalid HWND (99999) correctly rejected with error
- Zero HWND correctly rejected with error
- No yellow capture border in output image
- PNG signature verified (89504e47)

## Self-Check: PASSED