pix

Documentation

Overview

Package pix provides set of drawing functions for simple pixmap based displays. Such displays, unlike the vector or display-list based ones, require data in the form of ready-made array of pixels.

Only one drawing operation is required from the display driver: drawing an image on a selected rectangle. This basic drawing primitive is supported in hardware by many simple LCD and OLED display controlers like ILI9341, ILI948x, ST7796S, HX8357, SSD1351 and can be also easily implemented in software for other displays.

Index

• Constants
• func IsConvex(vertices ...image.Point) bool
• func StringWidth(s string, f font.Face) int
• func Width(s []byte, f font.Face) int
• type Area
  • func NewArea(r image.Rectangle, displays ...*Display) *Area
  • func (a *Area) Arc(p image.Point, mina, minb, maxa, maxb int, th0, th1 int32, fill bool)
  • func (a *Area) Bounds() image.Rectangle
  • func (a *Area) Color() color.Color
  • func (a *Area) Draw(r image.Rectangle, src image.Image, sp image.Point, mask image.Image, ...)
  • func (a *Area) Err(clear bool) error
  • func (a *Area) Fill(r image.Rectangle)
  • func (a *Area) FillQuad(p0, p1, p2, p3 image.Point)
  • func (a *Area) Flush()
  • func (a *Area) Line(p0, p1 image.Point)
  • func (a *Area) Mirror() int
  • func (a *Area) NewTextWriter(f font.Face) *TextWriter
  • func (a *Area) Origin() image.Point
  • func (a *Area) Point(x, y int)
  • func (a *Area) Quad(p0, p1, p2, p3 image.Point, fill bool)
  • func (a *Area) Rect() image.Rectangle
  • func (a *Area) RoundRect(p0, p1 image.Point, ra, rb int, fill bool)
  • func (a *Area) SetColor(c color.Color)
  • func (a *Area) SetColorRGBA(r, g, b, alpha uint8)
  • func (a *Area) SetMirror(mvxy int)
  • func (a *Area) SetOrigin(origin image.Point)
  • func (a *Area) SetRect(r image.Rectangle)
• type Display
  • func NewDisplay(drv Driver) *Display
  • func (d *Display) Bounds() image.Rectangle
  • func (d *Display) Driver() Driver
  • func (d *Display) Err(clear bool) error
  • func (d *Display) Flush()
  • func (d *Display) NewArea(r image.Rectangle) *Area
  • func (d *Display) Rect() image.Rectangle
  • func (d *Display) SetDir(dir int)
  • func (d *Display) SetOrigin(origin image.Point)
  • func (d *Display) SetRect(r image.Rectangle)
• type Driver
• type TextWriter
  • func (w *TextWriter) SetColor(c color.Color)
  • func (w *TextWriter) SetFace(f font.Face)
  • func (w *TextWriter) Write(s []byte) (int, error)
  • func (w *TextWriter) WriteString(s string) (int, error)

Constants

const (
	MI = images.MI // identity (no operation)
	MV = images.MV // swap X with Y
	MX = images.MX // mirror X axis
	MY = images.MY // mirror Y axis
)

const (
	NoWrap byte = iota
	WrapNewLine
	WrapSameLine
)

Wrapping modes determine what TextWriter does if the string does not fit in the drawing area.

const (
	BreakAny   byte = iota // break at any rune
	BreakSpace             // break at unicode White Space
)

Line breaking mode.

Functions

func IsConvex

func IsConvex(vertices ...image.Point) bool

IsConvex reports whether the given vertices describe a convex polygon.

func StringWidth

func StringWidth(s string, f font.Face) int

StringWidth returns the number of horizontal pixels that would be occupied by the string if it were drawn using the given font face and NoWrap mode.

func Width

func Width(s []byte, f font.Face) int

Width works like StringWidth but for byte slices.

Types

type Area

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

Area is the drawing area on the display. It has its own coordinates independent of its position on the display. Only one goroutine can use an area at the same time.

func NewArea

func NewArea(r image.Rectangle, displays ...*Display) *Area

NewArea creates new area that covers the given rectangle on the displays.

func (*Area) Arc

func (a *Area) Arc(p image.Point, mina, minb, maxa, maxb int, th0, th1 int32, fill bool)

Arc draws an arc with the center at p. The mina, minb, maxa, maxb represent the minimal and maximal radiuses in x and y direction. The th0 and th1 represent the starting and ending angle of the arc.

func (*Area) Bounds

func (a *Area) Bounds() image.Rectangle

