===============================================================================
 Sub Control — System Requirements (final build)
===============================================================================

Sub Control is a real-time screen-overlay censoring engine. It captures one monitor,
runs on-device vision/audio inference (NSFW/OCR/etc.), and composites effects
back onto a topmost, click-through overlay that excludes itself from capture.

This file lists what an end user needs to RUN a release build on each desktop
platform. Build-from-source notes are at the bottom.

License: proprietary — see the LICENSE file; third-party component licenses
are collected in THIRD-PARTY-LICENSES.md (both ship with every artifact).

Version: 0.1.0
Supported desktop targets: Windows (shipping), Linux (shipping),
                           macOS (in progress — see notes).


-------------------------------------------------------------------------------
 COMMON REQUIREMENTS (all platforms)
-------------------------------------------------------------------------------

- 64-bit OS and CPU (x86-64; Apple Silicon on macOS).
- A GPU that supports a modern graphics API (Vulkan / Direct3D 12 / Metal).
  Rendering, the tile-diff compositor, and the WGSL effect library all run on
  the GPU via wgpu — there is no software-render fallback intended for shipping.
- ~2 GB free disk for the app plus downloaded model weights. Detector, OCR, and
  (optional) Whisper models are fetched on first use, verified by SHA-256, and
  cached, so an INTERNET CONNECTION IS REQUIRED ON FIRST RUN (and whenever a new
  model/quality tier is selected). Weights are pulled from GitHub release assets.
- 8 GB RAM minimum; 16 GB recommended (more for higher inference quality tiers
  and GPU inference).
- Inference runs on the CPU by default (ONNX Runtime CPU execution provider,
  always available). GPU inference is optional and platform-specific (below).
- Audio modalities (speech-to-text via Whisper) are opt-in and CPU-only unless a
  GPU build is used.


-------------------------------------------------------------------------------
 WINDOWS
-------------------------------------------------------------------------------

Status: Supported.

OS:
  - Windows 10 version 2004 (build 19041) or newer, or Windows 11.
    (Windows.Graphics.Capture is used for capture, and the overlay's
     self-exclusion relies on WDA_EXCLUDEFROMCAPTURE, which requires 2004+.)

GPU / graphics:
  - Direct3D 12–capable GPU (feature level 11_0 or higher) with current drivers.
  - GPU inference uses DirectML and works on NVIDIA AND AMD out of the box —
    NO CUDA installation required. The needed DirectML.dll is bundled with the
    build. Falls back to CPU if no compatible device is present.
  - NVIDIA only, optional: Settings -> Detection -> GPU acceleration installs
    NVIDIA's CUDA/cuDNN runtime with one click (~1.5 GB download, ~2.2 GB on
    disk, kept beside the downloaded models and removable from the same row).
    Text detection runs several times faster on it. Nothing is installed
    system-wide, no Python or CUDA toolkit is involved, and Sub Control works fully
    without it. AMD and Intel GPUs are already at their platform's ceiling on
    DirectML, so the option is not shown there.
    Advanced: DROP_CUDA_DIR still points the loader at your own CUDA/cuDNN
    directories instead; scripts\setup-cuda-win.ps1 (the old pip-wheel route)
    remains for development and CI.

Runtime components:
  - Microsoft Edge WebView2 Runtime (used by the control panel).
    Pre-installed on Windows 11; many Windows 10 machines do NOT have it.
    The setup .exe installs it automatically when it's missing. The portable
    .zip can't do that — Sub Control shows a download prompt at startup instead, or
    grab it directly: https://go.microsoft.com/fwlink/p/?LinkId=2124703
  - No separate ONNX Runtime install — it ships with the binary.

Notes:
  - System master-volume control uses Core Audio (built in).


-------------------------------------------------------------------------------
 LINUX
-------------------------------------------------------------------------------

Status: Supported (Wayland and X11).

Display / capture stack (required):
  - PipeWire running, plus an xdg-desktop-portal implementation providing the
    ScreenCast interface (e.g. xdg-desktop-portal-wlr, -gnome, or -kde).
    Screen capture goes through the portal + PipeWire; without them there is no
    real capture.
  - A Wayland compositor or X11 session.

GPU / graphics:
  - Working Vulkan drivers:
      * Mesa (RADV/ANV) for AMD/Intel, or
      * Proprietary NVIDIA driver for NVIDIA GPUs.
  - Rendering/compositing use Vulkan via wgpu; DMA-BUF import is used for
    zero-copy capture where available.

Runtime libraries (install via your distro's packages):
  - GTK 3 (libgtk-3)
  - WebKitGTK 4.1 (webkit2gtk-4.1) — backs the control panel's webview.
  - PipeWire client libraries (libpipewire-0.3).
  - A recent glibc (built against a current mainstream distro).

GPU inference (optional):
  - NVIDIA only: the CUDA 12 runtime must be on the loader path to use the CUDA
    execution provider. See scripts/run-gpu.sh (uses pip nvidia wheels; no
    system-wide CUDA install needed). Without it, inference runs on CPU.

Overlay self-exclusion caveat:
  - KWin/Plasma supports keeping the overlay out of its own capture (window
    rule); GNOME has no equivalent, so a software self-mask/latch stopgap is
    used there.


-------------------------------------------------------------------------------
 macOS
-------------------------------------------------------------------------------

Status: IN PROGRESS — not yet a complete shipping target.
  The ScreenCaptureKit capture backend and the macOS webview panel/tray are not
  finished in this build. System-volume control (via AppleScript/osascript) is
  present. The requirements below are the INTENDED targets for the macOS build.

OS:
  - macOS 12.3 (Monterey) or newer — ScreenCaptureKit is required for capture;
    macOS 13 (Ventura) or newer recommended.

GPU / graphics:
  - Any Metal-capable Mac (Apple Silicon or recent Intel).
  - Rendering/compositing run on Metal via wgpu.

GPU inference (optional):
  - Whisper (audio) can use the Metal backend. Vision inference otherwise runs
    on the CPU execution provider.

Runtime components:
  - WKWebView (built into macOS) backs the control panel — no extra install.
  - Screen Recording permission must be granted (System Settings > Privacy &
    Security > Screen Recording).


-------------------------------------------------------------------------------
 BUILDING FROM SOURCE (developers)
-------------------------------------------------------------------------------

Toolchain (all platforms):
  - Rust (stable, edition 2021) with Cargo — install via rustup.
  - A C/C++ toolchain and CMake (required when building with audio/Whisper,
    which vendors and compiles whisper.cpp).
  - Internet access — model weights and a prebuilt ONNX Runtime are downloaded
    during build/first run.

Build:
    cargo build --release -p drop-app        # binary is named `drop`

Platform build dependencies:
  - Linux:  pipewire-devel (libpipewire headers), clang/clang-devel,
            gtk3-devel, webkit2gtk-4.1 dev headers.
            Optional GPU-Whisper feature also needs glslc (shaderc).
  - Windows: Windows 10/11 SDK (via Visual Studio Build Tools). Capture and
            DirectML EP are enabled automatically by target.
  - macOS:  Xcode command-line tools (Metal, ScreenCaptureKit SDK).

Relevant cargo features (drop-app):
  - cuda           Linux/NVIDIA GPU inference via the ONNX Runtime CUDA EP.
  - whisper-gpu    GPU-accelerated Whisper via the whisper.cpp Vulkan backend
                   (cross-vendor; needs glslc at build time).
  - pipewire       Real Linux screen capture (enabled by default on Linux).
  (Windows DirectML inference and WGC capture are enabled by target and need no
   feature flags.)

===============================================================================
