api

Documentation

Overview

Package font provides an high level API to access Opentype font properties. See packages [loader] and tables for a lower level, more detailled API.

Index

• Constants
• func ProcessCmap(cmap tables.Cmap, os2FontPage tables.FontPage) (Cmap, UnicodeVariations, error)
• type BitmapFormat
• type BitmapSize
• type Cmap
• type CmapIter
• type CmapRuneRanger
• type FontExtents
• type FontID
• type GID
• type GlyphBitmap
• type GlyphData
• type GlyphExtents
• type GlyphOutline
  • func (o GlyphOutline) Sideways(yOffset float32)
• type GlyphSVG
• type LineMetric
• type Segment
  • func (s *Segment) ArgsSlice() []SegmentPoint
• type SegmentOp
• type SegmentPoint
  • func (pt *SegmentPoint) Move(dx, dy float32)
• type UnicodeVariations
  • func (t UnicodeVariations) GetGlyphVariant(r, selector rune) (GID, uint8)

Constants

const (
	// VariantNotFound is returned when the font does not have a glyph for
	// the given rune and selector.
	VariantNotFound = iota
	// VariantUseDefault is returned when the regular glyph should be used (ignoring the selector).
	VariantUseDefault
	// VariantFound is returned when the font has a variant for the glyph and selector.
	VariantFound
)

Functions

func ProcessCmap

func ProcessCmap(cmap tables.Cmap, os2FontPage tables.FontPage) (Cmap, UnicodeVariations, error)

ProcessCmap sanitize the given 'cmap' subtable, and select the best encoding when several subtables are given. When present, the variation selectors are returned. [os2FontPage] is used for legacy arabic fonts.

The returned values are copied from the input 'cmap', meaning they do not retain any reference on the input storage.

Types

type BitmapFormat

type BitmapFormat uint8

BitmapFormat identifies the format on the glyph raw data. Across the various font files, many formats may be encountered : black and white bitmaps, PNG, TIFF, JPG.

const (

	// The [GlyphBitmap.Data] slice stores a black or white (0/1)
	// bit image, whose length L satisfies
	// L * 8 >= [GlyphBitmap.Width] * [GlyphBitmap.Height]
	BlackAndWhite BitmapFormat
	// The [GlyphBitmap.Data] slice stores a PNG encoded image
	PNG
	// The [GlyphBitmap.Data] slice stores a JPG encoded image
	JPG
	// The [GlyphBitmap.Data] slice stores a TIFF encoded image
	TIFF
)

type BitmapSize

type BitmapSize struct {
	Height, Width uint16
	XPpem, YPpem  uint16
}

BitmapSize expose the size of bitmap glyphs. One font may contain several sizes.

type Cmap

type Cmap interface {
	// Iter returns a new iterator over the cmap
	// Multiple iterators may be used over the same cmap
	// The returned interface is garanted not to be nil.
	Iter() CmapIter

	// Lookup avoid the construction of a map and provides
	// an alternative when only few runes need to be fetched.
	// It returns a default value and false when no glyph is provided.
	Lookup(rune) (GID, bool)
}

Cmap stores a compact representation of a cmap, offering both on-demand rune lookup and full rune range. It is conceptually equivalent to a map[rune]GID, but is often implemented more efficiently.

type CmapIter

type CmapIter interface {
	// Next returns true if the iterator still has data to yield
	Next() bool

	// Char must be called only when `Next` has returned `true`
	Char() (rune, GID)
}

CmapIter is an interator over a Cmap.

type CmapRuneRanger

type CmapRuneRanger interface {
	// RuneRanges returns a list of (start, end) rune pairs, both included.
	// `dst` is an optional buffer used to reduce allocations
	RuneRanges(dst [][2]rune) [][2]rune
}

CmapRuneRanger is implemented by cmaps whose coverage is defined in terms of rune ranges

type FontExtents

type FontExtents struct {
	Ascender  float32 // Typographic ascender.
	Descender float32 // Typographic descender.
	LineGap   float32 // Suggested line spacing gap.
}

FontExtents exposes font-wide extent values, measured in font units. Note that typically ascender is positive and descender negative in coordinate systems that grow up.

type FontID