Bounds return the area bounds.

func (*Area) Color

func (a *Area) Color() color.Color

Color returns the color used by drawing methods.

func (*Area) Draw

func (a *Area) Draw(r image.Rectangle, src image.Image, sp image.Point, mask image.Image, mp image.Point, op draw.Op)

Draw works like draw.DrawMask with dst set to the image representing the whole area.

func (*Area) Err

func (a *Area) Err(clear bool) error

Err runs through all the displays covered by a and calls thier Err methods until it encounters non-nil error.

func (*Area) Fill

func (a *Area) Fill(r image.Rectangle)

Fill fills the given rectangle.

func (*Area) FillQuad

func (a *Area) FillQuad(p0, p1, p2, p3 image.Point)

FillQuad draws a filled convex quadrilateral or triangle described by the given vertices. It obeys the filling rules so can be used to draw filled polygons composed of adjacent quadrilaterals/triangles ensuring that the common edges are drawn once. FillQuad draws a triangle if two adjacent vertices are identical.

func (*Area) Flush

func (a *Area) Flush()

Flush runs through all the displays covered by a and calls thier Flush methods.

func (*Area) Line

func (a *Area) Line(p0, p1 image.Point)

func (*Area) Mirror

func (a *Area) Mirror() int

Mirror returns current mirror drawing mode.

func (*Area) NewTextWriter

func (a *Area) NewTextWriter(f font.Face) *TextWriter

NewTextWriter provides a conveniet way to create new TextWriter. It can be used in place of the following set of statements:

w := new(TextWriter)
w.Area = a
w.Color = &image.Uniform{a.Color()}
w.Face = f
w.Wrap = WrapNewLine
w.Pos = a.Bounds().Min
_, w.Offset.Y = f.Size() // ascent

func (*Area) Origin

func (a *Area) Origin() image.Point

Returns the coordinate of the upper left corner of the area in the area's own coordinate system. The origin equals to a.Bounds().Min in MI mirror mode.

func (*Area) Point

func (a *Area) Point(x, y int)

Point provides a convenient way to fill one-pixel rectangle.

func (*Area) Quad

func (a *Area) Quad(p0, p1, p2, p3 image.Point, fill bool)

Quad draws a quadrilateral or triangle described by the given vertices. If fill is true the quadrilateral must be convex. Quad draws a triangle if two adjacent vertices are identical.

func (*Area) Rect

func (a *Area) Rect() image.Rectangle

Rect returns the rectangle set by SetRect.

func (*Area) RoundRect

func (a *Area) RoundRect(p0, p1 image.Point, ra, rb int, fill bool)

RoundRect can draw rectangles, ellipses and circles. If ra = rb = 0 it draws an empty or filled rectangle with a given diagonal (p0, p1). Non-zero ra enlarges the rectangle horizontally, non-zero rb enlarges it vertically. The enlarged rectangle has rounded corners with eliptic shape. If p0 = p1 RoundRect draws an ellipse with a given minor and major radius.

func (*Area) SetColor

func (a *Area) SetColor(c color.Color)

SetColor sets the color used by drawing methods.

func (*Area) SetColorRGBA

func (a *Area) SetColorRGBA(r, g, b, alpha uint8)

SetColorRGBA is equivalent of SetColor(color.RGBA{r, g, b, alpha}). Notice that r, g, b must be alpha-premultiplied, e.g. they must be less than or equal to alpha.

func (*Area) SetMirror

func (a *Area) SetMirror(mvxy int)

SetMirror sets mirror drawing mode. It affects all drawing methods and Bounds. Other Area's methods are unaffected.

func (*Area) SetOrigin

func (a *Area) SetOrigin(origin image.Point)

SetOrigin sets the coordinate of the upper left corner of the area. It does not affect the rectangle covered by the area but translates the area's own coordinate system in a way that the a.Bounds().Min = origin in MI mirror mode.

func (*Area) SetRect

func (a *Area) SetRect(r image.Rectangle)

SetRect sets the rectangle covered by the area on the displays.

type Display

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

Display represents a pixmap based display.

func NewDisplay

func NewDisplay(drv Driver) *Display

NewDisplay returns a new itialized display.

func (*Display) Bounds

func (d *Display) Bounds() image.Rectangle

Bounds returns the bounds of the display

func (*Display) Driver

func (d *Display) Driver() Driver

Driver returns the used driver

func (*Display) Err

func (d *Display) Err(clear bool) error

Err returns the saved error and clears it if the clear is true.

