Documentation ¶
Overview ¶
etxt is a package for text rendering designed to be used with Ebitengine, a 2D game engine made by Hajime Hoshi for Golang.
To get started, you should create a Renderer and set up a font and cache:
text := etxt.NewRenderer() text.SetFont(font) text.SetCache8MiB()
Then, you can further adjust the renderer properties with functions like Renderer.SetColor(), Renderer.SetSize(), Renderer.SetAlign(), Renderer.SetScale() and many others.
Once you have everything configured to your liking, drawing should be very straightforward:
text.Draw(canvas, "Hello world!", x, y)
To learn more, make sure to check the examples!
Index ¶
- Constants
- type Align
- type BlendMode
- type Direction
- type Font
- type GlyphMask
- type RectLineBreak
- type RectOptions
- type Renderer
- func (self *Renderer) Complex() *RendererComplex
- func (self *Renderer) Draw(target TargetImage, text string, x, y int) fract.Point
- func (self *Renderer) DrawInRect(target TargetImage, text string, x, y int, opts *RectOptions) fract.Point
- func (self *Renderer) Fract() *RendererFract
- func (self *Renderer) GetAlign() Align
- func (self *Renderer) GetBlendMode() BlendMode
- func (self *Renderer) GetCacheHandler() cache.GlyphCacheHandler
- func (self *Renderer) GetColor() color.Color
- func (self *Renderer) GetFont() *sfnt.Font
- func (self *Renderer) GetScale() float64
- func (self *Renderer) GetSize() float64
- func (self *Renderer) Measure(text string) fract.Rect
- func (self *Renderer) MeasureWithWrap(text string, widthLimit int) fract.Rect
- func (self *Renderer) SetAlign(align Align)
- func (self *Renderer) SetBlendMode(blendMode BlendMode)
- func (self *Renderer) SetCache8MiB()
- func (self *Renderer) SetCacheHandler(cacheHandler cache.GlyphCacheHandler)
- func (self *Renderer) SetColor(fontColor color.Color)
- func (self *Renderer) SetFont(font *sfnt.Font)
- func (self *Renderer) SetFontBytes(data []byte) error
- func (self *Renderer) SetScale(scale float64)
- func (self *Renderer) SetSize(size float64)
- type RendererComplex
- func (self *RendererComplex) Draw(screen TargetImage, text Text, x, y fract.Unit) fract.Point
- func (self *RendererComplex) DrawInRect(screen TargetImage, text Text, x, y fract.Unit, opts *RectOptions) fract.Point
- func (self *RendererComplex) GetBuffer() *sfnt.Buffer
- func (self *RendererComplex) GetDirection() Direction
- func (self *RendererComplex) GetFontIndex() int
- func (self *RendererComplex) GetFonts() []*sfnt.Font
- func (self *RendererComplex) GetRasterizer() mask.Rasterizer
- func (self *RendererComplex) GetSizer() sizer.Sizer
- func (self *RendererComplex) SetDirection(dir Direction)
- func (self *RendererComplex) SetFontIndex(index uint8) *sfnt.Font
- func (self *RendererComplex) SetFonts(fonts []*sfnt.Font)
- func (self *RendererComplex) SetRasterizer(rasterizer mask.Rasterizer)
- func (self *RendererComplex) SetSizer(fontSizer sizer.Sizer)
- type RendererFract
- func (self *RendererFract) Draw(target TargetImage, text string, x, y fract.Unit) fract.Point
- func (self *RendererFract) GetQuantization() (horz, vert fract.Unit)
- func (self *RendererFract) GetScale() fract.Unit
- func (self *RendererFract) GetSize() fract.Unit
- func (self *RendererFract) MeasureHeight(text string) fract.Unit
- func (self *RendererFract) SetQuantization(horz, vert fract.Unit)
- func (self *RendererFract) SetScale(scale fract.Unit)
- func (self *RendererFract) SetSize(size fract.Unit)
- type TargetImage
- type Text
- func (self *Text) Add(text string) *Text
- func (self *Text) AddGFX(gfxId uint8, logicalAdvance fract.Unit, payload uint16) *Text
- func (self *Text) AddGlyph(index sfnt.GlyphIndex)
- func (self *Text) AddGlyphs(indices []sfnt.GlyphIndex) *Text
- func (self *Text) AddLineBreak() *Text
- func (self *Text) AddPad(logicalPad fract.Unit) *Text
- func (self *Text) AddUtf8(bytes []byte) *Text
- func (self *Text) ClearBuffer()
- func (self *Text) GetOsc() float64
- func (self *Text) Pop() *Text
- func (self *Text) PopAll() *Text
- func (self *Text) PushBGND(gfxId uint8, logicalPad fract.Unit, payload uint16) *Text
- func (self *Text) PushFGND(gfxId uint8, logicalPad fract.Unit, payload uint16) *Text
- func (self *Text) PushFID(fontId uint8) *Text
- func (self *Text) PushRGBA(text string, rgba color.RGBA) *Text
- func (self *Text) SetOsc(point float64)
- func (self *Text) ShiftOsc(shift float64)
Constants ¶
const ( QtNone = fract.Unit(1) // full glyph position resolution (1/64ths of a pixel) Qt32th = fract.Unit(2) // quantize glyph positions to 1/32ths of a pixel Qt16th = fract.Unit(4) // quantize glyph positions to 1/16ths of a pixel Qt8th = fract.Unit(8) // quantize glyph positions to 1/ 8ths of a pixel Qt4th = fract.Unit(16) // quantize glyph positions to 1/ 4ths of a pixel QtHalf = fract.Unit(32) // quantize glyph positions to half of a pixel QtFull = fract.Unit(64) // full glyph position quantization (default) )
Quantization levels for RendererFract.SetQuantization().
Only the perfectly equidistant quantization values are given. Other values like fract.Unit(22) (~one third of a pixel = ceil(64/3)) could work too, but they all result in potentially uneven distributions of the glyph positions. These would make the results of text measuring functions dependent on the text direction, align and working position, which would make centering impractically complicated. The API would also become exceedingly difficult to use correctly.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Align ¶ added in v0.0.9
type Align uint8
Aligns are used to define how coordinates passed to renderer operations have to be interpreted. For example, if you try to draw text at (0, 0) with any align that's not top-left, the result is going to be clipped or not visible at all.
See Renderer.SetAlign() for more details.
const ( Left Align = 0b0001_0000 // horizontal align XCenter Align = 0b0010_0000 // horizontal align Right Align = 0b0100_0000 // horizontal align Top Align = 0b0000_0001 // vertical align YCenter Align = 0b0000_0010 // vertical align Baseline Align = 0b0000_0100 // vertical align Bottom Align = 0b0000_1000 // vertical align Center Align = XCenter | YCenter // full align )
Align constants for renderer operations. Vertical and horizontal aligns can be combined with a bitwise OR (|). See Renderer.SetAlign() for more details.
type BlendMode ¶ added in v0.0.9
type BlendMode = ebiten.Blend
The blend mode specifies how to compose colors when drawing glyphs:
- Without Ebitengine, the blend mode can be BlendOver, BlendReplace, BlendAdd, BlendSub, BlendMultiply, BlendCut and BlendFiftyFifty.
- With Ebitengine, the blend mode is Ebitengine's Blend.
I only ever change blend modes to make cutout text, but there's a lot of weird people out there, what can I say.
type Direction ¶
type Direction int8
Renderers can have their text direction configured as left-to-right or right-to-left. See [Renderer.SetDirection]().
Directions can be casted directly to unicode/bidi directions:
bidi.Direction(etxt.LeftToRight).
type Font ¶
A handy type alias for sfnt.Font so you don't need to import it when already working with etxt.
type GlyphMask ¶
type GlyphMask = *ebiten.Image
A GlyphMask is the image that results from rasterizing a glyph. You rarely need to use GlyphMasks directly unless using advanced functions.
Without Ebitengine (-tags gtxt), GlyphMask defaults to *image.Alpha. The image bounds are adjusted to allow drawing the glyph at its intended position. In particular, bounds.Min.Y is typically negative, with y = 0 corresponding to the glyph's baseline, y < 0 to the ascending portions and y > 0 to the descending ones.
With Ebitengine, GlyphMask defaults to *ebiten.Image.
type RectLineBreak ¶
type RectLineBreak uint8
Line breaking modes available for RectOptions.
const ( LineOverflow RectLineBreak = 0 LineClipLetter RectLineBreak = 1 // overflowing letters won't be drawn LineClipWord RectLineBreak = 2 // overflowing words won't be drawn LineEllipsis RectLineBreak = 3 // overflowing fragments will get a "..." ending LineWrapGreedy RectLineBreak = 4 // overflowing fragments will go to the next line )
type RectOptions ¶
type RectOptions struct { // Coordinates and dimensions of the area that we want to // draw the text in. See [RectOptions.SetArea]() if you // want to set the area with an image.Rectangle. Area fract.Rect // Line break mode. Defaults to [LineOverflow]. LineBreak RectLineBreak // When set to true, this flag will prevent the // renderer from drawing lines that may not fully // fall within the Area's allotted vertical space. VertClip bool }
Used by Renderer.DrawInRect(), Renderer.MeasureWithWrap() and similar functions that operate within a delimited rectangular area.
func (*RectOptions) SetArea ¶
func (self *RectOptions) SetArea(rect image.Rectangle)
Utility method to set the rect area with image.Rectangle instead of fract.Rectangle.
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
The Renderer is the main type for drawing text provided by etxt.
Renderers allow you to control font, text size, color, text alignment and more from a single place.
The zero value is valid, but you must set a font (e.g. Renderer.SetFont()) if you want to do anything useful with it. In most cases, you will also want to set a cache, the text size, the color and the align.
func NewRenderer ¶
func NewRenderer() *Renderer
Creates a new Renderer.
Setting a font through Renderer.SetFont() or Renderer.SetFontBytes() is required before being able to operate with it. It's also heavily recommended to set a cache (none by default) right from the start.
func (*Renderer) Complex ¶
func (self *Renderer) Complex() *RendererComplex
Access the renderer in RendererComplex mode. This mode allows accessing advanced renderer properties, as well as operating directly with glyphs and the more flexible Text type.
func (*Renderer) Draw ¶
Draws the given text with the current configuration (font, size, color, target, etc). The position at which the text will be drawn depends on the given pixel coordinates and the renderer's align (see Renderer.SetAlign() rules).
The returned value is the last unquantized dot position, only relevant for advanced use-cases.
Missing glyphs in the current font will cause the renderer to panic. Consider using [font.GetMissingRunes]() if you need to make your system more robust.
// [font.GetMissingRunes]: https://pkg.go.dev/github.com/tinne26/etxt/font#GetMissingRunes
func (*Renderer) DrawInRect ¶
func (self *Renderer) DrawInRect(target TargetImage, text string, x, y int, opts *RectOptions) fract.Point
func (*Renderer) Fract ¶ added in v0.0.9
func (self *Renderer) Fract() *RendererFract
Access the renderer in RendererFract mode. This mode allows you to configure or operate the renderer with an increased level of precision, up to 1/64th of a pixel.
func (*Renderer) GetAlign ¶
Returns the current align. See Renderer.SetAlign() documentation for more details on renderer aligns.
func (*Renderer) GetBlendMode ¶ added in v0.0.9
Returns the renderer's BlendMode. As far as I know, this is only strictly necessary when implementing draw operations with custom shaders.
func (*Renderer) GetCacheHandler ¶
func (self *Renderer) GetCacheHandler() cache.GlyphCacheHandler
Returns the current glyph cache handler, which is nil by default.
Rarely used unless you are examining the cache handler manually.
func (*Renderer) GetScale ¶ added in v0.0.9
Returns the current display scaling factor used for the text as a float64. See Renderer.SetScale() for more details.
func (*Renderer) GetSize ¶ added in v0.0.9
Returns the current logical font size. The default value is 16.
Notice that the returned value doesn't take scaling into account (see Renderer.SetScale()).
func (*Renderer) Measure ¶ added in v0.0.9
Returns the dimensions of the area taken by the given text. Intuitively, this matches the shaded area that you see when highlighting or selecting text in browsers and text editors.
The results are affected by the renderer's font, size, quantization and sizer.
Notice that spilling (content falling outside the returned rect) is possible. In general it will be non-existent or very minor, but italics, fancy display fonts and script fonts are common offenders that you may want to watch out for.
func (*Renderer) MeasureWithWrap ¶ added in v0.0.9
Same as Renderer.Measure(), but using a width limit for line wrapping. Typically used in conjunction with Renderer.DrawInRect() when the LineWrapGreedy mode is used on RectOptions LineBreak field.
func (*Renderer) SetAlign ¶
The renderer's align defines how Renderer.Draw() and other operations interpret the coordinates passed to them. For example:
- If the align is set to (etxt.Top | etxt.Left), coordinates will be interpreted as the top-left corner of the box that the text needs to occupy.
- If the align is set to (etxt.Center), coordinates will be interpreted as the center of the box that the text needs to occupy.
See this image for a visual explanation instead.
Notice that aligns have separate horizontal and vertical components, so you can use calls like Renderer.SetAlign(etxt.Right) to change only one of the components (the horizontal in this case).
By default, the renderer's align is (etxt.Baseline | etxt.Left).
func (*Renderer) SetBlendMode ¶ added in v0.0.9
Sets the blend mode to be used on subsequent operations. The default blend mode will compose glyphs over the active target with regular alpha blending.
func (*Renderer) SetCache8MiB ¶
func (self *Renderer) SetCache8MiB()
Utility method to set a cache that will get you started. For a more manual and adjustable approach, see Renderer.SetCacheHandler().
func (*Renderer) SetCacheHandler ¶
func (self *Renderer) SetCacheHandler(cacheHandler cache.GlyphCacheHandler)
Sets the glyph cache handler used by the renderer. By default, no cache is used, but you almost always want to set one.
The easiest way is to use Renderer.SetCache8MiB(), but that's not suitable for all use-cases. The general approach is to create a cache manually, obtain a cache handler from it and set it:
glyphsCache := cache.NewDefaultCache(16*1024*1024) // 16MiB cache renderer.SetCacheHandler(glyphsCache.NewHandler())
See cache.NewDefaultCache() for more details.
A cache handler can only be used with a single renderer, but you may create multiple handlers from the same underlying cache and use them with multiple renderers.
func (*Renderer) SetColor ¶
Sets the color to be used on subsequent draw operations. The default color is white.
func (*Renderer) SetFont ¶
Sets the font to be used on subsequent operations. Without a font, a renderer is fundamentally useless, so don't forget to set this up.
See also Renderer.SetFontBytes().
func (*Renderer) SetFontBytes ¶
Utility method to set the font by passing its raw data and letting the renderer parse it. This method should be avoided if you want to reuse the font data at different points in your application; in that case, parsing the font only once (e.g. using [font.Library]) and setting it with Renderer.SetFont() is the way to go.
func (*Renderer) SetScale ¶ added in v0.0.9
Sets the display scaling factor to be used for the text size on subsequent operations.
If you don't know much about display scaling, read this guide. Understanding display scaling is critical to be able to render non-crappy text across different devices.
The scale must be non-negative. Its default value is 1.0.
func (*Renderer) SetSize ¶ added in v0.0.9
Sets the logical font size to be used on subsequent operations. Sizes are given in pixels and can't be negative. Maximum size is limited around ~16K.
By default, the renderer will draw text at a logical size of 16px.
The relationship between font size and the size of its glyphs is complicated and can vary a lot between fonts, but to provide a general reference:
- A capital latin letter is usually around 70% as tall as the given size. E.g.: at 16px, "A" will be 10-12px tall.
- A lowercase latin letter is usually around 48% as tall as the given size. E.g.: at 16px, "x" will be 7-9px tall.
See also Renderer.SetScale() for proper handling of high resolution text and display scaling.
type RendererComplex ¶
type RendererComplex Renderer
A wrapper type for using a Renderer in "complex mode". This mode allows accessing advanced renderer properties, as well as operating directly with glyphs and the more flexible Text type. These types are relevant when working with complex scripts and text shaping, among others.
Notice that this type exists almost exclusively for documentation and structuring purposes. To most effects, you could consider the methods part of Renderer itself.
func (*RendererComplex) Draw ¶
func (self *RendererComplex) Draw(screen TargetImage, text Text, x, y fract.Unit) fract.Point
func (*RendererComplex) DrawInRect ¶
func (self *RendererComplex) DrawInRect(screen TargetImage, text Text, x, y fract.Unit, opts *RectOptions) fract.Point
func (*RendererComplex) GetBuffer ¶
func (self *RendererComplex) GetBuffer() *sfnt.Buffer
Exposes the renderer's internal *sfnt.Buffer. Only exposed for advanced interaction with the sfnt package.
func (*RendererComplex) GetDirection ¶
func (self *RendererComplex) GetDirection() Direction
func (*RendererComplex) GetFontIndex ¶
func (self *RendererComplex) GetFontIndex() int
func (*RendererComplex) GetFonts ¶
func (self *RendererComplex) GetFonts() []*sfnt.Font
func (*RendererComplex) GetRasterizer ¶
func (self *RendererComplex) GetRasterizer() mask.Rasterizer
Returns the current glyph mask rasterizer.
This function is only useful when working with configurable rasterizers; ignore it if you are using the default glyph mask rasterizer.
Mask rasterizers are not concurrent-safe, so be careful with what you do and where you put them.
func (*RendererComplex) GetSizer ¶
func (self *RendererComplex) GetSizer() sizer.Sizer
Returns the current sizer.Sizer.
The most common use of sizers is adjusting line height or glyph interspacing. Outside of that, sizers can also be relevant when trying to obtain information about font metrics or when making custom glyph mask rasterizers, but it's fairly uncommon for the average user to have to worry about all these things.
func (*RendererComplex) SetDirection ¶
func (self *RendererComplex) SetDirection(dir Direction)
Sets the text direction to be used on subsequent operations.
Do not confuse text direction with horizontal align. Text direction is typically only changed for right-to-left languages like Arabic, Hebrew or Persian.
By default, the direction is LeftToRight.
func (*RendererComplex) SetFontIndex ¶
func (self *RendererComplex) SetFontIndex(index uint8) *sfnt.Font
Sets the active font index to the given value. Returns the newly active font.
func (*RendererComplex) SetFonts ¶
func (self *RendererComplex) SetFonts(fonts []*sfnt.Font)
func (*RendererComplex) SetRasterizer ¶
func (self *RendererComplex) SetRasterizer(rasterizer mask.Rasterizer)
Sets the glyph mask rasterizer to be used on subsequent operations. Nil rasterizers are not allowed.
func (*RendererComplex) SetSizer ¶
func (self *RendererComplex) SetSizer(fontSizer sizer.Sizer)
Sets the current sizer.Sizer, which must be non-nil.
The most common use of sizers is adjusting line height or glyph interspacing. Outside of that, sizers can also be relevant when trying to obtain information about font metrics or when making custom glyph mask rasterizers, but it's fairly uncommon for the average user to have to worry about all these things.
type RendererFract ¶ added in v0.0.9
type RendererFract Renderer
A wrapper type for using a Renderer in "fractional mode". This mode allows you to configure or operate the renderer with an increased level of precision, up to 1/64th of a pixel.
Fractional operations are typically relevant when animating or trying to respect the text flow with the highest precision possible.
The fractional getters and setters can also be useful when saving state of the renderer to be restored later, as floating point conversions can be avoided.
All the fractional operations depend on the fract.Unit type, so make sure to check out the etxt/fract subpackage if you need more context to understand how everything ties together.
Notice that this type exists almost exclusively for documentation and structuring purposes. To most effects, you could consider the methods part of Renderer itself.
func (*RendererFract) Draw ¶ added in v0.0.9
func (self *RendererFract) Draw(target TargetImage, text string, x, y fract.Unit) fract.Point
func (*RendererFract) GetQuantization ¶ added in v0.0.9
func (self *RendererFract) GetQuantization() (horz, vert fract.Unit)
Returns the current quantization levels. See RendererFract.SetQuantization() for more context.
func (*RendererFract) GetScale ¶ added in v0.0.9
func (self *RendererFract) GetScale() fract.Unit
Fractional version of Renderer.GetScale().
func (*RendererFract) GetSize ¶ added in v0.0.9
func (self *RendererFract) GetSize() fract.Unit
Fractional version of Renderer.GetSize().
func (*RendererFract) MeasureHeight ¶
func (self *RendererFract) MeasureHeight(text string) fract.Unit
func (*RendererFract) SetQuantization ¶
func (self *RendererFract) SetQuantization(horz, vert fract.Unit)
Sets the renderer's quantization level. You should use QtNone, Qt4th, QtHalf, QtFull and the other existing constants. As their documentation explains, other arbitrary values may get you in trouble.
By default, quantization is fully enabled (QtFull, QtFull).
Values below one or above 64 fractional units will panic.
func (*RendererFract) SetScale ¶ added in v0.0.9
func (self *RendererFract) SetScale(scale fract.Unit)
Same as Renderer.SetScale(), but avoids a conversion from float64 to fract.Unit.
func (*RendererFract) SetSize ¶ added in v0.0.9
func (self *RendererFract) SetSize(size fract.Unit)
Fractional version of Renderer.SetSize().
type TargetImage ¶
type TargetImage = *ebiten.Image
Alias to allow compiling the package without Ebitengine (-tags gtxt).
Without Ebitengine, TargetImage defaults to image/draw.Image.
type Text ¶
type Text struct {
// contains filtered or unexported fields
}
The text may be added as utf8, raw glyphs or a mix of both, with some styling directives also supported through control codes.
func (*Text) AddGlyph ¶
func (self *Text) AddGlyph(index sfnt.GlyphIndex)
func (*Text) AddLineBreak ¶
func (*Text) ClearBuffer ¶
func (self *Text) ClearBuffer()
Clears the internal buffer without deallocating its memory.
func (*Text) PushBGND ¶
Formatting directive to set a background draw function. To cancel the directive, use Text.Pop() or Text.PopAll().
func (*Text) PushRGBA ¶
Formatting directive to alter the text color. To cancel the directive, use Text.Pop() or Text.PopAll().
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
The cache subpackage defines the [GlyphCacheHandler] interface used within etxt and provides a default cache implementation.
|
The cache subpackage defines the [GlyphCacheHandler] interface used within etxt and provides a default cache implementation. |
examples
|
|
ebiten/aligns
Module
|
|
ebiten/bbcode
Module
|
|
ebiten/color_markup
Module
|
|
ebiten/debug_glyph
Module
|
|
ebiten/measure
Module
|
|
ebiten/miss_handler
Module
|
|
ebiten/twine
Module
|
|
ebiten/twine_demo
Module
|
|
ebiten/words
Module
|
|
The mask subpackage defines the [Rasterizer] interface used within etxt and provides multiple ready-to-use implementations.
|
The mask subpackage defines the [Rasterizer] interface used within etxt and provides multiple ready-to-use implementations. |
The sizer subpackage defines the [Sizer] interface used within etxt and provides multiple ready-to-use implementations.
|
The sizer subpackage defines the [Sizer] interface used within etxt and provides multiple ready-to-use implementations. |