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)
- func DrawWithOptions(dst *ebiten.Image, text string, face font.Face, ...)
- func FaceWithLineHeight(face font.Face, lineHeight float64) font.Face
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BoundString ¶
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 ¶ added in v2.1.0
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).ReplacePixels` and put them into the cache if necessary
+ Draw them onto the destination by `(*ebiten.Image).DrawImage`
CacheGlyphs = Create glyphs by `(*ebiten.Image).ReplacePixels` 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).ReplacePixels` 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.
func Draw ¶
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. 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).ReplacePixels` and put them into the cache if necessary
+ Draw them onto the destination by `(*ebiten.Image).DrawImage`
CacheGlyphs = Create glyphs by `(*ebiten.Image).ReplacePixels` 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 ¶ added in v2.2.0
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. op is the options to draw glyph images. The origin point is a 'dot' (period) position. Be careful that the origin point is not left-upper corner position of dst. The default glyph color is while. op's ColorM adjusts the color.
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. 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).ReplacePixels` and put them into the cache if necessary
+ Draw them onto the destination by `(*ebiten.Image).DrawImage`
CacheGlyphs = Create glyphs by `(*ebiten.Image).ReplacePixels` 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.
Types ¶
This section is empty.
Source Files