Class NetConsoleDriver

Namespace

SharpConsoleUI.Drivers

Assembly

SharpConsoleUI.dll

Provides a cross-platform console driver implementation.

public class NetConsoleDriver : IConsoleDriver, IGraphicsProtocol

Inheritance

object

NetConsoleDriver

Implements

IConsoleDriver

IGraphicsProtocol

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

Remarks

Windows: Uses .NET Console APIs with Win32 console mode configuration for virtual terminal input/output and mouse reporting.

Unix: Bypasses .NET's Console infrastructure entirely, using raw libc I/O for both input (read from stdin fd 0) and output (write to stdout fd 1). Terminal is put into raw mode via tcgetattr/tcsetattr (cfmakeraw equivalent), and an alternate screen buffer is used for clean display. Console.Out is redirected to /dev/null to prevent .NET runtime code from touching stdout. Window size is queried via ioctl TIOCGWINSZ instead of Console.WindowWidth/Height. SIGINT/SIGTSTP are suppressed via signal() instead of Console.TreatControlCAsInput.

Why: .NET's ConsolePal.Unix calls tcsetattr on every Console.ReadKey, Console.SetCursorPosition, Console.CursorVisible, and even Console.OutputEncoding access. Each tcsetattr briefly toggles the ECHO flag, creating windows where raw mouse/keyboard ANSI sequences leak to the screen. The only reliable fix is to never touch any Console.* property on the hot path.

