bmfont

README

bmfont

A Go package to load and render bitmap fonts created with AngelCode's bitmap font generator or other tools that generate output in the same format.

This package uses the text format for font descriptor files (.fnt), not the binary format.

Documentation

Package documentation is available on pkg.go.dev.

Example usage

Load a bitmap font and draw text to an image:

package main

import (
	"log"

	"github.com/fzipp/bmfont"
)

func main() {
	font, err := bmfont.Load("ExampleFont.fnt")
	if err != nil {
		log.Fatal(err)
	}
	img := image.NewRGBA(image.Rect(0, 0, 600, 300))
	font.DrawText(img, image.Pt(10, 20), `hello, world
This is an example.
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ`)
	// ...
}

Measure the text before drawing in order to determine the size of the image:

package main

import (
	"log"

	"github.com/fzipp/bmfont"
)

func main() {
	font, err := bmfont.Load("ExampleFont.fnt")
	if err != nil {
		log.Fatal(err)
	}

    text := `hello, world
This is an example.
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ`

	bounds := font.MeasureText(text)
	img := image.NewRGBA(image.Rect(0, 0, bounds.Dx(), bounds.Dy()))
	font.DrawText(img, image.Point{}.Sub(bounds.Min), text)
	// ...
}

Only load the descriptor of a bitmap font:

package main

import (
	"fmt"
	"log"

	"github.com/fzipp/bmfont"
)

func main() {
	desc, err := bmfont.LoadDescriptor("ExampleFont.fnt")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(desc.Info.Face)
	fmt.Println("line height:", desc.Common.LineHeight)
	fmt.Println("letter A width:", desc.Chars['A'].Width)
}

License

This project is free and open source software licensed under the BSD 3-Clause License.

Documentation

Overview

Package bmfont reads bitmap fonts created with AngelCode's bitmap font generator or other tools that generate output in the same format, and draws texts with these fonts on images.

The parser for the font descriptor files (.fnt) reads the text format, not the binary format. Format description: http://www.angelcode.com/products/bmfont/doc/file_format.html

Index

• type BitmapFont
  • func Load(path string) (f *BitmapFont, err error)
  • func Read(r io.Reader, sheets SheetReaderFunc) (f *BitmapFont, err error)
  • func (f *BitmapFont) DrawText(dst draw.Image, pos image.Point, text string)
  • func (f *BitmapFont) MeasureText(text string) image.Rectangle
• type Channel
• type ChannelInfo
• type Char
  • func (c *Char) Bounds() image.Rectangle
  • func (c *Char) Offset() image.Point
  • func (c *Char) Pos() image.Point
  • func (c *Char) Size() image.Point
• type CharPair
• type Common
  • func (c *Common) Scale() image.Point
• type Descriptor
  • func LoadDescriptor(path string) (d *Descriptor, err error)
  • func ReadDescriptor(r io.Reader) (d *Descriptor, err error)
• type Info
• type Kerning
• type Padding
• type Page
• type SheetReaderFunc
• type Spacing

Types

type BitmapFont

type BitmapFont struct {
	// Descriptor holds the metadata for the font, such as positions and bounds
	// of the characters in the sheet images.
	Descriptor *Descriptor
	// PageSheets contains the loaded sheet images for the pages. The keys
	// correspond to the keys of the pages map in the descriptor.
	PageSheets map[int]image.Image
}

A BitmapFont is a bitmap font based on one or more sheet images for the characters and a font descriptor.

func Load

func Load(path string) (f *BitmapFont, err error)

Load loads a bitmap font from a BMFont descriptor file (.fnt) in text format including all the referenced page sheet images. The resulting bitmap font is ready to be used to draw text on an image.

func Read

func Read(r io.Reader, sheets SheetReaderFunc) (f *BitmapFont, err error)

Read reads a bitmap font from a BMFont descriptor in text format including all the referenced page sheet images. The page sheet images are read from the readers provided by the given SheetReaderFunc. These sheet readers are closed after use. If you want to keep them open wrap them via io.NopCloser. The resulting bitmap font is ready to be used to draw text on an image.

