PassthroughForge

Menu BarProfile dropdown

Top-left of the window. Combobox listing all saved profiles plus quick-action buttons.

Profile dropdown, Save, +New buttons in the top menu bar.

Buttons

Close-up of the Profile combobox, Save and + New buttons.

Control	Function
Profile combobox	Click to drop down a list of all saved profiles. Selecting one immediately loads its full state - masks, color, transforms, gaze settings.
Save	Saves the current state back to the profile that's currently loaded. Overwrites without asking. Use + New if you want to keep the original intact.
+ New	Creates a brand new profile from the current state. If the rename textbox in the Profiles panel has a name typed in, that name is used (with auto-suffix if it collides). Otherwise `Profile 1`, `Profile 2`... is auto-generated.

Menu BarRecenter All Masks

Big blue button to the right of + New. Performs a Snap to View: rigidly rotates the whole mask group around your head pivot so the centroid lines up with your forward direction. Distances and heights between masks are preserved exactly.

The blue Recenter All Masks button next to +New.

Important: profile data on disk is NOT modified. The snap is stored as a session-only pivot + rotation offset. Use Settings -> Reset Snap to revert to pristine profile state.

Settings menu - Reset Snap entry that reverts the session offset.

Shortcut: Ctrl + Delete. Same action available from the global keyboard hook in tray mode.

Snap to View result: mask group rotated to face the player. — Before / after the snap: mask group rigidly rotated around the head pivot to face the player.

Menu BarSettings menu

Drops down a menu with passthrough-color controls and global behaviour toggles.

Settings menu opened, showing color and snap controls.

Color controls

Passthrough Color	RGB color picker. The mask interior is filled with this color, and Virtual Desktop's chroma-key replaces it with the camera feed.
Hex: #RRGGBB	Read-only display of the chosen color as hex. Useful for matching VD's chroma-key setting.
Copy	Copies the hex code to clipboard.
Magenta / Green / Blue	One-click presets. Default is dark blue `#0000B4`.

Snap controls

Snap Masks to Current View	Same as the Recenter All Masks button or Ctrl+Delete.
Reset Snap	Clears the session pivot + rotation + position offset. Masks return to their pristine profile coordinates.

Behaviour toggles

Mask fade (ms)	0 = instant snap when toggling masks on/off. Slider up to 500ms for smooth fade.
Always on Top	Pins the desktop window above all others. Useful for second-monitor setups.
Capture Mouse (endless drag)	Clips the cursor inside the window AND wraps it across edges so DragFloat / SliderFloat values can be dragged endlessly.
Mask Shortcuts...	Opens the keyboard-binding configuration window (see below).

Menu BarHelp menu

Quick reference of mouse/keyboard shortcuts inline. The full list is on the main page under Shortcuts.

Menu BarStep mode pill

Top-right of the menu bar. Shows the current keyboard nudge step: NORMAL x1, FINE x0.1 (green), or COARSE x5 (orange). Click to cycle through the modes. Default toggles: Q (Fine), E (Coarse). Tap once to enter, tap again to leave.

Step mode pill in three states: Normal, Fine, Coarse.

The selected step multiplies all keyboard transform shortcuts: Ctrl+Arrow translates by 1 cm in Normal, 1 mm in Fine, 5 cm in Coarse.

EditorDrawing Tools

Choose the tool you want to draw your mask with.

Drawing Tools card with all six tool radio buttons.

Tool	Effect
None	Default. Canvas clicks/drags do nothing - safe state for adjusting position via shortcuts without accidentally drawing.
Polygon	Click to place vertices, right-click on empty canvas to apply, right-click on point for context menu (Bezier toggle, Fillet, Delete).
Rectangle	Click + drag to fill an axis-aligned rectangle with the passthrough color.
Brush	Click + drag to paint a soft circle with the size from the slider that appears next to the radio buttons.
Eraser	Same as brush but removes pixels (alpha = 0).
Fill	Bucket flood-fill: click any region and the connected area is filled with the passthrough color. Use Eraser to remove a fill.

