FrameBuffer API

Low-level framebuffer API for direct rendering to terminal cells

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

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

x · number · required

X coordinate (column)

y · number · required

Y coordinate (row)

char · string · required

Character to display (first codepoint used)

fg · RGBA · required

Foreground color

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

x · number · required

Starting X coordinate

y · number · required

Starting Y coordinate

fg · RGBA · required

Foreground color

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