tcg

README

TCG - terminal cell graphics

Go Graphics library for use in a text terminal. Only 1bit graphics can be used with two colors. Used unicode block symbols for drawing. 2x3 mode is supported by the Iosevka font or some terminals (like default on Ubuntu).

Features

• Available 5 graphics modes, from 2x3 pixels grid for terminal symbol to 1x1, 1x2 and 2x2, or you can create own custom mode with your graphics
• Set/get one pixel
• Drawings: lines (vertical, horizontal, or with any angle), boxes, circles, arcs
• Fill area with a different options, for example fill with patterns
• Buffer manipulating: cut, clone, convert to/from stdlib Image or text
• Buffer transform: BitBlt with options, clear, flip, invert, scroll (vertical, horizontal)
• Sub-package for turtle graphics, also available drawing by text script
• Sprite support with Put, Withdraw, Move, etc methods

Install

go get github.com/msoap/tcg

Usage

package main

import (
	"log"

	"github.com/gdamore/tcell/v2"
	"github.com/msoap/tcg"
)

func main() {
	tg, err := tcg.New(tcg.Mode2x3) // each terminal symbol contains a 2x3 pixels grid, also you can use 1x1, 1x2, and 2x2 modes
	if err != nil {
		log.Fatalf("create tg: %s", err)
	}

	i := 0
	for {
		pixColor := tg.Buf.At(10, 10)       // get color of pixel
		tg.Buf.Set(11, 11, pixColor)        // draw one pixel with color from 10,10
		tg.Buf.Line(0, 0, 50, i, tcg.Black) // draw a diagonal line
		tg.Show()                           // synchronize buffer with screen

		if ev, ok := tg.TCellScreen.PollEvent().(*tcell.EventKey); ok && ev.Rune() == 'q' {
			break // exit by 'q' key
		}
		i++
	}

	tg.Finish() // finish application and restore screen
}

See more examples in examples folder.

Screenshot

Game of Life example in iTerm2 terminal:

See more screenshots.

TODO

• fonts support
• sprites
• animation in sprite

See also

• Go terminal library - github.com/gdamore/tcell
• Turtle graphics
• Try it in the Go Playground

Unicode symbols:

• Block Elements - wikipedia
• Block Elements - unicode.org
• Symbols for Legacy Computing - wikipedia
• Symbols for Legacy Computing - unicode.org

Supported fonts (for "2x3" mode):

• Iosevka font

Documentation

Index

• Constants
• Variables
• func ParseSizeString(in string) (int, int, error)
• type BitBltOpt
  • func BBAnd() BitBltOpt
  • func BBMask(mask *Buffer) BitBltOpt
  • func BBOpFn(fn func(orig, src int) int) BitBltOpt
  • func BBOr() BitBltOpt
  • func BBTransparent() BitBltOpt
  • func BBXor() BitBltOpt
• type Buffer
  • func MustNewBufferFromStrings(in []string) Buffer
  • func NewBuffer(width, height int) Buffer
  • func NewBufferFromImage(img image.Image) Buffer
  • func NewBufferFromStrings(in []string) (*Buffer, error)
  • func (b *Buffer) Arc(x, y int, r float64, from, to float64, color int)
  • func (b Buffer) At(x, y int) int
  • func (b *Buffer) BitBlt(xd, yd, width, height int, from Buffer, xs, ys int, opts ...BitBltOpt)
  • func (b *Buffer) BitBltAll(x, y int, from Buffer, opts ...BitBltOpt)
  • func (b *Buffer) Circle(x, y, r int, color int)
  • func (b *Buffer) Clear()
  • func (b Buffer) Clone() *Buffer
  • func (b Buffer) Cut(x, y, width, height int) Buffer
  • func (b *Buffer) Fill(x, y int, opts ...FillOpt)
  • func (b *Buffer) FillRect(x, y int, width, height int, color int)
  • func (b *Buffer) HFlip()
  • func (b *Buffer) HLine(x, y int, length int, color int)
  • func (b *Buffer) HScroll(cnt int)
  • func (b *Buffer) Invert()
  • func (b Buffer) IsEqual(a Buffer) bool
  • func (b *Buffer) Line(x1, y1, x2, y2 int, color int)
  • func (b *Buffer) Rect(x, y int, width, height int, color int)
  • func (b Buffer) RenderAsStrings(mode PixelMode) []string
  • func (b *Buffer) Set(x, y int, color int)
  • func (b Buffer) String() string
  • func (b Buffer) Strings() []string
  • func (b Buffer) ToImage() image.Image
  • func (b *Buffer) VFlip()
  • func (b *Buffer) VLine(x, y int, length int, color int)
  • func (b *Buffer) VScroll(cnt int)