func (*BitmapFont) DrawText

func (f *BitmapFont) DrawText(dst draw.Image, pos image.Point, text string)

DrawText draws the given text on the destination image starting at the given position. The start position is on the base line of the first line of text, and the characters usually extend above the base line. The text may contain newlines. Text with multiple lines is drawn left aligned.

func (*BitmapFont) MeasureText

func (f *BitmapFont) MeasureText(text string) image.Rectangle

MeasureText calculates the bounding box for the given text as if it was drawn at position (0, 0). The Min point usually has a negative Y coordinate, since the start position of DrawText is on the base line and the characters extend above the base line. The X coordinate can also be negative, depending on the character offsets.

type Channel

type Channel int

const (
	Blue  Channel = 1
	Green Channel = 2
	Red   Channel = 4
	Alpha Channel = 8
	All   Channel = 15
)

type ChannelInfo

type ChannelInfo int

const (
	Glyph ChannelInfo = iota
	Outline
	GlyphAndOutline
	Zero
	One
)

type Char

type Char struct {
	ID       rune
	X        int
	Y        int
	Width    int
	Height   int
	XOffset  int
	YOffset  int
	XAdvance int
	Page     int
	Channel  Channel
}

func (*Char) Bounds

func (c *Char) Bounds() image.Rectangle

func (*Char) Offset

func (c *Char) Offset() image.Point

func (*Char) Pos

func (c *Char) Pos() image.Point

func (*Char) Size

func (c *Char) Size() image.Point

type CharPair

type CharPair struct {
	First, Second rune
}

CharPair is a pair of characters. It is used as the key in the font's kerning map.

type Common

type Common struct {
	LineHeight   int
	Base         int
	ScaleW       int
	ScaleH       int
	Packed       bool
	AlphaChannel ChannelInfo
	RedChannel   ChannelInfo
	GreenChannel ChannelInfo
	BlueChannel  ChannelInfo
}

func (*Common) Scale

func (c *Common) Scale() image.Point

type Descriptor

type Descriptor struct {
	Info    Info
	Common  Common
	Pages   map[int]Page
	Chars   map[rune]Char
	Kerning map[CharPair]Kerning
}

A Descriptor holds metadata for a bitmap font.

func LoadDescriptor

func LoadDescriptor(path string) (d *Descriptor, err error)

LoadDescriptor loads the font descriptor data from a BMFont descriptor file in text format (usually with the file extension .fnt). It does not load the referenced page sheet images. If you also want to load the page sheet images, use the Load function to get a complete BitmapFont instance.

func ReadDescriptor

func ReadDescriptor(r io.Reader) (d *Descriptor, err error)

ReadDescriptor parses font descriptor data in BMFont's text format from a reader. It does not load the referenced page sheet images. If you also want to load the page sheet images, use the Load function to get a complete BitmapFont instance.

type Info

type Info struct {
	Face     string
	Size     int
	Bold     bool
	Italic   bool
	Charset  string
	Unicode  bool
	StretchH int
	Smooth   bool
	AA       int
	Padding  Padding
	Spacing  Spacing
	Outline  int
}

type Kerning

type Kerning struct {
	Amount int
}

Kerning is a horizontal offset in pixels to be used if a specific character pair occurs when drawing text. It is used for the values in the font's kerning map.

type Padding

type Padding struct {
	Up, Right, Down, Left int
}

type Page

type Page struct {
	ID   int
	File string
}

type SheetReaderFunc

type SheetReaderFunc func(filename string) (io.ReadCloser, error)

A SheetReaderFunc is a function that provides a reader for a page sheet image file name. It is used by the Read function to load a font from a different source than only the file system. The filename parameter is the name provided by the File field of a Page in the font descriptor.

type Spacing

type Spacing struct {
	Horizontal, Vertical int
}