0
# Buffers and Graphics
1

2
Terminal Kit provides advanced display management through screen buffers, text buffers, and image rendering capabilities. These components enable complex graphics, animations, and efficient screen updates.
3

4
## Screen Buffers
5

6
### ScreenBuffer
7

8
```javascript { .api }
9
new termkit.ScreenBuffer(options: ScreenBufferOptions): ScreenBuffer;
10
```
11

12
Standard screen buffer for double-buffered display management.
13

14
```javascript { .api }
15
interface ScreenBufferOptions {
16
  dst: Terminal;
17
  x?: number;
18
  y?: number;
19
  width?: number;
20
  height?: number;
21
  blending?: boolean;
22
  wrap?: boolean;
23
  tabWidth?: number;
24
  forceSize?: boolean;
25
}
26
```
27

28
```javascript
29
const term = require('terminal-kit').terminal;
30
const termkit = require('terminal-kit');
31

32
// Create screen buffer
33
const screenBuffer = new termkit.ScreenBuffer({
34
  dst: term,
35
  width: 80,
36
  height: 25
37
});
38

39
// Draw to buffer
40
screenBuffer.put({ x: 10, y: 5, attr: { color: 'red' } }, 'Hello World!');
41

42
// Update terminal
43
screenBuffer.draw();
44
```
45

46
### ScreenBufferHD
47

48
```javascript { .api }
49
new termkit.ScreenBufferHD(options: ScreenBufferHDOptions): ScreenBufferHD;
50
```
51

52
High-definition screen buffer with sub-cell resolution and 32-bit RGBA support.
53

54
```javascript { .api }
55
interface ScreenBufferHDOptions extends ScreenBufferOptions {
56
  cellWidth?: number;
57
  cellHeight?: number;
58
}
59
```
60

61
```javascript
62
// Create HD buffer for detailed graphics
63
const hdBuffer = new termkit.ScreenBufferHD({
64
  dst: term,
65
  width: 160,
66
  height: 50,
67
  cellWidth: 2,
68
  cellHeight: 1
69
});
70

71
// Draw with sub-pixel precision
72
hdBuffer.setPixel(25, 10, { r: 255, g: 100, b: 50, a: 255 });
73
hdBuffer.draw();
74
```
75

76
## Screen Buffer Methods
77

78
### Drawing Operations
79

80
```javascript { .api }
81
// Text operations
82
screenBuffer.put(options: PutOptions, text: string): void;
83
screenBuffer.get(options: GetOptions): string;
84

85
// Cell operations  
86
screenBuffer.setAttrAt(x: number, y: number, attr: CellAttributes): void;
87
screenBuffer.getAttrAt(x: number, y: number): CellAttributes;
88

89
// Bulk operations
90
screenBuffer.fill(options: FillOptions): void;
91
screenBuffer.clear(): void;
92

93
interface PutOptions {
94
  x?: number;
95
  y?: number;
96
  attr?: CellAttributes;
97
  wrap?: boolean;
98
  direction?: 'right' | 'down' | 'left' | 'up';
99
}
100

101
interface CellAttributes {
102
  color?: string | number;
103
  bgColor?: string | number;
104
  bold?: boolean;
105
  italic?: boolean;
106
  underline?: boolean;
107
  // ... other style attributes
108
}
109
```
110

111
```javascript
112
// Fill area with character and attributes
113
screenBuffer.fill({
114
  char: '█',
115
  attr: { color: 'blue', bgColor: 'white' },
116
  region: { x: 5, y: 5, width: 20, height: 10 }
117
});
118

119
// Put text with custom attributes
120
screenBuffer.put({
121
  x: 10,
122
  y: 3,
123
  attr: { color: 'brightGreen', bold: true }
124
}, 'Status: OK');
125
```
126

127
### Region Operations
128

129
```javascript { .api }
130
// Copy regions
131
screenBuffer.copyRegion(options: CopyRegionOptions): void;
132
screenBuffer.moveRegion(src: Region, dst: Point): void;
133

134
// Region scrolling
135
screenBuffer.vScroll(options: ScrollOptions): void;
136
screenBuffer.hScroll(options: ScrollOptions): void;
137

138
interface Region {
139
  x: number;
140
  y: number;
141
  width: number;
142
  height: number;
143
}
144

145
interface ScrollOptions {
146
  top?: number;
147
  bottom?: number;
148
  left?: number;
149
  right?: number;
150
  rows?: number;
151
  columns?: number;
152
}
153
```
154

