Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Rikitav/Terminality/llms.txt

Use this file to discover all available pages before exploring further.

Every time Terminality redraws a widget it calls RenderOverride(RenderContext& context) with a RenderContext scoped to the widget’s allocated rectangle. The context clips all drawing to that region and writes into a shared RenderBuffer. When the frame is done, the buffer diffs itself against the previous snapshot and flushes only changed cells to the terminal. This page documents the full surface of RenderContext, the RenderStream fluent helper, and the RenderBuffer that backs them.

​
Class: RenderContext

A RenderContext is created by the engine and passed to RenderOverride. You do not instantiate it directly in application code. Every drawing method coordinates through the owning RenderBuffer using absolute buffer positions derived from the widget’s Rect.

​
Constructor (internal)

RenderContext(RenderBuffer& buffer, Rect targetRect);
Used internally by the engine. targetRect defines the clipping region in buffer coordinates.

​
CreateInner

RenderContext CreateInner(Rect targetRect);
Returns a new RenderContext clipped to targetRect within the current context’s bounds. Useful when a composite widget wants to render sub-sections with tighter clipping. The inner rect is clamped so it never escapes the outer bounds.
​
targetRect
Rect
required
Target rectangle in the parent context’s local coordinate space.
​
return
RenderContext
A new context clipped to the intersection of targetRect and the current context.

​
ContextRect

Rect ContextRect();
Returns the current clipping rectangle in buffer-absolute coordinates.
​
return
Rect
The absolute Rect this context draws into.

​
SetCell (two overloads)

void SetCell(uint32_t x, uint32_t y, const CellInfo& cell);
void SetCell(uint32_t x, uint32_t y, wchar_t ch, Color fg = Color::WHITE, Color bg = Color::BLACK);
Writes a single character cell at local coordinates (x, y). Coordinates outside the clipping rect are silently ignored. The second overload creates a CellInfo inline.
​
x
uint32_t
required
Column in local (context-relative) coordinates.
​
y
uint32_t
required
Row in local coordinates.
​
cell / ch
CellInfo or wchar_t
required
The cell state or character to write.

​
GetCell

const CellInfo& GetCell(uint32_t x, uint32_t y) const;
Reads the current cell state at local coordinates. Returns a default CellInfo (space, white on black) for out-of-bounds positions.
​
return
const CellInfo&
The cell at (x, y), or an empty cell if the coordinates are out of range.

​
BeginText

RenderStream BeginText(Point startPos = Point(0, 0));
Creates a RenderStream anchored at startPos. The stream inherits this context and allows chaining color changes and text output with <<. See RenderStream below.
​
startPos
Point
default:"Point(0, 0)"
Starting cursor position within the context’s local coordinate space.
​
return
RenderStream
A stream object bound to this context.

​
RenderRaw

void RenderRaw(const Point& point, const std::string& rawData);
Writes raw bytes as characters starting at point, without color or encoding conversion. Intended for pre-formatted ANSI escape sequences or character art.

​
RenderText (four overloads)

void RenderText(const Point& point, const std::wstring& text,
                Color fg = Color::WHITE, Color bg = Color::BLACK, bool wrap = false);
void RenderText(const Point& point, const std::string& text, ...);
void RenderText(const Point& point, const wchar_t* text, ...);
void RenderText(const Point& point, const char* text, ...);
Renders a text string at point with the given foreground and background colors. When wrap is true, text that overflows the width wraps to the next row. All overloads converge on the std::wstring implementation.
​
point
Point
required
Top-left origin of the text in local coordinates.
​
text
string or wchar_t*
required
The text content to render.
​
fg
Color
default:"Color::WHITE"
Foreground (character) color.
​
bg
Color
default:"Color::BLACK"
Background color behind the text.
​
wrap
bool
default:"false"
When true, text wraps to subsequent rows instead of clipping at the right edge.

​
RenderRectangle (multiple overloads)

void RenderRectangle(const Point& point, const Size& size);
void RenderRectangle(const Point& point, const Size& size, Color fg, Color bg);
void RenderRectangle(const Point& point, const Size& size, RectangleStyle style);
void RenderRectangle(const Point& point, const Size& size, Color fg, Color bg, RectangleStyle style);
// Width/height scalar overloads mirror the above
void RenderRectangle(const Point& point, int32_t width, int32_t height);
void RenderRectangle(const Point& point, int32_t width, int32_t height, Color fg, Color bg);
void RenderRectangle(const Point& point, int32_t width, int32_t height, RectangleStyle style);
void RenderRectangle(const Point& point, int32_t width, int32_t height, Color fg, Color bg, RectangleStyle style);
Fills a rectangle with characters produced by style. The default style fills with #. A RectangleStyle is a function pointer wchar_t(*)(const Point&, const Size&) that receives each cell’s local position and the rectangle’s size; return L'\0' to skip a cell. 
// Custom border-drawing style
wchar_t BorderStyle(const Point& p, const Size& sz)
{
    bool top    = p.Y == 0;
    bool bottom = p.Y == sz.Height - 1;
    bool left   = p.X == 0;
    bool right  = p.X == sz.Width - 1;

    if (top    && left)  return L'┌';
    if (top    && right) return L'┐';
    if (bottom && left)  return L'└';
    if (bottom && right) return L'┘';
    if (top    || bottom) return L'─';
    if (left   || right)  return L'│';
    return L'\0'; // leave interior cells untouched
}

context.RenderRectangle(Point(0, 0), Size(20, 5), Color::CYAN, Color::BLACK, BorderStyle);

