text

Documentation

Overview

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

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

Deprecated: as of v2.7. Use text/v2 instead.

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)
• func DrawWithOptions(dst *ebiten.Image, text string, face font.Face, ...)
• func FaceWithLineHeight(face font.Face, lineHeight float64) font.Face
• type Glyph
  • func AppendGlyphs(glyphs []Glyph, face font.Face, text string) []Glyph

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 origin position in this figure: https://developer.apple.com/library/archive/documentation/TextFonts/Conceptual/CocoaTextArchitecture/Art/glyphterms_2x.png.

BoundString behaves almost exactly like golang.org/x/image/font's BoundString, but newline characters '\n' in the input string move the text position to the following line.

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.

Deprecated: as of v2.6. Use golang.org/x/image/font.BoundString instead, or use a face's Metrics (Ascent and Descent) and font.MeasureString instead.

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.

Glyphs used for rendering are cached in least-recently-used way. Then old glyphs might be evicted from the cache. As the cache capacity has limit, it is not guaranteed that all the glyphs for runes given at CacheGlyphs are cached. The cache is shared with Draw.

Draw/DrawWithOptions and CacheGlyphs are implemented like this:

Draw        = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
            + Draw them onto the destination by `(*ebiten.Image).DrawImage`
CacheGlyphs = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary

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 (`(*ebiten.Image).WritePixels` and `(*ebiten.Image).DrawImage`) 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 regardless of the size of the text.

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

One rune can have multiple variations of glyphs due to sub-pixels in X direction. CacheGlyphs creates all such variations for one rune, while Draw creates only necessary glyphs.

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 the origin position in this figure: https://developer.apple.com/library/archive/documentation/TextFonts/Conceptual/CocoaTextArchitecture/Art/glyphterms_2x.png. Be careful that this doesn't represent upper-left corner position.

clr is the color for text rendering.

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. Then old glyphs might be evicted from the cache. As the cache capacity has limit, it is not guaranteed that all the glyphs for runes given at Draw are cached. The cache is shared with CacheGlyphs.

It is OK to call Draw with a same text and a same face at every frame in terms of performance.

Draw/DrawWithOptions and CacheGlyphs are implemented like this:

Draw        = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
            + Draw them onto the destination by `(*ebiten.Image).DrawImage`
CacheGlyphs = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary

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.

func DrawWithOptions

func DrawWithOptions(dst *ebiten.Image, text string, face font.Face, options *ebiten.DrawImageOptions)

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

face is the font for text rendering. options is the options to draw glyph images. The origin point is the origin position in this figure: https://developer.apple.com/library/archive/documentation/TextFonts/Conceptual/CocoaTextArchitecture/Art/glyphterms_2x.png. Be careful that the origin point is not upper-left corner position of dst. The default glyph color is white. options' ColorScale adjusts the color.

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. Then old glyphs might be evicted from the cache. As the cache capacity has limit, it is not guaranteed that all the glyphs for runes given at DrawWithOptions are cached. The cache is shared with CacheGlyphs.

It is OK to call DrawWithOptions with a same text and a same face at every frame in terms of performance.

Draw/DrawWithOptions and CacheGlyphs are implemented like this:

Draw        = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
            + Draw them onto the destination by `(*ebiten.Image).DrawImage`
CacheGlyphs = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary

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

DrawWithOptions is concurrent-safe.

func FaceWithLineHeight

func FaceWithLineHeight(face font.Face, lineHeight float64) font.Face

FaceWithLineHeight returns a font.Face with the given lineHeight in pixels. The returned face will otherwise have the same glyphs and metrics as face.

Types

type Glyph

type Glyph struct {
	// Rune is a character for this glyph.
	Rune rune

	// Image is an image for this glyph.
	// Image is a grayscale image i.e. RGBA values are the same.
	// Image should be used as a render source and should not be modified.
	Image *ebiten.Image

	// X is the X position to render this glyph.
	// The position is determined in a sequence of characters given at AppendGlyphs.
	// The position's origin is the first character's origin position.
	X float64

	// Y is the Y position to render this glyph.
	// The position is determined in a sequence of characters given at AppendGlyphs.
	// The position's origin is the first character's origin position.
	Y float64
}

Glyph is information to render one glyph.

func AppendGlyphs

func AppendGlyphs(glyphs []Glyph, face font.Face, text string) []Glyph

AppendGlyphs appends the glyph information to glyphs. You can render each glyphs as you like. See examples/text for an example of AppendGlyphs.