text

package
v2.8.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 17, 2024 License: Apache-2.0 Imports: 23 Imported by: 205

Documentation

Overview

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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Advance 

func Advance(text string, face Face) 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 AppendVectorPath 

func AppendVectorPath(path *vector.Path, text string, face Face, options *LayoutOptions)

AppndVectorPath appends a vector path for glyphs to the given path.

AppendVectorPath works only when the face is *GoTextFace or a composite face using *GoTextFace so far. For other types, AppendVectorPath does nothing.

func CacheGlyphs 

func CacheGlyphs(text string, face Face)

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. If you really care about the performance, CacheGlyphs might be useful.

CacheGlyphs is concurrent-safe.

func Draw 

func Draw(dst *ebiten.Image, text string, face Face, options *DrawOptions)

Draw draws a given text on a given destination image dst. face is the font for text rendering.

The '\n' newline character puts the following text on the next line.

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.

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

Draw is concurrent-safe.

Rendering region

A rectangle region where a text is put is called a 'rendering region'. The position of the text in the rendering region is determined by the specified primary and secondary alignments.

The actual rendering position of the rendering region depends on the alignments in DrawOptions. By default, if the face's primary direction is left-to-right, the rendering region's upper-left position is (0, 0). Note that this is different from text v1. In text v1, (0, 0) is always the origin position.

Alignments

For horizontal directions, the start and end depends on the face. If the face is GoTextFace, the start and the end depend on the Direction property. If the face is GoXFace, the start and the end are always left and right respectively.

For vertical directions, the start and end are top and bottom respectively.

If the horizontal alignment is left, the rendering region's left X comes to the destination image's origin (0, 0). If the horizontal alignment is center, the rendering region's middle X comes to the origin. If the horizontal alignment is right, the rendering region's right X comes to the origin.

If the vertical alignment is top, the rendering region's top Y comes to the destination image's origin (0, 0). If the vertical alignment is center, the rendering region's middle Y comes to the origin. If the vertical alignment is bottom, the rendering region's bottom Y comes to the origin.

func Measure 

func Measure(text string, face Face, lineSpacingInPixels float64) (width, height float64)

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.

Types

type Align 

type Align int

Align is the alignment that determines how to put a text. 

const (
	AlignStart Align = iota
	AlignCenter
	AlignEnd
)

type Direction 

type Direction int

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. 

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
)

type DrawOptions 

type DrawOptions struct {
	ebiten.DrawImageOptions
	LayoutOptions
}

DrawOptions represents options for the Draw function.

DrawOption embeds ebiten.DrawImageOptions. DrawImageOptions.GeoM is an additional geometry transformation after putting the rendering region along with the specified alignments. DrawImageOptions.ColorScale scales the text color.

type Face 

type Face interface {
	// Metrics returns the metrics for this Face.
	Metrics() Metrics
	// contains filtered or unexported methods
}

Face is an interface representing a font face. The implementations are only faces defined in this package, like GoTextFace and GoXFace.

type Glyph 

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 must not be modified.
	//
	// Image can be nil.
	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

	// OriginX is the X position of the origin of this glyph.
	OriginX float64

	// OriginY is the Y position of the origin of this glyph.
	OriginY float64

	// OriginOffsetX is the adjustment value to the X position of the origin of this glyph.
	// OriginOffsetX is usually 0, but can be non-zero for some special glyphs or glyphs in the vertical text layout.
	OriginOffsetX float64

	// OriginOffsetY is the adjustment value to the Y position of the origin of this glyph.
	// OriginOffsetY is usually 0, but can be non-zero for some special glyphs or glyphs in the vertical text layout.
	OriginOffsetY float64
}

Glyph represents one glyph to render.

func AppendGlyphs 

func AppendGlyphs(glyphs []Glyph, text string, face Face, options *LayoutOptions) []Glyph

AppendGlyphs appends glyphs to the given slice and returns a slice.

AppendGlyphs is a low-level API, and you can use AppendGlyphs to have more control than Draw. AppendGlyphs is also available to precache glyphs.

For the details of options, see Draw function.

AppendGlyphs is concurrent-safe.

type GoTextFace 

