This page details the internal mechanisms by which Windows Terminal parses and processes VT (Virtual Terminal) escape sequences. It covers the parsing logic (StateMachine), sequence recognition and dispatch (OutputStateMachineEngine), the dispatch interface (ITermDispatch), its Windows Console API adapter implementation (AdaptDispatch), and the terminal buffer abstraction layer (ITerminalApi). This system converts raw VT character streams into terminal state updates including buffer text, cursor movement, and styling.
This documentation focuses on output processing (from applications to screen), but also briefly covers relevant input processing. For complementary details, refer to pages on Terminal Control Architecture and Text Buffer System.
The VT sequence processing system consists of layered components that gradually transform raw bytes into terminal state changes:
StateMachine (parser): Implements a stateful parser that reads individual characters and recognizes VT sequences by transitioning across states per the VT specification src/terminal/parser/stateMachine.hpp14-27
OutputStateMachineEngine (recognizer): Implements the engine interface that maps abstract parser events to concrete VT dispatch calls identifying commands and parameters src/terminal/parser/OutputStateMachineEngine.hpp20-53
ITermDispatch (dispatch interface): Defines the interface for all terminal VT commands (cursor moves, text output, attribute changes, etc.) src/terminal/adapter/ITermDispatch.hpp23-200
AdaptDispatch (adapter): Implements ITermDispatch with Windows Console semantics, converting VT commands to buffer operations via ITerminalApi src/terminal/adapter/adaptDispatch.hpp33-191
ITerminalApi (terminal abstraction): Abstracts buffer state and viewport manipulation to support different host backends (Windows Terminal, conhost) src/terminal/adapter/ITerminalApi.hpp20-150
Diagram: Code layer and runtime object structure
Sources: src/terminal/parser/stateMachine.hpp14-27 src/terminal/parser/OutputStateMachineEngine.hpp20-53 src/terminal/adapter/adaptDispatch.hpp33-191 src/terminal/adapter/ITerminalApi.hpp20-150 src/terminal/adapter/termDispatch.hpp22-106 src/terminal/adapter/ITermDispatch.hpp23-200
The processing pipeline for VT escape sequences transforms application output streams into updated terminal display states as follows:
Sequence details:
Application Output: VT bytes generated by running programs.
ConPTY or direct write feeds bytes into VT parser.
StateMachine transitions through states parsing sequences.
OutputStateMachineEngine identifies sequences and calls dispatch methods.
AdaptDispatch executes commands, modifying terminal buffer and cursor via ITerminalApi.
Sources: src/terminal/parser/OutputStateMachineEngine.cpp54-190 src/terminal/adapter/adaptDispatch.cpp62-191
StateMachine is a deterministic state machine that parses each input character and transitions through VT parser states. It buffers parameters, intermediates, and OSC strings until sequences are fully matched and actions can be dispatched src/terminal/parser/stateMachine.cpp14-201
| State | Description | Triggers |
|---|---|---|
Ground | Normal text printing and control characters | Printable text |
Escape | ESC character received, start an escape | \x1b (ESC) |
CsiEntry | CSI sequence start (ESC + [) | ESC + [ |
CsiParam | Parsing CSI parameters | Digits, ; separator |
OscString | Parsing OSC string content | After OSC start (ESC + ]) |
DcsString | Parsing DCS string content | After DCS start (ESC + P) |
Input: Processes one character at a time through ProcessCharacter().
Transition: Changes internal state according to VT spec rules:
Action Execution: When sequences complete (e.g., final byte detected), executes corresponding action on the engine interface (e.g., ActionCsiDispatch).
Parameter Storage: Buffers intermediate and final parameters, allowing dispatch of fully parsed parameters src/terminal/parser/stateMachine.cpp19-24
Sources: src/terminal/parser/stateMachine.hpp14-27 src/terminal/parser/stateMachine.cpp14-201
OutputStateMachineEngine implements the IStateMachineEngine interface, transforming parser actions into concrete VT method calls on ITermDispatch. It recognizes sequences based on a VTID: a packed code combining intermediates and final byte(s) to identify sequences uniquely src/terminal/parser/OutputStateMachineEngine.cpp20-25
| Method | Purpose | Example Sequences |
|---|---|---|
ActionExecute | Handle single C0 control characters | BEL, BS, LF, CR |
ActionPrint | Print a character | Normal glyph characters |
ActionPrintString | Print string blocks | Runs of plain text |
ActionEscDispatch | Simple ESC sequences | ESC 7 (DECSC), ESC 8 (DECRC) |
ActionCsiDispatch | Complex CSI sequences | CUU, CUD (cursor moves), SGR (attributes) |
ActionOscDispatch | Operating system commands | OSC 0 (Set window title), OSC 7 (CWD) |
VT sequences are identified using a 64-bit VTID constructed from:
Intermediate bytes: e.g. space ' ', $, ?
Final byte: e.g. 'm' for SGR, 'H' for CUP
This allows quick switch-case dispatching.
Sources: src/terminal/parser/OutputStateMachineEngine.cpp197-215 src/terminal/parser/OutputStateMachineEngine.hpp58-170
ITermDispatch is a pure virtual interface defining all VT commands the state machine engine can call. This includes cursor movement, screen erasing, attribute changes, printing characters/strings, and extended features src/terminal/adapter/ITermDispatch.hpp23-200
| Class | Description | Source File |
|---|---|---|
ITermDispatch | Abstract interface defining all VT command callbacks | ITermDispatch.hpp |
TermDispatch | Base class providing no-op defaults for most commands except printing; useful for tests | termDispatch.hpp |
AdaptDispatch | Implements full VT semantics for Windows Console using ITerminalApi | adaptDispatch.hpp |
OutputStateMachineEngine calls methods on this interface to effect terminal changes.
Sources: src/terminal/adapter/ITermDispatch.hpp23-200 src/terminal/adapter/termDispatch.hpp22-106 src/terminal/adapter/adaptDispatch.hpp33-191
AdaptDispatch is the Windows Console-specific implementation of ITermDispatch. It realizes VT commands with actual buffer and viewport changes using the ITerminalApi abstraction src/terminal/adapter/adaptDispatch.cpp40-49
Diagram: AdaptDispatch members and their roles
Sources: src/terminal/adapter/adaptDispatch.hpp33-49 src/terminal/adapter/adaptDispatch.cpp40-49
Print(char): Translates input character with _termOutput.TranslateKey(). Special handling avoids printing DEL character unless remapped src/terminal/adapter/adaptDispatch.cpp62-73
PrintString(string): Optionally translates each character in the string, then writes to buffer src/terminal/adapter/adaptDispatch.cpp82-98
_WriteToBuffer(string):
SetGraphicsRendition(VTParameters) handles SGR sequences by iterating through parameters and updating text attributes accordingly, such as foreground/background colors, bold, underline, reset, etc. src/terminal/adapter/adaptDispatch.hpp73
Sources: src/terminal/adapter/adaptDispatch.hpp73 src/terminal/adapter/adaptDispatch.cpp40-49
ITerminalApi abstracts terminal buffers, cursor state, and terminal features to decouple AdaptDispatch from underlying implementations. It provides methods to manipulate the terminal state, query system modes, set viewport position, and send responses back to the connected application src/terminal/adapter/ITerminalApi.hpp20-150
| Implementation | Location | Description |
|---|---|---|
Terminal | src/cascadia/TerminalCore/TerminalApi.cpp | Windows Terminal's terminal engine implementation |
ConhostInternalGetSet | src/host/outputStream.cpp | Adapter for conhost screen buffer and input system |
ConhostInternalGetSet holds a reference to an IIoProvider for console IO and accesses the screen buffer and input buffer directly src/host/outputStream.cpp22-65 It also implements response writing and mode querying.
Sources: src/terminal/adapter/ITerminalApi.hpp20-150 src/cascadia/TerminalCore/TerminalApi.cpp23-44 src/host/outputStream.cpp22-65
To create the VT processing stack, host apps instantiate an ITerminalApi implementation and then layer the adapter and parser:
This stack is prepared so that as bytes stream in through StateMachine::ProcessCharacter(), eventual dispatch calls reach AdaptDispatch executing terminal logic against the buffer.
Sources: src/host/outputStream.cpp22-82 src/terminal/parser/OutputStateMachineEngine.cpp20-25 src/terminal/parser/stateMachine.cpp14-32
The input side of VT processing is handled by InputStateMachineEngine. This engine processes VT sequences generated by user input (such as function keys, modifiers) and translates these into console input events.
Key features:
Mapping from CSI, SS3, and generic VT input codes to Windows virtual keys and modifiers src/terminal/parser/InputStateMachineEngine.cpp22-85
Special handling of control characters for generating synthesized key events src/terminal/parser/InputStateMachineEngine.cpp160-203
Support for waiting on Device Attributes reports (DA1) for terminal capability queries src/terminal/parser/InputStateMachineEngine.cpp104-130
Sources: src/terminal/parser/InputStateMachineEngine.cpp22-203
The VT Sequence Processing system in Windows Terminal is architected with modular separation:
StateMachine handles the lexical parsing and state transitions of the VT protocol.
OutputStateMachineEngine interprets sequences, converting them into typed dispatch calls.
ITermDispatch defines the full set of VT commands for output.
AdaptDispatch performs the actual terminal modifications by invoking ITerminalApi interfaces.
ITerminalApi abstracts terminal buffer access, allowing adaptation for different host implementations (Windows Terminal core or conhost).
This design enables extensible and testable handling of the VT standard with clear layering between parsing, recognition, and execution.
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.