framebuffer

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2013 License: BSD-1-Clause Imports: 14 Imported by: 0

README

framebuffer

Note: This is work in progress. Use at your own risk.

This library allows a Go application to draw arbitrary graphics to the Linux Framebuffer. This allows one to create graphical applications without the need for a monolithic display manager like X.

This is a pure Go implementation.

Because the framebuffer offers direct access to a chunk of memory mapped pixel data, it is strongly advised to keep all actual drawing operations confined to the thread that initialized the framebuffer.

The framebuffer is usually initialized to a specific display mode by the kernel itself. While this library supplies the means to alter the current display mode, this may not always have any effect as a driver can choose to ignore your requested values. Besides that, it is generally considered safer to use the external fbset command for this purpose. Video modes for the framebuffer require very precise timing values to be supplied along with any desired resolution. Doing this incorrectly can damage the display.

fbset comes with a set of default modes which are stored in the file /etc/fb.modes. We read this file and extract the set of video modes from it. These modes each have a name by which they can be identified. When supplying a new mode to this package, it should come in the form of this name. For example: "1600x1200-76".

New video modes can be added to the /etc/fb.modes file.

The framebuffer obscures the terminal, so any debug or error data written to stdout and/or stderr, will not be visible while it is running. To get access to this data, pipe their outputs to a file:

./myapp 1> stdout.log 2>error.log

Known issues

  • Running a program which writes to the Framebuffer, may fail with a permission error. This is likely because your current user is not part of the video group. Add the user to this group and all should be well.

  • This library draws directly the raw framebuffer. This means that it may interfere with other applications doing the same thing. This includes X, if it is running. While we take every effort to appropriately handle switching between the various applications, this should always be kept in mind.

  • There may be ioctl errors when trying to run a program in a terminal emulator. This happens because the API requires a real tty. Ideally this should be fixed at some point.

Usage

go get github.com/jteeuwen/framebuffer

License

Unless otherwise stated, all of the work in this project is subject to a 1-clause BSD license. Its contents can be found in the enclosed LICENSE file.

Documentation

Overview

This library allows a Go application to draw arbitrary graphics to the Linux Framebuffer. This allows one to create graphical applications without the need for a monolithic display manager like X.

Because the framebuffer offers direct access to a chunk of memory mapped pixel data, it is strongly advised to keep all actual drawing operations confined to the thread that initialized the framebuffer.

Index

Constants

View Source 
const (
	SyncHorHighAct  = 1 << iota // horizontal sync high active
	SyncVertHighAct             // vertical sync high active
	SyncExt                     // external sync
	SyncCompHighAct             // composite sync high active
	SyncBroadcast               // broadcast video timings
	SyncOnGreen                 // sync on green
)
View Source 
const (
	VModeNonInterlaced = 0 // non interlaced
	VModeInterlaced    = 1 // interlaced
	VModeDouble        = 2 // double scan
	VModeOddFieldFirst = 4 // interlaced: top line first
	VModeMask          = 255
	VModeYWrap         = 256 // ywrap instead of panning
	VModeSmoothXPan    = 512 // smooth xpan possible (internally used)
	VModeCanUpdate     = 512 // don't update x/yoffset
)
View Source 
const (
	PF_UNKNOWN = iota
	PF_RGBA    // 32-bit color
	PF_BGRA    // 32-bit color
	PF_RGB_555 // 16-bit color
	PF_RGB_565 // 16-bit color
	PF_BGR_555 // 16-bit color
	PF_BGR_565 // 16-bit color
	PF_INDEXED // 8-bit color (grayscale or paletted).
)

List of known image/pixel formats.

Variables

View Source 
var (
	Black     = RGBColor{0x00, 0x00, 0x00}
	DarkGrey  = RGBColor{0x55, 0x55, 0x55}
	LightGrey = RGBColor{0xaa, 0xaa, 0xaa}
	White     = RGBColor{0xff, 0xff, 0xff}
	Red       = RGBColor{0xff, 0x00, 0x00}
	Green     = RGBColor{0x00, 0xff, 0x00}
	Blue      = RGBColor{0x00, 0x00, 0xff}
)

