text

package
v0.0.0-...-5e2a49b Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source 
const AsciiGlyphCount = 128

Variables

View Source 
var AllocPageFn func() int

AllocPageFn allocates and returns a new atlas page index. Wired by root.

View Source 
var NextPageFn func() int

NextPageFn returns the next available atlas page index. Wired by root.

View Source 
var RegisterPageFn func(pageIndex int, img *ebiten.Image)

RegisterPageFn registers an atlas page image. Wired by root.

Functions

func GenerateSDFFromBitmaps 

func GenerateSDFFromBitmaps(glyphs []GlyphBitmap, opts SDFGenOptions) (*image.NRGBA, []byte, error)

GenerateSDFFromBitmaps creates an SDF atlas from pre-rasterized glyph bitmaps. This is the core algorithm used by both runtime and offline generation paths. Each GlyphBitmap should have its Img field set to the rasterized glyph.

Returns the atlas image and metrics JSON.

func IsPixelFont 

func IsPixelFont(f Font) bool

IsPixelFont returns true if the font implements the pixelFontMarker interface.

func LoadFontFromPath 

func LoadFontFromPath(path string) ([]byte, error)

LoadFontFromPath reads a TTF/OTF file from disk.

func LoadFontFromSystem 

func LoadFontFromSystem(name string) ([]byte, error)

LoadFontFromSystem searches OS system font directories for a font by name.

Types

type DistanceFieldFont 

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

DistanceFieldFont renders text from a pre-generated SDF or MSDF atlas. It implements the Font interface for measurement and layout.

func LoadDistanceFieldFont 

func LoadDistanceFieldFont(jsonData []byte, pageIndex uint16) (*DistanceFieldFont, error)

LoadDistanceFieldFont parses SDF font metrics JSON and returns a DistanceFieldFont. The pageIndex specifies which atlas page the SDF glyphs are on.

func LoadDistanceFieldFontFromTTF 

func LoadDistanceFieldFontFromTTF(ttfData []byte, opts SDFGenOptions) (*DistanceFieldFont, *ebiten.Image, *image.NRGBA, error)

LoadDistanceFieldFontFromTTF generates an SDF font atlas at runtime from TTF/OTF data. Uses pure-Go rasterization (golang.org/x/image/font/opentype) so it can be called before the Ebitengine game loop starts. Returns the DistanceFieldFont, the atlas as an ebiten.Image (caller must register via Scene.RegisterPage), the raw atlas as an *image.NRGBA (for saving to disk), and any error.

func LoadDistanceFieldFontFromTTFMSDF 

func LoadDistanceFieldFontFromTTFMSDF(ttfData []byte, opts SDFGenOptions) (*DistanceFieldFont, *ebiten.Image, *image.NRGBA, error)

LoadDistanceFieldFontFromTTFMSDF generates an MSDF atlas from TTF/OTF data. It extracts glyph outlines, computes per-channel signed distances, and packs the results into an atlas. Distances are encoded in R, G, B channels; the MSDF shader reads median(R,G,B) to recover sharp edges and corners.

EXPERIMENTAL — MSDF produces inconsistent rendering quality compared to SDF. Multi-contour glyphs (0, 8, @, etc.) exhibit anti-aliasing artifacts and channel divergence that degrades text appearance. The pipeline is architecturally complete (edge coloring, contour combiner, error correction) but the output quality does not match the reference msdfgen implementation. Use LoadDistanceFieldFontFromTTF (single-channel SDF) for production use.

func NewFontFromTTF 

func NewFontFromTTF(ttfData []byte, size float64) (*DistanceFieldFont, error)

NewFontFromTTF generates an SDF font from TTF/OTF data, registers the atlas page via function pointers, and returns the font ready to use.

func NewFontFromTTFOpts 

func NewFontFromTTFOpts(ttfData []byte, opts SDFGenOptions) (*DistanceFieldFont, error)

NewFontFromTTFOpts generates an SDF font from TTF/OTF data using explicit SDFGenOptions. PageIndex is overwritten by an allocated page.

