Zutty developer guide

While Zutty itself compiles and runs on Linux as well as BSD platforms, the test toolkit assumes a specific development environment (most notably: Linux platform with bash as the default shell, and the presence of a window manager with certain standard capabilities).

Please also note that the reference signatures of screen captures are valid for ImageMagick version 6 only; version 7 has altered the image signature hash algorithm, which breaks the hashes included in the tests.

Each executable script under test/ is an individually runnable test suite. It is written as a plain old bash script, sourcing the testbase.sh test code library and using its facilities. For example, truecolor.sh is a very simple test script to test support for setting color attributes to truecolor (24 bit) values. The full script is reproduced below:

#!/usr/bin/env bash

cd $(dirname $0)
source testbase.sh

IN "source truecolor_inc.sh\r"
SNAP truecolor_01 33a31e4d3b9fbe486c27b01764dc1823

The script starts by declaring itself as a shell script, then setting up its working directory to be the location of the script (a convenience to make relative file paths work in later parts of the script, independent of the location the script was invoked from). Then testbase.sh is sourced.

The actual test code is just two lines, starting with the commands IN and SNAP. These are invocations of functions defined in testbase.sh and execute in the environment set up by sourcing that file.

IN will send the specified string, as keyboard input, to the terminal under test. In our example, the shell running in the terminal will source the file truecolor_inc.sh that contains some setup code (not reproduced here) to make a certain pattern appear on the terminal. Note the trailing \r that will result in a virtual Enter keypress.

The subsequent SNAP will capture the resulting terminal window content under the name truecolor_01, generate a signature (hash) of it, and compare that with the supplied value. If there is a match, the output is verified to be correct; else a test failure is reported.

The snap name is used to save the captured window image under test/output/<profile>. This is useful for later inspection of test results. With the default profile (see Test profiles below), the output of this test will be saved as test/output/zutty/truecolor_01.png.

There are some other useful functions exported by the test framework, e.g.: CHECK_DEPS, CHECK_FILES, and WAIT_FOR_DOT_COMPLETE. If you encounter them in test script code, it is best to look directly in testbase.sh for their implementation.

Note that starting and stopping of the terminal under test is done as part of the test framework and nothing is explicitly written in the test script. See Test profiles below on how to control the details of this process.

Test scripts similar to the one shown above (building on testbase.sh) all take a uniform set of command line options. All arguments are optional, below defaults are in effect for omitted ones. Syntax: --<arg-name>=<arg-value>; value defaults to "yes" if omitted.

Option             Default
--------------------------
--ci-mode          no
--debug            no
--profile          zutty
--step             no
--update-sig       no

The list of correctness tests (automatically run in sequence by The CI test script):

• keys.sh: Keyboard input handling (see Key mapping sequences for further documentation). Note: This test might fail if your computer is configured to use a non-US keyboard.
• nonascii.sh: Test displaying non-ascii (double-width and other exotic) characters, based on the Emacs 'hello' file (M-x view-hello-file)
• scrollback.sh: Scrollback (page history) support
• title.sh: Setting the window title from within the terminal via escape sequences
• truecolor.sh: True color support
• utf8.sh: UTF-8 support (based on the UTF-8 decoder capability and stress test by Markus Kuhn)
• vttest.sh: VTTEST screens. Note: This suite depends on a specific version of vttest, and will complain if the version found does not match. Just run the vttest install script mentioned by the error message, and you should be good to go.
• wraptest.sh: Additional tests for verifying the correctness of last-column/pending-wrap subtleties. Note: This suite depends on the wraptest program (not bundled with the zutty source repository). Just run the install script mentioned by the error message you get on the first run, and you should be good to go.

Apart from running all the tests via The CI test script (which you should routinely run during development, and especially before sending a patch or opening a pull request), it is also possible to run any of the above tests manually. For example, to run the test automating a traversal of Vttest's menu system (and in case of running against Zutty, also verifying that results are as expected):

test/vttest.sh

Do not forget about the Common test script options above; those become useful during development (both of Zutty itself and the test suites). For example, to run the above test step-by-step (stopping at each image checkpoint):

test/vttest.sh --step