Some named colors

View Source 
var (
	AliceBlue            = RGBColor{0xF0, 0xF8, 0xFF}
	AntiqueWhite         = RGBColor{0xFA, 0xEB, 0xD7}
	Aquamarine           = RGBColor{0x7F, 0xFF, 0xD4}
	Azure                = RGBColor{0xF0, 0xFF, 0xFF}
	Beige                = RGBColor{0xF5, 0xF5, 0xDC}
	Bisque               = RGBColor{0xFF, 0xE4, 0xC4}
	BlanchedAlmond       = RGBColor{0xFF, 0xEB, 0xCD}
	BlueViolet           = RGBColor{0x8A, 0x2B, 0xE2}
	Brown                = RGBColor{0xA5, 0x2A, 0x2A}
	BurlyWood            = RGBColor{0xDE, 0xB8, 0x87}
	CadetBlue            = RGBColor{0x5F, 0x9E, 0xA0}
	Chartreuse           = RGBColor{0x7F, 0xFF, 0x00}
	Chocolate            = RGBColor{0xD2, 0x69, 0x1E}
	Coral                = RGBColor{0xFF, 0x7F, 0x50}
	CornflowerBlue       = RGBColor{0x64, 0x95, 0xED}
	Cornsilk             = RGBColor{0xFF, 0xF8, 0xDC}
	Crimson              = RGBColor{0xDC, 0x14, 0x3C}
	Cyan                 = RGBColor{0x00, 0xFF, 0xFF}
	DarkBlue             = RGBColor{0x00, 0x00, 0x8B}
	DarkCyan             = RGBColor{0x00, 0x8B, 0x8B}
	DarkGoldenrod        = RGBColor{0xB8, 0x86, 0x0B}
	DarkGray             = RGBColor{0xA9, 0xA9, 0xA9}
	DarkGreen            = RGBColor{0x00, 0x64, 0x00}
	DarkKhaki            = RGBColor{0xBD, 0xB7, 0x6B}
	DarkMagenta          = RGBColor{0x8B, 0x00, 0x8B}
	DarkOliveGreen       = RGBColor{0x55, 0x6B, 0x2F}
	DarkOrange           = RGBColor{0xFF, 0x8C, 0x00}
	DarkOrchid           = RGBColor{0x99, 0x32, 0xCC}
	DarkRed              = RGBColor{0x8B, 0x00, 0x00}
	DarkSalmon           = RGBColor{0xE9, 0x96, 0x7A}
	DarkSeaGreen         = RGBColor{0x8F, 0xBC, 0x8F}
	DarkSlateBlue        = RGBColor{0x48, 0x3D, 0x8B}
	DarkSlateGray        = RGBColor{0x2F, 0x4F, 0x4F}
	DarkTurquoise        = RGBColor{0x00, 0xCE, 0xD1}
	DarkViolet           = RGBColor{0x94, 0x00, 0xD3}
	DeepPink             = RGBColor{0xFF, 0x14, 0x93}
	DeepSkyBlue          = RGBColor{0x00, 0xBF, 0xFF}
	DimGray              = RGBColor{0x69, 0x69, 0x69}
	DodgerBlue           = RGBColor{0x1E, 0x90, 0xFF}
	FireBrick            = RGBColor{0xB2, 0x22, 0x22}
	FloralWhite          = RGBColor{0xFF, 0xFA, 0xF0}
	ForestGreen          = RGBColor{0x22, 0x8B, 0x22}
	Gainsboro            = RGBColor{0xDC, 0xDC, 0xDC}
	GhostWhite           = RGBColor{0xF8, 0xF8, 0xFF}
	Gold                 = RGBColor{0xFF, 0xD7, 0x00}
	Goldenrod            = RGBColor{0xDA, 0xA5, 0x20}
	GreenYellow          = RGBColor{0xAD, 0xFF, 0x2F}
	Honeydew             = RGBColor{0xF0, 0xFF, 0xF0}
	HotPink              = RGBColor{0xFF, 0x69, 0xB4}
	IndianRed            = RGBColor{0xCD, 0x5C, 0x5C}
	Indigo               = RGBColor{0x4B, 0x00, 0x82}
	Ivory                = RGBColor{0xFF, 0xFF, 0xF0}
	Khaki                = RGBColor{0xF0, 0xE6, 0x8C}
	Lavender             = RGBColor{0xE6, 0xE6, 0xFA}
	LavenderBlush        = RGBColor{0xFF, 0xF0, 0xF5}
	LawnGreen            = RGBColor{0x7C, 0xFC, 0x00}
	LemonChiffon         = RGBColor{0xFF, 0xFA, 0xCD}
	LightBlue            = RGBColor{0xAD, 0xD8, 0xE6}
	LightCoral           = RGBColor{0xF0, 0x80, 0x80}
	LightCyan            = RGBColor{0xE0, 0xFF, 0xFF}
	LightGoldenrodYellow = RGBColor{0xFA, 0xFA, 0xD2}
	LightGreen           = RGBColor{0x90, 0xEE, 0x90}
	LightGray            = RGBColor{0xD3, 0xD3, 0xD3}
	LightPink            = RGBColor{0xFF, 0xB6, 0xC1}
	LightSalmon          = RGBColor{0xFF, 0xA0, 0x7A}
	LightSeaGreen        = RGBColor{0x20, 0xB2, 0xAA}
	LightSkyBlue         = RGBColor{0x87, 0xCE, 0xFA}
	LightSlateGray       = RGBColor{0x77, 0x88, 0x99}
	LightSteelBlue       = RGBColor{0xB0, 0xC4, 0xDE}
	LightYellow          = RGBColor{0xFF, 0xFF, 0xE0}
	LimeGreen            = RGBColor{0x32, 0xCD, 0x32}
	Linen                = RGBColor{0xFA, 0xF0, 0xE6}
	Magenta              = RGBColor{0xFF, 0x00, 0xFF}
	MediumAquamarine     = RGBColor{0x66, 0xCD, 0xAA}
	MediumBlue           = RGBColor{0x00, 0x00, 0xCD}
	MediumOrchid         = RGBColor{0xBA, 0x55, 0xD3}
	MediumPurple         = RGBColor{0x93, 0x70, 0xD8}
	MediumSeaGreen       = RGBColor{0x3C, 0xB3, 0x71}
	MediumSlateBlue      = RGBColor{0x7B, 0x68, 0xEE}
	MediumSpringGreen    = RGBColor{0x00, 0xFA, 0x9A}
	MediumTurquoise      = RGBColor{0x48, 0xD1, 0xCC}
	MediumVioletRed      = RGBColor{0xC7, 0x15, 0x85}
	MidnightBlue         = RGBColor{0x19, 0x19, 0x70}
	MintCream            = RGBColor{0xF5, 0xFF, 0xFA}
	MistyRose            = RGBColor{0xFF, 0xE4, 0xE1}
	Moccasin             = RGBColor{0xFF, 0xE4, 0xB5}
	NavajoWhite          = RGBColor{0xFF, 0xDE, 0xAD}
	OldLace              = RGBColor{0xFD, 0xF5, 0xE6}
	OliveDrab            = RGBColor{0x68, 0x8E, 0x23}
	Orange               = RGBColor{0xFF, 0xA5, 0x00}
	OrangeRed            = RGBColor{0xFF, 0x45, 0x00}
	Orchid               = RGBColor{0xDA, 0x70, 0xD6}
	PaleGoldenrod        = RGBColor{0xEE, 0xE8, 0xAA}
	PaleGreen            = RGBColor{0x98, 0xFB, 0x98}
	PaleTurquoise        = RGBColor{0xAF, 0xEE, 0xEE}
	PaleVioletRed        = RGBColor{0xD8, 0x70, 0x93}
	PapayaWhip           = RGBColor{0xFF, 0xEF, 0xD5}
	PeachPuff            = RGBColor{0xFF, 0xDA, 0xB9}
	Peru                 = RGBColor{0xCD, 0x85, 0x3F}
	Pink                 = RGBColor{0xFF, 0xC0, 0xCB}
	Plum                 = RGBColor{0xDD, 0xA0, 0xDD}
	PowderBlue           = RGBColor{0xB0, 0xE0, 0xE6}
	RosyBrown            = RGBColor{0xBC, 0x8F, 0x8F}
	RoyalBlue            = RGBColor{0x41, 0x69, 0xE1}
	SaddleBrown          = RGBColor{0x8B, 0x45, 0x13}
	Salmon               = RGBColor{0xFA, 0x80, 0x72}
	SandyBrown           = RGBColor{0xF4, 0xA4, 0x60}
	SeaGreen             = RGBColor{0x2E, 0x8B, 0x57}
	Seashell             = RGBColor{0xFF, 0xF5, 0xEE}
	Sienna               = RGBColor{0xA0, 0x52, 0x2D}
	SkyBlue              = RGBColor{0x87, 0xCE, 0xEB}
	SlateBlue            = RGBColor{0x6A, 0x5A, 0xCD}
	SlateGray            = RGBColor{0x70, 0x80, 0x90}
	Snow                 = RGBColor{0xFF, 0xFA, 0xFA}
	SpringGreen          = RGBColor{0x00, 0xFF, 0x7F}
	SteelBlue            = RGBColor{0x46, 0x82, 0xB4}
	Tan                  = RGBColor{0xD2, 0xB4, 0x8C}
	Thistle              = RGBColor{0xD8, 0xBF, 0xD8}
	Tomato               = RGBColor{0xFF, 0x63, 0x47}
	Turquoise            = RGBColor{0x40, 0xE0, 0xD0}
	Violet               = RGBColor{0xEE, 0x82, 0xEE}
	Wheat                = RGBColor{0xF5, 0xDE, 0xB3}
	WhiteSmoke           = RGBColor{0xF5, 0xF5, 0xF5}
	YellowGreen          = RGBColor{0x9A, 0xCD, 0x32}
)