func NewMSDFFontFromTTF 

func NewMSDFFontFromTTF(ttfData []byte, size float64) (*DistanceFieldFont, error)

NewMSDFFontFromTTF generates an MSDF font from TTF/OTF data. MSDF encodes per-channel directional distances into R, G, B, enabling sharper corners and crisper edges than single-channel SDF at all display sizes.

EXPERIMENTAL — MSDF produces inconsistent rendering quality compared to SDF. Multi-contour glyphs (0, 8, @, etc.) exhibit anti-aliasing artifacts and channel divergence that degrades text appearance. Use NewFontFromTTF (single-channel SDF) for production text rendering.

func NewMSDFFontFromTTFOpts 

func NewMSDFFontFromTTFOpts(ttfData []byte, opts SDFGenOptions) (*DistanceFieldFont, error)

NewMSDFFontFromTTFOpts generates an MSDF font from TTF/OTF data using explicit SDFGenOptions. PageIndex is overwritten by an allocated page.

EXPERIMENTAL — MSDF produces inconsistent rendering quality compared to SDF. Multi-contour glyphs (0, 8, @, etc.) exhibit anti-aliasing artifacts and channel divergence that degrades text appearance. Use NewFontFromTTFOpts (single-channel SDF) for production text rendering.

func (*DistanceFieldFont) DistanceRange 

func (f *DistanceFieldFont) DistanceRange() float64

DistanceRange returns the pixel range of the distance field.

func (*DistanceFieldFont) FontSize 

func (f *DistanceFieldFont) FontSize() float64

FontSize returns the design size (in pixels) that the SDF was generated at.

func (*DistanceFieldFont) GlyphLookup 

func (f *DistanceFieldFont) GlyphLookup(r rune) *Glyph

GlyphLookup returns the glyph for the given rune, or nil if not found.

func (*DistanceFieldFont) IsMultiChannel 

func (f *DistanceFieldFont) IsMultiChannel() bool

IsMultiChannel returns true if this is an MSDF font (multi-channel SDF).

func (*DistanceFieldFont) Kern 

func (f *DistanceFieldFont) Kern(first, second rune) int16

Kern returns the kerning amount for the given rune pair.

func (*DistanceFieldFont) LineHeight 

func (f *DistanceFieldFont) LineHeight() float64

LineHeight returns the vertical distance between baselines in native atlas pixels.

func (*DistanceFieldFont) MeasureString 

func (f *DistanceFieldFont) MeasureString(s string) (width, height float64)

MeasureString returns the pixel width and height of the rendered text in native atlas pixels.

func (*DistanceFieldFont) Page 

func (f *DistanceFieldFont) Page() uint16

Page returns the atlas page index for this font.

func (*DistanceFieldFont) SetLineHeight 

func (f *DistanceFieldFont) SetLineHeight(h float64)

SetLineHeight sets the line height. Intended for test setup only.

func (*DistanceFieldFont) SetTTFData 

func (f *DistanceFieldFont) SetTTFData(data []byte)

SetTTFData sets the TTF data on the font.

func (*DistanceFieldFont) TTFData 

func (f *DistanceFieldFont) TTFData() []byte

TTFData returns the original TTF/OTF byte data, or nil if the font was not created from TTF.

type Font 

type Font interface {
	// MeasureString returns the pixel width and height of the rendered text
	// in native atlas pixels, accounting for newlines and the font's line height.
	MeasureString(text string) (width, height float64)
	// LineHeight returns the vertical distance between baselines in native atlas pixels.
	LineHeight() float64
}

Font is the interface for text measurement and layout. Implemented by DistanceFieldFont and PixelFont.

All measurements are in native atlas pixels. To get display-sized values, use TextBlock.MeasureDisplay or scale manually by TextBlock.FontScale().

type Glyph 

type Glyph struct {
	ID       rune
	X, Y     uint16
	Width    uint16
	Height   uint16
	XOffset  int16
	YOffset  int16
	XAdvance int16
	Page     uint16
}

