pixfont

README

pixfont

A simple, lightweight Pixel Font (aka bitmap fonts) package for Go that works with the standard image/draw package. If you want scaling, anti-aliasing, TrueType fonts, or other "fancy" features then I suggest you check out https://github.com/golang/freetype

However, if you just want to put a little bit of text in your generated image and don't care about aliasing, or if you can't afford run-time font dependencies or additional overhead, or you need something that "just works"... Well then pixfont has exactly what you want.

pixfont comes ready-to-go with a public domain 8x8 pixel fixed-width font from the bygone era of PCs (created by Marcel Sondaar / IBM).

Basic, just-put-some-text-in-my-image usage is straightforward:

package main

import (
        "image"
        "image/color"
        "image/png"
        "os"

        "github.com/pbnjay/pixfont"
)

func main() {
        img := image.NewRGBA(image.Rect(0, 0, 150, 30))

        pixfont.DrawString(img, 10, 10, "Hello, World!", color.Black)

        f, _ := os.OpenFile("hello.png", os.O_CREATE|os.O_RDWR, 0644)
        png.Encode(f, img)
}

Resulting Image:

Roll your own font

The default font isn't what you're looking for? Here's how to create your own pixel font for use with this package.

Step one: Create a .png image of all the characters you want to include in a single row. For example, say we want to use the great font Minecraftia by Andrew Tyler. Here's a copy of the preview image provided with the download.

Step two: Find the start offset and list of characters in order. In the image above, we have a start offset of 1,20 and characters A-Z a-z 0-9. Many more are available in the real font, which could be extracted as well with a more complete image.

Step three: If you're lucky, just run fontgen on the image to create your font:

$ ./fontgen -x=1 -y=20 -h=8 -a="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" -img minecraftia.png -o minecraftia

In the minecraftia example however, we need to do a minor edit before we can generate the pixfont code, so we follow the alternate path:

Step three: Run fontgen on the image and create an intermedia text representation:

$ ./fontgen -x=1 -y=20 -h=8 -a="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789" -img minecraftia.png > minecraftia.txt

Step four: Review the text version to be sure that all characters matched up correctly. The first character on each line is the letter being mapped, and either a space or an 'X' occurs between the square brackets to denote the pixels.

In Minecraftia, the tail of the lowercase L touches the lowercase M, causing the automatic extracter to merge the characters:

		l  [X      ]
		l  [X      ]
		l  [X XX X ]
		l  [X X X X]
		l  [X X X X]
		l  [X X   X]
		l  [ XX   X]
		l  [       ]
		m  [       ]
		m  [       ]
		m  [ XXXX  ]
		m  [ X   X ]
		m  [ X   X ]
		m  [ X   X ]
		m  [ X   X ]
		m  [       ]

The easiest way to handle this without making a new image is to remove an l or m from the -a alphabet parameter, and edit the intermediate text file to separate the letters:

$ ./fontgen -x=1 -y=20 -h=8 -a="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklnopqrstuvwxyz0123456789" -img minecraftia.png > minecraftia.txt
$ vim minecraftia.txt

Step five: Generate the output file using the intermediate text file:

$ ./fontgen -txt minecraftia.txt -o minecraftia

Now just import the font into your code. For example, to use Minecraftia in the Hello World example above:

// file main.go

package main

import (
        "image"
        "image/color"
        "image/png"
        "os"

        "main/minecraftia"
)

func main() {
        img := image.NewRGBA(image.Rect(0, 0, 150, 30))

        minecraftia.Font.DrawString(img, 10, 10, "Hello, World!", color.Black)

        f, _ := os.OpenFile("hello.png", os.O_CREATE|os.O_RDWR, 0644)
        png.Encode(f, img)
}

Resulting Image: -- Note the missing , and ! since they were not included in the extracted character set. I'll leave inclusion of those as an excercise for the reader.

Variable Width Fonts

To create a variable width font (i.e. an i is skinnier than a w), just add -v to all invocations of fontgen. When you need to make edits to the font, just ensure that characters are flush with the left edge for best display.

Here's the minecraftia result image with a variable width:

License

Code for this package is release under the MIT License. The bundled 8x8 font was released into the public domain by Marcel Sondaar / IBM.

Documentation

Overview

Package pixfont is a simple pixel font library that allows for text drawing in the standard image and image/draw packages. It is very useful when heavyweight TrueType fonts and the freetype-go package are not available or desired. Since fonts are simple bitmap images, scaling is not possible and aliasing will occur.

See the included fontgen tool if you wish to convert or include your own pixel font in your project.

Index