124 named unix colors.

View Source 
var RGB555Model = color.ModelFunc(
	func(c color.Color) color.Color {
		if _, ok := c.(RGBColor); ok {
			return c
		}

		r, g, b, _ := c.RGBA()
		return RGBColor{
			uint8(r>>8) & mask5,
			uint8(g>>8) & mask5,
			uint8(b>>8) & mask5,
		}
	})
View Source 
var RGB565Model = color.ModelFunc(
	func(c color.Color) color.Color {
		if _, ok := c.(RGBColor); ok {
			return c
		}

		r, g, b, _ := c.RGBA()
		return RGBColor{
			uint8(r>>8) & mask5,
			uint8(g>>8) & mask6,
			uint8(b>>8) & mask5,
		}
	})

Functions

This section is empty.

Types

type BGR555 

type BGR555 struct {
	Pix    []byte
	Rect   image.Rectangle
	Stride int
}

func (*BGR555) At 

func (i *BGR555) At(x, y int) color.Color

func (*BGR555) Bounds 

func (i *BGR555) Bounds() image.Rectangle

func (*BGR555) ColorModel 

func (i *BGR555) ColorModel() color.Model

func (*BGR555) PixOffset 

func (i *BGR555) PixOffset(x, y int) int

func (*BGR555) Set 