type GoTextFace struct {
	// Source is the font face source.
	Source *GoTextFaceSource

	// Direction is the rendering direction.
	// The default (zero) value is left-to-right horizontal.
	Direction Direction

	// Size is the font size in pixels.
	Size float64

	// Language is a hint for a language (BCP 47).
	Language language.Tag

	// Script is a hint for a script code hint of (ISO 15924).
	// If this is empty, the script is guessed from the specified language.
	Script language.Script
	// contains filtered or unexported fields
}

GoTextFace is a Face implementation for go-text's font.Face (github.com/go-text/typesetting). With a GoTextFace, shaping.HarfBuzzShaper is always used as a shaper internally. GoTextFace includes the source and various options.

Unlike GoXFace, one GoTextFace instance doesn't have its own glyph image cache. Instead, a GoTextFaceSource has a glyph image cache. You can casually create multiple GoTextFace instances from the same GoTextFaceSource.

func (*GoTextFace) Metrics 

func (g *GoTextFace) Metrics() Metrics

Metrics implements Face.

func (*GoTextFace) RemoveFeature 

func (g *GoTextFace) RemoveFeature(tag Tag)

RemoveFeature removes a feature value.

func (*GoTextFace) RemoveVariation 

func (g *GoTextFace) RemoveVariation(tag Tag)

RemoveVariation removes a variation value.

func (*GoTextFace) SetFeature 

func (g *GoTextFace) SetFeature(tag Tag, value uint32)

SetFeature sets a feature value. For font features, see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/OpenType_fonts_guide for more details.

func (*GoTextFace) SetVariation 

func (g *GoTextFace) SetVariation(tag Tag, value float32)

SetVariation sets a variation value. For font variations, see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide for more details.

type GoTextFaceSource 

type GoTextFaceSource struct {
	// contains filtered or unexported fields
}

GoTextFaceSource is a source of a GoTextFace. This can be shared by multiple GoTextFace objects.

func NewGoTextFaceSource 

func NewGoTextFaceSource(source io.Reader) (*GoTextFaceSource, error)

NewGoTextFaceSource parses an OpenType or TrueType font and returns a GoTextFaceSource object.

func NewGoTextFaceSourcesFromCollection 

func NewGoTextFaceSourcesFromCollection(source io.Reader) ([]*GoTextFaceSource, error)

NewGoTextFaceSourcesFromCollection parses an OpenType or TrueType font collection and returns a slice of GoTextFaceSource objects.

func (*GoTextFaceSource) Metadata 

func (g *GoTextFaceSource) Metadata() Metadata

Metadata returns its metadata.

func (*GoTextFaceSource) UnsafeInternal 

func (g *GoTextFaceSource) UnsafeInternal() any

UnsafeInternal returns its font.Face. The return value type is any since github.com/go-text/typesettings's API is now unstable.

UnsafeInternal is unsafe since this might make internal cache states out of sync.

UnsafeInternal might have breaking changes even in the same major version.

type GoXFace 

type GoXFace struct {
	// contains filtered or unexported fields
}

GoXFace is a Face implementation for a semi-standard font.Face (golang.org/x/image/font). GoXFace is useful to transit from existing codebase with text v1, or to use some bitmap fonts defined as font.Face. GoXFace must not be copied by value.

Unlike GoFontFace, one GoXFace instance has its own glyph image cache. You should reuse the same GoXFace instance as much as possible.

func NewGoXFace 

func NewGoXFace(face font.Face) *GoXFace

NewGoXFace creates a new GoXFace from a semi-standard font.Face.

func (*GoXFace) Metrics 

func (s *GoXFace) Metrics() Metrics

Metrics implements Face.

func (*GoXFace) UnsafeInternal 

func (s *GoXFace) UnsafeInternal() font.Face

UnsafeInternal returns its internal font.Face.

UnsafeInternal is unsafe since this might make internal cache states out of sync.

UnsafeInternal might have breaking changes even in the same major version.

type LayoutOptions 

type LayoutOptions struct {
	// LineSpacing is a distance between two adjacent lines's baselines.
	// The unit is in pixels.
	LineSpacing float64

	// PrimaryAlign is an alignment of the primary direction, in which a text in one line is rendered.
	// The primary direction is the horizontal direction for a horizontal-direction face,
	// and the vertical direction for a vertical-direction face.
	// The meaning of the start and the end depends on the face direction.
	PrimaryAlign Align

	// SecondaryAlign is an alignment of the secondary direction, in which multiple lines are rendered.
	// The secondary direction is the vertical direction for a horizontal-direction face,
	// and the horizontal direction for a vertical-direction face.
	// The meaning of the start and the end depends on the face direction.
	SecondaryAlign Align
}

