Core Terminal Engine

Relevant source files

Purpose and Scope

The Core Terminal Engine in the Windows Terminal repository is the fundamental terminal emulation layer engineered to process virtual terminal (VT) sequences, maintain terminal state, manage text buffers, and provide data for rendering. This engine is structured in a layered, modular fashion to separate concerns cleanly and allow extensibility and maintainability.

This page offers a high-level overview of the three primary layers in the terminal engine stack:

TermControl (UI layer): The front-facing WinRT XAML control managing interaction and visual presentation.
ControlCore (Logic layer): The orchestration layer that manages engine lifecycle, rendering, and connections.
Terminal (Engine layer): The core VT parser and terminal state machine managing buffer contents and VT processing.

For in-depth technical details, refer to the child pages that accompany this overview:

Terminal Control Architecture — Focuses on the WinRT control and interfaces.
Text Buffer System — Details buffer and cell storage mechanisms.
VT Sequence Processing — Explains VT parsing pipeline.
ConPTY and VT I/O — Describes PTY connection and VT input handling.
Console Host Architecture — Covers conhost.exe legacy console host internals.

Architecture Overview

The Core Terminal Engine is realized as a clean three-layer stack, separating UI, terminal logic, and emulation state management. This modular layering is critical for testability, reuse, and easier UI integration.

Layered Architecture Diagram

This separation ensures that UI concerns like XAML event handling and resizing do not clutter the core terminal logic, while ControlCore allows bridging the Terminal core with UI seamlessly.

Core Components

1. TermControl (The UI Layer)

TermControl is a WinRT XAML UserControl component that represents the visible terminal element inside the Windows Terminal app or any host that consumes the terminal control. It handles:

Rendering surfaces via SwapChainPanel and DirectX swap chains,
User interaction such as keyboard and mouse event routing,
Data binding and exposing API for querying terminal state,
Automation peers for UI Automation (UIA) and accessibility,
Integration with input panes and IME via TSF handle.

The control acts as the primary UI touchpoint for embedding terminals and exposing terminal features to app consumers.

For API and event details, see the WinRT IDL interface in `TermControl.idl` and the implementation in `TermControl.cpp`

2. ControlCore (The Logic and Orchestration Layer)

ControlCore is the logic engine that sits between the UI layer and the Terminal engine. It encapsulates:

The Terminal instance (state, buffer, and parser),
The rendering engine and pipeline (Renderer with AtlasEngine),
The connected process communication channel (ITerminalConnection),
Terminal appearance and dynamic settings management,
Input processing from the UI layer to the engine,
Event dispatching and terminal state synchronization.

It is designed to be independent of UI frameworks, making it easier to test and reuse in different hosting environments.

ControlCore accepts raw VT output from the connected process, orchestrates parsing via the terminal, and manages rendering state and requests.

Refer to `ControlCore.h` and `ControlCore.cpp` for constructor, callback setup, and lifecycle details.

3. Terminal (The Emulation Engine Layer)

At the heart lies the Terminal class representing the stateful terminal emulation core responsible for:

Parsing VT sequences via a StateMachine parser,
Managing the TextBuffer that stores character cells, attributes, and hyperlinks,
Maintaining terminal state like cursor, modes, scrollback, and colors,
Providing APIs for terminal state queries, state updates, and rendering data,
Translating input events to VT input sequences for sending to processes,
Implementing VT engine interfaces (ITerminalApi, ITerminalInput, IRenderData).

Incoming text from the PTY backend is fed through the Terminal::Write() method which drives parsing and updates to the text buffer.

See `Terminal.hpp` and `Terminal.cpp` for the full definition and core implementation.

Data Flow Diagrams

Output Data Flow (Process Output to Buffer)

This pipeline starts with encoded VT output from the connected process, delivered to ControlCore. It then flows into the terminal parsing and buffer update layers.

UI to Engine Input Data Flow (User Input to PTY Process)

The stack handles raw input events at the UI layer, which propagate down through the logic layers where input is encoded into VT sequences sent to the terminal backend.