func (i *BGR555) Set(x, y int, c color.Color)

func (*BGR555) SetRGB 

func (i *BGR555) SetRGB(x, y int, c RGBColor)

type BGR565 

type BGR565 struct {
	Pix    []byte
	Rect   image.Rectangle
	Stride int
}

func (*BGR565) At 

func (i *BGR565) At(x, y int) color.Color

func (*BGR565) Bounds 

func (i *BGR565) Bounds() image.Rectangle

func (*BGR565) ColorModel 

func (i *BGR565) ColorModel() color.Model

func (*BGR565) PixOffset 

func (i *BGR565) PixOffset(x, y int) int

func (*BGR565) Set 

func (i *BGR565) Set(x, y int, c color.Color)

func (*BGR565) SetRGB 

func (i *BGR565) SetRGB(x, y int, c RGBColor)

type BGRA 

type BGRA struct {
	Pix    []byte
	Rect   image.Rectangle
	Stride int
}

func (*BGRA) At 

func (i *BGRA) At(x, y int) color.Color

func (*BGRA) Bounds 

func (i *BGRA) Bounds() image.Rectangle

func (*BGRA) ColorModel 

func (i *BGRA) ColorModel() color.Model

func (*BGRA) PixOffset 

func (i *BGRA) PixOffset(x, y int) int

