FrameBuffer API

OptimizedBuffer

The OptimizedBuffer class (also known as FrameBuffer) provides low-level access to terminal rendering. It manages a grid of cells, each containing a character, foreground color, background color, and text attributes.

Creating Buffers

OptimizedBuffer.create

function

Create a new framebuffer

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

width

number

required

Width in terminal cells

height

number

required

Height in terminal cells

widthMethod

'unicode' | 'wcwidth' | 'no_zwj'

required

Character width calculation method

options.respectAlpha

boolean

Whether to respect alpha channel when compositing. Default: false

options.id

string

Optional identifier for debugging

Properties

width

number

Buffer width in cells

height

number

Buffer height in cells

widthMethod

WidthMethod

Character width calculation method used by this buffer

respectAlpha

boolean

Whether alpha blending is enabled

ptr

Pointer

Native pointer to the underlying buffer (for advanced use)

buffers

object

Direct access to raw buffer data

{
  char: Uint32Array        // Unicode codepoints
  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.)
}

Drawing Methods

clear

function

Clear the entire buffer with a background color

clear(bg?: RGBA): void

RGBA

Background color. Default: RGBA.fromValues(0, 0, 0, 1)

setCell

function

Set a single cell with no alpha blending

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

number

required

X coordinate (column)

number

required

Y coordinate (row)

char

string

required

Character to display (first codepoint used)

RGBA

required

Foreground color

RGBA

required

Background color

attributes

number

Text attributes (bold, italic, underline, etc.). Default: 0

setCellWithAlphaBlending

function

Set a single cell with alpha blending

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

Same parameters as setCell, but blends colors using alpha channel.

drawText

function

Draw text at a position with optional selection

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

text

string

required

Text to draw

number

required

Starting X coordinate

number

required

Starting Y coordinate

RGBA

required

Foreground color

RGBA

Background color

attributes

number

Text attributes. Default: 0

selection

object

Optional selection range to highlight

drawChar

function

Draw a single character by codepoint

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

char

number

required

Unicode codepoint

fillRect

function

Fill a rectangular area with a background color

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

drawBox

function

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

borderStyle

'single' | 'double' | 'rounded' | 'thick' | 'dashed'

Border style preset

border

boolean | BorderSides[]

required

Which sides to draw: true for all sides, or array like ["top", "left"]

titleAlignment

'left' | 'center' | 'right'

Title text alignment. Default: "left"

drawGrid

function

Draw a grid with custom column/row offsets

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

Compositing

drawFrameBuffer

function

Composite another framebuffer onto this one

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

destX

number

required

Destination X coordinate

destY

number

required

Destination Y coordinate

frameBuffer

OptimizedBuffer

required

Source buffer to composite

sourceX

number

Source region X offset

sourceY

number

Source region Y offset

sourceWidth

number

Source region width

sourceHeight

number

Source region height

drawTextBuffer

function

Draw a TextBufferView

drawTextBuffer(textBufferView: TextBufferView, x: number, y: number): void

drawEditorView

function

Draw an EditorView

drawEditorView(editorView: EditorView, x: number, y: number): void

Image Rendering

drawSuperSampleBuffer

function

Draw pixel data with supersampling

drawSuperSampleBuffer(
  x: number,
  y: number,
  pixelDataPtr: Pointer,
  pixelDataLength: number,
  format: "bgra8unorm" | "rgba8unorm",
  alignedBytesPerRow: number
): void

drawGrayscaleBuffer

function

Draw grayscale intensity data

drawGrayscaleBuffer(
  posX: number,
  posY: number,
  intensities: Float32Array,
  srcWidth: number,
  srcHeight: number,
  fg?: RGBA | null,
  bg?: RGBA | null
): void

drawGrayscaleBufferSupersampled

function

Draw grayscale data with supersampling for smoother rendering

drawGrayscaleBufferSupersampled(
  posX: number,
  posY: number,
  intensities: Float32Array,
  srcWidth: number,
  srcHeight: number,
  fg?: RGBA | null,
  bg?: RGBA | null
): void

Clipping and Opacity

pushScissorRect

function

Push a clipping rectangle onto the stack

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

popScissorRect

function

Pop the top clipping rectangle from the stack

popScissorRect(): void

clearScissorRects

function

Remove all clipping rectangles

clearScissorRects(): void

pushOpacity

function

Push an opacity value onto the stack (multiplies with existing opacity)

pushOpacity(opacity: number): void

opacity

number

required

Opacity value between 0.0 and 1.0

popOpacity

function

Pop the top opacity value from the stack

popOpacity(): void

getCurrentOpacity

function

Get the current effective opacity

getCurrentOpacity(): number

clearOpacity

function

Clear the opacity stack

clearOpacity(): void

Utilities

resize

function

Resize the buffer (clears content)

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

setRespectAlpha

function

Enable or disable alpha blending

setRespectAlpha(respectAlpha: boolean): void

getNativeId

function

Get the buffer’s native identifier

getNativeId(): string

getRealCharBytes

function

Get the resolved character data as UTF-8 bytes

getRealCharBytes(addLineBreaks?: boolean): Uint8Array

addLineBreaks

boolean

Whether to add newlines between rows. Default: false

getSpanLines

function

Extract buffer content as styled text spans

getSpanLines(): CapturedLine[]

Returns an array of lines, each containing spans with text, colors, and attributes.

destroy

function

Destroy the buffer and free native resources

destroy(): void

Example

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

// Create a 80x24 buffer
const buffer = OptimizedBuffer.create(80, 24, "unicode", {
  respectAlpha: true,
  id: "main-buffer"
})

// Clear with dark background
buffer.clear(RGBA.fromValues(0.1, 0.1, 0.1, 1))

// Draw text
buffer.drawText(
  "Hello, World!",
  5, 10,
  RGBA.fromHex("#00FF00"),
  RGBA.fromValues(0, 0, 0, 0)
)

// Draw a box
buffer.drawBox({
  x: 10,
  y: 5,
  width: 40,
  height: 10,
  border: true,
  borderStyle: "rounded",
  borderColor: RGBA.fromHex("#FFFFFF"),
  backgroundColor: RGBA.fromValues(0.2, 0.2, 0.3, 1),
  title: "My Box",
  titleAlignment: "center"
})

// Use clipping
buffer.pushScissorRect(0, 0, 40, 12)
buffer.drawText("Clipped text", 0, 0, RGBA.fromHex("#FF0000"))
buffer.popScissorRect()

// Clean up when done
buffer.destroy()

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

FrameBuffer API

OptimizedBuffer

Creating Buffers

Properties

Drawing Methods

Compositing

Image Rendering

Clipping and Opacity

Utilities

Example

Build docs developers (and LLMs) love

Core API

Text & Editing

Rendering

Input Handling

Layout

Advanced

Documentation Index

​OptimizedBuffer

​Creating Buffers

​Properties

​Drawing Methods

​Compositing

​Image Rendering

​Clipping and Opacity

​Utilities

​Example

Build docs developers (and LLMs) love

OptimizedBuffer

Creating Buffers

Properties

Drawing Methods

Compositing

Image Rendering

Clipping and Opacity

Utilities

Example