Thread Safety and Synchronization

The Terminal engine uses a recursive ticket lock (til::recursive_ticket_lock) to synchronize access between threads that read buffer state (render thread/UI) and those that write (VT input thread).
Output-consuming methods acquire a write lock to modify buffer and state safely.
Rendering and state query methods use a read lock to ensure consistency while painting.
Internal assertions, such as _assertLocked(), enforce correct lock usage.
ControlCore orchestrates dispatch callbacks and timer-based tasks carefully respecting thread safety.

Summary Table of Key Code Entities and Responsibilities

Component	Role/Responsibility	Key Files / Lines
TermControl	UI hosting, input event handling, WinRT XAML surface	TerminalControl/TermControl.idl:28-160 TerminalControl/TermControl.cpp:40-190
ControlCore	Terminal logic orchestration, renderer & connection bridge	TerminalControl/ControlCore.h:79-135 TerminalControl/ControlCore.cpp:60-218
Terminal	VT engine: parser, buffer, state management	TerminalCore/Terminal.hpp:54-180 TerminalCore/Terminal.cpp:27-91
StateMachine	Parsing VT escape sequences	TerminalCore/Terminal.cpp:53-56 (usage)
AdaptDispatch	Dispatches VT sequences to buffer and terminal state	TerminalCore/Terminal.cpp, referenced by Terminal
TextBuffer	Stores terminal text cells, attributes, and scrollback	TerminalCore/TextBuffer (covered in detail in child page)

Further Exploration

To understand implementation details, protocol processing, and buffering, consult the linked child pages:

Sources:
src/cascadia/TerminalControl/TermControl.idl28-160
src/cascadia/TerminalControl/TermControl.cpp40-190
src/cascadia/TerminalControl/ControlCore.h79-135
src/cascadia/TerminalControl/ControlCore.cpp60-218
src/cascadia/TerminalCore/Terminal.hpp54-180
src/cascadia/TerminalCore/Terminal.cpp27-91

Core Terminal Engine

Relevant source files

Purpose and Scope

This page offers a high-level overview of the three primary layers in the terminal engine stack:

TermControl (UI layer): The front-facing WinRT XAML control managing interaction and visual presentation.
ControlCore (Logic layer): The orchestration layer that manages engine lifecycle, rendering, and connections.
Terminal (Engine layer): The core VT parser and terminal state machine managing buffer contents and VT processing.

For in-depth technical details, refer to the child pages that accompany this overview:

Terminal Control Architecture — Focuses on the WinRT control and interfaces.
Text Buffer System — Details buffer and cell storage mechanisms.
VT Sequence Processing — Explains VT parsing pipeline.
ConPTY and VT I/O — Describes PTY connection and VT input handling.
Console Host Architecture — Covers conhost.exe legacy console host internals.

Architecture Overview

Layered Architecture Diagram

This separation ensures that UI concerns like XAML event handling and resizing do not clutter the core terminal logic, while ControlCore allows bridging the Terminal core with UI seamlessly.

Core Components

1. TermControl (The UI Layer)

TermControl is a WinRT XAML UserControl component that represents the visible terminal element inside the Windows Terminal app or any host that consumes the terminal control. It handles:

Rendering surfaces via SwapChainPanel and DirectX swap chains,
User interaction such as keyboard and mouse event routing,
Data binding and exposing API for querying terminal state,
Automation peers for UI Automation (UIA) and accessibility,
Integration with input panes and IME via TSF handle.

The control acts as the primary UI touchpoint for embedding terminals and exposing terminal features to app consumers.

For API and event details, see the WinRT IDL interface in `TermControl.idl` and the implementation in `TermControl.cpp`

2. ControlCore (The Logic and Orchestration Layer)

ControlCore is the logic engine that sits between the UI layer and the Terminal engine. It encapsulates:

The Terminal instance (state, buffer, and parser),
The rendering engine and pipeline (Renderer with AtlasEngine),
The connected process communication channel (ITerminalConnection),
Terminal appearance and dynamic settings management,
Input processing from the UI layer to the engine,
Event dispatching and terminal state synchronization.