func (*BGRA) Set 

func (i *BGRA) Set(x, y int, c color.Color)

func (*BGRA) SetRGBA 

func (i *BGRA) SetRGBA(x, y int, c color.RGBA)

type Canvas 

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

Linux Framebuffer implementation.

func Open 

func Open(dm *DisplayMode) (c *Canvas, err error)

Open opens the framebuffer with the given display mode.

If mode is nil, the default framebuffer mode is used.

The framebuffer is usually initialized to a specific display mode by the kernel itself. While this library supplies the means to alter the current display mode, this may not always have any effect as a driver can choose to ignore your requested values. Besides that, it is generally considered safer to use the external `fbset` command for this purpose.

Video modes for the framebuffer require very precise timing values to be supplied along with any desired resolution. Doing this incorrectly can damage the display. Refer to Canvas.Modes() and Canvas.FindMode() for more information. Canvas.CurrentMode() can be used to see which mode is actually being used.

func (*Canvas) Accelerated 

func (c *Canvas) Accelerated() bool

Accelerated returns true if the framebuffer currently supports hardware acceleration.

func (*Canvas) Buffer 

func (c *Canvas) Buffer() []byte

Buffer provides direct access to the entire memory-mapped pixel buffer.

func (*Canvas) Clear 

func (c *Canvas) Clear()

Clear clears (zeroes) the framebuffer memory.

func (*Canvas) Close 

func (c *Canvas) Close() (err error)

Close closes the framebuffer and cleans up its resources.

func (*Canvas) CurrentMode 

func (c *Canvas) CurrentMode() (*DisplayMode, error)

CurrentMode returns the current framebuffer display mode.

func (*Canvas) FindMode 

func (c *Canvas) FindMode(name string) *DisplayMode

FindMode finds the display mode with the given name. Returns nil if it does not exist.

The external `fbset` tool comes with a set of default modes which are stored in the file `/etc/fb.modes`. We read this file and extract the set of video modes from it. These modes each have a name by which they can be identified. When supplying a new mode to this function, it should come in the form of this name. For example: "1600x1200-76".

New video modes can be added to the `/etc/fb.modes` file.

func (*Canvas) Image 

func (c *Canvas) Image() (draw.Image, error)

Image returns the pixel buffer as a draw.Image instance. Returns nil if something went wrong.

func (*Canvas) Modes 

func (c *Canvas) Modes() ([]*DisplayMode, error)

Modes returns the list of supported display modes. These are read from `/etc/fb.modes`. This can be called before the framebuffer has been opened.

func (*Canvas) Palette 

func (c *Canvas) Palette() (color.Palette, error)

Palette returns the current framebuffer color palette.

func (*Canvas) SetPalette 

func (c *Canvas) SetPalette(pal color.Palette) error

SetPalette sets the current framebuffer color palette.

type DisplayMode 