• type FillOpt
  • func WithAllAreas() FillOpt
  • func WithMask(buf Buffer) FillOpt
  • func WithPattern(buf Buffer) FillOpt
• type Opt
  • func WithBackgroundColor(colorName string) Opt
  • func WithClip(x, y, width, height int) Opt
  • func WithClipCenter(width, height int) Opt
  • func WithColor(colorName string) Opt
• type PixelMode
  • func NewPixelMode(width, height int, charMapping []rune) (*PixelMode, error)
  • func (pm PixelMode) Height() int
  • func (pm *PixelMode) Set(in string) error
  • func (pm PixelMode) String() string
  • func (pm PixelMode) Width() int
• type Tcg
  • func New(mode PixelMode, opts ...Opt) (*Tcg, error)
  • func (tg *Tcg) Finish()
  • func (tg *Tcg) PrintStr(x, y int, str string)
  • func (tg *Tcg) PrintStrStyle(x, y int, str string, style tcell.Style)
  • func (tg *Tcg) ScreenSize() (int, int)
  • func (tg *Tcg) SetClip(x, y, width, height int) error
  • func (tg *Tcg) SetClipCenter(width, height int) error
  • func (tg *Tcg) Show()

Examples

• Buffer.Arc
• Buffer.Circle
• Buffer.FillRect
• Buffer.HLine
• Buffer.Line
• Buffer.Rect
• Buffer.VLine

Constants

const (
	White = 0 // without pixel
	Black = 1 // it will be black on a terminal with light theme, and white on dark terminals
)

pixel colors

Variables

var (
	// predefined modes with 1x1, 1x2, 2x2 and 2x3 pixels per character
	Mode1x1 = PixelMode{/* contains filtered or unexported fields */}
	Mode1x2 = PixelMode{/* contains filtered or unexported fields */}
	Mode2x2 = PixelMode{/* contains filtered or unexported fields */}
	Mode2x3 = PixelMode{/* contains filtered or unexported fields */}

	// Simple mode for debug or unittests with "." and "*" chars as colors
	Mode1x1Simple = PixelMode{/* contains filtered or unexported fields */}

	// 2x4 mode based on Braille symbols (https://en.wikipedia.org/wiki/Braille_Patterns)
	Mode2x4Braille = PixelMode{/* contains filtered or unexported fields */}
)

Functions

func ParseSizeString

func ParseSizeString(in string) (int, int, error)

ParseSizeString - parse size in "80x25" format

Types

type BitBltOpt

type BitBltOpt func(*bitBltOptions)

Options for BitBlt

func BBAnd

func BBAnd() BitBltOpt

BBAnd - AND operation for each pixel of source and destination

func BBMask

func BBMask(mask *Buffer) BitBltOpt

BBMask - copy only pixels with color != 0 in mask

func BBOpFn

func BBOpFn(fn func(orig, src int) int) BitBltOpt

BBOpFn - add function for each pixel of source and destination

func BBOr

func BBOr() BitBltOpt

BBOr - OR operation for each pixel of source and destination

func BBTransparent

func BBTransparent() BitBltOpt

BBTransparent - if true, then BitBlt will not copy pixels with color 0 (transparent)

func BBXor

func BBXor() BitBltOpt

BBXor - XOR operation for each pixel of source and destination

type Buffer

type Buffer struct {
	Width  int
	Height int
	// contains filtered or unexported fields
}

Buffer - implement base screen pixel buffer

func MustNewBufferFromStrings

func MustNewBufferFromStrings(in []string) Buffer

MustNewBufferFromStrings - get new buffer object from list of strings and die on error

func NewBuffer

func NewBuffer(width, height int) Buffer

NewBuffer - get new buffer object

func NewBufferFromImage

func NewBufferFromImage(img image.Image) Buffer

NewBufferFromImage - get new buffer from image.Image object

func NewBufferFromStrings

func NewBufferFromStrings(in []string) (*Buffer, error)

NewBufferFromStrings - get new buffer object from list of strings (00110001, 0001001, ...) such symbols are also valid: " ** ", "..##.."

func (*Buffer) Arc

func (b *Buffer) Arc(x, y int, r float64, from, to float64, color int)

