OptimizedBuffer

Overview

The OptimizedBuffer class provides a high-performance, double-buffered rendering system for terminal UIs. It manages character cells, colors, attributes, and supports advanced features like scissor rects, opacity, and various drawing primitives.

Creating a Buffer

OptimizedBuffer.create()

Create a new optimized buffer.

static create(
  width: number,
  height: number,
  widthMethod: WidthMethod,
  options?: { respectAlpha?: boolean; id?: string }
): OptimizedBuffer

width

number

Width in terminal cells

height

number

Height in terminal cells

widthMethod

'unicode' | 'wcwidth'

Character width calculation method

options.respectAlpha

boolean

default:false

Whether to respect alpha channel in colors

options.id

string

Optional identifier for debugging

OptimizedBuffer

The created buffer instance

Example

import { OptimizedBuffer } from '@opentui/core'

const buffer = OptimizedBuffer.create(80, 24, 'unicode', {
  respectAlpha: true,
  id: 'main-buffer'
})

Properties

width

number

Buffer width in cells (read-only)

height

number

Buffer height in cells (read-only)

widthMethod

WidthMethod

Character width calculation method (read-only)

respectAlpha

boolean

Whether alpha blending is enabled

string

Buffer identifier

Basic Drawing Methods

clear()

Clear the entire buffer with a background color.

clear(bg?: RGBA): void

RGBA

default:"RGBA.fromValues(0, 0, 0, 1)"

Background color

Example

import { RGBA } from '@opentui/core'

buffer.clear(RGBA.fromHex('#1a1a1a'))

setCell()

Set a single cell’s character, colors, and attributes.

setCell(
  x: number,
  y: number,
  char: string,
  fg: RGBA,
  bg: RGBA,
  attributes?: number
): void

number

X coordinate (column)

number

Y coordinate (row)

char

string

Character to display (single character or grapheme cluster)

RGBA

Foreground color

RGBA

Background color

attributes

number

default:0

Text attributes (bold, italic, underline, etc.)

setCellWithAlphaBlending()

Set a cell with alpha blending.

setCellWithAlphaBlending(
  x: number,
  y: number,
  char: string,
  fg: RGBA,
  bg: RGBA,
  attributes?: number
): void

Parameters are the same as setCell(), but colors are blended with existing colors based on alpha values.

drawText()

Draw text at a position.

drawText(
  text: string,
  x: number,
  y: number,
  fg: RGBA,
  bg?: RGBA,
  attributes?: number,
  selection?: {
    start: number
    end: number
    bgColor?: RGBA
    fgColor?: RGBA
  } | null
): void

text

string

Text to draw

number

X coordinate (starting column)

number

Y coordinate (row)

RGBA

Foreground color

RGBA

Background color (optional)

attributes

number

default:0

Text attributes

selection

object

Optional selection range to highlight

Example

buffer.drawText('Hello, World!', 10, 5, 
  RGBA.fromHex('#ffffff'),
  RGBA.fromHex('#000000')
)

// With selection
buffer.drawText('Select this', 0, 0,
  RGBA.fromHex('#ffffff'),
  RGBA.fromHex('#000000'),
  0,
  { start: 7, end: 11, bgColor: RGBA.fromHex('#0066cc') }
)

fillRect()

Fill a rectangular area with a color.

fillRect(
  x: number,
  y: number,
  width: number,
  height: number,
  bg: RGBA
): void

number

X coordinate

number

Y coordinate

width

number

Rectangle width

height

number

Rectangle height

RGBA

Fill color

drawBox()

Draw a bordered box with optional title.

drawBox(options: {
  x: number
  y: number
  width: number
  height: number
  borderStyle?: BorderStyle
  customBorderChars?: Uint32Array
  border: boolean | BorderSides[]
  borderColor: RGBA
  backgroundColor: RGBA
  shouldFill?: boolean
  title?: string
  titleAlignment?: 'left' | 'center' | 'right'
}): void

options.x

number

X coordinate

options.y

number

Y coordinate

options.width

number

Box width

options.height

number

Box height

options.borderStyle

Border style preset

options.border

boolean | ('top' | 'right' | 'bottom' | 'left')[]

Which borders to draw (true = all sides)

options.borderColor

RGBA

Border color

options.backgroundColor

RGBA

Background color

options.shouldFill

boolean

default:false

Whether to fill the box interior

options.title

string

Optional title text

options.titleAlignment

'left' | 'center' | 'right'

default:"'left'"

Title alignment

Example

buffer.drawBox({
  x: 5,
  y: 5,
  width: 30,
  height: 10,
  borderStyle: 'rounded',
  border: true,
  borderColor: RGBA.fromHex('#666666'),
  backgroundColor: RGBA.fromHex('#000000'),
  shouldFill: true,
  title: 'My Window',
  titleAlignment: 'center'
})

Advanced Drawing

drawFrameBuffer()

Draw another buffer onto this buffer (compositing).

drawFrameBuffer(
  destX: number,
  destY: number,
  frameBuffer: OptimizedBuffer,
  sourceX?: number,
  sourceY?: number,
  sourceWidth?: number,
  sourceHeight?: number
): void

destX

number

Destination X coordinate

destY

number

Destination Y coordinate

frameBuffer

OptimizedBuffer

Source buffer to draw

sourceX

number

Optional source X (for partial copy)

sourceY

number

Optional source Y

sourceWidth

number

Optional source width

sourceHeight

number

Optional source height

drawGrid()

Draw a grid with borders.

drawGrid(options: {
  borderChars: Uint32Array
  borderFg: RGBA
  borderBg: RGBA
  columnOffsets: Int32Array
  rowOffsets: Int32Array
  drawInner: boolean
  drawOuter: boolean
}): void