Glyph holds glyph metrics and atlas position.

type GlyphBitmap 

type GlyphBitmap struct {
	ID       rune
	Img      *image.Alpha // rasterized glyph (grayscale)
	XOffset  int
	YOffset  int
	XAdvance int
	// contains filtered or unexported fields
}

GlyphBitmap holds a rasterized glyph and its metrics for atlas packing.

type GlyphPos 

type GlyphPos struct {
	X, Y   float64
	Region types.TextureRegion
	Page   uint16
}

GlyphPos is the computed screen position and region for a single glyph.

type PixelFont 

type PixelFont struct {
	CellW, CellH       int // cell size in pixels
	PadTop, PadRight   int // pixels trimmed from each side of each cell
	PadBottom, PadLeft int
	Page               uint16              // atlas page index
	Cols               int                 // number of columns in the spritesheet grid
	Glyphs             [128]pixelGlyph     // ASCII fast lookup
	GlyphSet           [128]bool           // which ASCII entries are populated
	ExtGlyphs          map[rune]pixelGlyph // extended chars
}

PixelFont is a pixel-perfect bitmap font renderer for monospaced spritesheets. Each character occupies a fixed cell in a grid on a single atlas page. Scaling is integer-only (1x, 2x, 3x) to preserve pixel-perfect rendering.

func NewPixelFont 

func NewPixelFont(img *ebiten.Image, cellW, cellH int, chars string) *PixelFont

NewPixelFont creates a pixel font from a spritesheet image.

func (*PixelFont) AddGlyph 

func (pf *PixelFont) AddGlyph(r rune, x, y uint16)

AddGlyph registers a glyph at the given atlas position.

func (*PixelFont) AdvanceH 

func (pf *PixelFont) AdvanceH() int

AdvanceH returns the effective line height after vertical trim.

func (*PixelFont) AdvanceW 

func (pf *PixelFont) AdvanceW() int

AdvanceW returns the effective character advance width after horizontal trim.

func (*PixelFont) GlyphLookup 

func (pf *PixelFont) GlyphLookup(r rune) (x, y uint16, found bool)

GlyphLookup returns the atlas position of a glyph, and whether it was found.

func (*PixelFont) LineHeight 

func (pf *PixelFont) LineHeight() float64

LineHeight returns the effective line height in native pixels (after vertical trim).

func (*PixelFont) MeasureString 

func (pf *PixelFont) MeasureString(text string) (width, height float64)

MeasureString returns the pixel width and height of the rendered text in native (unscaled) pixels. Monospaced: each character is cellW wide.

func (*PixelFont) TrimCell 

func (pf *PixelFont) TrimCell(top, right, bottom, left int)

TrimCell trims pixels from each side of every cell.

type SDFGenOptions 

type SDFGenOptions struct {
	// Size is the font size in pixels for rasterization.
	Size float64
	// DistanceRange is the pixel range of the distance field (typically 4-8).
	DistanceRange float64
	// Chars is the set of characters to include. Empty means printable ASCII (32-126).
	Chars string
	// AtlasWidth is the maximum atlas width in pixels. Default 1024.
	AtlasWidth int
	// PageIndex is the atlas page index for the generated font. Default 0.
	PageIndex uint16
	// MSDF enables multi-channel SDF generation.
	MSDF bool
}

SDFGenOptions configures SDF atlas generation.

func (*SDFGenOptions) Defaults 

func (o *SDFGenOptions) Defaults()

Defaults fills in zero-valued options with sensible defaults.

type TextBlock 

