OptimizedBuffer

High-performance buffer for terminal rendering operations

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 · 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

id · string

Buffer identifier

Basic Drawing Methods

clear()

Clear the entire buffer with a background color.

clear(bg?: RGBA): void

bg · 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

x · number

X coordinate (column)

y · number

Y coordinate (row)

char · string

Character to display (single character or grapheme cluster)

fg · RGBA

Foreground color

bg · 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

x · number

X coordinate (starting column)

y · number

Y coordinate (row)

fg · RGBA

Foreground color

bg · 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

x · number

X coordinate

y · number

Y coordinate

width · number

Rectangle width

height · number

Rectangle height

bg · 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 · 'single' | 'double' | 'rounded' | 'bold' | 'double-single' | 'single-double'

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

x · number

X coordinate

y · 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 · 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[] · 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 · 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)

fg · Float32Array

Foreground colors (RGBA, 4 floats per cell)

bg · 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()