type DisplayMode struct {
	Name   string
	Format PixelFormat

	XRes  int // Visible resolution.
	YRes  int
	XVRes int // Virtual resolution (viewport).
	YVRes int
	Bpp   int // Bit depth.

	// Timing: All values in pixclocks, except pixclock.
	Pixclock int // Pixel clock in picoseconds.
	Left     int // Time in pixclocks from sync to picture.
	Right    int // Time in pixclocks from picture to sync.
	Upper    int // Time in pixclocks from sync to picture.
	Lower    int // Time in pixclocks from picture to sync.
	HSync    int // Time in pixclocks of horizontal sync.
	VSync    int // Time in pixclocks of vertical sync.
	Sync     int // See SyncXXXX values.
	VMode    int // See VModeXXXX values.
}

DisplayMode defines a supported display mode.

func (*DisplayMode) Stride 

func (dm *DisplayMode) Stride() int

Stride returns the width, in bytes, for a single row of pixels.

type PixelFormat 

type PixelFormat struct {
	RedBits    uint8 // Bit count for the red channel.
	RedShift   uint8 // Shift offset for the red channel.
	GreenBits  uint8 // Bit count for the green channel.
	GreenShift uint8 // Shift offset for the green channel.
	BlueBits   uint8 // Bit count for the blue channel.
	BlueShift  uint8 // Shift offset for the blue channel.
	AlphaBits  uint8 // Bit count for the alpha channel.
	AlphaShift uint8 // Shift offset for the alpha channel.
}

PixelFormat describes the color layout of a single pixel in a given pixel buffer. Specifically, how many and which bits are occupied by a given color channel.

For example, a standard RGBA pixel would look like this: 

       | bit 31                 bit 0 |
       |                              |
pixel: rrrrrrrrggggggggbbbbbbbbaaaaaaaa

The PixelFormat for this looks as follows: 

red bits:  8
red shift: 24

green bits:  8
green shift: 16

blue bits:  8
blue shift: 8

alpha bits:  8
alpha shift: 0

We can extract the channel information as follows: 

red_mask := (1 << red_bits) - 1
green_mask := (1 << green_bits) - 1
blue_mask := (1 << blue_bits) - 1
alpha_mask := (1 << alpha_bits) - 1

r := (pixel >> red_shift) & red_mask
g := (pixel >> green_shift) & green_mask
b := (pixel >> blue_shift) & blue_mask
a := (pixel >> alpha_shift) & alpha_mask

func (PixelFormat) Stride 

func (p PixelFormat) Stride() int

Stride returns the width, in bytes, for a single pixel.

func (PixelFormat) Type 

func (p PixelFormat) Type() int

Type returns an integer constant from the PF_XXX list, which identifies the type of pixelformat.

type RGB555 

type RGB555 struct {
	Pix    []byte
	Rect   image.Rectangle
	Stride int
}

func (*RGB555) At 

func (i *RGB555) At(x, y int) color.Color

func (*RGB555) Bounds 

func (i *RGB555) Bounds() image.Rectangle

func (*RGB555) ColorModel 

func (i *RGB555) ColorModel() color.Model

func (*RGB555) PixOffset 

func (i *RGB555) PixOffset(x, y int) int

func (*RGB555) Set 

func (i *RGB555) Set(x, y int, c color.Color)

func (*RGB555) SetRGB 

func (i *RGB555) SetRGB(x, y int, c RGBColor)

type RGB565 

type RGB565 struct {
	Pix    []byte
	Rect   image.Rectangle
	Stride int
}

func (*RGB565) At 

func (i *RGB565) At(x, y int) color.Color

func (*RGB565) Bounds 

func (i *RGB565) Bounds() image.Rectangle

func (*RGB565) ColorModel 

func (i *RGB565) ColorModel() color.Model

func (*RGB565) PixOffset 

func (i *RGB565) PixOffset(x, y int) int

func (*RGB565) Set 

func (i *RGB565) Set(x, y int, c color.Color)

func (*RGB565) SetRGB 

func (i *RGB565) SetRGB(x, y int, c RGBColor)

type RGBColor 

type RGBColor struct {
	R, G, B uint8
}

func (RGBColor) RGBA 

func (c RGBColor) RGBA() (r, g, b, a uint32)

Source Files

View all Source files

Directories

Path Synopsis
examples
simpleapp command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.