Core Terminal Engine

Relevant source files

Purpose and Scope

The Core Terminal Engine is the emulation layer responsible for processing virtual terminal (VT) sequences, managing text storage, and maintaining terminal state. This page provides an overview of the layered architecture: TermControl (UI), ControlCore (Logic), and Terminal (Engine). It summarizes how data flows from a connection, is stored in memory, and is prepared for rendering.

For information about:

The deep dive into WinRT and logic separation, see Terminal Control Architecture
Detailed text buffer implementation and character storage, see Text Buffer System
VT sequence parsing and execution details, see VT Sequence Processing
Connection to child processes via ConPTY, see ConPTY and VT I/O
How the terminal content is rendered to screen, see Rendering System

Architecture Overview

The terminal engine follows a strict three-layer hierarchy to separate UI concerns from terminal emulation logic and state.

Layered Architecture Diagram

This diagram bridges "Natural Language" concepts to the specific code entities that define the terminal stack.

Sources: src/cascadia/TerminalControl/TermControl.h46-48 src/cascadia/TerminalControl/ControlInteractivity.h34-39 src/cascadia/TerminalControl/ControlCore.h79-84 src/cascadia/TerminalCore/Terminal.hpp54-58

Core Components

1. TermControl (The View)

The TermControl class is a WinRT XAML UserControl that serves as the primary entry point for the UI src/cascadia/TerminalControl/TermControl.idl28-32 It handles XAML-specific concerns like focus, keyboard events via IDirectKeyListener, and hosting the SwapChainPanel for rendering.

Sources: src/cascadia/TerminalControl/TermControl.idl28-32 src/cascadia/TerminalControl/TermControl.cpp147

2. ControlCore (The Logic Bridge)

ControlCore encapsulates the non-UI logic of a terminal instance src/cascadia/TerminalControl/ControlCore.h8-11 It orchestrates the relationship between the Terminal engine, the Renderer, and the ITerminalConnection src/cascadia/TerminalControl/ControlCore.cpp68-70

Initialization: Sets up the Terminal instance and attaches the Renderer src/cascadia/TerminalControl/ControlCore.cpp100-155
Settings: Propagates settings changes to both the engine and the renderer src/cascadia/TerminalControl/ControlCore.cpp97-99
Connection: Manages the ITerminalConnection which provides the data stream src/cascadia/TerminalControl/ControlCore.cpp105

Sources: src/cascadia/TerminalControl/ControlCore.h8-11 src/cascadia/TerminalControl/ControlCore.cpp68-70 src/cascadia/TerminalControl/ControlCore.cpp100-155 src/cascadia/TerminalControl/ControlCore.cpp97-99 src/cascadia/TerminalControl/ControlCore.cpp105

3. Terminal (The Engine)

The Terminal class is the stateful core of the system, defined in src/cascadia/TerminalCore/Terminal.hpp54-58 It maintains the emulation state and manages the TextBuffer.

Interface	Purpose	Key Methods
`ITerminalApi`	VT state modification	`SetSystemMode()`, `SetWindowTitle()` src/cascadia/TerminalCore/Terminal.hpp133-168
`IRenderData`	Data provider for Renderer	`GetTextBuffer()`, `GetViewport()` src/cascadia/TerminalCore/Terminal.hpp57
`ITerminalInput`	User input translation	`SendKeyEvent()`, `SendMouseEvent()` src/cascadia/TerminalCore/Terminal.hpp174-177

Sources: src/cascadia/TerminalControl/ControlCore.cpp100-160 src/cascadia/TerminalCore/Terminal.cpp28-56 src/cascadia/TerminalCore/Terminal.hpp54-177

Data Flow

Output Pipeline (PTY to Buffer)

This diagram maps the data flow from the underlying process connection to the internal text storage.

Incoming data arrives via Terminal::Write(std::wstring_view) src/cascadia/TerminalCore/Terminal.hpp106 It is processed by the StateMachine, which uses an OutputStateMachineEngine to drive an AdaptDispatch instance src/cascadia/TerminalCore/Terminal.cpp53-55 This dispatcher finally modifies the TextBuffer src/cascadia/TerminalCore/Terminal.cpp51

Sources: src/cascadia/TerminalCore/Terminal.hpp106 src/cascadia/TerminalCore/Terminal.cpp51-56 src/cascadia/TerminalControl/ControlCore.cpp100-110

Input Pipeline (User to Connection)

Event Capture: TermControl receives Win32/XAML input events (e.g., OnDirectKeyEvent) src/cascadia/TerminalControl/TermControl.cpp147
Interactivity: ControlInteractivity processes high-level actions like selection or scrolling src/cascadia/TerminalControl/ControlInteractivity.cpp54-70
Translation: Terminal::SendKeyEvent uses TerminalInput to translate keys into VT sequences src/cascadia/TerminalCore/Terminal.hpp176
Transmission: ControlCore sends the resulting strings to the ITerminalConnection src/cascadia/TerminalControl/ControlCore.cpp105

Sources: src/cascadia/TerminalControl/TermControl.cpp147 src/cascadia/TerminalControl/ControlInteractivity.cpp49-50 src/cascadia/TerminalCore/Terminal.hpp176 src/cascadia/TerminalControl/ControlCore.cpp105

Thread Safety and Locking

The Terminal engine employs a til::recursive_ticket_lock to synchronize access between the background VT processing thread and the UI/Render threads.

Locking for Writing: Required when the StateMachine is updating the TextBuffer or terminal state src/cascadia/TerminalCore/Terminal.hpp111
Locking for Reading: Required when the Renderer is traversing the TextBuffer to paint a frame src/cascadia/TerminalCore/Terminal.hpp110 This is also used by RenderData::LockConsole() in conhost.exe src/host/renderData.cpp90-93
Assertions: The codebase uses _assertLocked() extensively to ensure internal state is never accessed unsafely src/cascadia/TerminalCore/Terminal.hpp108

Sources: src/cascadia/TerminalCore/Terminal.hpp108-112 src/cascadia/TerminalCore/Terminal.cpp101 src/host/renderData.cpp90-93