options.borderChars

Uint32Array

Border characters (9 elements: TL, T, TR, L, C, R, BL, B, BR)

options.borderFg

RGBA

Border foreground color

options.borderBg

RGBA

Border background color

options.columnOffsets

Int32Array

Array of column X positions

options.rowOffsets

Int32Array

Array of row Y positions

options.drawInner

boolean

Draw inner grid lines

options.drawOuter

boolean

Draw outer border

Clipping and Opacity

pushScissorRect()

Push a clipping rectangle (subsequent draws are clipped to this region).

pushScissorRect(x: number, y: number, width: number, height: number): void

number

X coordinate

number

Y coordinate

width

number

Rectangle width

height

number

Rectangle height

popScissorRect()

Remove the most recent scissor rectangle.

popScissorRect(): void

clearScissorRects()

Remove all scissor rectangles.

clearScissorRects(): void

pushOpacity()

Push an opacity level (0 = transparent, 1 = opaque). Opacity levels are multiplied.

pushOpacity(opacity: number): void

opacity

number

Opacity value (0-1)

popOpacity()

Remove the most recent opacity level.

popOpacity(): void

getCurrentOpacity()

Get the current composite opacity.

getCurrentOpacity(): number

number

Current opacity value

clearOpacity()

Remove all opacity levels.

clearOpacity(): void

Buffer Management

resize()

Resize the buffer.

resize(width: number, height: number): void

width

number

New width

height

number

New height

destroy()

Destroy the buffer and free resources.

destroy(): void

setRespectAlpha()

Enable or disable alpha blending.

setRespectAlpha(respectAlpha: boolean): void

respectAlpha

boolean

Whether to respect alpha channel

Advanced Features

getSpanLines()

Get buffer content as structured spans (for text extraction, testing).

getSpanLines(): CapturedLine[]

CapturedLine[]

Array of lines with styled spans

CapturedLine Structure

interface CapturedLine {
  spans: CapturedSpan[]
}

interface CapturedSpan {
  text: string
  fg: RGBA
  bg: RGBA
  attributes: number
  width: number
}

getRealCharBytes()

Get the raw character data as UTF-8 bytes.

getRealCharBytes(addLineBreaks?: boolean): Uint8Array

addLineBreaks

boolean

default:false

Whether to add line breaks between rows

Uint8Array

UTF-8 encoded character data

Raw Buffer Access

buffers

Access raw buffer arrays (advanced use only).

get buffers(): {
  char: Uint32Array
  fg: Float32Array
  bg: Float32Array
  attributes: Uint32Array
}

char

Uint32Array

Character codepoints (with flags)

Float32Array

Foreground colors (RGBA, 4 floats per cell)

Float32Array

Background colors (RGBA, 4 floats per cell)

attributes

Uint32Array

Text attributes (bold, italic, etc.)

Example Usage

import { OptimizedBuffer, RGBA } from '@opentui/core'

const buffer = OptimizedBuffer.create(80, 24, 'unicode')

// Clear with dark background
buffer.clear(RGBA.fromHex('#1a1a1a'))

// Draw a box
buffer.drawBox({
  x: 10,
  y: 5,
  width: 60,
  height: 14,
  borderStyle: 'rounded',
  border: true,
  borderColor: RGBA.fromHex('#666666'),
  backgroundColor: RGBA.fromHex('#000000'),
  shouldFill: true,
  title: 'Console Output',
  titleAlignment: 'center'
})

// Draw text inside
buffer.drawText('Hello, World!', 15, 8,
  RGBA.fromHex('#00ff00'),
  RGBA.fromHex('#000000')
)

// Use scissor rect for clipping
buffer.pushScissorRect(10, 5, 60, 14)
buffer.drawText('This text is clipped', 5, 6,
  RGBA.fromHex('#ffffff')
)
buffer.popScissorRect()

// Use opacity
buffer.pushOpacity(0.5)
buffer.fillRect(20, 10, 40, 5, RGBA.fromHex('#ff0000'))
buffer.popOpacity()

// Cleanup
buffer.destroy()

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

​Overview

​Creating a Buffer

​OptimizedBuffer.create()

​Example

​Properties

​Basic Drawing Methods

​clear()

​Example

​setCell()

​setCellWithAlphaBlending()

​drawText()

​Example

​fillRect()

​drawBox()

​Example

​Advanced Drawing

​drawFrameBuffer()

​drawGrid()

​Clipping and Opacity

​pushScissorRect()

​popScissorRect()

​clearScissorRects()

​pushOpacity()

​popOpacity()

​getCurrentOpacity()

​clearOpacity()

​Buffer Management

​resize()

​destroy()

​setRespectAlpha()

​Advanced Features

​getSpanLines()

​CapturedLine Structure

​getRealCharBytes()

​Raw Buffer Access

​buffers

​Example Usage

Build docs developers (and LLMs) love

Overview

Creating a Buffer

OptimizedBuffer.create()

Example

Properties

Basic Drawing Methods

clear()

Example

setCell()

setCellWithAlphaBlending()

drawText()

Example

fillRect()

drawBox()

Example

Advanced Drawing

drawFrameBuffer()

drawGrid()

Clipping and Opacity

pushScissorRect()

popScissorRect()

clearScissorRects()

pushOpacity()

popOpacity()

getCurrentOpacity()

clearOpacity()

Buffer Management

resize()

destroy()

setRespectAlpha()

Advanced Features

getSpanLines()

CapturedLine Structure

getRealCharBytes()

Raw Buffer Access

buffers

Example Usage