Arc - draw circle arc, from and to: 0 .. 360

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.Arc(5, 5, 4, 45, 225, tcg.Black)
	fmt.Println(b)

}

Output:

..........
...*****..
..**...**.
.**.......
.*........
.*........
.*........
.**.......
..........
..........

func (Buffer) At

func (b Buffer) At(x, y int) int

At - get pixel color from buffer

func (*Buffer) BitBlt

func (b *Buffer) BitBlt(xd, yd, width, height int, from Buffer, xs, ys int, opts ...BitBltOpt)

BitBlt - copy part of buffer into this buffer xd, yd - destination coordinates xs, ys - source coordinates

func (*Buffer) BitBltAll

func (b *Buffer) BitBltAll(x, y int, from Buffer, opts ...BitBltOpt)

BitBltAll - copy whole buffer into this buffer

func (*Buffer) Circle

func (b *Buffer) Circle(x, y, r int, color int)

Circle - draw a circle using the Midpoint Circle Algorithm

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.Circle(5, 5, 4, tcg.Black)
	fmt.Println(b)

}

Output:

..........
....***...
..**...**.
..*.....*.
.*.......*
.*.......*
.*.......*
..*.....*.
..**...**.
....***...

func (*Buffer) Clear

func (b *Buffer) Clear()

Clear - fill whole buffer with White

func (Buffer) Clone

func (b Buffer) Clone() *Buffer

Clone to new buffer

func (Buffer) Cut

func (b Buffer) Cut(x, y, width, height int) Buffer

Cut area to the new buffer, without change current buffer

func (*Buffer) Fill

func (b *Buffer) Fill(x, y int, opts ...FillOpt)

Fill an area with black color

func (*Buffer) FillRect

func (b *Buffer) FillRect(x, y int, width, height int, color int)

FillRect - draw filled rectangle

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.FillRect(1, 1, 8, 8, tcg.Black)
	fmt.Println(b)

}

Output:

..........
.********.
.********.
.********.
.********.
.********.
.********.
.********.
.********.
..........

func (*Buffer) HFlip

func (b *Buffer) HFlip()

HFlip - horizontal flip image buffer

func (*Buffer) HLine

func (b *Buffer) HLine(x, y int, length int, color int)

HLine - draw horizontal line

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.HLine(0, 5, 10, tcg.Black)
	fmt.Println(b)

}

Output:

..........
..........
..........
..........
..........
**********
..........
..........
..........
..........

func (*Buffer) HScroll

func (b *Buffer) HScroll(cnt int)

HScroll - horizontal scroll image buffer by cnt pixels, cnt > 0 - scroll right, cnt < 0 - left

func (*Buffer) Invert

func (b *Buffer) Invert()

Invert pixels in the buffer

func (Buffer) IsEqual

func (b Buffer) IsEqual(a Buffer) bool

IsEqual - are two buffers equal?

func (*Buffer) Line

func (b *Buffer) Line(x1, y1, x2, y2 int, color int)

Line - draw line using the Bresenham's algorithm

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.Line(0, 0, 9, 9, tcg.Black)
	fmt.Println(b)

}

Output:

*.........
.*........
..*.......
...*......
....*.....
.....*....
......*...
.......*..
........*.
.........*

func (*Buffer) Rect

func (b *Buffer) Rect(x, y int, width, height int, color int)

Rect - draw rectangle with 1px frame

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.Rect(1, 1, 8, 8, tcg.Black)
	fmt.Println(b)

}

Output:

..........
.********.
.*......*.
.*......*.
.*......*.
.*......*.
.*......*.
.*......*.
.********.
..........

func (Buffer) RenderAsStrings

func (b Buffer) RenderAsStrings(mode PixelMode) []string

RenderAsStrings - render buffer as slice of strings with pixel characters

func (*Buffer) Set

func (b *Buffer) Set(x, y int, color int)

Set - put pixel into buffer

func (Buffer) String

func (b Buffer) String() string

String - render as string with new-line separator: "..*..\n*....*\n..*.."

func (Buffer) Strings

func (b Buffer) Strings() []string

Strings - render as slice of string, ["...**...", ...]

func (Buffer) ToImage

func (b Buffer) ToImage() image.Image

ToImage - convert buffer to std Image with Gray colorspace, for example for save buffer to image file like png

func (*Buffer) VFlip

func (b *Buffer) VFlip()

VFlip - vertical flip image buffer

func (*Buffer) VLine