Approach inspired by Terminal.Gui v2 (https://github.com/gui-cs/Terminal.Gui), which solved the same problem in their Unix NetDriver by using raw file descriptor I/O and avoiding all .NET Console APIs on Unix. Key techniques adopted: reading from stdin fd 0 directly (not /dev/tty, to avoid byte competition with .NET's internal fd 0 reader), tcflush to clear pending input, and alternate screen buffer usage.

Constructors

NetConsoleDriver(NetConsoleDriverOptions)

Initializes a new instance of the NetConsoleDriver class with configuration options.

public NetConsoleDriver(NetConsoleDriverOptions options)

Parameters

options NetConsoleDriverOptions

Configuration options for the driver.

Exceptions

ArgumentNullException

Thrown when options is null.

ApplicationException

Thrown when console mode configuration fails on Windows platforms.

NetConsoleDriver(RenderMode)

Initializes a new instance of the NetConsoleDriver class with a specific render mode.

public NetConsoleDriver(RenderMode renderMode = RenderMode.Buffer)

Parameters

renderMode RenderMode

The rendering mode to use. Defaults to Buffer.

Exceptions

ApplicationException

Thrown when console mode configuration fails on Windows platforms.

Properties

Options

Gets the driver configuration options.

public NetConsoleDriverOptions Options { get; }

Property Value

NetConsoleDriverOptions

RenderMode

Gets the rendering mode for console output.

public RenderMode RenderMode { get; }

Property Value

RenderMode

The current render mode.

Remarks

The render mode is set during driver construction and cannot be changed afterward.

ScreenSize

Gets the current size of the console screen.

public Size ScreenSize { get; }

Property Value

Size

A Size representing the width and height of the console in characters.

SupportsKittyGraphics

Whether the terminal supports Kitty graphics protocol.

public bool SupportsKittyGraphics { get; }

Property Value

bool

Methods

Cleanup()

Restores the console to its original configuration.

public void Cleanup()

Remarks

On Windows, this method restores the original console modes for input, output, and error handles. This method is automatically called by Stop().

Exceptions

ApplicationException

Thrown when restoring console modes fails on Windows platforms.

Clear()

Clears the console screen or buffer.

public void Clear()

DeleteImage(uint)

Delete a previously transmitted image from the terminal.

public void DeleteImage(uint imageId)

Parameters

imageId uint

The image identifier to delete.

FillCells(int, int, int, char, Color, Color)

Fills a horizontal run of cells at the specified position with the given character and colors.

public void FillCells(int x, int y, int width, char character, Color fg, Color bg)

Parameters

x int

The starting horizontal position (column).

y int

The vertical position (row).

width int

The number of cells to fill.

character char

The character to fill with.

fg Color

The foreground color.

bg Color

The background color.

Flush()

Flushes any buffered output to the console.

public void Flush()

Remarks

For buffered render modes, this triggers the actual rendering to the console. For direct render modes, this may be a no-op.

GetDirtyCharacterCount()

Gets the count of dirty characters in the rendering buffer.

public int GetDirtyCharacterCount()

Returns

int

The number of dirty characters, or 0 if not using buffered rendering.

Initialize(ConsoleWindowSystem)

Initializes the driver with a reference to the window system. Called by ConsoleWindowSystem after state services are created.

public void Initialize(ConsoleWindowSystem windowSystem)

Parameters

windowSystem ConsoleWindowSystem

The window system instance

ResetCursorShape()

Resets the cursor to the default shape.

public void ResetCursorShape()

SetCursorPosition(int, int)

Sets the cursor position on the console screen.

public void SetCursorPosition(int x, int y)

Parameters

x int

The column position (0-based).

y int

The row position (0-based).

SetCursorShape(CursorShape)

Sets the cursor shape/style.

public void SetCursorShape(CursorShape shape)

Parameters

shape CursorShape

The desired cursor shape.

SetCursorVisible(bool)

Sets the visibility of the cursor.

public void SetCursorVisible(bool visible)

Parameters

visible bool

True to show the cursor, false to hide it.

SetNarrowCell(int, int, char, Color, Color)

Sets a single cell at the specified position with the given character and colors.

public void SetNarrowCell(int x, int y, char character, Color fg, Color bg)

Parameters

x int

The horizontal position (column).

y int

The vertical position (row).

character char

The character to write.

fg Color

The foreground color.

bg Color

The background color.

Start()

Starts the console driver, initializing input handling and enabling mouse/keyboard events.

public void Start()

Stop()

Stops the console driver, disabling input handling and restoring the console to its original state.

public void Stop()

TransmitImage(uint, byte[], int, int)

Transmit an image to the terminal for virtual placement. The image is assigned the given ID and sized to span the specified number of terminal columns and rows.

public void TransmitImage(uint imageId, byte[] pngData, int columns, int rows)

Parameters

imageId uint

Unique image identifier.

pngData byte[]

PNG-encoded image data.

columns int

Number of terminal columns the image spans.

rows int

Number of terminal rows the image spans.

TransmitRawRgb(uint, byte[], int, int, int, int)

Transmit a raw RGB24 frame to the terminal, sized to span the given cell area. Retransmitting with the same imageId updates the image in place, which is how high-frame-rate video playback works without per-frame delete churn. The default implementation throws NotSupportedException; drivers that support streaming raw frames (such as NetConsoleDriver for Kitty graphics) override it.

public void TransmitRawRgb(uint imageId, byte[] rgbData, int pixelWidth, int pixelHeight, int columns, int rows)

Parameters

imageId uint

Unique image identifier. Reuse across frames for in-place updates.

rgbData byte[]

Raw RGB24 pixel data, pixelWidth * pixelHeight * 3 bytes, row-major.

pixelWidth int

Pixel width of the frame.

pixelHeight int

Pixel height of the frame.

columns int

Number of terminal columns the image spans.

rows int

Number of terminal rows the image spans.

UpdateRawRgbFrame(uint, byte[], int, int)

Update the root-frame pixel data of a previously transmitted image with fresh raw RGB24 bytes, without affecting any active placements. This is the correct primitive for streaming video: the existing virtual placements keep referencing the image and the terminal redraws them against the new pixels. Issuing TransmitRawRgb(uint, byte[], int, int, int, int) with the same id would instead delete all existing placements per the Kitty protocol spec, which would cause the image to disappear until placeholder cells are re-emitted.

public void UpdateRawRgbFrame(uint imageId, byte[] rgbData, int pixelWidth, int pixelHeight)

Parameters

imageId uint

rgbData byte[]

pixelWidth int

pixelHeight int

WriteBufferRegion(int, int, CharacterBuffer, int, int, int, Color)

Copies a horizontal strip of cells from a CharacterBuffer directly to the console output buffer, bypassing ANSI string serialization and parsing.

public void WriteBufferRegion(int destX, int destY, CharacterBuffer source, int srcX, int srcY, int width, Color fallbackBg)

Parameters

destX int

Destination screen X position.

destY int

Destination screen Y position.

source CharacterBuffer

The source CharacterBuffer.

srcX int

Source X offset within the buffer.

srcY int

Source Y (row) within the buffer.

width int

Number of cells to write.

fallbackBg Color

Background color for padding when source is out of bounds.

Events

KeyPressed

Occurs when a key is pressed on the keyboard.

public event EventHandler<ConsoleKeyInfo>? KeyPressed

Event Type

EventHandler<ConsoleKeyInfo>

MouseEvent

Occurs when a mouse event is detected.

public event IConsoleDriver.MouseEventHandler? MouseEvent

Event Type

IConsoleDriver.MouseEventHandler

ScreenResized

Occurs when the console screen is resized.

public event EventHandler<Size>? ScreenResized

Event Type

EventHandler<Size>