Tip: the brush size slider only appears when Brush or Eraser is selected.

EditorFiles card

Import PNG	Loads any image and uses its alpha channel as the mask shape. Pixels with alpha > 128 become the passthrough color, everything else is transparent. Good for stencils / silhouettes.
Import 3D	Loads an STL or FBX file, projects its silhouette to a 2D shape and uses that as the mask. Useful for projecting hardware models.
Export PNG	Writes the current mask pixels (RGBA) to a PNG file - good for backups or sharing.

EditorCanvas / Edit cards

Fill All	Fills the entire texture with the passthrough color (full passthrough quad). Mostly used to start with a "blank passthrough sheet" you then carve away from with the Eraser.
Clear	Wipes all pixels to alpha=0 (fully transparent / no passthrough).
Undo	Reverts the last drawing operation.
Redo	Re-applies an undone operation.

EditorView card

Zoom Canvas - / +	Discrete zoom buttons. Each press multiplies/divides zoom by 1.25.
1:1	Reset zoom and pan to default centered view.
Grid checkbox	Toggles a divisions grid overlay on the canvas - useful for symmetric polygon placement.

Mouse alternative: Ctrl + Wheel zooms continuously and centers on the cursor; Ctrl + Middle Drag pans.

EditorReference Image card

Loads any image (typically a cockpit photo) as a tracing background. The image is fitted to the canvas with correct aspect ratio and centered.

Reference image loaded behind the canvas for tracing.

Load Reference	Open file dialog to pick an image.
Show / Hide	Toggle visibility of the loaded reference.
Opacity slider	0 = invisible, 1 = fully opaque.
Rotate 90 / 180 / 270	Rotates the reference if your photo is in portrait or upside-down.

EditorActions card

TRACE VR	Toggles a special render mode: every painted pixel of the SELECTED mask is drawn yellow in VR (instead of using passthrough), all other masks become invisible. Used for fine-aligning the painted shape with the real cockpit.
Face Me	Rotates the currently selected mask so its surface normal points exactly at your head. Disables Auto-Face mode (which keeps the rotation live).

Trace VR caveat: the upload to the GPU happens at 30 Hz for 8K masks while in trace mode (vs. event-driven in normal mode), so the editor UI may feel slightly heavier. Turn it off when not aligning.

EditorPolygon tool detail

The polygon tool is the most powerful drawing tool. Each click places a vertex; right-clicking on the canvas applies the polygon (rasterizes it to the mask pixels). After applying, the polygon vertices are saved with the mask so you can re-edit later.

Polygon tool in action - vertices, bezier handles, mirror line.

Per-vertex actions

Drag a vertex	Repositions it.
Right-click on a vertex	Opens context menu: Corner / Bezier toggle (controls handle visibility), Fillet radius (adds a rounded corner on apply), Delete.
Right-click on an edge	Inserts a new vertex at the click position.
Drag a Bezier handle	Adjusts the curve tangent at that vertex.
Hover + Del	Deletes hovered vertex.
Esc	Cancel the in-progress polygon (no apply).

Mirror mode

The Mirror checkbox creates a real-time mirrored preview of the polygon along a vertical axis through the first placed point. On apply, both the original and the mirrored shape are rasterized in one go. Bezier handles and fillet radii are mirrored correctly.

Right Panel[Pr] Profiles

Manages saved profiles - each profile holds a complete mask layout, color, and transform offsets.

[Pr] Profiles section with profile list and management buttons.

Profile name textbox	The name used by Save As / + New. Pre-filled with the loaded profile's name; edit it to rename or create variations.
Save As	Saves the current state under the typed name. If the name already exists it is overwritten without asking.
+ New	Same as the menu-bar version: creates a fresh profile (typed name preferred, otherwise auto "Profile N").
Profile list (one row each)	Click to load a profile. The currently loaded profile is highlighted green. The default (auto-loaded) profile gets a star prefix.
Set Auto / Auto label	Marks a profile as the auto-load default for next launch. Only one profile can have this.
Delete	Permanently deletes the profile JSON. No undo.

