Skip to main content

​
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()

Build docs developers (and LLMs) love

Get started for freeTalk to us