type TextBlock struct {
	// Content is the text string to render. Supports embedded newlines.
	Content string
	// Font is the font used for measurement and rendering.
	Font Font
	// FontSize is the desired display size in pixels. Applied at render time as a
	// scale factor (FontSize / Font.LineHeight()), independent of ScaleX/ScaleY.
	// Defaults to 16. Set to 0 or negative to use the font's native atlas size.
	FontSize float64
	// Align controls horizontal alignment within the wrap width or measured bounds.
	Align types.TextAlign
	// WrapWidth is the maximum line width in screen pixels before word wrapping.
	// Internally converted to atlas pixels via FontScale. Zero means no wrapping.
	WrapWidth float64
	// Color is the fill color for the text glyphs.
	Color types.Color
	// LineHeight overrides the font's default line height. Zero uses Font.LineHeight().
	LineHeight float64
	// Sharpness tightens the SDF edge smoothstep window. 0.0 = default rendering,
	// 1.0 = sharpest (half the default smoothing width). Values around 0.5–0.7
	// give crisp edges without aliasing on most display densities.
	Sharpness float64

	// Cached layout (unexported)
	LayoutDirty bool
	MeasuredW   float64
	MeasuredH   float64
	Lines       []TextLine // cached line layout

	// SDF rendering fields
	TextEffects   *TextEffects    // nil = no effects (plain fill)
	SdfVerts      []ebiten.Vertex // local-space glyph quads, rebuilt on layout change
	SdfInds       []uint16        // glyph index buffer
	SdfVertCount  int             // active vertex count
	SdfIndCount   int             // active index count
	SdfUniforms   map[string]any  // cached uniform map (allocated once, updated in place)
	SdfShader     *ebiten.Shader  // cached SDF vs MSDF shader selection
	UniformsDirty bool            // triggers uniform rebuild
}

TextBlock holds text content, formatting, and cached layout state.

func (*TextBlock) EffectiveLineHeight 

func (tb *TextBlock) EffectiveLineHeight() float64

EffectiveLineHeight returns the effective line height in atlas pixels.

func (*TextBlock) FontScale 

func (tb *TextBlock) FontScale() float64

FontScale returns the scale factor that maps native atlas pixels to display pixels. Returns 1.0 when FontSize is zero/negative or Font is nil. pixelFont should be true if the font is a PixelFont (integer scaling).

func (*TextBlock) Invalidate 

func (tb *TextBlock) Invalidate()

Invalidate invalidates the cached layout and SDF image, forcing recomputation on the next frame.

func (*TextBlock) Layout 

func (tb *TextBlock) Layout() []TextLine

Layout recomputes glyph positions if dirty. Returns the cached lines. Dispatches to LayoutSDF or LayoutPixel based on font type.

func (*TextBlock) LayoutPixel 

func (tb *TextBlock) LayoutPixel(glyphLookup func(r rune) (x, y uint16, found bool), page uint16, cellW, cellH, padLeft, padTop, advW, advH int)

LayoutPixel computes glyph positions for a pixel font (monospaced grid).

func (*TextBlock) LayoutSDF 

func (tb *TextBlock) LayoutSDF(glyphLookup func(r rune) *Glyph, kernLookup func(first, second rune) int16, page uint16)

LayoutSDF computes glyph positions for an SDF font (DistanceFieldFont).

func (*TextBlock) MeasureDisplay 

func (tb *TextBlock) MeasureDisplay(text string) (width, height float64)

MeasureDisplay returns the display-pixel width and height of the rendered text, accounting for FontSize scaling.

func (*TextBlock) RebuildLocalVerts 

func (tb *TextBlock) RebuildLocalVerts(lineHeight float64)

RebuildLocalVerts builds local-space vertex/index buffers from the laid-out glyph positions.

type TextEffects 

type TextEffects struct {
	OutlineWidth   float64 // 0 = no outline
	OutlineColor   types.Color
	GlowWidth      float64 // 0 = no glow
	GlowColor      types.Color
	ShadowOffset   types.Vec2 // (0,0) = no shadow
	ShadowColor    types.Color
	ShadowSoftness float64
}

TextEffects configures text effects (outline, glow, shadow) rendered in a single shader pass. All widths are in distance-field units (relative to the font's DistanceRange).

type TextLine 

type TextLine struct {
	Glyphs []GlyphPos
	Width  float64
}

TextLine stores one line of laid-out glyphs.

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.