Right Panel[L] Layer - Mask

The mask list. Each row is one mask in the current profile. The order is the rendering order (top of list = drawn under everything else).

[L] Layer - Mask list with reorder arrows and visibility toggles.

+ Add Mask	Creates a new empty mask, spawned 1 m in front of your head, head-yaw aligned. Subsequent masks are staggered 30 cm to the right so they don't overlap.
Duplicate	Creates an exact copy of the selected mask, including pixel content.
Mirror	Creates a mirrored child of the selected mask. The child syncs its position (X negated), rotation (Y / Z negated) and pixel content (horizontally flipped) from the source. Edit only the source.
(o) toggle	Mask visibility checkbox - same as Ctrl+F1..F8 hotkey for that mask.
v / ^ arrows	Move the mask up or down in the render order (Z-order).
Mask name	Click to select and edit. Press Enter to commit the new name.
X (close button on tab)	Removes the mask. Confirmation dialog appears.

Right Panel[G] Global Offset

Translation and rotation applied to ALL world-anchored masks. Modified automatically by Snap to View, can be edited manually for fine group-level adjustments.

[G] Global Offset sliders for translate and rotate.

Offset X / Y / Z	Translates the whole group. Held Alt = fine, Shift = fast.
G.Pitch / G.Yaw / G.Roll	Euler-angle rotation of the group around world axes (around the pivot if a Snap is active, otherwise around origin).
Reset All Offsets	Clears every offset to zero / identity. Same as Settings -> Reset Snap.

Right Panel[M] Mirror & Group

Per-mask mirror controls. Visible only when a mask is selected.

[M] Mirror & Group with Create Mirror / distance slider.

Create Mirror	Same as the Mirror button in the mask list - spawns a linked mirror child.
Unlink Mirror	Visible only on mirror children. Detaches the child from its source - the child becomes an independent editable mask with its current state frozen.
Mirror Distance slider	Visible when a mirror pair is selected. Sets the X-axis distance between the source and mirror child centers in one slider.

Right Panel[V] Visibility & Activation

Gaze Activated	When checked, the mask only fades in while you're looking within an angular cone of its center. Cone width controlled by the slider next to it (5..90 degrees).
Gaze angle slider	Half-angle of the activation cone. 30 deg is the default and works for most cockpit panels.
Render on top of other masks	Forces this mask to draw above all others in the OpenXR composition layer order, even if geometrically further away. Use for PDF / document overlays.

Right Panel[T] Tracking

Per-mask tracking target. Determines whether the mask sits in world-space or follows a controller in real time.

[T] Tracking dropdown - World / Left / Right Controller.

