tilegraphics

README

Tile based graphics rendering

This package implements tile-based graphics rendering, intended to be used on small SPI-connected screens with a slow bus. It is designed to reduce the number of pixels to redraw on every update, by only updating the parts of the screen that did in fact change.

It is not yet complete. Currently the following objects can be drawn:

• Rectangles with a solid color.
• Layers that contain more objects and can be moved/resized.
• Transparency: blending a semi-transparent foreground color with a solid background color.
• Lines with support for transparency and anti-aliasing.

License

This project has been licensed under the BSD 2-clause license, see the LICENSE file for details.

Documentation

Overview

Package tilegraphics implements a graphics rendering using small tiles. This is especially useful for devices with a slow bus to the display, like screens driven over SPI.

Instantiate an Engine object using NewEngine and draw objects on it. The objects can be changed and moved after creation. These changes are recorded, but not directly sent to the screen. They're only sent on the next call to Display(). It is therefore recommended to only call Display() when the display should really be updated, to send all the updates in a single batch for improved performance.

Index

• Constants
• func ApplyAlpha(c color.RGBA, alpha uint8) color.RGBA
• func Blend(bottom, top color.RGBA) color.RGBA
• type Displayer
• type Engine
  • func NewEngine(display Displayer) *Engine
  • func (e *Engine) Display()
  • func (e *Engine) NewLayer(x, y, width, height int16, background color.RGBA) *Layer
  • func (e *Engine) NewLine(x1, y1, x2, y2 int16, stroke color.RGBA) *Line
  • func (e *Engine) NewRectangle(x, y, width, height int16, c color.RGBA) *Rectangle
  • func (e *Engine) SetBackgroundColor(background color.RGBA)
• type Layer
  • func (l *Layer) Move(x, y, width, height int16)
  • func (l *Layer) NewLayer(x, y, width, height int16, background color.RGBA) *Layer
  • func (l *Layer) NewLine(x1, y1, x2, y2 int16, stroke color.RGBA) *Line
  • func (l *Layer) NewRectangle(x, y, width, height int16, c color.RGBA) *Rectangle
  • func (l *Layer) SetBackgroundColor(background color.RGBA)
• type Line
• type Rectangle
  • func (r *Rectangle) Move(x, y, width, height int16)

Constants

const TileSize = 8

TileSize is the size (width and height) of a tile. A tile will take up TileSize*TileSize*4 bytes of memory during rendering.

Functions

func ApplyAlpha

func ApplyAlpha(c color.RGBA, alpha uint8) color.RGBA

ApplyAlpha takes a color (that may be semi-transparent) and applies the given alpha to it, making it even more transparent. It does so while taking gamma into account, see Blend.

func Blend

func Blend(bottom, top color.RGBA) color.RGBA

Blend takes a fully opaque background color and a foreground color that may be semi-transparent and blends them together.

Color blending uses a gamma of 2.0, which is close to the commonly used gamma of ~2.2 but is much easier to calculate efficiently. It is slightly off the ideal gamma curve, but in practice it looks almost identical.

For more information on why blending isn't trivial in sRGB color space: https://www.youtube.com/watch?v=LKnqECcg6Gw https://blog.johnnovak.net/2016/09/21/what-every-coder-should-know-about-gamma/ https://ninedegreesbelow.com/photography/linear-gamma-blur-normal-blend.html

Types

type Displayer

type Displayer interface {
	// Size returns the display size in pixels. It must never change.
	Size() (int16, int16)

	// Display sends the last updates to the screen, if needed.
	// The display might be updated directly or only after this method has been
	// called, depending on the implementation.
	Display() error

	// FillRectangle fills the given rectangle with the given color, and returns
	// an error if something went wrong.
	FillRectangle(x, y, width, height int16, c color.RGBA) error

	// FillRectangleWithBuffer fills the given rectangle with a slice of colors.
	// The buffer is stored in row major order.
	FillRectangleWithBuffer(x, y, width, height int16, buffer []color.RGBA) error
}

Displayer is the display interface required by the rendering engine.

type Engine

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

Engine is the actual rendering engine. Use NewEngine to construct a new rendering engine.

func NewEngine

func NewEngine(display Displayer) *Engine

NewEngine creates a new rendering engine based on the displayer interface.

func (*Engine) Display

func (e *Engine) Display()

Display updates the display with all the changes that have been done since the last update.

func (*Engine) NewLayer

func (e *Engine) NewLayer(x, y, width, height int16, background color.RGBA) *Layer

NewLayer creates a new layer to the display with the given background color.

func (*Engine) NewLine

func (e *Engine) NewLine(x1, y1, x2, y2 int16, stroke color.RGBA) *Line

NewLine creates a new line with the two given coordinates and the given stroke color.

func (*Engine) NewRectangle

func (e *Engine) NewRectangle(x, y, width, height int16, c color.RGBA) *Rectangle

NewRectangle adds a new rectangle to the display with the given color.

func (*Engine) SetBackgroundColor

func (e *Engine) SetBackgroundColor(background color.RGBA)

SetBackgroundColor updates the background color of the display. Note that the alpha channel should be 100% (255) and will be ignored.

type Layer

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

Layer contains other objects, but makes sure no containing objects will draw outside of its boundaries. This object provides some encapsulation and improves performance when rendering many objects on a screen.

func (*Layer) Move

func (l *Layer) Move(x, y, width, height int16)

Move sets the new position and size of this layer.

func (*Layer) NewLayer

func (l *Layer) NewLayer(x, y, width, height int16, background color.RGBA) *Layer

NewLayer returns a new layer inside this layer, with the given coordinates (relative to the parent layer) and the given background color.

func (*Layer) NewLine

func (l *Layer) NewLine(x1, y1, x2, y2 int16, stroke color.RGBA) *Line

NewLine creates a new line with the given coordinates and line color. There is no restriction on the order of coordinates. Note that x2, y2 is inclusive, not exlusive, meaning that those pixels will get painted as well.

func (*Layer) NewRectangle

func (l *Layer) NewRectangle(x, y, width, height int16, c color.RGBA) *Rectangle

NewRectangle adds a new rectangle to the layer with the given color.

func (*Layer) SetBackgroundColor

func (l *Layer) SetBackgroundColor(background color.RGBA)

SetBackgroundColor updates the background color of this layer.

type Line

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

Line is an anti-aliased line drawn between two coordinates (inclusive), with a given color. It supports transparency in the color.

type Rectangle

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

Rectangle is a single rectangle drawn on the display that can be moved around.

func (*Rectangle) Move

func (r *Rectangle) Move(x, y, width, height int16)

Move sets the new position and size of this rectangle.