A separate test fonts.sh exists that is very similar to the correctness tests above, but is not part of The CI test script. This renders a captured hardcopy of a terminal-intensive program (BpyTOP) exercising many features (chiefly, Unicode line drawing glyphs) that are helpful in spotting errors in the font loading and rasterization process employed by Zutty, and validates the result across a matrix of several font faces and sizes. Please read the commentary in the test script for the fonts required to run the test.

The performance of Zutty can be verified with the below tests. These are to be run manually (similar to how you run any of the Correctness tests on an ad-hoc basis). The goal of these tests is to get a handle on performance under repeatable circumstances.

Since everyone's hardware and systems are different, it does not make too much sense to compare numbers obtained by different people at different times. Rather, it is most useful to compare the results obtained on the same system (running the comparison tests after one another without any changes to the rest of the system), with the goal of comparing a proposed set of patches to the baseline of Zutty, or to compare Zutty with another terminal emulator.

Needless to say: when running the below scripts, your machine should be otherwise idle.

While correctness tests should ideally be run on both the debug build (do this by passing --debug to the test scripts) and the normal build, it does not make sense to run performance tests on the debug build. The results would be meaningless due to excessive logging and hitting other debug-only code paths.

Current performance tests:

• cat_dict.sh: Arguably the dumbest possible performance test of any text terminal, this test consists of outputting a very long text file containing (mostly) very short lines with English words, one per line. This test will be repeated a number of times (check TIMES in the script) and the overall timing and data throughput will be computed at the end. Since the input does not contain any terminal controls (escape sequences), it is a measure of the raw incoming data rate the terminal can sustain while frequently forced to scroll/page its output. This load resembles one extreme end of the way a terminal can be used.
• cat_vtscript.sh: This test generates load resembling the other extreme end of possible terminal usage, by outputting the stream of data written to the terminal in the course of the VTTEST cycle (see vttest.sh among the Correctness tests). However, instead of verifying the correctness of the generated screen output, here we are interested in the performance of processing the input stream heavy on all kinds of escape sequences. Screen updates are dominated by intra-screen rewrites and relatively little scrolling/paging activity is forced. Similar to the cat_dict.sh test, the input is fed into the terminal a number of times, and overall timing and throughput is measured and calculated.

The script test/run_ci.sh will run all automated Correctness tests in sequence with the --ci-mode option, stopping and exiting with a nonzero return code if any of them exits with an error, and concluding with a confirmatory message and zero return code otherwise.

You should always run this at a convenient time (it will occupy your screen for about 25 minutes) and observe the successful result before sending a patch with your changes. For extra confidence, build Zutty both with and without debug, and run the CI script both with and without the --debug option.

If you have changed anything related to font loading or rasterization (font.cc or fontpack.cc), make sure you run the Font rasterization tests as well. Please read the commentary in the test script for more context.

Given that our method of testing is independent of the terminal itself (meaning that we do not rely on any hooks or test instrumentation in the terminal itself), we can run the same tests against other terminals, too. This is useful for comparison and research purposes. The default profile is zutty, invoking the locally built Zutty executable as the unit under test.

Profiles are defined as shell include files under test/profiles, and can be invoked by passing the --profile option to the test script. For example, to run the VTTEST suite against xterm:

./test/vttest.sh [--step] --profile=xterm

Available profiles can be enumerated by looking in test/profiles/ (pass their name without the .sh extension to --profile, as above). The list is also printed by the test script in case an invalid profile name is given.

Each test profile contains a program invocation assigned to UUT_EXE, used to launch the terminal under test with the right arguments. The terminal must be configured so that its geometry is 80 characters wide and 24 rows tall.

Some other variables set up in the profile encode different capabilities to control the test scripts so that unsupported features are skipped (and the terminal does not encounter confusing escape sequences). Examples: MISSING_ANSWERBACK, MISSING_DSR, MISSING_SECONDARY_DA, SUPPORTS_VT52, SUPPORTS_VT220. Please check the script files for details.

Note that validation against the stored image hashes does not make sense, unless preparations are made to ensure that the terminal settings (size, font, etc.) are perfectly identical. Even then, differences from the valid output stored for Zutty do not necessarily constitute bugs in any other terminal, unless the rendered screen content is visibly wrong. For this reason, auto-validation of the saved screens runs in a relaxed mode for all profiles other than zutty. This means that for terminals other than Zutty, matches are still prominently displayed (by a line reading MATCH in green), while non-matches are considered normal and indicated by DONE, followed by a metric of the image difference compared to the reference. The output image and the image generated for Zutty will be diffed, resulting in a difference image that will highlight differences with red.