func (b *Buffer) VLine(x, y int, length int, color int)

VLine - draw vertical line

Example

package main

import (
	"fmt"

	"github.com/msoap/tcg"
)

func main() {
	b := tcg.NewBuffer(10, 10)
	b.VLine(5, 0, 10, tcg.Black)
	fmt.Println(b)

}

Output:

.....*....
.....*....
.....*....
.....*....
.....*....
.....*....
.....*....
.....*....
.....*....
.....*....

func (*Buffer) VScroll

func (b *Buffer) VScroll(cnt int)

VScroll - vertical scroll image buffer by cnt pixels, cnt > 0 - scroll down, cnt < 0 - up

type FillOpt

type FillOpt func(*fillOptions)

FillOpt - fill options

func WithAllAreas

func WithAllAreas() FillOpt

WithAllAreas - option for Fill method: fill in all areas, not necessarily continuous. Makes sense only when filled with a pattern.

func WithMask

func WithMask(buf Buffer) FillOpt

WithMask - option for Fill method: add mask from Buffer

func WithPattern

func WithPattern(buf Buffer) FillOpt

WithPattern - option for Fill method, which provide fill pattern from another buffer

type Opt

type Opt func(*tcgConfig) error

Opt - options type for New tcg screen

func WithBackgroundColor

func WithBackgroundColor(colorName string) Opt

WithBackgroundColor - set default background color of pixels, this will affect the block of pixels per full symbol color can be in the form of different options: "blue", "yellow" or "#ffaa11", see tcell.GetColor

func WithClip

func WithClip(x, y, width, height int) Opt

WithClip - set clip of screen, x, y, w, h - is in screen character coordinates, not pixels

func WithClipCenter

func WithClipCenter(width, height int) Opt

WithClipCenter - set clip of screen, placed in the center of screen w, h - is in screen character coordinates, not pixels

func WithColor

func WithColor(colorName string) Opt

WithColor - set default color of pixels, this will affect the block of pixels per full symbol color can be in the form of different options: "blue", "yellow" or "#ffaa11", see tcell.GetColor

type PixelMode

type PixelMode struct {
	// contains filtered or unexported fields
}

PixelMode - graphics mode, size and symbols for graphics

func NewPixelMode

func NewPixelMode(width, height int, charMapping []rune) (*PixelMode, error)

NewPixelMode - create new custom mode, charMapping slice must contain all combinations of pixels that the symbol can show. For example for 2x3 mode you need provide 64 symbols: 2^(2*3), for 3x3: 512

func (PixelMode) Height

func (pm PixelMode) Height() int

Height - returns the height in pixels of one character in the text console

func (*PixelMode) Set

func (pm *PixelMode) Set(in string) error

Set from string (for using with flag.Var())

func (PixelMode) String

func (pm PixelMode) String() string

String representation like "2x3"

func (PixelMode) Width

func (pm PixelMode) Width() int

Width - returns the width in pixels of one character in the text console

type Tcg

type Tcg struct {
	Width, Height int          // screen or clip of screen width/height in pixels
	TCellScreen   tcell.Screen // tcell object for keyboard interactions, or low level interactions with terminal screen
	Buf           Buffer       // buffer presents current screen
	// contains filtered or unexported fields
}

Tcg - tcell graphics object

func New

func New(mode PixelMode, opts ...Opt) (*Tcg, error)

New - get new object with tcell inside

func (*Tcg) Finish

func (tg *Tcg) Finish()

Finish application

func (*Tcg) PrintStr

func (tg *Tcg) PrintStr(x, y int, str string)

PrintStr - print string on screen, with white on black style string don't save in the buffer of pixels! x, y - is in screen character coordinates, not pixels. Also x/y coordinates is not use Clip of the screen, it's always absolute.

func (*Tcg) PrintStrStyle

func (tg *Tcg) PrintStrStyle(x, y int, str string, style tcell.Style)

PrintStrStyle - print string on screen see the PrintStr about restrictions

func (*Tcg) ScreenSize

func (tg *Tcg) ScreenSize() (int, int)

ScreenSize - returns terminal screen size in chars (width, height)

func (*Tcg) SetClip

func (tg *Tcg) SetClip(x, y, width, height int) error

SetClip - set new clip of screen

func (*Tcg) SetClipCenter

func (tg *Tcg) SetClipCenter(width, height int) error

SetClipCenter - set new clip in the center of screen

func (*Tcg) Show

func (tg *Tcg) Show()

Show - update screen