2 RRLL: ANSI Buffers

8.10

2 RRLL: ANSI Buffers

Dominik Pantůček <dominik.pantucek@trustica.cz>

Racket Rogue-Like Library: ANSI Buffers

Manipulating rectangular character buffers with foreground and background color.

This module provides constructor bindings from rrll/abuf/private/core and all bindings from rrll/abuf/output and rrll/abuf/drawing.

2.1 Core ANSI Buffers Functions

(require rrll/abuf/private/core)

package: rrll-abuf

struct
(struct abuf (width height cells offset stride buffer))
  width : fixnum?
  height : fixnum?
  cells : (vectorof acell?)
  offset : fixnum?
  stride : fixnum?
  buffer : bytes?

Rectangular area of terminal filled with acell?s.

procedure
(make-abuf width height) → abuf?
width : fixnum?
height : fixnum?

Creates a new, empty abuf? of given width and height.

procedure
(make-sub-abuf ab x y width height) → abuf?
  ab : abuf?
  x : fixnum?
  y : fixnum?
  width : fixnum?
  height : fixnum?

Creates a new abuf? which is a rectangular part of already existing abuf?.

2.2 ANSI Cells

(require rrll/abuf/private/acell)

package: rrll-abuf

struct
(struct acell (char fg bg dirty)
    #:mutable
    #:transparent)
  char : char?
  fg : fixnum?
  bg : fixnum?
  dirty : boolean?

A structure representing single ANSI cell on screen.

procedure
(acell=? a b) → boolean?
a : acell?
b : acell?

Compares two ansi-cell? values and returns true if one would look like the other when output. It compares the character and both colors of the cell.

procedure
(update-acell! cell
char
[ #:fg fg
#:bg bg
#:set-dirty set-dirty]) → void?
  cell : acell?
  char : char?
  fg : (or/c fixnum? #f) = #f
  bg : (or/c fixnum? #f) = #f
  set-dirty : boolean? = #t

Updates single cell character and foreground and background color and optionally sets the dirty bit if anything changed and set-dirty is #t.

procedure
(copy-acell! dst
src
[ #:only-dirty only-dirty
#:clear-dirty clear-dirty
#:set-dirty set-dirty]) → void?
  dst : acell?
  src : acell?
  only-dirty : boolean? = #f
  clear-dirty : boolean? = #f
  set-dirty : boolean? = #t

Copies single cell contents into another and optionally sets the dirty bit if anything changed and set-dirty is #t.

If only-dirty is #t, the copy is performed only if the src cell is dirty.

If anything changed, clear-dirty is #t and the source cell was dirty its dirty flag is set back to #f.

If anything changed and set-dirty is #t, the destination cell dirty flag is set to #t.

2.3 Output to Terminal

(require rrll/abuf/output)

package: rrll-abuf

procedure
(display-abuf ab
[ x0
y0
#:only-dirty only-dirty
#:clear-dirty clear-dirty
#:linear linear]) → void?
  ab : abuf?
  x0 : fixnum? = 0
  y0 : fixnum? = 0
  only-dirty : boolean? = #t
  clear-dirty : boolean? = #t
  linear : boolean = #f

Displays given abuf? on terminal.

The picture is positioned at coordinates [x0,y0] with [0,0] being the upper left corner of the terminal and X coordinate growing to the right and Y coordinate growing down.

If only-dirty is #t then only cells marked dirty as identified by acell-dirty? are displayed.

For each cell output with clear-dirty being #t and the source cell was dirty its dirty flag is set back to #f.

If linear is #t, cursor movement is restricted to newlines and forward movement on the current line.

2.4 ANSI Pictures Drawing

(require rrll/abuf/drawing)

package: rrll-abuf

procedure
(abuf-putchar! ab
x
y
ch
[ #:fg fg
#:bg bg
#:set-dirty set-dirty]) → void?
  ab : abuf?
  x : fixnum?
  y : fixnum?
  ch : char?
  fg : fixnum? = #x7f7f7f
  bg : fixnum? = #x0
  set-dirty : boolean? = #t

Puts a character into a abuf? at specified position using given foreground and background colors. By default it sets modified cell’s dirty bit to #t.

procedure
(abuf-putstring! ab
x
y
str
[ #:fg fg
#:bg bg
#:set-dirty set-dirty]) → void?
  ab : abuf?
  x : fixnum?
  y : fixnum?
  str : string?
  fg : fixnum? = #x7f7f7f
  bg : fixnum? = #x0
  set-dirty : boolean? = #t

Draws given str to given position in the picture in given color.

If set-dirty is #t, sets the acell-dirty? flag on the destination cells if they have been changed.

procedure
(abuf-clear! ab
ch
[ #:fg fg
#:bg bg
#:set-dirty set-dirty]) → void?
  ab : abuf?
  ch : char?
  fg : fixnum? = #x7f7f7f
  bg : fixnum? = #x0
  set-dirty : boolean? = #t

Clears the abuf? with specified character, color and background attributes.

If set-dirty is #t, sets the acell-dirty? flag on the destination cells if they have been changed.

procedure
(abuf-bar! dst
x
y
w
h
[ #:fg fg
#:bg bg
#:set-dirty set-dirty]) → void?
  dst : abuf?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  fg : fixnum? = #x7f7f7f
  bg : fixnum? = #x0
  set-dirty : boolean? = #t

Draws a filled rectangle (a bar) of given width and height with character, color and background attributes.

If set-dirty is #t, sets the acell-dirty? flag on the destination cells if they have been changed.

procedure
(abuf-box! dst
x
y
w
h
[ type
#:fg fg
#:bg bg
#:set-dirty set-dirty]) → void?
  dst : abuf?
  x : fixnum?
  y : fixnum?
  w : fixnum?
  h : fixnum?
  type : (or/c 'ascii 'single 'dashed 'thick 'double) = 'single
  fg : fixnum? = #x7f7f7f
  bg : fixnum? = #x0
  set-dirty : boolean? = #t

Draws a rectangle outline (a box) of given width and height with character based on type, color and background attributes.

If set-dirty is #t, sets the acell-dirty? flag on the destination cells if they have been changed.

procedure
(abuf-overlay! dst
src
[ dx
dy
#:w sw
#:h sh
#:sx sx
#:sy sy
#:only-dirty only-dirty
#:clear-dirty clear-dirty
#:set-dirty set-dirty]) → void?
  dst : abuf?
  src : abuf?
  dx : fixnum? = 0
  dy : fixnum? = 0
  sw : (or/c fixnum? #f) = #f
  sh : (or/c fixnum? #f) = #f
  sx : fixnum? = 0
  sy : fixnum? = 0
  only-dirty : boolean? = #f
  clear-dirty : boolean? = #f
  set-dirty : boolean? = #t

Overlays src over dst at coordinates dst-x,dst-y. The dimensions of the src region are taken from src’s dimensions if the arguments are #f. By default it sets the dirty bit on all modified cells.

contents ← prev up next →

1	RRLL: Actor Basic 2.0
2	RRLL: ANSI Buffers
3	RRLL: Abuf Canvas
4	RRLL: Canvas
5	RRLL: Rendering Canvas
6	RRLL: Color Support
7	RRLL: Single-Channel Flomaps
8	RRLL: Futures
9	RRLL: Functional Grids
10	RRLL: Helpers
11	RRLL: Math
12	RRLL: Mutable Future Queue
13	RRLL: Rasterizer
14	RRLL: Renderer
15	RRLL: Terminal I/ O
16	RRLL: Ticker
17	RRLL: Unsafe

2.1	Core ANSI Buffers Functions
2.2	ANSI Cells
2.3	Output to Terminal
2.4	ANSI Pictures Drawing