giorune

README

giorune

giorune is about the layout and painting of a rune using the harfbuzz shaper and gio's painting capabilities without using gio/text. While evaluating gio it turned out that tibetan scripture is typeset wrongly. Tashi delek as it should be

screenshot correct typesetting

and as it set by gio:

screenshot incorrect gio-typesetting

I.e. the vocals superscribe the wrong positions. Since I'm not smart enough to understand the ins and outs of gio/text I wondered if I might be smart enough to do something like a reference implementation of gio/text.

The implementation of giorune and its command is test driven and guided by the ideas of "easy things should be easy ..." and "premature optimization is the root of all evil".

There is a demo which shows a sequence of runes with a black background and cyan foreground vertically and horizontally centered. I'm not sure what would be the most simple gio-only-code to achieve the same thing.

go run git.sr.ht/~slukits/giorune/cmd/demo/center@latest

An other demo shows a widget whose font size adapts to the window size.

go run git.sr.ht/~slukits/giorune/cmd/demo/fitting@latest

Documentation

Index

• Constants
• Variables
• func NewFontLibForEmbedded() *internal.FontLib
• type Faces
  • func ReadFontsDir(d string, lib FontLib) (Faces, error)
  • func (ff Faces) SelectFace(family string, weight metadata.Weight, style metadata.Style) (*font.Face, error)
• type Font
  • func Fitting(fnt *Font, dim image.Point, ll ...string) *Font
  • func HorizontallyFitting(fnt *Font, width int, ss ...string) *Font
  • func VerticallyFitting(fnt *Font, height int, ll ...string) *Font
  • func (f *Font) Center(r rune, viewport image.Rectangle) image.Rectangle
  • func (f *Font) Clone() *Font
  • func (f *Font) Dim(r rune) image.Point
  • func (f *Font) Len() int
  • func (f *Font) Paint(r rune, to *op.Ops, at image.Point)
  • func (f *Font) Path(r rune) clip.PathSpec
  • func (f *Font) Rune(r rune) R
• type FontLib
• type Option
  • func BGColor(c color.NRGBA) Option
  • func FGColor(c color.NRGBA) Option
• type R
  • func (r R) Dim() image.Point
• type Sequence
  • func (s *Sequence) Center(rr string, viewport image.Rectangle) image.Rectangle
  • func (s *Sequence) Clone() *Sequence
  • func (s *Sequence) Dim(rr string) (pt image.Point, ascent int)
  • func (s *Sequence) Paint(rr string, to *op.Ops, at image.Point, oo ...Option) (dim image.Point, ascent int)

Constants

const EmbeddedFontsDir = "fonts"

EmbeddedFontsDir is the directory in the embedded file system holding the embedded fonts.

Variables

var (
	// FaceDflt is the font face of a zero giorune.Font and is set in
	// giorune.init.
	FaceDflt *font.Face

	// SizeDflt is a zero giorune.Font's size.
	SizeDflt = 14
)

var (
	Black   = color.NRGBA{A: 255}
	Red     = color.NRGBA{R: 255, A: 255}
	Green   = color.NRGBA{G: 255, A: 255}
	Blue    = color.NRGBA{B: 255, A: 255}
	Yellow  = color.NRGBA{R: 255, G: 255, A: 255}
	Magenta = color.NRGBA{R: 255, B: 255, A: 255}
	Cyan    = color.NRGBA{G: 255, B: 255, A: 255}
	White   = color.NRGBA{R: 255, G: 255, B: 255, A: 255}
)

var ErrFaceNotFound = errors.New("view: select face: not found")

ErrFaceNotFound is returned by Faces.SelectFace if no font with given arguments can be found.

var FontsFS embed.FS

Functions

func NewFontLibForEmbedded

func NewFontLibForEmbedded() *internal.FontLib

NewFontLibForEmbedded returns an implementation of [view.FontLib] with an adapted [FontLib.ReadDir] method which operates on embedded [view.FontsFS] which has always slashes as directory separator no matter which os.

Types

type Faces

type Faces map[*font.Face]metadata.Description

A Faces instance holds open-type font-faces and their description.

var Embedded Faces

Embedded are the font-faces along with their descriptions which are embedded with this package. The Embedded font-faces are set by this package's init function.

func ReadFontsDir

func ReadFontsDir(d string, lib FontLib) (Faces, error)

ReadFontsDir utilizes given font-lib lib to read from given directory d all *.ttf files and parses them into returned faces. Note to read fonts of embedded file system provide giorune.NewFontLibForEmbedded otherwise lib may be nil because its default-implementation will do.

func (Faces) SelectFace

func (ff Faces) SelectFace(
	family string, weight metadata.Weight, style metadata.Style,
) (*font.Face, error)

SelectFace returns the first face which matches all three of the given font family its given weight and style. If no font with given Arguments is found an ErrFaceNotFound-error is returned.

type Font

type Font struct {
	Lib FontLib

	// Face wrapping the actual font and is used to shape the runes.
	// Face defaults to FaceDflt.  A change in face clears the font's
	// caches.
	Face *font.Face

	// Size of the font.  Size defaults to SizeDflt.  A change in size
	// clears the font's caches.
	Size int

	// Metric provides the device dependent density-independent and
	// scale-independent pixels per dp/sp; These values default to 1 and
	// are typically set from a gio FrameEvent.  An change in metric
	// clears the font's caches.
	Metric unit.Metric

	// Leading in percent it defaults to 3% since we need little air at
	// the bottom to have the glyphs not cut of at the bottom.
	Leading int
	// contains filtered or unexported fields
}