func (*Display) Flush

func (d *Display) Flush()

Flush ensures that everything drawn so far has been sent to the display controller. Using it is not required if the driver draws directly to the display without any buffering. Even then it is worth using Flush for code portability.

func (*Display) NewArea

func (d *Display) NewArea(r image.Rectangle) *Area

NewArea provides a convenient way to create a drawing area on the display. Use NewArea for areas that occupy more than one display.

func (*Display) Rect

func (d *Display) Rect() image.Rectangle

Rect returns the rectangle set by SetRect.

func (*Display) SetDir

func (d *Display) SetDir(dir int)

SetDir sets the display direction by rotate its default coordinate system by dir*90 degrees. The positive number means clockwise rotation, the negative one means counterclockwise rotation.

After SetDir the coordinates of all areas that use this display must be re-set (usng SetRect method) and their content should be redrawn. Use a.SetRect(a.Rect()) if the coordinates should remain the same.

func (*Display) SetOrigin

func (d *Display) SetOrigin(origin image.Point)

SetOrigin sets the coordinate used for the top left corner of the display. It does not change the size of the display or its position relative to the frame memory.

func (*Display) SetRect

func (d *Display) SetRect(r image.Rectangle)

SetRect sets the rectangle covered by the display in the frame memory provided by its driver. The r may exceed the dimensions of the frame memory, only the intersection will be used for drawing.

type Driver

type Driver interface {
	// SetDir sets the display direction rotating its default coordinate system
	// by dir*90 degrees. It returns the bounds of the frame memory for the new
	// direction. NewDisplay calls SetDir(0) before any other Driver method is
	// called so this is a good place for initialization code if required.
	SetDir(dir int) image.Rectangle

	// Draw works like draw.DrawMask with dst set to the image representing the
	// whole frame memory.
	//
	// The draw.Over operator may be implemented in a limited way but it must
	// at least support 1-bit transparency.
	//
	// Draw may assume the r is a non-empty rectangle that fits entirely on the
	// display and is entirely covered by src and mask.
	//
	// Draw is actually the only drawing operation required from a display
	// controller. The Fill operation below can be easily implemented by drawing
	// an uniform image.
	Draw(r image.Rectangle, src image.Image, sp image.Point, mask image.Image, mp image.Point, op draw.Op)

	// SetColor sets the color used by Fill method.
	SetColor(c color.Color)

	// Fill helps to increase prformance when drawing filled rectangles. Any
	// other geometric shape is drawn as a set of filed rectangles.
	//
	// Fill(r) is intended to be a faster counterpart of
	//
	//	Draw(r, image.Uniform{c}, image.Point{}, nil, image.Point{}, draw.Over)
	//
	// where c is the color set by SetColor.
	Fill(r image.Rectangle)

	// Flush allows to flush the drivers internal buffers. Drivers are allowed
	// to implement any kind of buffering if the direct drawing to the frame
	// memory is problematic or inefficient.
	Flush()

	// Err returns the saved error and clears it if clear is true. If an error
	// has occured the driver should avoid any actions that may cause further
	// errors until the recorded error is cleared.
	Err(clear bool) error
}

Driver defines the interface to be implemented by display controller drivers or anything else that wants to use drawing functions of pix package.

type TextWriter

type TextWriter struct {
	Area   *Area       // drawing area
	Face   font.Face   // source of glyphs
	Color  image.Image // glyph color (foreground image)
	Pos    image.Point // position of the next glyph
	Offset image.Point // offset from the Pos to the glyph origin
	Wrap   byte        // wrapping mode
	Break  byte        // line breaking mode
	// contains filtered or unexported fields
}

TextWriter allows to write a text on an area. At least the Area, Face and Color fields must be set before use it.

Notice that the Color field type is image.Image, not color.Color. Set it to &image.Uniform{color} for traditional uniform color of glyphs.

func (*TextWriter) SetColor

func (w *TextWriter) SetColor(c color.Color)

SetColor provides a convenient way to set drawing color. If the w.Color contains value of type *image.Uniform it modifies the color of the current image. Otherwise it sets w.Color to &image.Uniform{c}.

func (*TextWriter) SetFace

func (w *TextWriter) SetFace(f font.Face)

SetFace provides a convenient way to set w.Face and at the same time modify w.Offset in such a way that the current baseline is unaffected.

func (*TextWriter) Write

func (w *TextWriter) Write(s []byte) (int, error)

func (*TextWriter) WriteString

func (w *TextWriter) WriteString(s string) (int, error)