LayoutOptions represents options for layouting texts.

PrimaryAlign and SecondaryAlign determine where to put the text in the given region at Draw. Draw might render the text outside of the specified image bounds, so you might have to specify GeoM to make the text visible.

type LimitedFace 

type LimitedFace struct {
	// contains filtered or unexported fields
}

LimitedFace is a Face with glyph limitations.

func NewLimitedFace 

func NewLimitedFace(face Face) *LimitedFace

NewLimitedFace creates a new LimitedFace from the given face. In the default state, glyphs for any runes are limited and not rendered. You have to call AddUnicodeRange to add allowed glyphs.

func (*LimitedFace) AddUnicodeRange 

func (l *LimitedFace) AddUnicodeRange(start, end rune)

AddUnicodeRange adds a rune range for rendered glyphs. A range is inclusive, which means that a range contains the specified rune end.

func (*LimitedFace) Metrics 

func (l *LimitedFace) Metrics() Metrics

Metrics implements Face.

type Metadata 

type Metadata struct {
	Family  string
	Style   Style
	Weight  Weight
	Stretch Stretch
}

Metadata represents a font face's metadata.

type Metrics 

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

	// XHeight is the distance in pixels from the baseline to the top of the lower case letters.
	XHeight float64

	// CapHeight is the distance in pixels from the baseline to the top of the capital letters.
	CapHeight float64
}

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 MultiFace 

type MultiFace struct {
	// contains filtered or unexported fields
}

MultiFace is a Face that consists of multiple Face objects. The face in the first index is used in the highest priority, and the last the lowest priority.

There is a known issue: if the writing directions of the faces don't agree, the rendering result might be messed up.

func NewMultiFace 

func NewMultiFace(faces ...Face) (*MultiFace, error)

NewMultiFace creates a new MultiFace from the given faces.

NewMultiFace returns an error when no faces are given, or the faces' directions don't agree.

func (*MultiFace) Metrics 

func (m *MultiFace) Metrics() Metrics

Metrics implements Face.

type Stretch 

type Stretch float32
const (
	StretchUltraCondensed Stretch = Stretch(font.StretchUltraCondensed)
	StretchExtraCondensed Stretch = Stretch(font.StretchExtraCondensed)
	StretchCondensed      Stretch = Stretch(font.StretchCondensed)
	StretchSemiCondensed  Stretch = Stretch(font.StretchSemiCondensed)
	StretchNormal         Stretch = Stretch(font.StretchNormal)
	StretchSemiExpanded   Stretch = Stretch(font.StretchSemiExpanded)
	StretchExpanded       Stretch = Stretch(font.StretchExpanded)
	StretchExtraExpanded  Stretch = Stretch(font.StretchExtraExpanded)
	StretchUltraExpanded  Stretch = Stretch(font.StretchUltraExpanded)
)

type Style 

type Style uint8
const (
	StyleNormal Style = Style(font.StyleNormal)
	StyleItalic Style = Style(font.StyleItalic)
)

type Tag 

type Tag uint32

Tag is a tag for font variations and features. Tag is a 4-byte value like 'cmap'.

func MustParseTag 

func MustParseTag(str string) Tag

MustParseTag converts a string to Tag. If parsing fails, MustParseTag panics.

func ParseTag 

func ParseTag(str string) (Tag, error)

ParseTag converts a string to Tag.

func (Tag) String 

func (t Tag) String() string

String returns the Tag's string representation.

type Weight 

type Weight float32
const (
	WeightThin       Weight = Weight(font.WeightThin)
	WeightExtraLight Weight = Weight(font.WeightExtraLight)
	WeightLight      Weight = Weight(font.WeightLight)
	WeightNormal     Weight = Weight(font.WeightNormal)
	WeightMedium     Weight = Weight(font.WeightMedium)
	WeightSemibold   Weight = Weight(font.WeightSemibold)
	WeightBold       Weight = Weight(font.WeightBold)
	WeightExtraBold  Weight = Weight(font.WeightExtraBold)
	WeightBlack      Weight = Weight(font.WeightBlack)
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.