• Variables
• func DrawString(dr Drawable, x, y int, s string, clr color.Color) int
• func MeasureString(s string) int
• type Drawable
• type PixFont
  • func NewPixFont(w, h uint8, cm map[rune]uint16, d []uint32) *PixFont
  • func (p *PixFont) DrawRune(dr Drawable, x, y int, c rune, clr color.Color) (bool, int)
  • func (p *PixFont) DrawString(dr Drawable, x, y int, s string, clr color.Color) int
  • func (p *PixFont) GetHeight() int
  • func (p *PixFont) MeasureRune(c rune) (bool, int)
  • func (p *PixFont) MeasureString(s string) int
  • func (p *PixFont) SetVariableWidth(isVar bool)
• type StringDrawable
  • func (s *StringDrawable) PrefixString(p string) string
  • func (s *StringDrawable) Set(x, y int, c color.Color)
  • func (s *StringDrawable) String() string

Variables

var DefaultFont = Font8x8

DefaultFont is used by the convienence method DrawString, and is initialized to the Public Domain 8x8 fixed font with some unicode characters.

var Font8x8 = &PixFont{
	8, 8,
	eightMap,
	eightData,
	8,
}

Font8x8 is a fixed-width 8x8 pixel font which has been made available in the Public Domain. It looks a little bit like this (somewhat heavy, serifs, typical console font from early PCs)

  XXX                         X      XXXX              XXXX
 XX XX                       XX     XX  XX            XX  XX
 XX       XXXX    XXXXX     XXXXX   XX  XX   XX   XX  XX  XX
XXXX     XX  XX   XX  XX     XX      XXXX     XX XX    XXXX
 XX      XX  XX   XX  XX     XX     XX  XX     XXX    XX  XX
 XX      XX  XX   XX  XX     XX X   XX  XX    XX XX   XX  XX
XXXX      XXXX    XX  XX      XX     XXXX    XX   XX   XXXX

var Spacing = 1

Spacing is the pixel spacing to use between letters (1 px by default)

Functions

func DrawString

func DrawString(dr Drawable, x, y int, s string, clr color.Color) int

DrawString is a convienence method that calls DrawString using the DefaultFont

func MeasureString

func MeasureString(s string) int

MeasureString is a convienence method that calls MeasureString using the DefaultFont

Types

type Drawable

type Drawable interface {
	Set(x, y int, c color.Color)
}

Drawable is an interface which supports setting an x,y coordinate to a color.

type PixFont

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

PixFont represents a simple bitmap or pixel-based font that can be drawn using simple opaque-pixel operations (supported by image.Image and easily included in other packages).

func NewPixFont

func NewPixFont(w, h uint8, cm map[rune]uint16, d []uint32) *PixFont

NewPixFont creates a new PixFont with the provided character width/height and character map of offsets into a packed uint32 array of bits.

func (*PixFont) DrawRune

func (p *PixFont) DrawRune(dr Drawable, x, y int, c rune, clr color.Color) (bool, int)

DrawRune uses this PixFont to display a single rune in the provided color and position in Drawable. The x,y position represents the top-left corner of the rune. Drawable.Set is called for each opaque pixel in the font, leaving all other pixels in the Drawable as-is. If the rune has no representation in the PixFont, then DrawRune returns false and no drawing is done. DrawRune always returns the number of pixels to advance before drawing another character.

func (*PixFont) DrawString

func (p *PixFont) DrawString(dr Drawable, x, y int, s string, clr color.Color) int

DrawString uses this PixFont to display text in the provided color and the specified start position in Drawable. The x,y position represents the top-left corner of the first letter of s. Text is drawn by repeated calls to DrawRune for each character. DrawString returns the total pixel advance used by the string.

func (*PixFont) GetHeight

func (p *PixFont) GetHeight() int

GetHeight returns the height of the font in pixels.

func (*PixFont) MeasureRune

func (p *PixFont) MeasureRune(c rune) (bool, int)

MeasureRune measures the advance of a rune drawn using this PixFont.

func (*PixFont) MeasureString

func (p *PixFont) MeasureString(s string) int

MeasureString measures the pixel advance of a string drawn using this PixFont.

func (*PixFont) SetVariableWidth

func (p *PixFont) SetVariableWidth(isVar bool)

SetVariableWidth toggles the PixFont between drawing using variable width per character or the default fixed-width representation.

type StringDrawable

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

StringDrawable implements Drawable so you can do FIGlet-inspired pixel fonts in text. Obviously it's much simpler though.

func (*StringDrawable) PrefixString

func (s *StringDrawable) PrefixString(p string) string

PrefixString returns the current string representation of this Drawable with a user-provided prefix before each line. Useful for adding output in code comments.

func (*StringDrawable) Set

func (s *StringDrawable) Set(x, y int, c color.Color)

func (*StringDrawable) String

func (s *StringDrawable) String() string

String returns the current string representation of this Drawable.