​
RenderLine (multiple overloads)

void RenderLine(const Point& fromPoint, const Point& toPoint);
void RenderLine(const Point& fromPoint, const Point& toPoint, VectorStyle style);
void RenderLine(const Point& point, int32_t length, short direction = 0);
void RenderLine(const Point& point, int32_t length, VectorStyle style);
void RenderLine(const Vector& vector);
void RenderLine(const Vector& vector, VectorStyle style);
Draws a line using Bresenham’s algorithm. The default style chooses ─ for horizontal and │ for vertical movement. A VectorStyle is wchar_t(*)(const Point&, const Vector&); receive the current point and the full vector, return L'\0' to skip. direction 0 means horizontal, non-zero means vertical.

​
Class: RenderStream

RenderStream is a fluent, stream-style wrapper around RenderContext::RenderText. Obtain one by calling context.BeginText(). The stream tracks the current cursor position and active colors, advancing the cursor after each text write.

​
Positioning with <<

RenderStream& operator<<(const Point& point);
Moves the cursor to point without drawing anything.

​
Color with <<

RenderStream& operator<<(const RenderStreamColor& color);
Sets the foreground and/or background color for subsequent text. Use the SetFore, SetBack, and SetColor helpers to create a RenderStreamColor: 
inline RenderStreamColor SetColor(Color fg, Color bg = Color::BLACK);
inline RenderStreamColor SetFore(Color fg);
inline RenderStreamColor SetBack(Color bg);

​
Text output with <<

RenderStream& operator<<(const std::wstring& text);
RenderStream& operator<<(const std::string& text);
RenderStream& operator<<(const wchar_t* text);
RenderStream& operator<<(const char* text);
RenderStream& operator<<(int32_t value);
RenderStream& operator<<(uint32_t value);
RenderStream& operator<<(float value);
RenderStream& operator<<(double value);
Each write appends text at the current cursor position using the active foreground and background colors, then advances the cursor by the text width.

​
Manipulators

RenderStream& operator<<(RenderStream& (*manipulator)(RenderStream&));
Accepts stream manipulator functions. The built-in endl manipulator calls NewLine(): 
inline RenderStream& endl(RenderStream& stream);

​
NewLine

void NewLine();
Moves the cursor to column 0 of the next row.

​
Complete RenderOverride example

The MessageBubble widget from the test application demonstrates typical RenderStream usage: a single BeginText() call followed by chained color and text writes, with focused_ driving the color choice. 
void RenderOverride(RenderContext& context) override
{
    auto rin = context.BeginText();

    if (focused_)
    {
        rin << SetBack(Color::WHITE);
        rin << SetFore(Color::DARK_GRAY) << message_.Timestamp;
    }
    else
    {
        rin << SetBack(Color::BLACK);
        rin << SetFore(Color::LIGHT_GRAY) << message_.Timestamp;
    }

    rin << SetFore(message_.isAuthor ? Color::CYAN : Color::YELLOW);
    rin << " " << message_.Text;
}

​
Class: RenderBuffer

RenderBuffer is the backing store for the terminal display. It holds two cell grids — the current frame and the previous snapshot — and computes the dirty region between them so DiffRender only writes changed cells to stdout. You do not normally interact with RenderBuffer directly; RenderContext writes into it on your behalf. It is documented here for completeness and for use in custom engine extensions.

​
Constructor

RenderBuffer(uint32_t initialWidth, uint32_t initialHeight);
​
initialWidth
uint32_t
required
Initial column count. Must not exceed MAX_WIDTH (512).
​
initialHeight
uint32_t
required
Initial row count. Must not exceed MAX_HEIGHT (256).

​
Dimensions

uint32_t Width() const;
uint32_t Height() const;
void Resize(uint32_t newWidth, uint32_t newHeight);
Resize is called automatically by the engine when the terminal window size changes (after the debounce timer fires on ResizeFinishedEvent).

​
Cell access

void SetCell(uint32_t x, uint32_t y, const CellInfo& cell);
const CellInfo& GetCell(uint32_t x, uint32_t y) const;
Direct cell read/write. RenderContext uses these internally.

​
Clear

void Clear(const CellInfo& cell = CellInfo());
Fills the entire buffer with cell (default: space, white on black).

​
Dirty-region tracking

void Snapshot();
void DiffRender(std::wostream& out);
void BulkRender(std::wostream& out);
Snapshot copies the current buffer into the snapshot grid. DiffRender compares the current buffer to the snapshot and emits ANSI escape sequences only for cells that differ. BulkRender unconditionally emits all cells — used on first draw or after a resize. The engine calls these automatically each frame; applications do not need to call them.

​
Constants

ConstantValueDescription
MAX_WIDTH512Maximum column count
MAX_HEIGHT256Maximum row count

​
CellInfo struct

A single terminal cell: character, foreground color, and background color. 
struct CellInfo
{
    wchar_t Symbol = L' ';
    Color   Fore   = Color::WHITE;
    Color   Back   = Color::BLACK;

    CellInfo() = default;
    CellInfo(wchar_t symbol, Color fore = Color::WHITE, Color back = Color::BLACK);

    bool operator==(const CellInfo&) const;
    bool operator!=(const CellInfo&) const;
};
  • Color — Color::WHITE, Color::CYAN, and all named color values
  • Geometry — Point, Size, Rect, Vector types used throughout
  • DispatchTimer — drive per-frame animations by mutating properties from TickEvent

Build docs developers (and LLMs) love

Get started for freeTalk to us