155
### Display Management
156

157
```javascript { .api }
158
// Update display
159
screenBuffer.draw(options?: DrawOptions): void;
160
screenBuffer.drawCursor(): void;
161

162
// Buffer state
163
screenBuffer.resize(options: ResizeOptions): void;
164
screenBuffer.dump(): string;
165
screenBuffer.load(data: string): void;
166

167
interface DrawOptions {
168
  delta?: boolean;
169
  cursor?: boolean;
170
  inline?: boolean;
171
}
172
```
173

174
## Text Buffers
175

176
### TextBuffer
177

178
```javascript { .api }
179
new termkit.TextBuffer(options: TextBufferOptions): TextBuffer;
180
```
181

182
Specialized buffer for text processing with advanced formatting and markup support.
183

184
```javascript { .api }
185
interface TextBufferOptions {
186
  dst?: Terminal | ScreenBuffer;
187
  width?: number;
188
  height?: number;
189
  x?: number;
190
  y?: number;
191
  wrap?: boolean;
192
  hyphenate?: boolean;
193
  wordWrap?: boolean;
194
  tabWidth?: number;
195
  forceSize?: boolean;
196
}
197
```
198

199
```javascript
200
const textBuffer = new termkit.TextBuffer({
201
  dst: term,
202
  width: 60,
203
  height: 20,
204
  wordWrap: true
205
});
206

207
// Add formatted text
208
textBuffer.append('This is ^Rred^ text and ^Bblue^ text.\n');
209
textBuffer.append('Line with **bold** markup.\n');
210

211
// Render to terminal
212
term.clear();
213
textBuffer.draw();
214
```
215

216
### Text Buffer Operations
217

218
```javascript { .api }
219
// Content management
220
textBuffer.setText(text: string): void;
221
textBuffer.append(text: string, attr?: CellAttributes): void;
222
textBuffer.prepend(text: string, attr?: CellAttributes): void;
223
textBuffer.insert(text: string, index?: number): void;
224

225
// Navigation and selection
226
textBuffer.moveTo(x: number, y: number): void;
227
textBuffer.moveToEndOfBuffer(): void;
228
textBuffer.moveToBeginningOfBuffer(): void;
229

230
// Scrolling
231
textBuffer.scrollTo(y: number): void;
232
textBuffer.scroll(dy: number): void;
233
```
234

235
## Image Rendering
236

237
### Image Loading and Display
238

239
```javascript { .api }
240
// Load and display image
241
terminal.drawImage(url: string, options: ImageOptions, callback: ImageCallback): void;
242

243
// Image utilities
244
termkit.image.load(url: string, options: LoadOptions, callback: LoadCallback): void;
245

246
interface ImageOptions {
247
  x?: number;
248
  y?: number;
249
  width?: number;
250
  height?: number;
251
  shrink?: {
252
    width: number;
253
    height: number;
254
  };
255
}
256

257
interface LoadOptions {
258
  terminal?: Terminal;
259
  shrink?: object;
260
}
261

262
type ImageCallback = (error: Error | null) => void;
263
type LoadCallback = (error: Error | null, image: ImageData) => void;
264
```
265

266
```javascript
267
// Display image file
268
term.drawImage('./logo.png', {
269
  x: 10,
270
  y: 5,
271
  shrink: { width: 40, height: 20 }
272
}, (error) => {
273
  if (error) {
274
    term.red('Failed to load image: %s\n', error.message);
275
  } else {
276
    term.green('Image loaded successfully!\n');
277
  }
278
});
279

280
// Load image data for processing
281
termkit.image.load('./photo.jpg', {
282
  shrink: { width: 80, height: 40 }
283
}, (error, image) => {
284
  if (!error && image) {
285
    // Process image data
286
    term.moveTo(1, 20)('Image size: %dx%d\n', image.width, image.height);
287
  }
288
});
289
```
290

291
## High-Definition Graphics
292

293
### Pixel-Level Operations
294

