diff options
Diffstat (limited to 'docs/config.md')
| -rw-r--r-- | docs/config.md | 36 |
1 files changed, 32 insertions, 4 deletions
diff --git a/docs/config.md b/docs/config.md index 79a5e631..ff960aac 100644 --- a/docs/config.md +++ b/docs/config.md @@ -25,15 +25,16 @@ which `Config` reports as `no per-user config path`. `+Config` pane. It reports the startup path and every live config-like value: theme, colors, focus tint, syntax weight, wrapping, tag position, debug mode, the requested shell and the executable actually resolved at the last spawn, requested/effective GUI font -and size, tagline scale, panel transition, +and size, tagline scale, window opacity, panel transition, scene effects, hover delay, platform, native-image support, and (on SDL) whether the executable uses live-built shaders or the paired prebuilt shader snapshot. Platform-dependent rows say `unsupported` instead of looking like an off or -empty supported setting. The four fields of `config.Runtime.Capabilities` gate +empty supported setting. The five fields of `config.Runtime.Capabilities` gate them and are stated once as plain data in `builtins.capabilities`: `font_picker` is the SDL GUI and native macOS only, `scene_shaders` the same two, `panel_transitions` every -hosted shell, and `tagline_font_size` everything but the TTY and the board. So +hosted shell, `window_opacity` the SDL GUI only, and `tagline_font_size` +everything but the TTY and the board. So the TTY reports Font, TaglineSize and the scene shaders as unsupported; the browser reports Font, panel transitions and the scene shaders as unsupported, and its TaglineSize row reads `82% (build-time only)` — tagline font size is @@ -75,11 +76,12 @@ Wrap A line matches a builtin whose name takes NO argument only as that whole word: `Kill` runs, `Kill something` does not. A builtin that takes one (`takes_arg` in `src/builtins.zig`, or a `settings` row whose action is -`shell`, `theme`, `font` or `tagline_size` in `config.Runtime.settings`) takes +`shell`, `theme`, `font`, `tagline_size` or `window_opacity` in `config.Runtime.settings`) takes everything after the name as the argument. On a native build that is `Theme`, `ThemeFile`, `Font`, `TaglineSize`, `Shell`, `Save`, `Restore`, `Attach`, `Mount`, `Unmount`, `Find`, `Grep`, `Rename`, `WsSymbols`, `Look`, `Exec`, `Msg` and `EffectCode`. +The SDL GUI also has `WindowOpacity`, which takes one argument. (`Peek`, `Poke`, `Hexdump` and `Gpio` take one too, but they exist only where `builtins.Board.enabled` holds, and that build has no config file.) @@ -116,6 +118,32 @@ the current value. A `FocusTint` line in a fresh startup configuration disables the tint; a `SyntaxBold` line enables the stronger keyword weight. Those two appearance controls leave focus, selections and editing behavior unchanged. +`WindowOpacity <percent>` controls the opacity of everything in the SDL window +except text and the cursor, which stay fully opaque. Use `WindowOpacity 85` +to see the desktop through the editor, or `WindowOpacity 100` to restore full +opacity (the default). The argument must be a whole number from +0 through 100; missing or invalid values +leave the setting unchanged. At zero only text and the cursor remain visible. +Add the command to `init` to persist it. + +The same opacity applies to editor and embedded terminal backgrounds, UI +chrome, borders, scrollbars, gutters, and images. Overlapping non-text drawing +does not make those areas more opaque. Regular text, syntax colors, tagline +text, terminal glyphs, and the cursor keep their normal opacity. This does +not blend foreground colors into their cell backgrounds. The TTY +and other non-SDL hosts do not emulate this effect; their `Config` report says +`WindowOpacity: unsupported`. + +On native Wayland, Pardes uses an alpha-capable transparent surface. It does +not use whole-window opacity protocols such as `wp_alpha_modifier_v1`, because +those would also fade the text. Presentation uses the existing GPU offscreen +renderer followed by a readback and SDL renderer upload per presented frame, +which adds rendering cost. Other SDL drivers can report background transparency +as unsupported unless their rendering configuration is alpha-capable. +If the rendering backend cannot apply the request, Pardes reports the error +and keeps the last successfully applied opacity. `Config` reports the +percentage and marks a request as pending until the SDL host handles it. + ## Crash records A panic appends to `crashes` in that same directory, beside `init`, and only |