1foot.ini(5) File Formats Manual foot.ini(5)
2
6 foot.ini - configuration file for foot(1)
7
9 foot uses the standard unix configuration format, with section based
10 key/value pairs. The default section is unnamed (i.e. not prefixed with
11 a [section]).
12 foot will search for a configuration file in the following locations,
14 in this order:
15 • XDG_CONFIG_HOME/foot/foot.ini
17 • ~/.config/foot/foot.ini
18 • XDG_CONFIG_DIRS/foot/foot.ini
19
22 shell
23 Executable to launch. Typically a shell. Default: $SHELL if set,
24 otherwise the user's default shell (as specified in /etc/passwd).
25 You can also pass arguments. For example /bin/bash --norc.
26 login-shell
28 Boolean. If enabled, the shell will be launched as a login shell,
29 by prepending a '-' to argv[0]. Default: no.
30 term
32 Value to set the environment variable TERM to. Default: foot or
33 xterm-256color if built with -Dterminfo=disabled
34 font, font-bold, font-italic, font-bold-italic
36 Comma separated list of fonts to use, in fontconfig format. That
37 is, a font name followed by a list of colon-separated options. Most
38 noteworthy is :size=n, which is used to set the font size.
39 Examples:
41 • Dina:weight=bold:slant=italic
42 • Courier New:size=12
43 • Fantasque Sans Mono:fontfeatures=ss01
44 For each option, the first font is the primary font. The remaining
47 fonts are fallback fonts that will be used whenever a glyph cannot
48 be found in the primary font.
49 The fallback fonts are searched in the order they appear. If a
51 glyph cannot be found in any of the fallback fonts, the dynamic
52 fallback list from fontconfig (for the primary font) is searched.
53 font-bold, font-italic and font-bold-italic allow custom fonts to
55 be used for bold/italic/bold+italic fonts. If left unconfigured,
56 the bold/italic variants of the regular font(s) specified in font
57 are used. Note: you may have to tweak the size(s) of the custom
58 bold/italic fonts to match the regular font.
59 To disable bold and/or italic fonts, set e.g. font-bold to exactly
61 the same value as font.
62 Default: monospace:size=8 (font), not set (font-bold, font-italic,
64 font-bold-italic).
65 line-height
67 An absolute value, in points, that override line height from the
68 font metrics.
69 You can specify a height in pixels by using the px suffix: e.g.
71 line-height=12px.
72 See also: vertical-letter-offset.
74 Default: not set.
76 letter-spacing
78 Spacing between letters, in points. A positive value will increase
79 the cell size, and a negative value shrinks it.
80 You can specify a letter spacing in pixels by using the px suffix:
82 e.g. letter-spacing=2px.
83 See also: horizontal-letter-offset.
85 Default: 0.
87 horizontal-letter-offset, vertical-letter-offset
89 Configure the horizontal and vertical offsets used when positioning
90 glyphs within cells, in points, relative to the top left corner.
91 To specify an offset in pixels, append px: e.g. horizontal-letter-
93 offset=2px.
94 Default: 0.
96 box-drawings-uses-font-glyphs
98 Boolean. When disabled, foot generates box/line drawing characters
99 itself. The are several advantages to doing this instead of using
100 font glyphs:
101 • No antialiasing effects where e.g. line endpoints appear
103 dimmed down, or blurred.
104 • Line- and box characters are guaranteed to span the entire
105 cell, resulting in a gap-less appearance.
106 • No alignment issues, i.e. lines are centered when they
107 should be.
108 • Many fonts lack some, or all, of the line- and box drawing
109 characters, causing fallback fonts to be used, which re‐
110 sults in out-of-place looking glyphs (for example, badly
111 sized).
112 When enabled, box/line drawing characters are rendered using font
115 glyphs. This may result in a more uniform look, in some use cases.
116 Default: no.
118 dpi-aware
120 auto, yes, or no. When set to yes, fonts are sized using the moni‐
121 tor's DPI, making a font of a given size have the same physical
122 size, regardless of monitor. In other words, if you drag a foot
123 window between different monitors, the font size remains the same.
124 In this mode, the monitor's scaling factor is ignored; doubling the
126 scaling factor will not double the font size.
127 When set to no, the monitor's DPI is ignored. The font is instead
129 sized using the monitor's scaling factor; doubling the scaling fac‐
130 tor does double the font size.
131 Finally, if set to auto, fonts will be sized using the monitor's
133 DPI on monitors with a scaling factor of 1, but otherwise using the
134 scaling factor.
135 Default: auto
137 pad
139 Padding between border and glyphs, in pixels (subject to output
140 scaling), on the form XxY.
141 This will add at least X pixels on both the left and right sides,
143 and Y pixels on the top and bottom sides. The grid content will be
144 anchored in the top left corner. I.e. if the window manager forces
145 an odd window size on foot, the additional pixels will be added to
146 the right and bottom sides.
147 To instead center the grid content, append center (e.g. pad=5x5
149 center).
150 Default: 2x2.
152 resize-delay-ms
154 Time, in milliseconds, of "idle time" "before foot sends the new
155 window dimensions to the client application while doing an interac‐
156 tive resize of a foot window. Idle time in this context is a period
157 of time where the window size is not changing.
158 In other words, while you are fiddling with the window size, foot
160 does not send the updated dimensions to the client. Only when you
161 pause the fiddling for relay-size-ms milliseconds is the client up‐
162 dated.
163 Emphasis is on while here; as soon as the interactive resize ends
165 (i.e. when you let go of the window border), the final dimensions
166 is sent to the client, without any delays.
167 Setting it to 0 disables the delay completely.
169 Default: 100.
171 initial-window-size-pixels
173 Initial window width and height in pixels (subject to output scal‐
174 ing), on the form WIDTHxHEIGHT. The height includes the titlebar
175 when using CSDs. Mutually exclusive to initial-window-size-chars.
176 Default: 700x500.
177 initial-window-size-chars
179 Initial window width and height in characters, on the form WIDTHx‐
180 HEIGHT. Mutually exclusive to initial-window-size-pixels.'
181 Note that if you have a multi-monitor setup, with different scaling
183 factors, there is a possibility the window size will not be set
184 correctly. If that is the case, use initial-window-size-pixels in‐
185 stead.
186 Default: not set.
188 initial-window-mode
190 Initial window mode for each newly spawned window: windowed, maxi‐
191 mized or fullscreen. Default: windowed.
192 title
194 Initial window title. Default: foot.
195 app-id
197 Value to set the app-id property on the Wayland window to. The com‐
198 positor can use this value to e.g. group multiple windows, or apply
199 window management rules. Default: foot.
200 bold-text-in-bright
202 Semi-boolean. When enabled, bold text is rendered in a brighter
203 color (in addition to using a bold font). The color is brightened
204 by increasing its luminance.
205 If set to palette-based, rather than a simple yes|true, colors
207 matching one of the 8 regular palette colors will be brightened us‐
208 ing the corresponding bright palette color. Other colors will be
209 brightened by increasing the luminance.
210 Default: no.
212 bell
214 Action to perform when receiving a BEL character. Can be set to ei‐
215 ther set-urgency, notify or none.
216 When set to set-urgency, the margins will be painted in red when‐
218 ever BEL is received while the window does not have keyboard focus.
219 Note that Wayland currently does not have an urgency hint like X11.
220 The value set-urgency was chosen for forward-compatibility in the
221 hopes that a corresponding Wayland protocol is added in the future
222 (in which case foot will use that instead of painting its margins
223 red).
224 Applications can enable/disable this feature programmatically with
226 the CSI ? 1042 h and CSI ? 1042 l escape sequences.
227 Note: expect this feature to be replaced with proper compositor ur‐
229 gency support once/if that gets implemented.
230 When set to notify, foot will emit a desktop notification using the
232 command specified in the notify option, but only if the foot window
233 does not have keyboard focus.
234 When set to none, no special action is taken when receiving BEL.
236 Default: none.
238 word-delimiters
240 String of characters that act as word delimiters when selecting
241 text. Note that whitespace characters are always word delimiters,
242 regardless of this setting. Default: ,│`|:"'()[]{}<>
243 jump-label-letters
245 String of characters that will be when generating key sequences for
246 URL jump labels. Default: sadfjklewcmpgh.
247 notify
249 Command to execute to display a notification. ${title} and ${body}
250 will be replaced with the notification's actual title and body
251 (message content).
252 Applications can trigger notifications in the following ways:
254 • OSC 777: \e]777;notify;<title>;<body>\e\\
256 Notifications are inhibited if the foot window has keyboard focus.
259 Default: notify-send -a foot -i foot ${title} ${body}.
261 url-launch
263 Command to execute when opening URLs. ${url} will be replaced with
264 the actual URL. Default: xdg-open ${url}.
265 selection-target
267 Clipboard target to automatically copy selected text to. One of
268 none, primary, clipboard or both. Default: primary.
269 workers
271 Number of threads to use for rendering. Set to 0 to disable multi‐
272 threading. Default: the number of available logical CPUs (including
273 SMT). Note that this is not always the best value. In some cases,
274 the number of physical cores is better.
275 osc8-underline
277 When to underline OSC-8 URLs. Possible values are url-mode and al‐
278 ways.
279 When set to url-mode, OSC-8 URLs are only highlighted in URL mode,
281 just like auto-detected URLs.
282 When set to always, OSC-8 URLs are always highlighted, regardless
284 of their other attributes (bold, italic etc). Note that this does
285 not make them clickable.
286 Default: url-mode
288
290 lines
291 Number of scrollback lines. The maximum number of allocated lines
292 will be this value plus the number of visible lines, rounded up to
293 the nearest power of 2. Default: 1000.
294 multiplier
296 Amount to multiply mouse scrolling with. It is a decimal number,
297 i.e. fractions are allowed. Default: 3.0.
298 indicator-position
300 Configures the style of the scrollback position indicator. One of
301 none, fixed or relative. none disables the indicator completely.
302 fixed always renders the indicator near the top of the window, and
303 relative renders the indicator at the position corresponding to the
304 current scrollback position. Default: relative.
305 indicator-format
307 Which format to use when displaying the scrollback position indica‐
308 tor. Either percentage, line, or a custom fixed string. This option
309 is ignored if indicator-position=none. Default: empty string.
310
312 This section controls the cursor style and color. Note that applica‐
313 tions can change these at runtime.
314 style
316 Configures the default cursor style, and is one of: block, bar or
317 underline. Note that this can be overridden by applications. De‐
318 fault: block.
319 blink
321 Boolean. Enables blinking cursor. Note that this can be overridden
322 by applications. Default: no.
323 color
325 Two RRGGBB values specifying the foreground (text) and background
326 (cursor) colors for the cursor. Default: inversed foreground and
327 background colors. Note that this value only applies to the block
328 cursor. The other cursor styles are always rendered with the fore‐
329 ground color.
330
332 hide-when-typing
333 Boolean. When enabled, the mouse cursor is hidden while typing. De‐
334 fault: no.
335 alternate-scroll-mode
337 Boolean. This option controls the initial value for the alternate
338 scroll mode. When this mode is enabled, mouse scroll events are
339 translated to up/down key events when displaying the alternate
340 screen.
341 This lets you scroll with the mouse in e.g. pagers (like less)
343 without enabling native mouse support in them.
344 Alternate scrolling is not used if the application enables native
346 mouse support.
347 This option can be modified by applications at run-time using the
349 escape sequences CSI ? 1007 h (enable) and CSI ? 1007 l (disable).
350 Default: yes.
352
354 This section controls the 16 ANSI colors and the default foreground and
355 background colors. Note that applications can change these at runtime.
356 The colors are in RRGGBB format. That is, they do not have an alpha
358 component. You can configure the background transparency with the alpha
359 option.
360 foreground
362 Default RRGGBB foreground color. This is the color used when no
363 ANSI color is being used. Default: dcdccc.
364 background
366 Default RRGGBB background color. This is the color used when no
367 ANSI color is being used. Default: 111111.
368 regular0, regular1 .. regular7
370 The eight basic ANSI colors. Default: 222222, cc9393, 7f9f7f,
371 d0bf8f, 6ca0a3, dc8cc3, 93e0e3 and dcdccc (a variant of the zenburn
372 theme).
373 bright0, bright1 .. bright7
375 The eight bright ANSI colors. Default: 666666, dca3a3, bfebbf,
376 f0dfaf, 8cd0d3, fcace3, b3ffff and ffffff (a variant of the zenburn
377 theme).
378 alpha
380 Background translucency. A value in the range 0.0-1.0, where 0.0
381 means completely transparent, and 1.0 is opaque. Default: 1.0.
382 selection-foreground, selection-background
384 Foreground (text) and background color to use in selected text.
385 Note that both options must be set, or the default will be used.
386 Default: inverse foreground/background.
387 jump-labels
389 To RRGGBB values specifying the foreground (text) and background
390 colors to use when rendering jump labels in URL mode. Default: reg‐
391 ular0 regular3.
392 urls
394 Color to use for the underline used to highlight URLs in URL mode.
395 Default: regular3.
396
398 This section controls the look of the CSDs (Client Side Decorations).
399 Note that the default is to not use CSDs, but instead to use SSDs
400 (Server Side Decorations) when the compositor supports it.
401 Note that unlike the colors defined in the colors section, the color
403 values here are in AARRGGBB format. I.e. they contain an alpha compo‐
404 nent.
405 preferred
407 Which type of window decorations to prefer: client (CSD), server
408 (SSD) or none.
409 Note that this is only a hint to the compositor. Depending on com‐
411 positor support, and how it has been configured, it may instruct
412 foot to use CSDs even though this option has been set to server, or
413 render SSDs despite client or none being set.
414 Default: server.
416 size
418 Height, in pixels (subject to output scaling), of the titlebar. De‐
419 fault: 26.
420 color
422 Titlebar AARRGGBB color. Default: use the default foreground color.
423 button-width
425 Width, in pixels (subject to output scaling), of the minimize/maxi‐
426 mize/close buttons. Default: 26.
427 button-minimize-color
429 Minimize button's AARRGGBB color. Default: use the default regular4
430 color (blue).
431 button-maximize-color
433 Maximize button's AARRGGBB color. Default: use the default regular2
434 color (green).
435 button-close-color
437 Close button's AARRGGBB color. Default: use the default regular1
438 color (red).
439
441 This section lets you override the default key bindings.
442 The general format is action=combo1...comboN. That is, each action may
444 have one or more key combinations, space separated. Each combination is
445 on the form mod1+mod2+key. The names of the modifiers and the key must
446 be valid XKB key names.
447 Note that if Shift is one of the modifiers, the key must not be in up‐
449 per case. For example, Control+Shift+V will never trigger, but Con‐
450 trol+Shift+v will.
451 Note that Alt is usually called Mod1.
453 A key combination can only be mapped to one action. Lets say you want
455 to bind Control+Shift+R to fullscreen. Since this is the default short‐
456 cut for search-start, you first need to unmap the default binding. This
457 can be done by setting action=none; e.g. search-start=none.
458 scrollback-up-page
460 Scrolls up/back one page in history. Default: Shift+Page_Up.
461 scrollback-up-half-page
463 Scrolls up/back half of a page in history. Default: not set.
464 scrollback-up-line
466 Scrolls up/back a single line in history. Default: not set.
467 scrollback-down-page
469 Scroll down/forward one page in history. Default: Shift+Page_Down.
470 scrollback-down-half-page
472 Scroll down/forward half of a page in history. Default: not set.
473 scrollback-down-line
475 Scroll down/forward a single line in history. Default: not set.
476 clipboard-copy
478 Copies the current selection into the clipboard. Default: Con‐
479 trol+Shift+c.
480 clipboard-paste
482 Pastes from the clipboard. Default: Control+Shift+v.
483 primary-paste
485 Pastes from the primary selection. Default: Shift+Insert (also de‐
486 fined in mouse-bindings).
487 search-start
489 Starts a scrollback/history search. Default: Control+Shift+r.
490 font-increase
492 Increases the font size by 0.5pt. Default: Control+plus Con‐
493 trol+equal Control+KP_Add.
494 font-decrease
496 Decreases the font size by 0.5pt. Default: Control+minus Con‐
497 trol+KP_Subtract.
498 font-reset
500 Resets the font size to the default. Default: Control+0 Con‐
501 trol+KP_0.
502 spawn-terminal
504 Spawns a new terminal. If the shell has been configured to emit the
505 OSC 7 escape sequence, the new terminal will start in the current
506 working directory. Default: Control+Shift+n.
507 minimize
509 Minimizes the window. Default: not bound.
510 maximize
512 Toggle the maximized state. Default: not bound.
513 fullscreen
515 Toggles the fullscreen state. Default: not bound.
516 pipe-visible, pipe-scrollback, pipe-selected
518 Pipes the currently visible text, the entire scrollback, or the
519 currently selected text to an external tool. The syntax for this
520 option is a bit special; the first part of the value is the command
521 to execute enclosed in "[]", followed by the binding(s).
522 You can configure multiple pipes as long as the command strings are
524 different and the key bindings are unique.
525 Note that the command is not automatically run inside a shell; use
527 sh -c "command line" if you need that.
528 Example:
530 pipe-visible=[sh -c "xurls | uniq | tac | fuzzel | xargs -r
531 firefox"] Control+Print
532 Default: not bound
534 show-urls-launch
536 Enter URL mode, where all currently visible URLs are tagged with a
537 jump label with a key sequence that will open the URL. Default:
538 Control+Shift+u.
539 show-urls-copy
541 Enter URL mode, where all currently visible URLs are tagged with a
542 jump label with a key sequence that will place the URL in the clip‐
543 board. Default: none.
544
546 This section lets you override the default key bindings used in scroll‐
547 back search mode. The syntax is exactly the same as the regular key-
548 bindings.
549 cancel
551 Aborts the search. The viewport is restored and the primary selec‐
552 tion is not updated. Default: Control+g Escape.
553 commit
555 Exit search mode and copy current selection into the primary selec‐
556 tion. Viewport is not restored. To copy the selection to the regu‐
557 lar clipboard, use Control+Shift+c. Default: Return.
558 find-prev
560 Search backwards in the scrollback history for the next match. De‐
561 fault: Control+r.
562 find-next
564 Searches forwards in the scrollback history for the next match. De‐
565 fault: Control+s.
566 cursor-left
568 Moves the cursor in the search box one character to the left. De‐
569 fault: Left Control+b.
570 cursor-left-word
572 Moves the cursor in the search box one word to the left. Default:
573 Control+Left Mod1+b.
574 cursor-right
576 Moves the cursor in the search box one character to the right. De‐
577 fault: Right Control+f.
578 cursor-right-word
580 Moves the cursor in the search box one word to the right. Default:
581 Control+Left Mod1+b.
582 cursor-home
584 Moves the cursor in the search box to the beginning of the input.
585 Default: Home Control+a.
586 cursor-end
588 Moves the cursor in the search box to the end of the input. De‐
589 fault: End Control+e.
590 delete-prev
592 Deletes the character before the cursor. Default: BackSpace.
593 delete-prev-word
595 Deletes the word before the cursor. Default: Mod1+BackSpace Con‐
596 trol+BackSpace.
597 delete-next
599 Deletes the character after the cursor. Default: Delete.
600 delete-next-word
602 Deletes the word after the cursor. Default: Mod1+d Control+Delete.
603 extend-to-word-boundary
605 Extend current selection to the next word boundary. Default: Con‐
606 trol+w.
607 extend-to-next-whitespace
609 Extend the current selection to the next whitespace. Default: Con‐
610 trol+Shift+w.
611 clipboard-paste
613 Paste from the clipboard into the search buffer. Default: Control+v
614 Control+y.
615 primary-paste
617 Paste from the primary selection into the search buffer. Default:
618 Shift+Insert.
619
621 This section lets you override the default key bindings used in URL
622 mode. The syntax is exactly the same as the regular key-bindings.
623 cancel
625 Exits URL mode without opening an URL. Default: Control+g Control+d
626 Escape.
627 toggle-url-visible
629 By default, the jump label only shows the key sequence required to
630 activate it. This is fine as long as the URL is visible in the
631 original text.
632 But with e.g. OSC-8 URLs (the terminal version of HTML anchors,
634 i.e. "links"), the text on the screen can be something completey
635 different than the URL.
636 This action toggles between showing and hiding the URL on the jump
638 label.
639 Default: t.
641
643 This section lets you override the default mouse bindings.
644 The general format is action=combo1...comboN. That is, each action may
646 have one or more key combinations, space separated. Each combination is
647 on the form mod1+mod2+BTN_<name>[-COUNT]. The names of the modifiers
648 must be valid XKB key names, and the button name must be a valid libin‐
649 put name. You can find the button names using libinput debug-events.
650 Note that Shift cannot be used as a modifier in mouse bindings since it
652 is used to enable selection when the client application is grabbing the
653 mouse.
654 The trailing COUNT is optional and specifies the click count required
656 to trigger the binding. The default if COUNT is omitted is 1.
657 A modifier+button combination can only be mapped to one action. Lets
659 say you want to bind BTN_MIDDLE to fullscreen. Since BTN_MIDDLE is the
660 default binding for primary-paste, you first need to unmap the default
661 binding. This can be done by setting action=none; e.g. primary-
662 paste=none.
663 All actions listed under key-bindings can be user here as well.
665 select-begin
667 Begin an interactive selection. The selection is finalized, and
668 copied to the primary selection, when the button is released. De‐
669 fault: BTN_LEFT.
670 select-begin-block
672 Begin an interactive block selection. The selection is finalized,
673 and copied to the primary selection, when the button is released.
674 Default: Control+BTN_LEFT.
675 select-word
677 Begin an interactive word-wise selection, where words are separated
678 by whitespace and all characters defined by the word-delimiters op‐
679 tion. The selection is finalized, and copied to the primary selec‐
680 tion, when the button is released. Default: BTN_LEFT-2.
681 select-word-whitespace
683 Same as select-word, but the characters in the word-delimiters op‐
684 tion are ignored. I.e only whitespace characters act as delimiters.
685 The selection is finalized, and copied to the primary selection,
686 when the button is released. Default: Control+_BTN_LEFT-2.
687 select-row
689 Begin an interactive row-wise selection. The selection is final‐
690 ized, and copied to the primary selection, when the button is re‐
691 leased. Default: BTN_LEFT-3.
692 select-extend
694 Interactively extend an existing selection, using the original se‐
695 lection mode (normal, block, word-wise or row-wise). The selection
696 is finalized, and copied to the primary selection, when the button
697 is released. Default: BTN_RIGHT.
698 select-extend-character-wise
700 Same as select-extend, but forces the selection mode to normal
701 (i.e. character wise). Note that this causes subsequent select-ex‐
702 tend operations to be character wise. This action is ignored for
703 block selections. Default: Control+BTN_RIGHT.
704 primary-paste
706 Pastes from the primary selection. Default: BTN_MIDDLE.
707
709 This section is for advanced users and describes configuration options
710 that can be used to tweak foot's low-level behavior.
711 These options are not included in the example configuration. You should
713 not change these unless you understand what they do and note that
714 changing the default values will print a warning when launching foot.
715 Note that these options may change, or be removed at any time, without
717 prior notice.
718 When reporting bugs, please mention if, and to what, you have changed
720 any of these options.
721 scaling-filter
723 Overrides the default scaling filter used when down-scaling bitmap
724 fonts (e.g. emoji fonts). Possible values are none, nearest, bilin‐
725 ear, cubic or lanczos3. cubic and lanczos3 produce the best re‐
726 sults, but are slower (with lanczos3 being the best and slowest).
727 Default: lanczos3.
729 allow-overflowing-double-width-glyphs
731 Boolean. when enabled, double width glyphs with a character width
732 of 1 are allowed to overflow into the neighbouring cell.
733 One use case for this is fonts "icon" characters in the Unicode
735 private usage area, e.g. Nerd Fonts, or Powerline Fonts. Without
736 this option, such glyphs will appear "cut off".
737 Another use case are legacy emoji characters like WHITE FROWNING
739 FACE.
740 Note: this feature uses heuristics to determine which glyphs should
742 be allowed to overflow.
743 Default: yes.
745 render-timer
747 Enables a frame rendering timer, that prints the time it takes to
748 render each frame, in microseconds, either on-screen, to stderr, or
749 both. Valid values are none, osd, log and both. Default: none.
750 box-drawing-base-thickness
752 Line thickness to use for LIGHT box drawing line characters, in
753 points. This value is converted to pixels using the monitor's DPI,
754 and then multiplied with the cell size. The end result is that a
755 larger font (and thus larger cells) result in thicker lines. De‐
756 fault: 0.04.
757 delayed-render-lower, delayed-render-upper
759 These two values control the timeouts (in nanoseconds) that are
760 used to mitigate screen flicker caused by clients writing large,
761 non-atomic screen updates.
762 If a client splits up a screen update over multiple write(3) calls,
764 we may end up rendering an intermediate frame, quickly followed by
765 another frame with the final screen content. For example, the
766 client may erase part of the screen (or scroll) in one write, and
767 then write new content in one or more subsequent writes. Rendering
768 the frame when the screen has been erased, but not yet filled with
769 new content will be perceived as screen flicker.
770 The real solution to this is Application Synchronized Updates
772 (https://gitlab.freedesktop.org/terminal-wg/specifica‐
773 tions/-/merge_requests/2).
774 The problem with this is twofold - first, it has not yet been stan‐
776 dardized, and thus there are not many terminal emulators that im‐
777 plement it (foot does implement it), and second, applications must
778 be patched to use it.
779 Until this has happened, foot offers an interim workaround; an at‐
781 tempt to mitigate the screen flicker without affecting neither per‐
782 formance nor latency.
783 It is based on the fact that the screen is updated at a fixed in‐
785 terval (typically 60Hz). For us, this means it does not matter if
786 we render a new frame at the beginning of a frame interval, or at
787 the end. Thus, the goal is to introduce a delay between receiving
788 client data and rendering the resulting state, but without causing
789 a frame skip.
790 While it should be possible to estimate the amount of time left un‐
792 til the next frame, foot's algorithm is currently not that ad‐
793 vanced, but is based on statistics I guess you could say - the de‐
794 lay we introduce is so small that the risk of pushing the frame
795 over to the next frame interval is also very small.
796 Now, that was a lot of text. But what is it foot actually does?
798 When receiving client data, it schedules a timer, the delayed-ren‐
800 der-lower. If we do not receive any more client data before the
801 timer has run out, we render the frame. If however, we do receive
802 more data, the timer is re-scheduled. That is, each time we receive
803 client data, frame rendering is delayed another delayed-render-
804 lower nanoseconds.
805 Now, while this works very well with most clients, it would be pos‐
807 sible to construct a malicious client that keeps writing data at a
808 slow pace. To the user, this would look like foot has frozen as we
809 never get to render a new frame. To prevent this, an upper limit is
810 set - delayed-render-upper. If this timer runs out, we render the
811 frame regardless of what the client is doing.
812 If changing these values, note that the lower timeout must be set
814 lower than the upper timeout, but that this is not verified by
815 foot. Furthermore, both values must be less than 16ms (that is,
816 16000000 nanoseconds).
817 You can disable the feature altogether by setting either value to
819 0. In this case, frames are rendered "as soon as possible".
820 Default: lower=500000 (0.5ms), upper=8333333 (8.3ms - half a frame
822 interval).
823 damage-whole-window
825 Boolean. When enabled, foot will 'damage' the entire window each
826 time a frame has been rendered. This forces the compositor to re‐
827 draw the entire window. If disabled, foot will only 'damage' up‐
828 dated rows.
829 There is normally no reason to enable this. However, it has been
831 seen to workaround an issue with fractional scaling in Gnome.
832 Note that enabling this option is likely to increase CPU and/or GPU
834 usage (by the compositor, not by foot), and may have a negative im‐
835 pact on battery life.
836 Default: no.
838 max-shm-pool-size-mb
840 This option controls the amount of virtual memory used by the
841 pixmap memory to which the terminal screen content is rendered.
842 It does not change how much physical memory foot uses.
844 Foot uses a memory mapping trick to implement fast rendering of in‐
846 teractive scrolling (typically, but applies to "slow" scrolling in
847 general). Example: holding down the 'up' or 'down' arrow key to
848 scroll in a text editor.
849 For this to work, it needs a large amount of virtual address space.
851 Again, note that this is not physical memory.
852 On a normal x64 based computer, each process has 128TB of virtual
854 address space, and newer ones have 64PB. This is an insane amount
855 and most applications do not use anywhere near that amount.
856 Each foot terminal window can allocate up to 2GB of virtual address
858 space. With 128TB of address space, that means a maximum of 65536
859 windows in server/daemon mode (for 2GB). That should be enough,
860 yes?
861 However, the Wayland compositor also needs to allocate the same
863 amount of virtual address space. Thus, it has a slightly higher
864 chance of running out of address space since it needs to host all
865 running Wayland clients in the same way, at the same time.
866 In the off chance that this becomes a problem for you, you can re‐
868 duce the amount used with this option.
869 Or, for optimal performance, you can increase it to the maximum al‐
871 lowed value, 2GB (but note that you most likely will not notice any
872 difference compared to the default value).
873 Setting it to 0 disables the feature.
875 Note: this feature is always disabled in 32-bit.
877 Default: 512. Maximum allowed: 2048 (2GB).
879
881 foot(1), footclient(1)
882 2021-04-18 foot.ini(5)