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):
Documentation
¶
Index ¶
- Constants
- Variables
- func ParseSizeString(in string) (int, int, error)
- type BitBltOpt
- type Buffer
- 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
- type Opt
- type PixelMode
- type Tcg
- 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 ¶
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 ¶
Types ¶
type BitBltOpt ¶ added in v0.0.9
type BitBltOpt func(*bitBltOptions)
Options for BitBlt
func BBAnd ¶ added in v0.0.9
func BBAnd() BitBltOpt
BBAnd - AND operation for each pixel of source and destination
func BBOr ¶ added in v0.0.9
func BBOr() BitBltOpt
BBOr - OR operation for each pixel of source and destination
func BBTransparent ¶ added in v0.0.9
func BBTransparent() BitBltOpt
BBTransparent - if true, then BitBlt will not copy pixels with color 0 (transparent)
type Buffer ¶
Buffer - implement base screen pixel buffer
func MustNewBufferFromStrings ¶
MustNewBufferFromStrings - get new buffer object from list of strings and die on error
func NewBufferFromImage ¶
NewBufferFromImage - get new buffer from image.Image object
func NewBufferFromStrings ¶
NewBufferFromStrings - get new buffer object from list of strings (00110001, 0001001, ...) such symbols are also valid: " ** ", "..##.."
func (*Buffer) Arc ¶
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) BitBlt ¶
BitBlt - copy part of buffer into this buffer xd, yd - destination coordinates xs, ys - source coordinates
func (*Buffer) Circle ¶
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) FillRect ¶
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) HLine ¶
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 ¶
HScroll - horizontal scroll image buffer by cnt pixels, cnt > 0 - scroll right, cnt < 0 - left
func (*Buffer) Line ¶
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 ¶
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 ¶ added in v0.0.5
RenderAsStrings - render buffer as slice of strings with pixel characters
func (Buffer) String ¶ added in v0.0.5
String - render as string with new-line separator: "..*..\n*....*\n..*.."
func (Buffer) ToImage ¶
ToImage - convert buffer to std Image with Gray colorspace, for example for save buffer to image file like png
func (*Buffer) VLine ¶
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: .....*.... .....*.... .....*.... .....*.... .....*.... .....*.... .....*.... .....*.... .....*.... .....*....
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 WithPattern ¶
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 ¶ added in v0.0.3
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 ¶
WithClip - set clip of screen, x, y, w, h - is in screen character coordinates, not pixels
func WithClipCenter ¶
WithClipCenter - set clip of screen, placed in the center of screen w, h - is in screen character coordinates, not pixels
type PixelMode ¶ added in v0.0.4
type PixelMode struct {
// contains filtered or unexported fields
}
PixelMode - graphics mode, size and symbols for graphics
func NewPixelMode ¶ added in v0.0.4
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 ¶ added in v0.0.4
Height - returns the height 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 (*Tcg) PrintStr ¶
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 ¶
PrintStrStyle - print string on screen see the PrintStr about restrictions
func (*Tcg) ScreenSize ¶
ScreenSize - returns terminal screen size in chars (width, height)
func (*Tcg) SetClipCenter ¶
SetClipCenter - set new clip in the center of screen
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Script for generate 2x4 mode with Braille patterns See: https://en.wikipedia.org/wiki/Braille_Patterns
|
Script for generate 2x4 mode with Braille patterns See: https://en.wikipedia.org/wiki/Braille_Patterns |
|
examples
|
|
|
Package sprite - sprite object for drawing/moving on tcg.Buffer
|
Package sprite - sprite object for drawing/moving on tcg.Buffer |
|
Package turtle implement Turtle drawing
|
Package turtle implement Turtle drawing |