None (World)	Static world position. Default. Profile-stored coords + global offset.
Real Time Tracking Left Controller	Mask pose = (left controller pose) * (mask's stored offset). The mask follows your left hand.
Real Time Tracking Right Controller	Same for right hand.
Reset Offset (when tracked)	Sets the offset to identity - mask sits exactly at the controller's grip pose.

Motion rig tip: strap a controller to your motion-rig frame. Switch a mask to tracked mode and the cutout follows every pitch / roll / yaw the platform produces, keeping the cockpit panel cutout aligned even when the rig moves.

Right Panel[P] Position (head-relative)

The position sliders show head-relative coordinates: X = right of player's view, Y = up, Z = forward (positive) / behind (negative). The internal mask.transform stays in stage-space; this panel converts on the fly so values feel intuitive.

[P] Position sliders, head-relative coordinates.

X (right)	Drag to move along the player's right-axis. Held Alt = fine, Shift = fast.
Y (up)	Up/down in world coords (gravity-aligned).
Z (forward)	Forward / back relative to player's yaw.

Keyboard alternative: Ctrl + Arrows for X/Y, Ctrl + PgUp/PgDn for Z.

Right Panel[R] Rotation (world axes)

Pitch	Rotation around world X axis (front-to-back tilt).
Yaw	Rotation around world Y axis (vertical / heading).
Roll	Rotation around world Z axis (banking).

Implementation: rotations apply as world-frame quaternion left-multiplications, so they stay gimbal-lock free as you stack them. Editing one slider does not unexpectedly change the others.

Right Panel[S] Size & Resolution

Width / Height (m)	Physical size of the mask in meters as it appears in VR.
Lock aspect	When checked, editing one dimension scales the other proportionally.
Texture resolution	Internal pixel resolution of the mask buffer. Higher = sharper edges but more GPU bandwidth. Default 8192x8192. Document Masks usually need lower (e.g. 2048x2048).

Right Panel[3D] Preview

Wireframe preview of the mask group around the player's head pose. Updates live. Useful for understanding the spatial relationship between masks and validating where Recenter All Masks will land them.

[3D] Preview wireframe of mask group around head pose.

Show all checkbox

If unchecked, only the selected mask is drawn (simplifies the preview when you have many masks).

WorkflowShortcut configuration

Reachable via Settings -> Mask Shortcuts.... Opens a modal where every action's keyboard binding can be customized.

Shortcut configuration window with rebindable action table.

Step mode controls

Three buttons at the top set the current step multiplier directly: Normal (x1, default), Fine (x0.1), Coarse (x5). The toggles also fire automatically on the configured Toggle keys (Q / E by default).

Action table

Each row shows an action, its current binding (e.g. Ctrl+RightArrow), and Rebind / Clear buttons.

Rebind	Click and press the desired key combination. Modifier keys (Ctrl / Shift / Alt) are part of the binding - `LeftArrow` and `Ctrl+LeftArrow` are different bindings.
Clear	Removes the binding entirely. The action becomes inactive.

Other buttons

Reset to Defaults	Restores all bindings to factory defaults (Ctrl + arrows / numpad / Q / E).
Show Cheat Sheet in VR	Generates a 1024x768 image with all current bindings rendered as a panel and creates a "Shortcuts Help" mask floating ~1 m in front of you.

WorkflowTray mode

Click the Minimize button (top-right of the title bar) to send PassthroughForge to the system tray. While in tray:

Tray icon and the right-click context menu.

The window is hidden but the layer keeps publishing mask data to your sim.
All keyboard shortcuts are registered as Win32 RegisterHotKeys.
A low-level WH_KEYBOARD_LL hook is also installed to intercept keys before sims (DCS) which use DirectInput / RawInput see them.
The hook only fires when a known flight sim has foreground (DCS, MSFS, IL-2, War Thunder, Falcon BMS). Plain typing in Notepad / browser passes through normally.

X (close button) always quits the application - only the Minimize button sends to tray. The tray icon's right-click menu also has "Show PassthroughForge" (restore) and "Exit".

WorkflowVR cheat sheet

Settings -> Mask Shortcuts -> Show Cheat Sheet in VR builds a high-res image with the current keyboard bindings and creates a dedicated mask called "Shortcuts Help". It floats ~1 m in front of you, large enough to read at a glance.

In-VR cheat sheet floating in front of the player.

It's a normal mask - you can move it, hide it via Ctrl+F<n>, snap it to a controller, or delete it like any other. Re-press the menu item to regenerate it after rebinding.

WorkflowStatus bar

Bottom of the desktop window. Shows live state:

Status bar at the bottom of the desktop window.

SHM Active / Disconnected: green if the layer is connected, gray otherwise.
Masks: N: number of masks in the current profile.
Color: : the current passthrough color.
Step: Fine / Coarse: appears in green / orange when not in Normal step mode.

Complete Manual