display

Documentation

Overview

Package display implements interfaces for visual output devices. These can be pixel or text based.

Index

• Variables
• type Contrast
• type CursorDirection
• type CursorMode
• type DisplayBacklight
• type DisplayContrast
• type DisplayRGBBacklight
• type Drawer
• type Intensity
• type TextDisplay

Examples

• Drawer

Variables

var ErrInvalidCommand = errors.New("invalid command")

var ErrNotImplemented = errors.New("not implemented")

Types

type Contrast

type Contrast int

type CursorDirection

type CursorDirection int

const (
	// Constants for moving the cursor relative to it's current position.
	//
	// Move the cursor one unit back.
	Backward CursorDirection = iota
	// Move the cursor one unit forward.
	Forward
	Up
	Down
)

type CursorMode

type CursorMode int

const (
	// Turn the cursor Off
	CursorOff CursorMode = iota
	// Enable Underline Cursor
	CursorUnderline
	// Enable Block Cursor
	CursorBlock
	// Blinking
	CursorBlink
)

type DisplayBacklight

type DisplayBacklight interface {
	Backlight(intensity Intensity) error
}

Interface for displays that support a monochrome backlight. Displays that support RGB Backlights should implement this as well for maximum compatibility.

Many units that support this command write the value to EEPROM, which has a finite number of writes. To turn the unit on/off, use TextDisplay.Display()

type DisplayContrast

type DisplayContrast interface {
	Contrast(contrast Contrast) error
}

Interface for displays that support a programmable contrast adjustment. As with SetBacklight(), many devices serialize the value to EEPROM, which support only a finite number of writes, so this should be used sparingly.

type DisplayRGBBacklight

type DisplayRGBBacklight interface {
	RGBBacklight(red, green, blue Intensity) error
}

Interface for displays that support a RGB Backlight. E.G. the Sparkfun SerLCD

type Drawer

type Drawer interface {
	conn.Resource

	// ColorModel returns the device native color model.
	ColorModel() color.Model
	// Bounds returns the size of the output device.
	//
	// Generally displays should have Min at {0, 0} but this is not guaranteed in
	// multiple displays setup or when an instance of this interface represents a
	// section of a larger logical display.
	Bounds() image.Rectangle
	// Draw updates the display with this image.
	//
	// Only the pixels within the display boundary are updated. Partial update is
	// supported.
	//
	// Coordinates are top-left 0,0.
	//
	// dstRect aligns the the drawing operation in the display, enabling partial
	// update.
	//
	// srcPts aligns the image at this offset, enabling using a subset of the
	// source image. use image.Point{} to take the image at its origin.
	Draw(dstRect image.Rectangle, src image.Image, srcPts image.Point) error
}

Drawer represents a context to display pixels on an output device. It is a write-only interface.

What Drawer represents can be as varied as a 1 bit OLED display or a strip of LED lights. The implementation keeps a single frame buffer, so that partial updates can be done.

Example

package main

import (
	"image"
	"log"

	"periph.io/x/conn/v3/display"
	"periph.io/x/conn/v3/driver/driverreg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.Init(); err != nil {
		log.Fatal(err)
	}

	// Get a display output device, like an apa102 or ssd1306. For example:
	//   s, _ := spireg.Open("")
	//   d, _ := apa102.New(s, &apa102.DefaultOpts)
	var d display.Drawer

	// Get an image. You could load a PNG. Resize it to the device display size.
	img := image.NewNRGBA(d.Bounds())

	// Render the image. The normal use case is:
	// - Use d.Bounds() as the dstRect, to cover the whole screen.
	// - Use image.Point{} as 'srcPts' unless you want to offset inside
	//   the image.
	if err := d.Draw(d.Bounds(), img, image.Point{}); err != nil {
		log.Fatal(err)
	}
}

type Intensity

type Intensity int

type TextDisplay

type TextDisplay interface {
	// Enable/Disable auto scroll
	AutoScroll(enabled bool) (err error)
	// Return the number of columns the display supports
	Cols() int
	// Clear the display and move the cursor home.
	Clear() (err error)
	// Set the cursor mode. You can pass multiple arguments.
	// Cursor(CursorOff, CursorUnderline)
	//
	// Implementations should return an error if the value of mode is not
	// mode>= CursorOff && mode <= CursorBlink
	Cursor(mode ...CursorMode) (err error)
	// Move the cursor home (MinRow(),MinCol())
	Home() (err error)
	// Return the min column position.
	MinCol() int
	// Return the min row position.
	MinRow() int
	// Move the cursor forward or backward.
	Move(dir CursorDirection) (err error)
	// Move the cursor to arbitrary position. Implementations should return an
	// error if row < MinRow() || row > (Rows()-MinRow()), or col < MinCol()
	// || col > (Cols()-MinCol())
	MoveTo(row, col int) (err error)
	// Return the number of rows the display supports.
	Rows() int
	// Turn the display on / off
	Display(on bool) (err error)
	// return info about the display.
	String() string
	// Write a set of bytes to the display.
	Write(p []byte) (n int, err error)
	// Write a string output to the display.
	WriteString(text string) (n int, err error)
}

TextDisplay represents an interface to a basic character device. It provides standard methods implemented by a majority of character LCD devices. Pixel type displays can implement this interface if desired.