type FontID struct {
	File string // The filename or identifier of the font file.

	// The index of the face in a collection. It is always 0 for
	// single font files.
	Index uint16

	// For variable fonts, stores 1 + the instance index.
	// It is set to 0 to ignore variations, or for non variable fonts.
	Instance uint16
}

FontID represents an identifier of a font (possibly in a collection), and an optional variable instance.

type GID

type GID uint32

GID is used to identify glyphs in a font. It is mostly internal to the font and should not be confused with Unicode code points. Note that, despite Opentype font files using uint16, we choose to use uint32, to allow room for future extension.

const EmptyGlyph GID = math.MaxUint32

EmptyGlyph represents an invisible glyph, which should not be drawn, but whose advance and offsets should still be accounted for when rendering.

type GlyphBitmap

type GlyphBitmap struct {
	// The actual image content, whose interpretation depends
	// on the Format field.
	Data          []byte
	Format        BitmapFormat
	Width, Height int // number of columns and rows

	// Outline may be specified to be drawn with bitmap
	Outline *GlyphOutline
}

type GlyphData

type GlyphData interface {
	// contains filtered or unexported methods
}

GlyphData describe how to graw a glyph. It is either an GlyphOutline, GlyphSVG or GlyphBitmap.

type GlyphExtents

type GlyphExtents struct {
	XBearing float32 // Left side of glyph from origin
	YBearing float32 // Top side of glyph from origin
	Width    float32 // Distance from left to right side
	Height   float32 // Distance from top to bottom side
}

GlyphExtents exposes extent values, measured in font units. Note that height is negative in coordinate systems that grow up.

type GlyphOutline

type GlyphOutline struct {
	Segments []Segment
}

GlyphOutline exposes the path to draw for vector glyph. Coordinates are expressed in fonts units.

func (GlyphOutline) Sideways

func (o GlyphOutline) Sideways(yOffset float32)

Sideways updates the coordinates of the outline by applying a 90° clockwise rotation, and adding [yOffset] afterwards.

When used for vertical text, pass -Glyph.YOffset, converted in font units, as [yOffset] (a positive value to lift the glyph up).

type GlyphSVG

type GlyphSVG struct {
	// The SVG image content, decompressed if needed.
	// The actual glyph description is an SVG element
	// with id="glyph<GID>" (as in id="glyph12"),
	// and several glyphs may share the same Source
	Source []byte

	// According to the specification, a fallback outline
	// should be specified for each SVG glyphs
	Outline GlyphOutline
}

GlyphSVG is an SVG description for the glyph, as found in Opentype SVG table.

type LineMetric

type LineMetric uint8

LineMetric identifies one metric about the font.

const (
	// Distance above the baseline of the top of the underline.
	// Since most fonts have underline positions beneath the baseline, this value is typically negative.
	UnderlinePosition LineMetric = iota

	// Suggested thickness to draw for the underline.
	UnderlineThickness

	// Distance above the baseline of the top of the strikethrough.
	StrikethroughPosition

	// Suggested thickness to draw for the strikethrough.
	StrikethroughThickness

	SuperscriptEmYSize
	SuperscriptEmXOffset

	SubscriptEmYSize
	SubscriptEmYOffset
	SubscriptEmXOffset

	CapHeight
	XHeight
)

type Segment

type Segment struct {
	Op SegmentOp
	// Args is up to three (x, y) coordinates, depending on the
	// operation.
	// The Y axis increases up.
	Args [3]SegmentPoint
}

func (*Segment) ArgsSlice

func (s *Segment) ArgsSlice() []SegmentPoint

ArgsSlice returns the effective slice of points used (whose length is between 1 and 3).

type SegmentOp

type SegmentOp uint8

const (
	SegmentOpMoveTo SegmentOp = iota
	SegmentOpLineTo
	SegmentOpQuadTo
	SegmentOpCubeTo
)

type SegmentPoint

type SegmentPoint struct {
	X, Y float32 // expressed in fonts units
}

func (*SegmentPoint) Move

func (pt *SegmentPoint) Move(dx, dy float32)

Move translates the point.

type UnicodeVariations

type UnicodeVariations []variationSelector

func (UnicodeVariations) GetGlyphVariant

func (t UnicodeVariations) GetGlyphVariant(r, selector rune) (GID, uint8)

GetGlyphVariant returns the glyph index to used to [r] combined with [selector], with one of the tri-state flags [VariantNotFound, VariantUseDefault, VariantFound]