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 ES 2.0 programs. It deals with TrueType and Bitmap (raster) fonts (the last one is not yet implemented on this fork).

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

• func IsPow2(x uint32) bool
• func Pow2(x uint32) uint32
• func Pow2Image(src image.Image) image.Image
• type Charset
  • func (c Charset) Scale(factor int)
• type Direction
• type Font
  • func LoadTruetype(r io.Reader, uploader TextureUploader, scale int32, low, high rune, ...) (*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(format string, argv ...interface{}) (*shapes.Group, error)
• type FontConfig
  • func (fc *FontConfig) Load(r io.Reader) (err error)
  • func (fc *FontConfig) Save(w io.Writer) (err error)
• type Glyph
• type Texture
• type TextureUploader

Functions

func IsPow2

func IsPow2(x uint32) bool

IsPow2 returns true if the given value is a power-of-two.

func Pow2

func Pow2(x uint32) uint32

Pow2 returns the first power-of-two value >= to n. This can be used to create suitable texture dimensions.

func Pow2Image

func Pow2Image(src image.Image) image.Image

Pow2Image returns the given image, scaled to the smallest power-of-two dimensions larger or equal to the input dimensions. It preserves the image format and contents.

This is useful if an image is to be used as an OpenGL texture. These often require image data to have power-of-two dimensions.

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 LoadTruetype

func LoadTruetype(r io.Reader, uploader TextureUploader, 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(format string, argv ...interface{}) (*shapes.Group, error)

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"`
	// contains filtered or unexported fields
}

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.

type Texture

type Texture interface {
	Bounds() image.Rectangle
	Id() uint32
}

type TextureUploader

type TextureUploader interface {
	UploadRGBAImage(img *image.RGBA) Texture
}