#+TITLE: Zutty - Zero-cost Unicode Teletype#+OPTIONS: author:nil timestamp:nil toc:nil num:nil val:nil html-style:nil H:3 ^:{}#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="doc/org.css"/> #+BEGIN_CENTER*A high-end terminal for low-end systems* Homepage: https://tomscii.sig7.se/zutty \\Source: https://git.hq.sig7.se/zutty.git#+END_CENTER Zutty is a terminal emulator for the X Window System, functionallysimilar to several other X terminal emulators such as =xterm=, =rxvt=and countless others. It is also similar to other, much more modern,GPU-accelerated terminal emulators such as Alacritty and Kitty. Whatreally sets Zutty apart is its radically simple, yet extremelyefficient rendering implementation, coupled with a sufficientlycomplete feature set to make it useful for a wide range of users.Zutty offers high throughput with low latency, and strives to conformto relevant (published or de-facto) standards. Zutty is written in straightforward C++ and only relies on OpenGL ES3.1 for rendering, making it trivially portable to windowing systemsother than X and operating systems other than Linux. Zutty provides aclean implementation written from scratch, resulting in a minimal,maintainable, modern codebase unencumbered by historical baggage. Zutty is released under the GNU General Public License (GPL) v3 or (atyour option) any later version. Please refer to the file LICENSE forthe full text of the license. ** Documentation Core documentation (bundled with the Zutty sources): - [[./README.org][README]]: general overview (this document)- [[./doc/USAGE.org][User guide]]: guide and reference for all users- [[./doc/HACKING.org][Developer guide]]: internals, debugging, testing, contributing- [[./doc/KEYS.org][Key mapping sequences]]: reference on keyboard-induced sequences- [[./doc/VTTEST.org][Vttest results]]: documents the level of conformance against Vttest More about Zutty: - [[https://tomscii.sig7.se/zutty/wiki/Screenshots.html][Screenshots]]: Zutty in action- [[https://tomscii.sig7.se/zutty/wiki/FAQ.html][Frequently Asked Questions]]: What you never thought you'd need to know about Zutty- [[https://tomscii.sig7.se/2020/11/How-Zutty-works][How Zutty works]]: Rendering a terminal with an OpenGL Compute Shader- [[https://tomscii.sig7.se/2020/12/A-totally-biased-comparison-of-Zutty][A totally biased comparison of Zutty]] (to some better-known X terminal emulators)- [[https://tomscii.sig7.se/2021/01/Typing-latency-of-Zutty][Measured: Typing latency of Zutty]] (compared to others) ** Current status Zutty started out as a concept to prove the feasibility of using aGLES Compute Shader to render a fixed-width text grid entirely ingraphics hardware. From its modest beginnings as a technological proofof concept, Zutty has evolved considerably and is now perfectlycapable of serving as the main terminal emulator for heavy users ofthe command line. In particular, this author employs Zutty to run aworkload of =tmux=, =emacs= (=-nw=), =tig=, =mutt=, =htop=, and abunch of other applications making extensive use of the terminal(including its mouse support), with some Zutty instances running formonths at a time, on a very resource-constrained SBC (ab)used as adesktop.  The correctness, performance, and stability of Zutty isexcellent, as one would rightly expect from something as fundamentalas a terminal emulator. There is, however, a list of ancillary features that Zutty does notpresently implement. Completing the ones in scope is more or less amatter of straightforward implementation work within the alreadyexisting architecture of Zutty, and time will be spent on these inproportion to popular user demand. ** Notable features *** Radically simple, uniquely performant rendering technology The main idea behind Zutty is the implementation of "raw" charactervideo memory via OpenGL ES 3.1. This video memory is just an array ofcells backing all character grid locations, with each cell containingUnicode character codes plus color and other visual attributes. Thismemory area, allocated on the GPU, is mapped to make it directlywritable by the application.  This results in a conceptually similarinterface as to how one could write to the screen by directly pokingat physical video memory starting at 0xB8000 on the IBM PC. Zuttyemploys an OpenGL Compute Shader running on the GPU to read this videomemory and render output pixels. The full name of Zutty (dubbed the/Zero-cost Unicode Teletype/) stands for the remarkable fact that itsimage rendering is zero-cost from the host CPU perspective. Zutty requires OpenGL ES 3.1 because this is precisely the lowestversion with support for the Compute Shader, the enabling technologybehind Zutty. We have chosen OpenGL ES over OpenGL to widen the rangeof supported hardware platforms, primarily towards small, low-costSingle Board Computers.  These boards are commonly built around an ARMSoC with a graphics core supporting OpenGL ES, but not "desktop"OpenGL. Zutty is the first GPU-accelerated terminal for such low-costplatforms. *** Correct (and fairly complete) VT emulation Zutty substantially emulates the "commonly used" subsets of theprotocols of VT52, VT100, VT102, VT220, VT320, VT420 and VT520terminals (originally manufactured by DEC) as well as some more modernadditions defined by the de-facto standard =xterm= implementation. We take great care to ensure that Zutty passes the subset of VTTESTscreens that we care about (this amounts to the overwhelming majorityof tests concerned with actual screen rendering, and is subject tofurther extension). We have an automated regression testing setup torun VTTEST in Zutty and verify that the output is a pixel-perfectmatch of the pre-approved video output. You can thus expect theterminal output to be /correct/ -- be it driven by tmux, emacs (withorg-mode, helm, magit, etc.) or whatever else. Zutty handles cornercases (escape sequences) which, sadly enough, several popular terminalemulators do not correctly support. Zutty implements xterm's de-facto standard method (=modifyOtherKeys=)to expose non-trivial modifier key combinations to programs such asEmacs and Vim. Zutty also boasts mouse support (again, modeled afterxterm's capabilities) to make the user experience of many terminalapplications more interactive. In a perfect world, these would not be highlighted as such prominentfeatures, but unfortunately, our focus on correctness is rather theexception than the norm among widely used terminal emulators(including more modern ones). *** Font handling Zutty supports both fixed size (bitmap) and scaled (TTF, OTF) fonts.Up to four variants of a font are supported (Regular, Bold, Italic /Oblique, plus BoldItalic) with automatic, sensible fallbacks in caseany of them (apart from Regular) is missing. Zutty tries to locate thefont files itself under a configured font search path, and loads themon its own, without any support from the windowing system. Zutty is able to display CJK symbols (ideographs) in double-widthcells. This requires a suitable double-width font. This font can befixed or scaled independent from the main font (for example, you mayuse a scaled font for CJK along with a fixed main font). *** True color support Each grid cell in the virtual video memory emulated via OpenGL hasthree bytes reserved for the foreground color as well as thebackground color. As such, Zutty naturally supports true color (24bits / 16 million colors) on each cell's foreground and background,completely independent of each other and all other cells. *** Traditional X-clipboard / primary selection / copy-paste support Zutty supports the traditional method of "copy-paste" based on the XSelection API, and is accessible via the same GUI mechanisms thatlong-time =xterm= users are familiar with. Zutty faithfully replicates what =xterm= has provided for a very longtime: starting selections with the left button, adjusting them withthe right button, and cycling between snap-to-char/word/line withdouble clicks. This naturally yields the ability to select whole wordswith a double-click, and complete lines with a triple-click. Comparedwith =xterm=, one notable difference is a built-in, simpler rule forword boundaries (as opposed to user-adjustable definitions ofcharacter classes). It is possible to adjust the selection while navigating scrollback.Thus, the complete content of the screen buffer (page history pluson-screen lines), or any part of it, can be copied as a singleselection. No need to switch back and forth between source anddestination programs when copying large amounts of terminal output! Selecting a region with the mouse will set the primary selection, andpressing Control+Shift+C will copy that to the clipboard. Thismechanism is useful because it allows holding two separate pieces ofselection data at once. Zutty can also be configured to automaticallycopy the primary to the clipboard each time a selection is done. Paste the primary selection into the terminal via middle click orShift+Insert, like in =xterm=. Paste the clipboard viaControl+Shift+V. Just as with =xterm=, terminal programs might enable one of thesupported "mouse protocols" to provide mouse interaction on their userinterfaces; in such cases, press and hold the Shift key whileperforming the clicks and drags of the selection that you want toperform (both while copying and pasting). Holding Shift will cutthrough to the Zutty mouse handler instead of sending those mouseevents to the terminal program via the mouse protocol. So, regardlessof the program running in the terminal, you can always access thebuilt-in copy-paste support in Zutty; but you can also use whatevermouse support your program has. In addition, Zutty adds a unique feature for real power users of theterminal: rectangular selection. This is extremely useful if workingwith a vertically split terminal (think =emacs= or =tmux=). Simplytoggle between "regular" and "rectangular" selection mode with theSpace key while a selection adjustment is in progress (left or rightmouse button is held down). For your convenience, this settingpersists over individual selections made, throughout the lifetime of arunning Zutty terminal. *** Small, clean codebase The radical simplicity of our rendering technology allows for astraightforward virtual terminal implementation that happens to beextremely performant despite the lack of any fancy optimizations onthe source code level.  This also allows the codebase of Zutty to befairly small and understandable. Therefore, Zutty lends itself towardseducational use and as a vehicle for hacking on terminals. If you'vealways wanted to learn how a terminal emulator works from the insideout, consider studying the Zutty codebase (and associated developerdocumentation)! ** Omissions and limitations There are things that Zutty does not implement compared to other, moreestablished X terminal emulators (=xterm= being the gold standard ofcompleteness here). The below list gives an overview of what might beconsidered missing.  Some of them are clearly out of scope for Zutty,but some will possibly be implemented in the future. - Zutty is opinionated about the primacy of UTF-8, which means that  non-UTF-8 interaction is generally not supported, not even via  bridges such as =luit=.  DEC builtin character sets (such as the DEC  Special Graphics, DEC Technical Characters, etc.) and the escape  sequences to enable them are well implemented though, so users of  any modern Linux environment should never run into trouble. - Zutty is Unicode-based, but it is a terminal emulator, not an  all-purpose Unicode program. Therefore it does not aim to implement  the whole breadth and depth of glyph and language support that  Unicode defines.  Currently not supported:  - Characters with a code point above =U+FFFF= (that is, outside the    Basic Multilingual Plane);  - Bidirectional (right-to-left) text;  - Composing characters (things that can only be represented as a    base glyph plus one or more composing glyphs superimposed, even in    Unicode NFC representation). Do not confuse this with using the    /compose key/ to input accented or special characters missing from    your keyboard; that works fine!  - Possibly more esoteric features. - DEC VT100 double-height / double-width (DECDHL, DECDWL) lines are  not supported. Do not confuse this with double-width cells for wide  characters (e.g. CJK ideographs), which are supported. - Rectangular area operations (introduced by the DEC VT400 series) are  not supported. However, this set of features is optional and the  terminal's self-identification response clearly states the absence of  this support, so conforming client applications should not run into  any trouble. No fundamental technical reasons here other than the  lack of pressing need. - The mouse protocol implementation aims to be complete with the  exception of highlight tracking mode that is not implemented. Mouse  highlight tracking is a mode that requires cooperation from the  client application; it is not clear if any software actively used in  2020 needs this feature. - Blinking in general (blinking text driven by the SGR attribute 5,  and blinking cursor mode turned on/off by DEC-private set/reset  escape sequences) are not (yet) supported. Certain more esoteric  text attributes, such as the "concealed" bit, are also not  implemented. This is purely due to lack of bandwidth, and will most  likely be added in the future.