Surface

Namespace: Hex1b.Surfaces

Assembly: Hex1b.dll

A 2D grid of cells representing a rectangular area of terminal content.

public sealed class Surface : ISurfaceSource

Inheritance

Object → Surface

Implements

• ISurfaceSource

Constructors

Surface(int, int, CellMetrics)

Creates a new surface with the specified dimensions and cell metrics. All cells are initialized to .

Parameters:

• width (Int32): The width in columns. Must be positive.
• height (Int32): The height in rows. Must be positive.
• cellMetrics (CellMetrics): The pixel dimensions of terminal cells.

public Surface(int width, int height, CellMetrics cellMetrics)

Surface(int, int)

Creates a new surface with the specified dimensions and default cell metrics. All cells are initialized to .

Parameters:

• width (Int32): The width in columns. Must be positive.
• height (Int32): The height in rows. Must be positive.

public Surface(int width, int height)

Properties

CellCount

Gets the total number of cells in the surface.

Returns: Int32

public int CellCount { get; }

CellMetrics

Gets the cell metrics for this surface.

Returns: CellMetrics

public CellMetrics CellMetrics { get; }

HasKgp

Gets whether this surface contains any KGP (Kitty Graphics Protocol) images.

Returns: Boolean

public bool HasKgp { get; }

HasSixels

Gets whether this surface contains any sixel graphics.

Returns: Boolean

public bool HasSixels { get; }

Height

Gets the height of the surface in rows.

Returns: Int32

public int Height { get; }

this[int, int]

Gets or sets the cell at the specified position.

Parameters:

• x (Int32): The column (0-based).
• y (Int32): The row (0-based).

Returns: SurfaceCell

The cell at the specified position.

public SurfaceCell this[int x, int y] { get; set; }

Width

Gets the width of the surface in columns.

Returns: Int32

public int Width { get; }

Methods

AsSpan()

Gets a read-only span over all cells in row-major order.

Returns: ReadOnlySpan<SurfaceCell>

A span of all cells.

public ReadOnlySpan<SurfaceCell> AsSpan()

Clear()

Clears all cells to .

public void Clear()

Clear(SurfaceCell)

Clears all cells to the specified cell value.

Parameters:

• cell (SurfaceCell): The cell value to fill with.

public void Clear(SurfaceCell cell)

Clone()

Creates a deep copy of this surface.

Returns: Surface

A new surface with the same dimensions, cell metrics, and cell values.

public Surface Clone()

Composite(ISurfaceSource, int, int, Rect?)

Composites another surface source onto this surface at the specified offset.

Parameters:

• source (ISurfaceSource): The source to composite (Surface, CompositeSurface, or any ISurfaceSource).
• offsetX (Int32): The X offset in this surface where the source's (0,0) will be placed.
• offsetY (Int32): The Y offset in this surface where the source's (0,0) will be placed.
• clip (Nullable<Rect>): Optional clip rectangle in destination coordinates. If null, uses entire destination.

public void Composite(ISurfaceSource source, int offsetX, int offsetY, Rect? clip = null)

Fill(Rect, SurfaceCell)

Fills a rectangular region with the specified cell value. The region is clipped to the surface bounds.

Parameters:

• region (Rect): The region to fill.
• cell (SurfaceCell): The cell value to fill with.

public void Fill(Rect region, SurfaceCell cell)

GetCell(int, int)

Gets the cell at the specified position.

Parameters:

• x (Int32): The column (0-based).
• y (Int32): The row (0-based).

Returns: SurfaceCell

The cell at the specified position.

public SurfaceCell GetCell(int x, int y)

GetRow(int)

Gets a read-only span over the cells in a specific row.

Parameters:

• row (Int32): The row index (0-based).

Returns: ReadOnlySpan<SurfaceCell>

A span of cells in the specified row.

public ReadOnlySpan<SurfaceCell> GetRow(int row)

IsInBounds(int, int)

Checks if the specified position is within the surface bounds.

Parameters:

• x (Int32): The column (0-based).
• y (Int32): The row (0-based).

Returns: Boolean

True if the position is within bounds, false otherwise.

public bool IsInBounds(int x, int y)

TryGetCell(int, int, out SurfaceCell)

Tries to get the cell at the specified position. Returns false if the position is outside the surface bounds.

Parameters:

• x (Int32): The column (0-based).
• y (Int32): The row (0-based).
• cell (SurfaceCell): The cell at the position, or default if out of bounds.

Returns: Boolean

True if the position is valid, false otherwise.

public bool TryGetCell(int x, int y, out SurfaceCell cell)

TrySetCell(int, int, SurfaceCell)

Tries to set the cell at the specified position. Returns false if the position is outside the surface bounds.

Parameters:

• x (Int32): The column (0-based).
• y (Int32): The row (0-based).
• cell (SurfaceCell): The cell to set.

Returns: Boolean

True if the position is valid and the cell was set, false otherwise.

public bool TrySetCell(int x, int y, SurfaceCell cell)

WriteChar(int, int, char, Hex1bColor?, Hex1bColor?, CellAttributes)

Writes a single character to the surface at the specified position.

Parameters:

• x (Int32): The column (0-based).
• y (Int32): The row (0-based).
• character (Char): The character to write.
• foreground (Nullable<Hex1bColor>): The foreground color, or null for transparent.
• background (Nullable<Hex1bColor>): The background color, or null for transparent.
• attributes (CellAttributes): Text styling attributes.

Returns: Boolean

True if the character was written, false if the position was out of bounds.

public bool WriteChar(int x, int y, char character, Hex1bColor? foreground = null, Hex1bColor? background = null, CellAttributes attributes = CellAttributes.None)

WriteText(int, int, string, Hex1bColor?, Hex1bColor?, CellAttributes)

Writes text to the surface starting at the specified position.

Parameters:

• x (Int32): The starting column (0-based).
• y (Int32): The row (0-based).
• text (String): The text to write.
• foreground (Nullable<Hex1bColor>): The foreground color, or null for transparent.
• background (Nullable<Hex1bColor>): The background color, or null for transparent.
• attributes (CellAttributes): Text styling attributes.

Returns: Int32

The number of columns written (including continuations).

public int WriteText(int x, int y, string text, Hex1bColor? foreground = null, Hex1bColor? background = null, CellAttributes attributes = CellAttributes.None)

Remarks

A provides a buffer for rendering terminal content. It supports direct cell manipulation, text writing with automatic grapheme and wide character handling, and compositing with other surfaces.

Surfaces are fixed-size and use row-major storage for cache-efficient iteration. Thread safety is the caller's responsibility - surfaces are designed for high-performance single-threaded rendering.

Each surface carries that define the pixel dimensions of terminal cells. This is needed for sixel graphics, which are defined in pixels but must be mapped to cell boundaries for proper rendering and clipping.