search

jerch / xterm-addon-image

Image addon for xterm.js
MIT License
54 stars 6 forks source link

readme

xterm-addon-image

Image output in xterm.js.

Important note

Version 0.4.x will be the last version from this single repo. Future versions will reside as addon in the xterm.js main repo.

Install from npm

npm install --save xterm-addon-image

Release Compatibility

Clone & Build

The addon integrates tightly with the xterm.js base repo, esp. for tests and the demo. To properly set up all needed resources see bootstrap.sh or run it directly with

curl -s https://raw.githubusercontent.com/jerch/xterm-addon-image/master/bootstrap.sh | XTERMJS=5.2.0 IMAGEADDON=master bash

The addon sources and npm package definition reside under addons/xterm-addon-image.

Usage

import { Terminal } from 'xterm';
import { ImageAddon, IImageAddonOptions } from 'xterm-addon-image';

// customize as needed (showing addon defaults)
const customSettings: IImageAddonOptions = {
  enableSizeReports: true,    // whether to enable CSI t reports (see below)
  pixelLimit: 16777216,       // max. pixel size of a single image
  sixelSupport: true,         // enable sixel support
  sixelScrolling: true,       // whether to scroll on image output
  sixelPaletteLimit: 256,     // initial sixel palette size
  sixelSizeLimit: 25000000,   // size limit of a single sixel sequence
  storageLimit: 128,          // FIFO storage limit in MB
  showPlaceholder: true,      // whether to show a placeholder for evicted images
  iipSupport: true,           // enable iTerm IIP support
  iipSizeLimit: 20000000      // size limit of a single IIP sequence
}

// initialization
const terminal = new Terminal();
const imageAddon = new ImageAddon(customSettings);
terminal.loadAddon(imageAddon);

General Notes

Operation Modes

Storage and Drawing Settings

The internal storage holds images up to storageLimit (in MB, calculated as 4-channel RBGA unpacked, default 100 MB). Once hit images get evicted by FIFO rules. Furthermore images on the alternate buffer will always be erased on buffer changes.

The addon exposes two properties to interact with the storage limits at runtime:

By default the addon will show a placeholder pattern for evicted images that are still part of the terminal (e.g. in the scrollback). The pattern can be deactivated by toggling showPlaceholder.

Image Data Retrieval

The addon provides the following API endpoints to retrieve raw image data as canvas:

Memory Usage

The addon does most image processing in Javascript and therefore can occupy a rather big amount of memory. To get an idea where the memory gets eaten, lets look at the data flow and processing steps:

Following the steps above, a rough estimation of maximum memory usage by the addon can be calculated with these formulas (in bytes):

// storage alone
const storageBytes = storageUsage * storageLimit * 1024 * 1024;
// decoding alone
const decodingBytes = sixelSizeLimit + 2 * (pixelLimit * 4);

// totals
// inactive decoding
const totalInactive = storageBytes;
// active decoding
const totalActive = storageBytes + decodingBytes;

Note that browsers have offloading tricks for rarely touched memory segments, esp. storageBytes might not directly translate into real memory usage. Usage peaks will happen during active decoding of multiple big images due to the need of 2 full pixel buffers at the same time, which cannot be offloaded. Thus you may want to keep an eye on pixelLimit under limited memory conditions.
Further note that the formulas above do not respect the Javascript object's overhead. Compared to the raw buffer needs the book keeping by these objects is rather small (<<5%).

Why should I care about memory usage at all?
Well you don't have to, and it probably will just work fine with the addon defaults. But for bigger integrations, where much more data is held in the Javascript context (like multiple terminals on one page), it is likely to hit the engine's memory limit sooner or later under decoding and/or storage pressure.

How can I adjust the memory usage?

Terminal Interaction

Performance & Latency

Status

Changelog