A Font is the starting point to layout or paint a given rune respectively its glyph in set font face. A zero Font is ready to use. A once used font-instance may not be copied. A font's metric you typically set from a [app.FrameEvent]. Note a Font caches layout and painting of a rune respectively its graphical representation as a glyph. This cache is cleared when ever Font.Face, Font.Size or Font.Metric changes.

func Fitting

func Fitting(fnt *Font, dim image.Point, ll ...string) *Font

Fitting returns given Font fnt in the size that given lines ll fit into given dimension dim or the size is 1. Fitting returns nil if one of the given arguments is zero (or less).

func HorizontallyFitting

func HorizontallyFitting(fnt *Font, width int, ss ...string) *Font

HorizontallyFitting returns given Font fnt in the size that given strings ss fit into given width or the size is 1. HorizontallyFitting returns nil if one of the given arguments is zero (or less).

func VerticallyFitting

func VerticallyFitting(fnt *Font, height int, ll ...string) *Font

VerticallyFitting returns given Font fnt in the size that given lines ll fit into given height or the size is 1. VerticallyFitting returns nil if one of given arguments is zero (or less).

func (*Font) Center

func (f *Font) Center(r rune, viewport image.Rectangle) image.Rectangle

Center given rune r's dimensions horizontally and vertically within given viewport.

func (*Font) Clone

func (f *Font) Clone() *Font

Clone a font since a harfbuzz-shaper is not concurrency save.

func (*Font) Dim

func (f *Font) Dim(r rune) image.Point

Dim returns width and height of given rune.

func (*Font) Len

func (f *Font) Len() int

Len returns the number of cached runes.

func (*Font) Paint

func (f *Font) Paint(r rune, to *op.Ops, at image.Point)

Paint given rune to given operations stack *to* at given point *at* which is the upper left corner of the runes bounding box. I.e. the point 0/0 would paint given rune on "the beginning" at the "first line".

func (*Font) Path

func (f *Font) Path(r rune) clip.PathSpec

Path calculates the path-spec of given rune r's glyph in given font f.

func (*Font) Rune

func (f *Font) Rune(r rune) R

Rune maps given rune r to an R-instance which holds layout and painting information relative to given Font f and its set Font.Size and Font.Metric.

type FontLib

type FontLib interface {

	// ReadDir must provide the directory entries of a given directory.
	ReadDir(string) ([]fs.DirEntry, error)

	// ReadFile must provide the content of given file.
	ReadFile(string) ([]byte, error)

	// NewFont is expected to parse from a given bytes sequence a font
	// and its meta data.
	NewFont([]byte) (*font.Font, metadata.Description, error)

	// Join connects given elements to a returned path.
	Join(...string) string

	// Shape maps runes to glyphs.
	Shape(shaping.Input) shaping.Output
}

FontLib provides stdlib/third party lib functionality which may fail or is interesting to adapt/mock for other reasons. Note where ever giorune wants an implementation of FontLib it is optional and defaults to an internal default implementation. Is there a specific implementation needed for a specific use-case there is typically a constructor for that purpose around like giorune.NewFontLibForEmbedded.

type Option

type Option func(*op.Ops)

Option is typically a painting option adding what is other places called "material" to a painting operation.

func BGColor

func BGColor(c color.NRGBA) Option

BGColor fills a paint operation's clipping area with given color c. NOTE this executes gio-internal a paint.ColorOp operation i.e. one of the next options should be a FGColor option if something distinguishable should be painted on that background.

func FGColor

func FGColor(c color.NRGBA) Option

FGColor sets the painting color; typically added to paint operation after a potential BGColor.

type R

type R struct {
	HasGlyphs bool
	Ascent    fixed.Int26_6
	Descent   fixed.Int26_6
	shaping.Glyph
	// contains filtered or unexported fields
}

A R-instance holds layout and painting information of a rune's graphical representation relative to a given giorune.Font.

func (R) Dim

func (r R) Dim() image.Point

Dim returns the width and height of given rune.

type Sequence

type Sequence struct {

	// Font used to calculate dimensions of rune sequences and paint
	// them.
	Font *Font
	// contains filtered or unexported fields
}

Sequence may be used for layout calculations and paintings of rune sequences. Note as of now only vertical sequence from left to right is supported without ligatures.

func (*Sequence) Center

func (s *Sequence) Center(
	rr string, viewport image.Rectangle,
) image.Rectangle

Center given string dimensions horizontally and vertically within given viewport.

func (*Sequence) Clone

func (s *Sequence) Clone() *Sequence

Clone given Sequence s, i.e. returned sequence will have a different harfbuzz shaper instance which might be necessary since it is not concurrency save.

func (*Sequence) Dim

func (s *Sequence) Dim(rr string) (pt image.Point, ascent int)

Dim returns the width and height of given rune sequence rr and the biggest ascent. Note if a sequence contains runes with varying baselines the painting of that sequence will probably not turn out as desired.

func (*Sequence) Paint

func (s *Sequence) Paint(
	rr string, to *op.Ops, at image.Point, oo ...Option,
) (dim image.Point, ascent int)

Paint given rune-sequence rr to given operations list starting at at.X and at.Y+asc whereas the asc the biggest ascent in rr is; i.e. at.Y+asc is interpreted as baseline. I.e. having scriptures with different baselines in rr will most likely not yield the desired result. Given options oo are evaluated before rr is painted.