mirror of
https://github.com/hajimehoshi/ebiten.git
synced 2024-11-10 04:57:26 +01:00
257 lines
8.6 KiB
Go
257 lines
8.6 KiB
Go
// Copyright 2023 The Ebitengine 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 Ebitengine's image.
|
|
//
|
|
// For the example using a TrueType font, see examples in the examples directory.
|
|
package text
|
|
|
|
import (
|
|
"strings"
|
|
|
|
"golang.org/x/image/math/fixed"
|
|
|
|
"github.com/hajimehoshi/ebiten/v2"
|
|
"github.com/hajimehoshi/ebiten/v2/vector"
|
|
)
|
|
|
|
// Face is an interface representing a font face.
|
|
// The implementations are only faces defined in this package, like GoTextFace and GoXFace.
|
|
type Face interface {
|
|
// Metrics returns the metrics for this Face.
|
|
Metrics() Metrics
|
|
|
|
advance(text string) float64
|
|
|
|
hasGlyph(r rune) bool
|
|
|
|
appendGlyphsForLine(glyphs []Glyph, line string, indexOffset int, originX, originY float64) []Glyph
|
|
appendVectorPathForLine(path *vector.Path, line string, originX, originY float64)
|
|
|
|
direction() Direction
|
|
|
|
// private is an unexported function preventing being implemented by other packages.
|
|
private()
|
|
}
|
|
|
|
// Metrics holds the metrics for a Face.
|
|
// A visual depiction is at https://developer.apple.com/library/mac/documentation/TextFonts/Conceptual/CocoaTextArchitecture/Art/glyph_metrics_2x.png
|
|
type Metrics struct {
|
|
// HLineGap is the recommended amount of vertical space between two lines of text in pixels.
|
|
HLineGap float64
|
|
|
|
// HAscent is the distance in pixels from the top of a line to its baseline for horizontal lines.
|
|
HAscent float64
|
|
|
|
// HDescent is the distance in pixels from the bottom of a line to its baseline for horizontal lines.
|
|
// The value is typically positive, even though a descender goes below the baseline.
|
|
HDescent float64
|
|
|
|
// VLineGap is the recommended amount of horizontal space between two lines of text in pixels.
|
|
// If the face is GoXFace or the font doesn't support a vertical direction, VLineGap is 0.
|
|
VLineGap float64
|
|
|
|
// VAscent is the distance in pixels from the top of a line to its baseline for vertical lines.
|
|
// If the face is GoXFace or the font doesn't support a vertical direction, VAscent is 0.
|
|
VAscent float64
|
|
|
|
// VDescent is the distance in pixels from the top of a line to its baseline for vertical lines.
|
|
// If the face is GoXFace or the font doesn't support a vertical direction, VDescent is 0.
|
|
VDescent float64
|
|
}
|
|
|
|
func fixed26_6ToFloat32(x fixed.Int26_6) float32 {
|
|
return float32(x) / (1 << 6)
|
|
}
|
|
|
|
func fixed26_6ToFloat64(x fixed.Int26_6) float64 {
|
|
return float64(x) / (1 << 6)
|
|
}
|
|
|
|
func float32ToFixed26_6(x float32) fixed.Int26_6 {
|
|
return fixed.Int26_6(x * (1 << 6))
|
|
}
|
|
|
|
func float64ToFixed26_6(x float64) fixed.Int26_6 {
|
|
return fixed.Int26_6(x * (1 << 6))
|
|
}
|
|
|
|
func glyphVariationCount(face Face) int {
|
|
var s float64
|
|
if m := face.Metrics(); face.direction().isHorizontal() {
|
|
s = m.HAscent + m.HDescent
|
|
} else {
|
|
s = m.VAscent + m.VDescent
|
|
}
|
|
// The threshold is decided based on the rendering result of the examples (e.g. examples/text, examples/ui).
|
|
if s < 20 {
|
|
return 8
|
|
}
|
|
if s < 40 {
|
|
return 4
|
|
}
|
|
if s < 80 {
|
|
return 2
|
|
}
|
|
return 1
|
|
}
|
|
|
|
func adjustGranularity(x fixed.Int26_6, face Face) fixed.Int26_6 {
|
|
c := glyphVariationCount(face)
|
|
factor := (1 << 6) / fixed.Int26_6(c)
|
|
return x / factor * factor
|
|
}
|
|
|
|
// Glyph represents one glyph to render.
|
|
type Glyph struct {
|
|
// StartIndexInBytes is the start index in bytes for the given string at AppendGlyphs.
|
|
StartIndexInBytes int
|
|
|
|
// EndIndexInBytes is the end index in bytes for the given string at AppendGlyphs.
|
|
EndIndexInBytes int
|
|
|
|
// GID is an ID for a glyph of TrueType or OpenType font. GID is valid when the face is GoTextFace.
|
|
GID uint32
|
|
|
|
// Image is a rasterized glyph image.
|
|
// 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
|
|
}
|
|
|
|
// Advance returns the advanced distance from the origin position when rendering the given text with the given face.
|
|
//
|
|
// Advance doesn't treat multiple lines.
|
|
//
|
|
// Advance is concurrent-safe.
|
|
func Advance(text string, face Face) float64 {
|
|
return face.advance(text)
|
|
}
|
|
|
|
// Direction represents a direction of text rendering.
|
|
// Direction indicates both the primary direction, in which a text in one line is rendered,
|
|
// and the secondary direction, in which multiple lines are rendered.
|
|
type Direction int
|
|
|
|
const (
|
|
// DirectionLeftToRight indicates that the primary direction is from left to right,
|
|
// and the secondary direction is from top to bottom.
|
|
DirectionLeftToRight Direction = iota
|
|
|
|
// DirectionRightToLeft indicates that the primary direction is from right to left,
|
|
// and the secondary direction is from top to bottom.
|
|
DirectionRightToLeft
|
|
|
|
// DirectionTopToBottomAndLeftToRight indicates that the primary direction is from top to bottom,
|
|
// and the secondary direction is from left to right.
|
|
// This is used e.g. for Mongolian.
|
|
DirectionTopToBottomAndLeftToRight
|
|
|
|
// DirectionTopToBottomAndRightToLeft indicates that the primary direction is from top to bottom,
|
|
// and the secondary direction is from right to left.
|
|
// This is used e.g. for Japanese.
|
|
DirectionTopToBottomAndRightToLeft
|
|
)
|
|
|
|
func (d Direction) isHorizontal() bool {
|
|
switch d {
|
|
case DirectionLeftToRight, DirectionRightToLeft:
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
|
|
// Measure measures the boundary size of the text.
|
|
// With a horizontal direction face, the width is the longest line's advance, and the height is the total of line heights.
|
|
// With a vertical direction face, the width and the height are calculated in an opposite manner.
|
|
//
|
|
// Measure is concurrent-safe.
|
|
func Measure(text string, face Face, lineSpacingInPixels float64) (width, height float64) {
|
|
if text == "" {
|
|
return 0, 0
|
|
}
|
|
|
|
var primary float64
|
|
var lineCount int
|
|
for t := text; ; {
|
|
lineCount++
|
|
line, rest, found := strings.Cut(t, "\n")
|
|
a := face.advance(line)
|
|
if primary < a {
|
|
primary = a
|
|
}
|
|
if !found {
|
|
break
|
|
}
|
|
t = rest
|
|
}
|
|
|
|
m := face.Metrics()
|
|
|
|
if face.direction().isHorizontal() {
|
|
secondary := float64(lineCount-1)*lineSpacingInPixels + m.HAscent + m.HDescent
|
|
return primary, secondary
|
|
}
|
|
secondary := float64(lineCount-1)*lineSpacingInPixels + m.VAscent + m.VDescent
|
|
return secondary, primary
|
|
}
|
|
|
|
// CacheGlyphs pre-caches the glyphs for the given text and the given font face into the cache.
|
|
//
|
|
// CacheGlyphs doesn't treat multiple lines.
|
|
//
|
|
// Glyphs used for rendering are cached in the least-recently-used way.
|
|
// Then old glyphs might be evicted from the cache.
|
|
// As the cache capacity has limitations, it is not guaranteed that all the glyphs for runes given at CacheGlyphs are cached.
|
|
// The cache is shared with Draw and AppendGlyphs.
|
|
//
|
|
// One rune can have multiple variations of glyphs due to sub-pixels in X or Y direction.
|
|
// CacheGlyphs creates all such variations for one rune, while Draw and AppendGlyphs create only necessary glyphs.
|
|
//
|
|
// Draw and AppendGlyphs automatically create and cache 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.
|
|
//
|
|
// CacheGlyphs is concurrent-safe.
|
|
func CacheGlyphs(text string, face Face) {
|
|
var x, y float64
|
|
|
|
c := glyphVariationCount(face)
|
|
|
|
var buf []Glyph
|
|
// Create all the possible variations (#2528).
|
|
for i := 0; i < c; i++ {
|
|
buf = appendGlyphs(buf, text, face, x, y, nil)
|
|
buf = buf[:0]
|
|
|
|
if face.direction().isHorizontal() {
|
|
x += 1.0 / float64(c)
|
|
} else {
|
|
y += 1.0 / float64(c)
|
|
}
|
|
}
|
|
}
|