Please keep your changes in line with the coding style of the existing codebase. In particular, observe the following rules:

• Maximum source line width: 80 characters.
• No tabs, only spaces.
• Indentation: BSD (a.k.a. Allman) style with a width of three (3) spaces.
• Extra space before opening parens.

We are not interested in any opinions or debates on whether this style is good or bad and whether you like it or not; it is simply what we use every day (at least when working with C++). If you are interested in contributing to the codebase, please format your proposed changes accordingly.

… about anything that involves resource ownership, anything related to architecture, anything that changes the user interface, and anything that might be expensive (negatively affecting performance).

Let existing standards (published programming manuals of DEC VT-series terminals) as well as de-facto standard implementations (xterm) and tests (VTTEST) be your guide when it comes to specifications of correctness (see Useful resources), along with the spirit and philosophy outlined in the project README for design and implementation questions specific to Zutty. If you are uncertain, feel free to ask.

At a minimum, run all regression tests via The CI test script before pull-requesting any change.

If relevant to your change, run Performance tests with and without your changes to establish that the performance is maintained at its current level.

If you add or change user-visible functionality, please add or update the tests covering it.

If you change any functionality covered by existing documentation, or add anything that belongs in the same vein, please contribute appropriate documentation updates as well. Nobody will do documentation work for you.

The primary input to the OpenGL program of Zutty is a flat array of Cell structures. It is defined as a Shader Storage Buffer Object (GL SSBO), which means that the memory backing it is allocated by the GL system (ultimately by the graphics driver, preferably within GPU memory). Being an SSBO, this GL-backed object is cheap to frequently modify (on a frame-by-frame basis), as opposed to input textures that hold more permanent data.

The total length of the array is always equal to the terminal size (rows x cols in characters). The cells are addressed left to right, top to bottom. Each cell takes up 12 bytes, with 3 bytes currently unused (available for future extensions).

By way of the CharVdev::Mapping, the application is able to obtain a client-side mapping to this area, allowing direct manipulations of its content.