295
```javascript { .api }
296
// HD buffer pixel operations
297
hdBuffer.setPixel(x: number, y: number, rgba: RGBA): void;
298
hdBuffer.getPixel(x: number, y: number): RGBA;
299
hdBuffer.blendPixel(x: number, y: number, rgba: RGBA): void;
300

301
// Line and shape drawing  
302
hdBuffer.drawLine(x1: number, y1: number, x2: number, y2: number, rgba: RGBA): void;
303
hdBuffer.drawRect(x: number, y: number, width: number, height: number, rgba: RGBA): void;
304
hdBuffer.fillRect(x: number, y: number, width: number, height: number, rgba: RGBA): void;
305

306
interface RGBA {
307
  r: number; // 0-255
308
  g: number; // 0-255  
309
  b: number; // 0-255
310
  a: number; // 0-255
311
}
312
```
313

314
```javascript
315
const hdBuffer = new termkit.ScreenBufferHD({
316
  dst: term,
317
  width: 120,
318
  height: 40
319
});
320

321
// Draw gradient
322
for (let x = 0; x < 120; x++) {
323
  for (let y = 0; y < 40; y++) {
324
    const red = Math.floor(255 * x / 120);
325
    const green = Math.floor(255 * y / 40);
326
    hdBuffer.setPixel(x, y, { r: red, g: green, b: 100, a: 255 });
327
  }
328
}
329

330
hdBuffer.draw();
331
```
332

333
### Image Composition
334

335
```javascript { .api }
336
// Image blending modes
337
hdBuffer.drawImage(image: ImageData, options: DrawImageOptions): void;
338

339
interface DrawImageOptions {
340
  x?: number;
341
  y?: number;
342
  srcX?: number;
343
  srcY?: number;
344
  srcWidth?: number;
345
  srcHeight?: number;
346
  blending?: BlendMode;
347
  opacity?: number;
348
}
349

350
type BlendMode = 'normal' | 'multiply' | 'screen' | 'overlay' | 'add';
351
```
352

353
## Animation and Effects
354

355
### Buffer Animation
356

357
```javascript { .api }
358
// Animation helpers
359
screenBuffer.vScroll(rows: number, options?: ScrollOptions): void;
360
screenBuffer.hScroll(columns: number, options?: ScrollOptions): void;
361

362
// Custom animation loop
363
function animateBuffer() {
364
  // Clear buffer
365
  screenBuffer.clear();
366
  
367
  // Draw current frame
368
  drawFrame(frameNumber++);
369
  
370
  // Update display
371
  screenBuffer.draw({ delta: true });
372
  
373
  // Schedule next frame
374
  setTimeout(animateBuffer, 50);
375
}
376
```
377

378
### Sprite Management
379

380
```javascript
381
class Sprite {
382
  constructor(x, y, width, height, data) {
383
    this.x = x;
384
    this.y = y;
385
    this.width = width;
386
    this.height = height;
387
    this.data = data;
388
  }
389
  
390
  draw(buffer) {
391
    for (let dy = 0; dy < this.height; dy++) {
392
      for (let dx = 0; dx < this.width; dx++) {
393
        const char = this.data[dy * this.width + dx];
394
        if (char !== ' ') {
395
          buffer.put({
396
            x: this.x + dx,
397
            y: this.y + dy
398
          }, char);
399
        }
400
      }
401
    }
402
  }
403
  
404
  move(dx, dy) {
405
    this.x += dx;
406
    this.y += dy;
407
  }
408
}
409

410
// Usage
411
const player = new Sprite(10, 5, 3, 2, [
412
  '@@@',
413
  '|||'
414
]);
415

416
function gameLoop() {
417
  screenBuffer.clear();
418
  player.draw(screenBuffer);
419
  screenBuffer.draw();
420
  
421
  setTimeout(gameLoop, 100);
422
}
423
```
424

425
## Usage Examples
426

427
### Double-Buffered Animation
428

