ebiten/text/text.go

302 lines
8.2 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.
// Package text offers functions to draw texts on an Ebiten'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"
"math"
"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"
"github.com/hajimehoshi/ebiten/v2/internal/colormcache"
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 drawGlyph(dst *ebiten.Image, face font.Face, r rune, img *ebiten.Image, x, y fixed.Int26_6, clr ebiten.ColorM) {
if img == nil {
return
}
b := getGlyphBounds(face, r)
2017-07-15 20:25:57 +02:00
op := &ebiten.DrawImageOptions{}
op.GeoM.Translate(float64((x+b.Min.X)>>6), float64((y+b.Min.Y)>>6))
2018-04-23 15:42:38 +02:00
op.ColorM = clr
dst.DrawImage(img, op)
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 glyphImageCacheEntry struct {
image *ebiten.Image
atime int64
}
2017-07-15 20:25:57 +02:00
var (
glyphImageCache = map[font.Face]map[rune]*glyphImageCacheEntry{}
emptyGlyphs = map[font.Face]map[rune]struct{}{}
)
2017-07-15 20:25:57 +02:00
2020-11-03 08:36:10 +01:00
func getGlyphImages(face font.Face, runes []rune) []*ebiten.Image {
if _, ok := emptyGlyphs[face]; !ok {
emptyGlyphs[face] = map[rune]struct{}{}
}
if _, ok := glyphImageCache[face]; !ok {
glyphImageCache[face] = map[rune]*glyphImageCacheEntry{}
}
2017-07-15 20:25:57 +02:00
imgs := make([]*ebiten.Image, len(runes))
glyphBounds := map[rune]fixed.Rectangle26_6{}
2018-04-28 15:50:00 +02:00
neededGlyphIndices := map[int]rune{}
for i, r := range runes {
if _, ok := emptyGlyphs[face][r]; ok {
continue
}
2017-07-15 20:25:57 +02:00
if e, ok := glyphImageCache[face][r]; ok {
e.atime = now()
imgs[i] = e.image
continue
}
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 {
emptyGlyphs[face][r] = struct{}{}
continue
}
2017-07-15 20:25:57 +02:00
2018-04-28 15:50:00 +02:00
glyphBounds[r] = b
neededGlyphIndices[i] = r
2017-07-15 20:25:57 +02:00
}
for i, r := range neededGlyphIndices {
b := glyphBounds[r]
w, h := (b.Max.X - b.Min.X).Ceil(), (b.Max.Y - b.Min.Y).Ceil()
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,
}
x, y := -b.Min.X, -b.Min.Y
x, y = fixed.I(x.Ceil()), fixed.I(y.Ceil())
d.Dot = fixed.Point26_6{X: x, Y: y}
d.DrawString(string(r))
img := ebiten.NewImageFromImage(rgba)
if _, ok := glyphImageCache[face][r]; !ok {
glyphImageCache[face][r] = &glyphImageCacheEntry{
image: img,
atime: now(),
2018-04-25 19:11:45 +02:00
}
}
imgs[i] = img
2018-02-12 14:02:05 +01:00
}
return imgs
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).
2017-10-01 13:48:28 +02:00
// Be careful that this doesn't represent left-upper 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:
//
// * 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.
// It is OK to call Draw with a same text and a same face at every frame in terms of performance.
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) {
2017-07-15 20:25:57 +02:00
textM.Lock()
defer textM.Unlock()
2017-07-15 20:25:57 +02:00
fx, fy := fixed.I(x), fixed.I(y)
prevR := rune(-1)
2017-07-15 20:25:57 +02:00
faceHeight := face.Metrics().Height
2017-07-15 20:25:57 +02:00
runes := []rune(text)
2020-11-03 08:36:10 +01:00
glyphImgs := getGlyphImages(face, runes)
colorm := colormcache.ColorToColorM(clr)
2018-04-23 15:42:38 +02:00
for i, r := range runes {
if prevR >= 0 {
fx += face.Kern(prevR, r)
2017-07-15 20:25:57 +02:00
}
if r == '\n' {
fx = fixed.I(x)
fy += faceHeight
prevR = rune(-1)
continue
}
drawGlyph(dst, face, r, glyphImgs[i], fx, fy, colorm)
fx += 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 clearning up the cache, the number of glyphs might still exceeds the soft limit, but
// 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).
//
// 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.
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 []rune(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(
int(math.Floor(fixed26_6ToFloat64(bounds.Min.X))),
int(math.Floor(fixed26_6ToFloat64(bounds.Min.Y))),
int(math.Ceil(fixed26_6ToFloat64(bounds.Max.X))),
int(math.Ceil(fixed26_6ToFloat64(bounds.Max.Y))),
)
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.
//
// 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 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.
2020-11-03 12:35:55 +01:00
//
// If a rune's glyph is already cached, CacheGlyphs does nothing for the rune.
2020-11-03 09:12:49 +01:00
func CacheGlyphs(face font.Face, text string) {
textM.Lock()
defer textM.Unlock()
getGlyphImages(face, []rune(text))
}