text

Documentation

Overview

Package text offers functions to draw texts on an Ebiten's image.

For the example using a TTF font, see font package in the examples.

Index

• func BoundString(face font.Face, text string) image.Rectangle
• func CacheGlyphs(face font.Face, text string)
• func Draw(dst *ebiten.Image, text string, face font.Face, x, y int, clr color.Color)

Functions

func BoundString

func BoundString(face font.Face, text string) image.Rectangle

BoundString returns the measured size of a given string using a given font. This method will return the exact size in pixels that a string drawn by Draw will be. The bound's origin point indicates the dot (period) position. This means that if the text consists of one character '.', this dot is rendered at (0, 0).

This is very similar to golang.org/x/image/font's BoundString, but this BoundString calculates the actual rendered area considering multiple lines and space characters.

face is the font for text rendering. text is the string that's being measured.

Be careful that the passed font face is held by this package and is never released. This is a known issue (#498).

BoundString is concurrent-safe.

func CacheGlyphs

func CacheGlyphs(face font.Face, text string)

CacheGlyphs precaches the glyphs for the given text and the given font face into the cache.

Draw automatically creates and caches necessary glyphs, so usually you don't have to call CacheGlyphs explicitly. However, for example, when you call Draw for each rune of one big text, Draw tries to create the glyph cache and render it for each rune. This is very inefficient because creating a glyph image and rendering it are different operations and can never be merged as one draw call. CacheGlyphs creates necessary glyphs without rendering them so that these operations are likely merged into one draw call.

If a rune's glyph is already cached, CacheGlyphs does nothing for the rune.

func Draw

func Draw(dst *ebiten.Image, text string, face font.Face, x, y int, clr color.Color)

Draw draws a given text on a given destination image dst.

face is the font for text rendering. (x, y) represents a 'dot' (period) position. This means that if the given text consisted of a single character ".", it would be positioned at the given position (x, y). Be careful that this doesn't represent left-upper corner position.

clr is the color for text rendering.

If you want to adjust the position of the text, these functions are useful:

• text.BoundString: the rendered bounds of the given text.
• golang.org/x/image/font.Face.Metrics: the metrics of the face.

The '\n' newline character puts the following text on the next line. Line height is based on Metrics().Height of the font.

Glyphs used for rendering are cached in least-recently-used way. It is OK to call Draw with a same text and a same face at every frame in terms of performance.

Be careful that the passed font face is held by this package and is never released. This is a known issue (#498).

Draw is concurrent-safe.