429
```javascript
430
const term = require('terminal-kit').terminal;
431
const termkit = require('terminal-kit');
432

433
const screenBuffer = new termkit.ScreenBuffer({
434
  dst: term,
435
  width: term.width,
436
  height: term.height
437
});
438

439
let ballX = 10, ballY = 10;
440
let velocityX = 1, velocityY = 1;
441

442
function animate() {
443
  // Clear buffer
444
  screenBuffer.clear();
445
  
446
  // Update ball position
447
  ballX += velocityX;
448
  ballY += velocityY;
449
  
450
  // Bounce off walls
451
  if (ballX <= 0 || ballX >= term.width - 1) velocityX = -velocityX;
452
  if (ballY <= 0 || ballY >= term.height - 1) velocityY = -velocityY;
453
  
454
  // Draw ball
455
  screenBuffer.put({
456
    x: Math.floor(ballX),
457
    y: Math.floor(ballY),
458
    attr: { color: 'red' }
459
  }, '●');
460
  
461
  // Update display
462
  screenBuffer.draw({ delta: true });
463
  
464
  setTimeout(animate, 50);
465
}
466

467
term.clear();
468
animate();
469
```
470

471
### Text Processing with TextBuffer
472

473
```javascript
474
const term = require('terminal-kit').terminal;
475
const termkit = require('terminal-kit');
476

477
const textBuffer = new termkit.TextBuffer({
478
  dst: term,
479
  width: 60,
480
  height: 20,
481
  wordWrap: true
482
});
483

484
// Add formatted content
485
textBuffer.append('^R^+ERROR:^ Failed to connect to server.\n');
486
textBuffer.append('^Y^+WARNING:^ Connection timeout.\n');
487
textBuffer.append('^G^+SUCCESS:^ Connected successfully.\n');
488
textBuffer.append('\n');
489
textBuffer.append('This is a ^Bblue^ word and this is ^Rred^.\n');
490
textBuffer.append('**Bold text** and *italic text* are supported.\n');
491

492
// Create a scrollable log viewer
493
let scrollY = 0;
494

495
term.grabInput();
496
term.on('key', (name) => {
497
  switch (name) {
498
    case 'UP':
499
      if (scrollY > 0) scrollY--;
500
      break;
501
    case 'DOWN':
502
      scrollY++;
503
      break;
504
    case 'CTRL_C':
505
      term.releaseInput();
506
      process.exit();
507
      break;
508
  }
509
  
510
  term.clear();
511
  textBuffer.scrollTo(scrollY);
512
  textBuffer.draw();
513
});
514

515
// Initial render
516
term.clear();
517
textBuffer.draw();
518
```
519

520
### HD Graphics Example
521

522
```javascript
523
const term = require('terminal-kit').terminal;
524
const termkit = require('terminal-kit');
525

526
const hdBuffer = new termkit.ScreenBufferHD({
527
  dst: term,
528
  width: 160,
529
  height: 80
530
});
531

532
// Draw a rainbow gradient
533
function drawRainbow() {
534
  for (let x = 0; x < 160; x++) {
535
    for (let y = 0; y < 80; y++) {
536
      const hue = (x / 160) * 360;
537
      const saturation = 1;
538
      const lightness = 0.5 + 0.3 * Math.sin(y / 80 * Math.PI);
539
      
540
      // Convert HSL to RGB
541
      const chroma = termkit.chroma.hsl(hue, saturation, lightness);
542
      const [r, g, b] = chroma.rgb();
543
      
544
      hdBuffer.setPixel(x, y, { r, g, b, a: 255 });
545
    }
546
  }
547
  
548
  hdBuffer.draw();
549
}
550

551
// Draw geometric patterns
552
function drawPattern() {
553
  hdBuffer.clear();
554
  
555
  const centerX = 80;
556
  const centerY = 40;
557
  
558
  for (let angle = 0; angle < 360; angle += 10) {
559
    const rad = angle * Math.PI / 180;
560
    const x1 = centerX + Math.cos(rad) * 30;
561
    const y1 = centerY + Math.sin(rad) * 20;
562
    const x2 = centerX + Math.cos(rad) * 60;
563
    const y2 = centerY + Math.sin(rad) * 40;
564
    
565
    const color = termkit.chroma.hsl(angle, 1, 0.5).rgb();
566
    hdBuffer.drawLine(x1, y1, x2, y2, {
567
      r: color[0], g: color[1], b: color[2], a: 255
568
    });
569
  }
570
  
571
  hdBuffer.draw();
572
}
573

574
term.clear();
575
drawPattern();
576
```