1# WindowCapture - Architecture Documentation
  2
  3## Overview
  4
  5WindowCapture is a professional screenshot annotation tool built on .NET Framework 4.0.
  6It captures screen regions, opens them in a GPU-accelerated editor with annotations
  7(highlights, arrows, markers, text blocks, comment bubbles), and exports to clipboard,
  8files, or directly into Microsoft Word documents with AI-generated descriptions.
  9
 10**Build system:** PowerShell scripts (`build.ps1`, `compile.ps1`) invoking `csc.exe` from .NET 4.0.
 11**73 source files**, ~22,400 lines of C#.
 12
 13---
 14
 15## File Structure (73 files)
 16
 17### Entry Point
 18| File | Description |
 19|------|-------------|
 20| `Program.cs` | DPI awareness setup, Settings/KeyBindings load, routes to EditorForm (viewer) or TrayApp (capture) |
 21
 22### App Layer (3 files)
 23| File | Description |
 24|------|-------------|
 25| `App/TrayApp.cs` | System tray application, NotifyIcon, global Alt key activation |
 26| `App/Controller.cs` | Low-level keyboard hook (WH_KEYBOARD_LL), captures Alt keypress, launches FrozenOverlay |
 27| `App/PerformanceLogger.cs` | Measure() utility for profiling code sections |
 28
 29### UI - Editor Form (13 partial files)
 30| File | Description |
 31|------|-------------|
 32| `UI/EditorForm.cs` | **Core**: fields, properties, constructors, InitializeForm(), FinalizeInit() |
 33| `UI/EditorForm.Zoom.cs` | Smooth zoom animation (zoomTimer), fit-to-window, D2D init, viewport transform |
 34| `UI/EditorForm.Editing.cs` | Undo, copy to clipboard, save image, quick AI insert, open file dialog |
 35| `UI/EditorForm.Keyboard.cs` | Keyboard shortcuts (Space, Ctrl+Z, Escape, Ctrl+S, Ctrl+O, +/-) |
 36| `UI/EditorForm.GlassButtons.cs` | Glass-styled hover buttons (settings, minimize, maximize, close) with proximity glow |
 37| `UI/EditorForm.Paint.cs` | ScrollContainer_Paint (DWM blur tint, rounded corners, window border) |
 38| `UI/EditorForm.WindowChrome.cs` | ShowSettings, Dispose, ApplyRoundedCorners, DWM blur, WndProc (resize, NC handling) |
 39| `UI/EditorForm.Render.cs` | RenderFinalImage with all annotations for export (arrows, markers, text, bubbles) |
 40| `UI/EditorForm.WordExport.cs` | Word integration UI, panel window management |
 41| `UI/EditorForm.VideoPlayer.cs` | HTML5 video playback via WebBrowser control, JavaScript bridge |
 42| `UI/EditorForm.VideoPaint.cs` | Video overlay painting (seek bar, play/pause, volume controls) |
 43| `UI/EditorForm.ViewerMode.cs` | File browsing, image loading, folder scanning, preloading neighbors |
 44| `UI/EditorForm.Indicators.cs` | CalcElementGlow, PaintVolumeIndicator, PaintFileNameIndicator |
 45
 46### UI - Annotation Canvas (1 file)
 47| File | Description |
 48|------|-------------|
 49| `UI/AnnotationCanvas.cs` | **Core rendering surface**. Handles all annotation drawing, mouse interaction, D2D/GDI rendering, effect layers, zoom/pan transforms. See "Rendering Pipeline" below. |
 50
 51### UI - Audio Player (7 partial files)
 52| File | Description |
 53|------|-------------|
 54| `UI/AudioPlayerForm.cs` | Core: fields, constructor, SetupForm, DWM blur |
 55| `UI/AudioPlayerForm.Playback.cs` | MCI playback commands (play, pause, seek, volume) |
 56| `UI/AudioPlayerForm.Decode.cs` | Waveform decode via Media Foundation, file scanning |
 57| `UI/AudioPlayerForm.Metadata.cs` | ID3/FLAC/M4A metadata + album art extraction |
 58| `UI/AudioPlayerForm.Paint.cs` | Waveform rendering, window buttons, spectrogram slider |
 59| `UI/AudioPlayerForm.Input.cs` | Mouse/keyboard input, volume control, WndProc |
 60| `UI/AudioPlayerForm.Color.cs` | Album art color extraction (dominant color, HSV) |
 61
 62### UI - Dialogs & Panels (8 files)
 63| File | Description |
 64|------|-------------|
 65| `UI/SettingsDialog.cs` | Settings dialog with tabbed glass UI (General, Effects, Keys) |
 66| `UI/WordSidePanel.cs` | Side panel for Word export (description, caption, title page, Gemini AI) |
 67| `UI/WordExportDialog.cs` | Word document selection dialog |
 68| `UI/MediaDownloadDialog.cs` | Media download from web pages |
 69| `UI/TextBlockPopup.cs` | Popup for editing TextBlock properties (font, color, shadow, 3D) |
 70| `UI/DarkColorPicker.cs` | Custom dark-themed color picker dialog |
 71| `UI/KeyCaptureDialog.cs` | Dialog for capturing keyboard shortcut |
 72| `UI/OriginalizePreviewDialog.cs` | Preview dialog for document originalization |
 73
 74### UI - Other (4 files)
 75| File | Description |
 76|------|-------------|
 77| `UI/FrozenOverlay.cs` | Full-screen frozen screenshot overlay for region selection |
 78| `UI/VideoScriptBridge.cs` | JavaScript bridge class for HTML5 video communication |
 79| `UI/ToastNotification.cs` | Animated toast notification popup |
 80| `UI/Controls/DoubleBufferedPanel.cs` | Panel with DoubleBuffered=true for flicker-free rendering |
 81
 82### UI - Custom Controls (5 files)
 83| File | Description |
 84|------|-------------|
 85| `UI/Controls/DarkNumeric.cs` | Integer spinner with glass aesthetic |
 86| `UI/Controls/DarkFloatNumeric.cs` | Float spinner with glass aesthetic |
 87| `UI/Controls/DarkFontSizeNumeric.cs` | Font size spinner with preview |
 88| `UI/Controls/DarkComboBox.cs` | Dark dropdown list with custom scrollbar |
 89| `UI/Controls/GlassScrollPanel.cs` | Scrollable panel with glass-style scrollbar |
 90
 91### Models (10 files)
 92| File | Description |
 93|------|-------------|
 94| `Models/Settings.cs` | Static settings class. INI file persistence (`%APPDATA%/WindowCapture/settings.ini`) |
 95| `Models/KeyBindings.cs` | Keyboard shortcut mappings |
 96| `Models/HighlightRect.cs` | Highlight rectangle with BlurState, BlurRadius, DimDisabled |
 97| `Models/ArrowAnnotation.cs` | Bezier arrow (Start, End, Control1, Control2, HasCurve, Color, Width) |
 98| `Models/TextBlock.cs` | Text annotation (font, color, shadow, 3D rotation, outline) |
 99| `Models/NumberMarker.cs` | Numbered circle marker |
