gltext

README

gltext

Note: This package is experimental and subject to change. Use at your own discretion.

The gltext package offers a simple set of text rendering utilities for OpenGL programs. It deals with TrueType and Bitmap (raster) fonts. Text can be rendered in various directions (Left-to-right, right-to-left and top-to-bottom). This allows for correct display of text for various languages.

The package supports the full set of unicode characters, provided the loaded font does as well.

TODO

• Have a look at Valve's 'Signed Distance Field` techniques to render sharp font textures are different zoom levels.

  • SIGGRAPH2007_AlphaTestedMagnification.pdf
  • Youtube video

  More links to info in the youtube video description. An alternative might be a port of GLyphy

Known bugs

• Determining the height of truetype glyphs is not entirely accurate. It is unclear at this point how to get to this information reliably. Specifically the parts in LoadTruetype at truetype.go#L54+. The vertical glyph bounds computed by freetype-go are not correct for certain fonts. Right now we manually offset the value by added 4 to the height. This is an unreliable hack and should be fixed.
• freetype-go does not expose AdvanceHeight for vertically rendered fonts. This may mean that the Advance size for top-to-bottom fonts is incorrect.

Dependencies

go get code.google.com/p/freetype-go

Usage

go get github.com/go-gl/gltext

Refer to go-gl/examples/gltext for usage examples.

License

Copyright 2012 The go-gl Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Documentation

Overview

The gltext package offers a set of text rendering utilities for OpenGL programs. It deals with TrueType and Bitmap (raster) fonts.

Text can be rendered in predefined directions (Left-to-right, right-to-left and top-to-bottom). This allows for correct display of text for various languages.

This package supports the full set of unicode characters, provided the loaded font does as well.

Index

• type Charset
  • func (c Charset) Scale(factor int)
• type Direction
• type Font
  • func LoadBitmap(img, config io.Reader, scale int) (*Font, error)
  • func LoadTruetype(r io.Reader, scale int32, low, high rune, dir Direction) (*Font, error)
  • func (f *Font) Dir() Direction
  • func (f *Font) GlyphBounds() (int, int)
  • func (f *Font) Glyphs() Charset
  • func (f *Font) High() rune
  • func (f *Font) Low() rune
  • func (f *Font) Metrics(text string) (int, int)
  • func (f *Font) Printf(x, y float32, fs string, argv ...interface{}) error
  • func (f *Font) Release()
• type FontConfig
  • func (fc *FontConfig) Load(r io.Reader) (err error)
  • func (fc *FontConfig) Save(w io.Writer) (err error)
• type Glyph

Types

type Charset

type Charset []Glyph

A Charset represents a set of glyph descriptors for a font. Each glyph descriptor holds glyph metrics which are used to properly align the given glyph in the resulting rendered string.

func (Charset) Scale

func (c Charset) Scale(factor int)

Scale scales all glyphs by the given factor and repositions them appropriately. A scale of 1 retains the original size. A scale of 2 doubles the size of each glyph, etc.

This is useful when the accompanying sprite sheet is scaled by the same factor. In this case, we want the glyph data to match up with the new image.

type Direction

type Direction uint8

Direction represents the direction in which strings should be rendered.

const (
	LeftToRight Direction = iota // E.g.: Latin
	RightToLeft                  // E.g.: Arabic
	TopToBottom                  // E.g.: Chinese
)

Known directions.

type Font

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

A Font allows rendering of text to an OpenGL context.

func LoadBitmap

func LoadBitmap(img, config io.Reader, scale int) (*Font, error)

LoadBitmap loads a bitmap (raster) font from the given sprite sheet and config files. It is optionally scaled by the given scale factor.

A scale factor of 1 retains the original size. A factor of 2 doubles the font size, etc. A scale factor of 0 is not valid and will default to 1.

Supported image formats are 32-bit RGBA as PNG, JPEG and GIF.

func LoadTruetype

func LoadTruetype(r io.Reader, scale int32, low, high rune, dir Direction) (*Font, error)

LoadTruetype loads a truetype font from the given stream and applies the given font scale in points.

The low and high values determine the lower and upper rune limits we should load for this font. For standard ASCII this would be: 32, 127.

The dir value determines the orientation of the text we render with this font. This should be any of the predefined Direction constants.

func (*Font) Dir

func (f *Font) Dir() Direction

Dir returns the font's rendering orientation.

func (*Font) GlyphBounds

func (f *Font) GlyphBounds() (int, int)

GlyphBounds returns the largest width and height for any of the glyphs in the font. This constitutes the largest possible bounding box a single glyph will have.

func (*Font) Glyphs

func (f *Font) Glyphs() Charset

Glyphs returns the font's glyph descriptors.

func (*Font) High

func (f *Font) High() rune

High returns the font's upper rune bound.

func (*Font) Low

func (f *Font) Low() rune

Low returns the font's lower rune bound.

func (*Font) Metrics

func (f *Font) Metrics(text string) (int, int)

Metrics returns the pixel width and height for the given string. This takes the scale and rendering direction of the font into account.

Unknown runes will be counted as having the maximum glyph bounds as defined by Font.GlyphBounds().

func (*Font) Printf

func (f *Font) Printf(x, y float32, fs string, argv ...interface{}) error

Printf draws the given string at the specified coordinates. It expects the string to be a single line. Line breaks are not handled as line breaks and are rendered as glyphs.

In order to render multi-line text, it is up to the caller to split the text up into individual lines of adequate length and then call this method for each line seperately.

func (*Font) Release

func (f *Font) Release()

Release releases font resources. A font can no longer be used for rendering after this call completes.

type FontConfig

type FontConfig struct {
	// The direction determines the orientation of rendered strings and should
	// hold any of the pre-defined Direction constants.
	Dir Direction `json:"direction"`

	// Lower rune boundary
	Low rune `json:"rune_low"`

	// Upper rune boundary.
	High rune `json:"rune_high"`

	// Glyphs holds a set of glyph descriptors, defining the location,
	// size and advance of each glyph in the sprite sheet.
	Glyphs Charset `json:"glyphs"`
}

FontConfig describes raster font metadata.

It can be loaded from, or saved to a JSON encoded file, which should come with any bitmap font image.

func (*FontConfig) Load

func (fc *FontConfig) Load(r io.Reader) (err error)

Load reads font configuration data from the given JSON encoded stream.

func (*FontConfig) Save

func (fc *FontConfig) Save(w io.Writer) (err error)

Save writes font configuration data to the given stream as JSON data.

type Glyph

type Glyph struct {
	X      int `json:"x"`      // The x location of the glyph on a sprite sheet.
	Y      int `json:"y"`      // The y location of the glyph on a sprite sheet.
	Width  int `json:"width"`  // The width of the glyph on a sprite sheet.
	Height int `json:"height"` // The height of the glyph on a sprite sheet.

	// Advance determines the distance to the next glyph.
	// This is used to properly align non-monospaced fonts.
	Advance int `json:"advance"`
}

A Glyph describes metrics for a single font glyph. These indicate which area of a given image contains the glyph data and how the glyph should be spaced in a rendered string.