It is designed to be independent of UI frameworks, making it easier to test and reuse in different hosting environments.

ControlCore accepts raw VT output from the connected process, orchestrates parsing via the terminal, and manages rendering state and requests.

Refer to `ControlCore.h` and `ControlCore.cpp` for constructor, callback setup, and lifecycle details.

3. Terminal (The Emulation Engine Layer)

At the heart lies the Terminal class representing the stateful terminal emulation core responsible for:

Parsing VT sequences via a StateMachine parser,
Managing the TextBuffer that stores character cells, attributes, and hyperlinks,
Maintaining terminal state like cursor, modes, scrollback, and colors,
Providing APIs for terminal state queries, state updates, and rendering data,
Translating input events to VT input sequences for sending to processes,
Implementing VT engine interfaces (ITerminalApi, ITerminalInput, IRenderData).

Incoming text from the PTY backend is fed through the Terminal::Write() method which drives parsing and updates to the text buffer.

See `Terminal.hpp` and `Terminal.cpp` for the full definition and core implementation.

Data Flow Diagrams

Output Data Flow (Process Output to Buffer)

This pipeline starts with encoded VT output from the connected process, delivered to ControlCore. It then flows into the terminal parsing and buffer update layers.

UI to Engine Input Data Flow (User Input to PTY Process)

The stack handles raw input events at the UI layer, which propagate down through the logic layers where input is encoded into VT sequences sent to the terminal backend.

Thread Safety and Synchronization

The Terminal engine uses a recursive ticket lock (til::recursive_ticket_lock) to synchronize access between threads that read buffer state (render thread/UI) and those that write (VT input thread).
Output-consuming methods acquire a write lock to modify buffer and state safely.
Rendering and state query methods use a read lock to ensure consistency while painting.
Internal assertions, such as _assertLocked(), enforce correct lock usage.
ControlCore orchestrates dispatch callbacks and timer-based tasks carefully respecting thread safety.

Summary Table of Key Code Entities and Responsibilities

Component	Role/Responsibility	Key Files / Lines
TermControl	UI hosting, input event handling, WinRT XAML surface	TerminalControl/TermControl.idl:28-160 TerminalControl/TermControl.cpp:40-190
ControlCore	Terminal logic orchestration, renderer & connection bridge	TerminalControl/ControlCore.h:79-135 TerminalControl/ControlCore.cpp:60-218
Terminal	VT engine: parser, buffer, state management	TerminalCore/Terminal.hpp:54-180 TerminalCore/Terminal.cpp:27-91
StateMachine	Parsing VT escape sequences	TerminalCore/Terminal.cpp:53-56 (usage)
AdaptDispatch	Dispatches VT sequences to buffer and terminal state	TerminalCore/Terminal.cpp, referenced by Terminal
TextBuffer	Stores terminal text cells, attributes, and scrollback	TerminalCore/TextBuffer (covered in detail in child page)

Further Exploration

To understand implementation details, protocol processing, and buffering, consult the linked child pages:

Core Terminal Engine

Purpose and Scope

Architecture Overview

Layered Architecture Diagram

Core Components

1. TermControl (The UI Layer)

2. ControlCore (The Logic and Orchestration Layer)

3. Terminal (The Emulation Engine Layer)

Data Flow Diagrams

Output Data Flow (Process Output to Buffer)

UI to Engine Input Data Flow (User Input to PTY Process)

Thread Safety and Synchronization

Summary Table of Key Code Entities and Responsibilities

Further Exploration

On this page

Core Terminal Engine

Purpose and Scope

Architecture Overview

Layered Architecture Diagram

Core Components

1. TermControl (The UI Layer)

2. ControlCore (The Logic and Orchestration Layer)

3. Terminal (The Emulation Engine Layer)

Data Flow Diagrams

Output Data Flow (Process Output to Buffer)

UI to Engine Input Data Flow (User Input to PTY Process)

Thread Safety and Synchronization

Summary Table of Key Code Entities and Responsibilities

Further Exploration

On this page