100| `Models/CommentBubble.cs` | Speech bubble with tail (RoundedRect/Oval/Rectangle shapes) |
101| `Models/UndoAction.cs` | Undo stack entry (type + item reference) |
102| `Models/TitlePageData.cs` | Title page data for Word export |
103| `Models/LastSelectedIndices.cs` | Persisted UI selection state |
104| `Models/GeminiSettings.cs` | Gemini API configuration (models, fallback, status) |
105| `Models/AudioPlayerSettings.cs` | Audio player state persistence |
106
107### Effects (3 files)
108| File | Description |
109|------|-------------|
110| `Effects/D2DRenderer.cs` | **GPU rendering engine**. Direct2D HWND + offscreen composition. See "Rendering Pipeline". |
111| `Effects/EffectLayer.cs` | Non-destructive blur effect cache per highlight (CPU-based, used for export) |
112| `Effects/ImageEffects.cs` | CPU blur algorithms (box blur, motion blur) |
113
114### Integration (3 files)
115| File | Description |
116|------|-------------|
117| `Integration/WordIntegration.cs` | Microsoft Word COM automation (insert images, read document context) |
118| `Integration/DocxRenderer.cs` | .docx thumbnail extraction and text parsing |
119| `Integration/GeminiIntegration.cs` | Google Gemini API for AI image descriptions |
120
121### Detection (2 files)
122| File | Description |
123|------|-------------|
124| `Detection/Detector.cs` | Edge-based UI element detection (flood-fill algorithm on screenshot) |
125| `Detection/MediaParser.cs` | Extract media URLs from web pages (video/image sources) |
126
127### Helpers (7 files)
128| File | Description |
129|------|-------------|
130| `Helpers/BitmapHelper.cs` | Bitmap cloning, format conversion, pixel manipulation |
131| `Helpers/BlurHelper.cs` | DWM blur application (BlurBehind / Acrylic via SetWindowCompositionAttribute) |
132| `Helpers/ColorHelper.cs` | Color format conversions (hex, ABGR) |
133| `Helpers/FontHelper.cs` | Font management, system font enumeration |
134| `Helpers/GlowHelper.cs` | Cursor proximity glow computation for glass UI |
135| `Helpers/Logger.cs` | File-based logging to %APPDATA%/WindowCapture/logs/ |
136| `Helpers/MediaTypes.cs` | File extension to MIME type mapping |
137
138### Native Interop (4 files)
139| File | Description |
140|------|-------------|
141| `Native/WinApi.cs` | Windows API P/Invoke (keyboard hooks, DWM, window management, DPI) |
142| `Native/Direct2D.cs` | Direct2D COM interfaces and structs (ID2D1Factory, ID2D1RenderTarget, etc.) |
143| `Native/WasapiInterop.cs` | WASAPI COM interfaces (IAudioClient, IAudioCaptureClient) |
144| `Native/MediaFoundationInterop.cs` | Media Foundation COM interfaces (IMFSourceReader, IMFMediaType) |
145
146---
147
148## Key Processes
149
150### 1. Screen Capture Flow
151
152```
153User presses Alt (configurable)
154  -> Controller.cs: LowLevelKeyboardProc detects keydown
155  -> TrayApp.cs: StartCapture()
156  -> FrozenOverlay.cs: Takes screenshot, displays full-screen overlay
157     -> Detector.cs: Auto-detects UI elements via edge detection
158     -> User clicks region / draws rectangle / selects window
159  -> EditorForm constructor (Bitmap, GraphicsPath) opens editor
160```
161
162### 2. Rendering Pipeline (AnnotationCanvas.OnPaint)
163
164**D2D GPU Path** (primary, when Direct2D available):
165```
1661. D2DRenderer.BeginDraw()
167   -> renderTarget.BeginDraw() (HWND target)
168   -> offscreenRT.BeginDraw() (invisible buffer)
1692. Clear offscreen to transparent (for DWM blur)
1703. Render image to offscreen:
171   - No highlights: DrawImage (full, clear)
172   - With highlights:
173     a. DrawImageBlurred (background blur via downscale/upscale)
174     b. DrawDimOverlay (semi-transparent dark overlay)
175     c. For each highlight: PushClip -> DrawImage or DrawImageBlurred -> PopClip
1764. Get GDI Graphics from offscreen (GetDC interop)
1775. Draw annotations via GDI+ (arrows, markers, text, bubbles, crop guides)
1786. Release GDI Graphics (ReleaseDC)
1797. D2DRenderer.EndDraw()
180   -> offscreenRT.EndDraw()
181   -> Clear HWND target (prevents ghosting from RETAIN_CONTENTS)
182   -> Blit offscreen bitmap to HWND target
183   -> renderTarget.EndDraw() (present to screen)
184```
185
186**GDI+ CPU Path** (fallback):
187```
1881. Create/reuse back buffer bitmap
1892. Clear to dark background
1903. Draw image (full or thumbnail if zooming)
1914. Apply GDI+ transform (translate + scale)
1925. Draw annotations
1936. Blit back buffer to screen
194```
195
196### 3. Annotation System
197
198**Types and interactions:**
199| Annotation | Create | Move | Resize | Effect | Delete |
200|---|---|---|---|---|---|
201| HighlightRect | LMB drag | Drag border area | Corner/edge handles | LMB click=BlurInside, RMB click=BlurOutside, DblLMB=MotionInside, DblRMB=MotionOutside, MMB hold=ToggleDim | Ctrl+Z undo |
202| ArrowAnnotation | RMB drag | Drag start/end points (preserves curve) | - | - | Ctrl+Z undo |
203| NumberMarker | MMB click | Drag | - | - | Ctrl+Z undo |
204| TextBlock | LMB double-click empty | Drag | RMB+wheel=font size | - | Ctrl+Z undo |
205| CommentBubble | RMB double-click empty | Drag (tail follows) | RMB+wheel=font size | - | Ctrl+Z undo |
206
207**Arrow Bezier curve:**
208- New arrows start straight (Control1 at 30%, Control2 at 70% of line)
209- Drag Control1/Control2 handles (orange circles) to curve
210- Dragging Start/End points (blue squares) moves associated control point by same delta (preserves curve shape)
211
212### 4. Effect Layer System
213
214**EffectTypes:** None, BlurInside, BlurOutside, MotionBlurInside, MotionBlurOutside
215
216**CPU path (EffectLayer.cs):** Used for export (GetFullCompositeImage).
217- Clones original bitmap
218- Applies blur to clone (inside rect or entire image)
219- For Outside effects: blurs everything, dims, restores clear area via pixel copy
220- Caches result until highlight moves or parameters change
221
222**GPU path (D2DRenderer.cs):** Used for live rendering (OnPaint).
223- DrawImageBlurred: downscale to small RT → upscale back (bilinear = blur effect)
224- Strength 1-10 controls downscale factor
225- Strength > 3 adds second pass through even smaller target
226- Clip regions isolate highlight areas
227
228### 5. Zoom System (EditorForm.Zoom.cs)
229
230**Static Viewport Architecture:**
231- Canvas stays `Dock = DockStyle.Fill` (fills scrollContainer)
232- Image position controlled by `drawX`, `drawY`, `drawScale` on AnnotationCanvas
233- D2D render target matches viewport size, not image size
234
235**Zoom animation:**
236- Mouse wheel → ApplyZoom() sets targetZoom
237- zoomTimer (16ms interval) interpolates current → target (35% per frame)
238- Each frame calls SetViewportTransform() → Invalidate() → OnPaint
239- BeginZoomAnimation() creates low-res thumbnail for fast rendering during animation
240- EndZoomAnimation() disposes thumbnail, renders full quality
241
242**Coordinate system:**
243- Image coords: pixel position in original bitmap (0,0 = top-left of image)
244- Viewport coords: pixel position on screen canvas
245- ToImageCoords(screenPt): `(pt.X - drawX) / drawScale`
246- ToScreenCoords(imgPt): `imgPt * drawScale + drawX`
247
248### 6. Glass UI System
249
250**DWM blur background:**
251- BlurHelper.Apply() uses SetWindowCompositionAttribute or DwmExtendFrameIntoClientArea
252- BlurBehind or Acrylic mode (configurable)
253- Semi-transparent tint overlay (ScrollContainer_Paint)
254
255**Glass buttons (top-right):**
256- Settings (gear), Minimize, Maximize, Close
257- Proximity-based visibility (appear when cursor within 170px)
258- Directional edge lighting toward cursor
259- Smooth alpha fade (quadratic falloff)
260
261**Glow system (GlowHelper):**
262- All SettingsDialog controls track cursor proximity
263- Paints glow effect based on distance to cursor
264- 40ms timer updates glow state
265
266### 7. Word Integration
267
268```
269Space key (hold 250ms) -> WordSidePanel opens
270  -> User writes description/caption
271  -> Insert button -> WordIntegration.InsertImage()
272     -> COM automation: Word.Application.ActiveDocument
273     -> Composite image rendered (GetFullCompositeImage)
274     -> Image inserted with caption and description
275
276Ctrl+Space -> Quick AI insert
277  -> GeminiIntegration generates description from image
278  -> WordIntegration inserts with AI-generated text
279```
280
281### 8. Audio/Video Playback
282
283**Video:** WebBrowser control with HTML5 `<video>` tag.
284VideoScriptBridge provides C#→JS communication.
285Custom overlay paints seek bar, play/pause, volume controls.
286
287**Audio:** Custom AudioPlayerForm with WASAPI decode, waveform visualization,
288ID3/FLAC/M4A metadata, album art extraction, dominant color theming.
289
290---
291
292## Keyboard Shortcuts
293
294| Key | Context | Action |
295|-----|---------|--------|
296| Space (short) | Editor | Copy to clipboard + close |
297| Space (hold 250ms) | Editor | Show Word export panel |
298| Ctrl+Space | Editor | Quick AI insert to Word |
299| Ctrl+Z | Editor | Undo last annotation |
300| Escape | Editor | Close editor |
301| Ctrl+S | Editor | Save image as file |
302| Ctrl+O | Editor (viewer) | Open media file |
303| Alt (hold) | Editor | Enable auto-detect mode |
304| +/- | Editor | Zoom in/out |
305| R | Viewer mode | Fit to window |
306| F | Viewer mode | Zoom 1:1 |
307| Space | Video | Play/pause |
308| Left/Right | Video | Seek +/-5 seconds |
309| M | Video | Mute/unmute |
310
311## Mouse Controls
312
313| Action | Context | Result |
314|--------|---------|--------|
315| LMB drag | Empty area | Draw highlight rectangle |
316| RMB drag | Empty area | Draw arrow |
317| MMB click | Empty area | Place numbered marker |
318| LMB click | On highlight | Toggle BlurInside |
319| RMB click | On highlight | Toggle BlurOutside |
320| LMB double-click | On highlight | Toggle MotionBlurInside |
321| RMB double-click | On highlight | Toggle MotionBlurOutside |
322| MMB hold (200ms) | On highlight | Toggle dim |
323| LMB double-click | Empty area | Create text block |
324| RMB double-click | Empty area | Create comment bubble |
325| RMB + wheel | Over text/bubble | Change font size |
326| RMB + wheel | Over arrow handle | Change arrow width |
327| Mouse wheel | Anywhere | Zoom in/out |
328| MMB drag | Anywhere | Pan (when zoomed in) |
329| Drag border | On highlight | Move highlight |
330| Drag corner/edge | On highlight | Resize highlight |
331| Drag start/end | On arrow | Move endpoint (preserves curve) |
332| Drag CP1/CP2 | On arrow | Bend bezier curve |
333
334---
335
336## Settings System
337
338**File:** `%APPDATA%/WindowCapture/settings.ini` (key=value pairs)
339
340**To add a new setting:**
3411. Add `public static TYPE Name = DEFAULT;` in `Models/Settings.cs`
3422. Add `case "Name": Name = TYPE.Parse(val); break;` in `Settings.Load()`
3433. Add `"Name=" + Name` in `Settings.Save()`
3444. Add `Name = DEFAULT;` in `Settings.ResetDefaults()`
3455. Add UI control in `UI/SettingsDialog.cs` (appropriate tab page)
3466. Map control value in `SaveSettings()` and `ResetToDefaults()`
347
348**Available dark controls:** DarkNumeric (int), DarkFloatNumeric (float), DarkComboBox (dropdown), CheckBox, Button (color picker via DarkColorPicker).
349
350---
351
352## Build
353
354```powershell
355# Debug build
356powershell -ExecutionPolicy Bypass -File build.ps1
357
358# Release build
359powershell -ExecutionPolicy Bypass -File compile.ps1
360
361# Output
362bin/WindowCapture.exe
363```
364
365**Requirements:** .NET Framework 4.0 (csc.exe from v4.0.30319), Windows 7+.
366**Resources:** `icon.ico`, `Bebas Neue Bold.ttf` (embedded font).
367**References:** System.dll, System.Drawing.dll, System.Windows.Forms.dll, Microsoft.CSharp.dll, System.Core.dll.