ebiten/text/text.go

502 lines
15 KiB
Go
Raw Normal View History

2017-07-15 20:25:57 +02:00
// Copyright 2017 The Ebiten Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
2023-02-07 04:05:43 +01:00
// Package text offers functions to draw texts on an Ebitengine's image.
2017-07-16 23:39:06 +02:00
//
2017-10-07 20:14:33 +02:00
// For the example using a TTF font, see font package in the examples.
2017-07-15 20:25:57 +02:00
package text
import (
"image"
"image/color"
"sync"
2017-07-15 20:25:57 +02:00
"golang.org/x/image/font"
"golang.org/x/image/math/fixed"
2020-10-03 19:35:13 +02:00
"github.com/hajimehoshi/ebiten/v2"
2020-11-03 09:12:49 +01:00
"github.com/hajimehoshi/ebiten/v2/internal/hooks"
2017-07-15 20:25:57 +02:00
)
var (
monotonicClock int64
)
func now() int64 {
return monotonicClock
}
2020-11-03 09:12:49 +01:00
func init() {
hooks.AppendHookOnBeforeUpdate(func() error {
monotonicClock++
return nil
})
}
func fixed26_6ToFloat64(x fixed.Int26_6) float64 {
2020-05-13 16:31:17 +02:00
return float64(x>>6) + float64(x&((1<<6)-1))/float64(1<<6)
}
func adjustOffsetGranularity(x fixed.Int26_6) fixed.Int26_6 {
return x / (1 << 4) * (1 << 4)
}
func drawGlyph(dst *ebiten.Image, img *ebiten.Image, topleft fixed.Point26_6, op *ebiten.DrawImageOptions) {
if img == nil {
return
}
2021-07-27 10:01:36 +02:00
op2 := &ebiten.DrawImageOptions{}
if op != nil {
*op2 = *op
2021-11-11 16:17:51 +01:00
op2.GeoM.Reset()
2021-07-27 10:01:36 +02:00
}
2022-11-23 14:16:41 +01:00
op2.GeoM.Translate(fixed26_6ToFloat64(topleft.X), fixed26_6ToFloat64(topleft.Y))
if op != nil {
op2.GeoM.Concat(op.GeoM)
}
2022-11-23 14:16:41 +01:00
2021-07-27 10:01:36 +02:00
dst.DrawImage(img, op2)
2017-07-15 20:25:57 +02:00
}
var (
glyphBoundsCache = map[font.Face]map[rune]fixed.Rectangle26_6{}
)
func getGlyphBounds(face font.Face, r rune) fixed.Rectangle26_6 {
if _, ok := glyphBoundsCache[face]; !ok {
glyphBoundsCache[face] = map[rune]fixed.Rectangle26_6{}
}
if b, ok := glyphBoundsCache[face][r]; ok {
return b
2017-07-15 20:25:57 +02:00
}
b, _, _ := face.GlyphBounds(r)
glyphBoundsCache[face][r] = b
return b
2017-07-15 20:25:57 +02:00
}
type glyphImageCacheKey struct {
rune rune
xoffset fixed.Int26_6
}
type glyphImageCacheEntry struct {
image *ebiten.Image
atime int64
}
2017-07-15 20:25:57 +02:00
var (
glyphImageCache = map[font.Face]map[glyphImageCacheKey]*glyphImageCacheEntry{}
)
2017-07-15 20:25:57 +02:00
func getGlyphImage(face font.Face, r rune, offset fixed.Point26_6) *ebiten.Image {
if _, ok := glyphImageCache[face]; !ok {
glyphImageCache[face] = map[glyphImageCacheKey]*glyphImageCacheEntry{}
}
2017-07-15 20:25:57 +02:00
key := glyphImageCacheKey{
rune: r,
xoffset: offset.X,
}
if e, ok := glyphImageCache[face][key]; ok {
e.atime = now()
return e.image
}
2017-07-15 20:25:57 +02:00
b := getGlyphBounds(face, r)
w, h := (b.Max.X - b.Min.X).Ceil(), (b.Max.Y - b.Min.Y).Ceil()
if w == 0 || h == 0 {
glyphImageCache[face][key] = &glyphImageCacheEntry{
image: nil,
atime: now(),
}
return nil
2017-07-15 20:25:57 +02:00
}
if b.Min.X&((1<<6)-1) != 0 {
w++
}
if b.Min.Y&((1<<6)-1) != 0 {
h++
}
rgba := image.NewRGBA(image.Rect(0, 0, w, h))
d := font.Drawer{
Dst: rgba,
Src: image.White,
Face: face,
}
2022-11-23 14:16:41 +01:00
x, y := -b.Min.X, -b.Min.Y
x += offset.X
y += offset.Y
d.Dot = fixed.Point26_6{X: x, Y: y}
d.DrawString(string(r))
img := ebiten.NewImageFromImage(rgba)
glyphImageCache[face][key] = &glyphImageCacheEntry{
2022-11-23 14:16:41 +01:00
image: img,
atime: now(),
2018-02-12 14:02:05 +01:00
}
return img
2018-02-12 14:02:05 +01:00
}
2017-07-15 20:25:57 +02:00
var textM sync.Mutex
2017-07-17 09:17:01 +02:00
// Draw draws a given text on a given destination image dst.
2017-07-15 20:25:57 +02:00
//
// face is the font for text rendering.
2017-10-01 13:48:28 +02:00
// (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).
2022-08-21 13:02:09 +02:00
// Be careful that this doesn't represent upper-left corner position.
//
2017-07-15 20:25:57 +02:00
// clr is the color for text rendering.
//
// If you want to adjust the position of the text, these functions are useful:
//
2022-08-03 13:48:02 +02:00
// - 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.
//
2017-07-16 19:15:00 +02:00
// Glyphs used for rendering are cached in least-recently-used way.
2021-04-26 19:28:52 +02:00
// 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.
2021-04-26 18:58:28 +02:00
// The cache is shared with CacheGlyphs.
//
2021-04-26 19:28:52 +02:00
// It is OK to call Draw with a same text and a same face at every frame in terms of performance.
//
2021-07-27 10:01:36 +02:00
// Draw/DrawWithOptions and CacheGlyphs are implemented like this:
2021-04-26 18:58:28 +02:00
//
// Draw = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
2022-08-03 13:48:02 +02:00
// + Draw them onto the destination by `(*ebiten.Image).DrawImage`
// CacheGlyphs = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
2017-07-16 19:13:30 +02:00
//
// 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.
2017-07-19 19:20:15 +02:00
func Draw(dst *ebiten.Image, text string, face font.Face, x, y int, clr color.Color) {
2021-07-27 10:01:36 +02:00
op := &ebiten.DrawImageOptions{}
op.GeoM.Translate(float64(x), float64(y))
op.ColorScale.ScaleWithColor(clr)
2021-07-27 10:01:36 +02:00
DrawWithOptions(dst, text, face, op)
}
// 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.
2022-08-21 13:02:09 +02:00
// Be careful that the origin point is not upper-left corner position of dst.
2022-09-14 06:56:59 +02:00
// The default glyph color is white. op's ColorM adjusts the color.
2021-07-27 10:01:36 +02:00
//
// If you want to adjust the position of the text, these functions are useful:
//
2022-08-03 13:48:02 +02:00
// - text.BoundString: the rendered bounds of the given text.
// - golang.org/x/image/font.Face.Metrics: the metrics of the face.
2021-07-27 10:01:36 +02:00
//
// 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.
//
2021-07-27 10:38:34 +02:00
// It is OK to call DrawWithOptions with a same text and a same face at every frame in terms of performance.
2021-07-27 10:01:36 +02:00
//
// Draw/DrawWithOptions and CacheGlyphs are implemented like this:
//
// Draw = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
2022-08-03 13:48:02 +02:00
// + Draw them onto the destination by `(*ebiten.Image).DrawImage`
// CacheGlyphs = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
2021-07-27 10:01:36 +02:00
//
// 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 DrawWithOptions(dst *ebiten.Image, text string, face font.Face, options *ebiten.DrawImageOptions) {
textM.Lock()
defer textM.Unlock()
2021-07-27 10:01:36 +02:00
var dx, dy fixed.Int26_6
prevR := rune(-1)
2017-07-15 20:25:57 +02:00
faceHeight := face.Metrics().Height
for _, r := range text {
if prevR >= 0 {
2021-07-27 10:01:36 +02:00
dx += face.Kern(prevR, r)
2017-07-15 20:25:57 +02:00
}
if r == '\n' {
2021-07-27 10:01:36 +02:00
dx = 0
dy += faceHeight
prevR = rune(-1)
continue
}
// Adjust the position to the integers.
// The current glyph images assume that they are rendered on integer positions so far.
b := getGlyphBounds(face, r)
offset := fixed.Point26_6{
X: (adjustOffsetGranularity(dx) + b.Min.X) & ((1 << 6) - 1),
Y: b.Min.Y & ((1 << 6) - 1),
}
img := getGlyphImage(face, r, offset)
drawGlyph(dst, img, fixed.Point26_6{
X: dx + b.Min.X - offset.X,
Y: dy + b.Min.Y - offset.Y,
}, options)
2021-07-27 10:01:36 +02:00
dx += glyphAdvance(face, r)
prevR = r
2017-07-15 20:25:57 +02:00
}
2020-11-03 09:12:49 +01:00
// cacheSoftLimit indicates the soft limit of the number of glyphs in the cache.
// If the number of glyphs exceeds this soft limits, old glyphs are removed.
// Even after cleaning up the cache, the number of glyphs might still exceed the soft limit, but
2020-11-03 09:12:49 +01:00
// this is fine.
const cacheSoftLimit = 512
2020-11-03 08:36:10 +01:00
// Clean up the cache.
2020-11-03 09:12:49 +01:00
if len(glyphImageCache[face]) > cacheSoftLimit {
for r, e := range glyphImageCache[face] {
2020-11-03 09:12:49 +01:00
// 60 is an arbitrary number.
if e.atime < now()-60 {
delete(glyphImageCache[face], r)
}
}
}
}
// 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.
2020-07-29 17:54:57 +02:00
// 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).
//
2022-04-03 19:55:09 +02:00
// 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.
2020-07-29 17:54:57 +02:00
// 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 BoundString(face font.Face, text string) image.Rectangle {
textM.Lock()
defer textM.Unlock()
m := face.Metrics()
faceHeight := m.Height
fx, fy := fixed.I(0), fixed.I(0)
prevR := rune(-1)
var bounds fixed.Rectangle26_6
for _, r := range text {
if prevR >= 0 {
fx += face.Kern(prevR, r)
}
if r == '\n' {
fx = fixed.I(0)
fy += faceHeight
prevR = rune(-1)
continue
}
b := getGlyphBounds(face, r)
b.Min.X += fx
b.Max.X += fx
b.Min.Y += fy
b.Max.Y += fy
bounds = bounds.Union(b)
fx += glyphAdvance(face, r)
prevR = r
}
return image.Rect(
2022-08-12 17:28:30 +02:00
bounds.Min.X.Floor(),
bounds.Min.Y.Floor(),
bounds.Max.X.Ceil(),
bounds.Max.Y.Ceil(),
)
2017-07-15 20:25:57 +02:00
}
2020-11-03 09:12:49 +01:00
// CacheGlyphs precaches the glyphs for the given text and the given font face into the cache.
2021-04-26 19:28:52 +02:00
//
// 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.
2021-04-26 18:58:28 +02:00
// The cache is shared with Draw.
2020-11-03 09:12:49 +01:00
//
2021-07-27 10:01:36 +02:00
// Draw/DrawWithOptions and CacheGlyphs are implemented like this:
2021-04-26 19:28:52 +02:00
//
// Draw = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
2022-08-03 13:48:02 +02:00
// + Draw them onto the destination by `(*ebiten.Image).DrawImage`
// CacheGlyphs = Create glyphs by `(*ebiten.Image).WritePixels` and put them into the cache if necessary
2021-04-26 19:28:52 +02:00
//
2020-11-03 09:12:49 +01:00
// 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
2020-11-03 11:54:51 +01:00
// 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
2021-04-26 19:20:10 +02:00
// 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.
2021-04-26 18:58:28 +02:00
//
2020-11-03 12:35:55 +01:00
// 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.
2020-11-03 09:12:49 +01:00
func CacheGlyphs(face font.Face, text string) {
textM.Lock()
defer textM.Unlock()
var dx fixed.Int26_6
prevR := rune(-1)
for _, r := range text {
if prevR >= 0 {
dx += face.Kern(prevR, r)
}
if r == '\n' {
dx = 0
continue
}
b := getGlyphBounds(face, r)
// Cache all 4 variations for one rune (#2528).
for i := 0; i < 4; i++ {
offset := fixed.Point26_6{
X: (fixed.Int26_6(i*(1<<4)) + b.Min.X) & ((1 << 6) - 1),
Y: b.Min.Y & ((1 << 6) - 1),
}
getGlyphImage(face, r, offset)
}
dx += glyphAdvance(face, r)
prevR = r
}
2020-11-03 09:12:49 +01:00
}
// FaceWithLineHeight returns a font.Face with the given lineHeight in pixels.
// The returned face will otherwise have the same glyphs and metrics as face.
func FaceWithLineHeight(face font.Face, lineHeight float64) font.Face {
return faceWithLineHeight{
face: face,
lineHeight: fixed.Int26_6(lineHeight * (1 << 6)),
}
}
type faceWithLineHeight struct {
face font.Face
lineHeight fixed.Int26_6
}
func (f faceWithLineHeight) Close() error {
return f.face.Close()
}
func (f faceWithLineHeight) Glyph(dot fixed.Point26_6, r rune) (dr image.Rectangle, mask image.Image, maskp image.Point, advance fixed.Int26_6, ok bool) {
return f.face.Glyph(dot, r)
}
func (f faceWithLineHeight) GlyphBounds(r rune) (bounds fixed.Rectangle26_6, advance fixed.Int26_6, ok bool) {
return f.face.GlyphBounds(r)
}
func (f faceWithLineHeight) GlyphAdvance(r rune) (advance fixed.Int26_6, ok bool) {
return f.face.GlyphAdvance(r)
}
func (f faceWithLineHeight) Kern(r0, r1 rune) fixed.Int26_6 {
return f.face.Kern(r0, r1)
}
func (f faceWithLineHeight) Metrics() font.Metrics {
m := f.face.Metrics()
m.Height = f.lineHeight
return m
}
// Glyph is information to render one 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.
2022-04-02 12:00:11 +02:00
// 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 dot ('.') 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 dot ('.') position.
Y float64
}
// AppendGlyphs appends the glyph information to glyphs.
// You can render each glyphs as you like. See examples/text for an example of AppendGlyphs.
func AppendGlyphs(glyphs []Glyph, face font.Face, text string) []Glyph {
textM.Lock()
defer textM.Unlock()
var pos fixed.Point26_6
prevR := rune(-1)
faceHeight := face.Metrics().Height
for _, r := range text {
if prevR >= 0 {
pos.X += face.Kern(prevR, r)
}
if r == '\n' {
pos.X = 0
pos.Y += faceHeight
prevR = rune(-1)
continue
}
b := getGlyphBounds(face, r)
offset := fixed.Point26_6{
X: (adjustOffsetGranularity(pos.X) + b.Min.X) & ((1 << 6) - 1),
Y: b.Min.Y & ((1 << 6) - 1),
}
if img := getGlyphImage(face, r, offset); img != nil {
2022-11-23 14:16:41 +01:00
// Adjust the position to the integers.
// The current glyph images assume that they are rendered on integer positions so far.
glyphs = append(glyphs, Glyph{
Rune: r,
Image: img,
X: fixed26_6ToFloat64(pos.X + b.Min.X - offset.X),
Y: fixed26_6ToFloat64(pos.Y + b.Min.Y - offset.Y),
})
}
pos.X += glyphAdvance(face, r)
prevR = r
}
return glyphs
}