Font rendering is implemented by a font atlas, which is a texture containing a bitmap of all font characters rasterized to a certain size. The atlas is a single image held in graphics memory, divided into character-size cells (measured by the chosen font face's pixel dimensions) on a rectangular grid. Having all characters pre-rasterized into a single 2D image is customary in OpenGL text rendering, and is highly beneficial for performance and memory reasons. Each font glyph supported by the font face has a pair of atlas coordinates, denoting the row and column of the grid cell with the chosen glyph.

Zutty goes a step further than most, and allows the application layer to communicate directly by writing Unicode code points to the input character video memory area. The translation from Unicode code point to atlas coordinates decouples the application from having to deal with this font-specific mapping, on a per-character basis, on the client side.

The Unicode to atlas position mapping is created and stored on initialization and font loading, and is read-only for the GL program. This is a 256x256 2D texture that maps all 16-bit unicode code points to an atlas grid position. It is initialized with the GL data type GL_LUMINANCE_ALPHA (two channels), from an array with two 8-bit integers per texel (8 bits for either atlas grid coordinate).

This allows direct lookups for any 16 bit Unicode code point in the shader and returns two bytes, one for the atlas row and column each.

If the value stored for atlas (row,col) is (0,0), that means there is no glyph for that code point in the font. As a measure of convenience, the font loader ensures that there is a blank glyph stored at that atlas location, so no special GLSL code is needed to handle this case.

Once the atlas coordinates of the glyph to be drawn are known, the corresponding area of the atlas glyph texture is rendered onto the output image texture. The atlas glyph texture is a 2D image holding all the pre-rendered glyphs supported by the loaded font. Its dimensions are auto-computed based on the number of glyphs in the font and the glyph dimensions, to produce a pixel size as close to square as possible. This is necessary so the row and column coordinate will both fit into a single byte (the maximum number of characters rasterized from a font is 2^16 (65536), corresponding to the Unicode Basic Multilingual Plane).

Texture encoding: 1 byte per texel, gray-scale (0 = black, 255 = white)

The atlas texture is stored as a 2D array with one layer for each font face loaded. The mapping from unicode code point to atlas grid location is the same across fonts, and is determined by the primary font (loaded into texture array index 0). Each subsequent layer starts out as a copy of the primary atlas layer, with glyphs successively overwritten for each defined code point in the alternate font. This means that when referencing an alternate font, the shader does not have to care about whether the alternate font has a glyph for the given code point – if nothing else, the primary font's glyph will be present.

The glyph-sized rectangle on the atlas glyph texture, as defined by the atlas coordinates, contains a gray-scale image of the character to be rendered. The destination of this rendering is an image, accumulating the output from all the compute shaders running in parallel, each rendering a single character cell in the terminal window.

The dimensions of this image texture are set according to the terminal window's character grid size (window size, minus split-character border area at the bottom and right edges). The output texture is rendered onto the viewport area using a quad in the most straightforward way. All the work of computing the terminal window content is done by the compute shader that sets color values of individual pixels in the output texture.

To display CJK characters, the rendering pipeline was extended to support double-width cells. These cells are marked with the dwidth flag being set in the left cell, and the dwidth_cont (double-width continuation) flag set in the right cell. The latter flag is only used in the shader to short-circuit rendering, as its area will be rendered by the compute shader instance rendering the left cell.

The double-width font is loaded separately from the layered main font variants that share a common atlas mapping. This font, if present, has its own atlas glyph texture and atlas position mapping texture. Other than this overhead, everything is handled very much the same way.

To understand the memory layout of cells mapped to the screen grid, consider the below figure:

           0 --> +-----------------------+
                 |                       |
                 .          (1)          .
                 |                       |
                 +-----------------------+
   marginTop --> +-----------------------+    <
                 |                       |    <
                 .          (3)          .    <
                 |                       |    <
                 +-----------------------+    < scrolling
  scrollHead --> +-----------------------+    <   area
                 |                       |    <
                 .          (2)          .    <
                 |                       |    <
                 +-----------------------+    <
marginBottom --> +-----------------------+
                 |                       |
                 .          (4)          .
                 |                       |
                 +-----------------------+
       nRows -->

The storage can be conceptually divided into four consecutive areas. Area (1) between row 0 and marginTop (non-inclusive) is non-scrolling (it might be empty though, if marginTop is zero). The same applies to area (4) that begins with the row numbered marginBottom and extends to the bottom of the screen (this area is empty if marginBottom equals nRows).

The area beginning with row marginTop and ending just above, but not including marginBottom is the scrolling area. The current logical top of the scrolling area is marked by scrollHead, which is the first row of area (2). The scrolling area extends downwards to the last row above marginBottom, and logically continues with area (3) that starts with the row marginTop, ending with the last row above scrollHead.

When a new row is appended to the scrolling area, scrollHead is moved down, unless it would become equal to marginBottom, in which case it jumps back up to marginTop. In any case, newly written content will overwrite the row marked by the original position of scrollHead, which has conceptually dropped off the top of the scrolling area.

Due to this storage scheme, lines on the screen (logically numbered from 0 to nRows - 1 will not always be physically stored in consecutive order. The method Frame::unwrapCellStorage () resets (straightens out) this logical-to-physical mapping, which is necessary before the scrolling limits marginTop and marginBottom can be changed or the frame can be resized. In the reset state, scrollHead equals marginTop, which means area (2) fills the space between (1) and (4), while (3) is empty.

The above scheme is a special case with the number of off-screen lines (defined by the saveLines configuration value) being zero. In reality, the buffer allocated for the frame contains space for a total of (visible) nRows plus an additional (off-screen) saveLines rows' worth of cells. Apart from that, operational aspects of filling the buffer with data are exactly as described above: the scrolling area is delimited by marginTop and marginBottom, and scrollHead points to the logically top-most row within the scrolling area (moved downwards as the content at the top edge scrolls out of the window). Note that this architecture guarantees that the computational complexity of scrolling is O(1) with respect to the size of the scrollback buffer. Having a large scrollback buffer will certainly cost memory, but it will have zero impact on performance.

If there are no top/bottom margins set, the whole storage acts as a (potentially very large) scrolling area, of which only nRows rows are visible (available to the Vterm via screen-based coordinates) at any point in time:

                0 --> +-----------------------+    <
                      |                       |    <
                      .          (3)          .    < scrolling
                      |     [off-screen]      |    <   area
                      +-----------------------+    <
       scrollHead --> +-----------------------+    <   <--------- posY = 0
                      |                       |    <   < active      ...
                      .          (2)          .    <   <  area       ...
                      |                       |    <   <             ...
                      +-----------------------+    <   <--------- posY = nRows - 1
scrollHead + nRows -> +-----------------------+    <
                      |                       |    <
                      .          (2)          .    <
                      |     [off-screen]      |    <
                      +-----------------------+    <
nRows + saveLines -->

The second part of area (2) and the entirety of area (3) contain off-screen lines. The number of saved history rows with valid data is maintained in the private counter historyRows, so that scrolling the view up into any still unused, blank buffer area can be avoided.

The Vterm continues to "see" the active area as if it was the whole buffer, its topmost row having posY = 0. Naturally, the active area might wrap around the end of the buffer. In this case, it is the second part of area (3) that contains saved (off-screen) lines:

                0 --> +-----------------------+    <   <
                      |                       |    <   < active      ...
                      .          (3)          .    <   <  area       ...
                      |                       |    <   < (pt. 2)     ...
                      +-----------------------+    <   <--------- posY = nRows - 1
scrollHead + nRows -> +-----------------------+    <
(mod buffer length)   |                       |    <
                      .          (3)          .    < scrolling
                      |     [off-screen]      |    <   area
                      +-----------------------+    <
       scrollHead --> +-----------------------+    <   <--------- posY = 0
                      |                       |    <   < active      ...
                      .          (2)          .    <   <  area       ...
                      |                       |    <   < (pt. 1)     ...
                      +-----------------------+    <   <
nRows + saveLines -->

Note that internally, marginTop will be 0 and marginBottom will be nRows + saveLines (reflecting the physical extent of the buffer). The externally reported value of marginBottom will continue to be nRows, so Vterm can continue to use the margin settings in its own logic, mostly to establish whether the cursor position is within the margins.

In case the Vterm sets top/bottom margins (meaning that at least one of them differs from its reset value of 0 / nRows, respectively), the Frame will rearrange its storage so that the physical start of the buffer contains the active area with parts (1) to (4), and the rest contains the lines of saved history. This has the advantage that marginTop, marginBottom and scrollHead continue to be valid with the active area as a frame of reference (pun not intended), without having to apply offsets to them.

                0 --> +-----------------------+    <
                      |                       |    <  active
                      .          (1)          .    <   area
                      |                       |    <
                      +-----------------------+    <
        marginTop --> +-----------------------+    <    <
                      |                       |    <    <
                      .          (3)          .    <    <
                      |                       |    <    <
                      +-----------------------+    <    < scrolling
       scrollHead --> +-----------------------+    <    <   area
                      |                       |    <    <
                      .          (2)          .    <    <
                      |                       |    <    <
                      +-----------------------+    <    <
     marginBottom --> +-----------------------+    <
                      |                       |    <
                      .          (4)          .    <
                      |                       |    <
                      +-----------------------+    <
            nRows --> +-----------------------+
                      |                       |
                      .          (0)          .
                      |     [off-screen]      |
                      +-----------------------+
nRows + saveLines -->

The initial status of the above layout is when scrollHead equals marginTop, meaning that area (3) is empty. This is the layout that calling unwrapCellStorage () will set up, and is done every time prior to the frame being resized, or the top/bottom margins adjusted.

Given the above defined memory layouts, it is easy to see how the screen can be directed to display something other than the active area. The view position is defined by a single row offset viewOffset that can take values from 0 (display the active area) up to and including saveLines (display the top of history).

Essentially, when copying frame data into the CharVdev for display, viewOffset has to be subtracted from the start of the frame (scrollHead in case of no margins, or 0 if there are margins), wrapping around the buffer limits as necessary. Then, the data has to be copied from that starting point in order, following the numbering of data sections (0) through (4), until nRows rows have been copied.