| // Copyright 2015 The Go Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style |
| // license that can be found in the LICENSE file. |
| |
| // Package font defines an interface for font faces, for drawing text on an |
| // image. |
| // |
| // Other packages provide font face implementations. For example, a truetype |
| // package would provide one based on .ttf font files. |
| package font // import "golang.org/x/image/font" |
| |
| import ( |
| "image" |
| "image/draw" |
| "io" |
| "unicode/utf8" |
| |
| "golang.org/x/image/math/fixed" |
| ) |
| |
| // TODO: who is responsible for caches (glyph images, glyph indices, kerns)? |
| // The Drawer or the Face? |
| |
| // Face is a font face. Its glyphs are often derived from a font file, such as |
| // "Comic_Sans_MS.ttf", but a face has a specific size, style, weight and |
| // hinting. For example, the 12pt and 18pt versions of Comic Sans are two |
| // different faces, even if derived from the same font file. |
| // |
| // A Face is not safe for concurrent use by multiple goroutines, as its methods |
| // may re-use implementation-specific caches and mask image buffers. |
| // |
| // To create a Face, look to other packages that implement specific font file |
| // formats. |
| type Face interface { |
| io.Closer |
| |
| // Glyph returns the draw.DrawMask parameters (dr, mask, maskp) to draw r's |
| // glyph at the sub-pixel destination location dot, and that glyph's |
| // advance width. |
| // |
| // It returns !ok if the face does not contain a glyph for r. This includes |
| // returning !ok for a fallback glyph (such as substituting a U+FFFD glyph |
| // or OpenType's .notdef glyph), in which case the other return values may |
| // still be non-zero. |
| // |
| // The contents of the mask image returned by one Glyph call may change |
| // after the next Glyph call. Callers that want to cache the mask must make |
| // a copy. |
| Glyph(dot fixed.Point26_6, r rune) ( |
| dr image.Rectangle, mask image.Image, maskp image.Point, advance fixed.Int26_6, ok bool) |
| |
| // GlyphBounds returns the bounding box of r's glyph, drawn at a dot equal |
| // to the origin, and that glyph's advance width. |
| // |
| // It returns !ok if the face does not contain a glyph for r. This includes |
| // returning !ok for a fallback glyph (such as substituting a U+FFFD glyph |
| // or OpenType's .notdef glyph), in which case the other return values may |
| // still be non-zero. |
| // |
| // The glyph's ascent and descent are equal to -bounds.Min.Y and |
| // +bounds.Max.Y. The glyph's left-side and right-side bearings are equal |
| // to bounds.Min.X and advance-bounds.Max.X. A visual depiction of what |
| // these metrics are is at |
| // https://developer.apple.com/library/archive/documentation/TextFonts/Conceptual/CocoaTextArchitecture/Art/glyphterms_2x.png |
| GlyphBounds(r rune) (bounds fixed.Rectangle26_6, advance fixed.Int26_6, ok bool) |
| |
| // GlyphAdvance returns the advance width of r's glyph. |
| // |
| // It returns !ok if the face does not contain a glyph for r. This includes |
| // returning !ok for a fallback glyph (such as substituting a U+FFFD glyph |
| // or OpenType's .notdef glyph), in which case the other return values may |
| // still be non-zero. |
| GlyphAdvance(r rune) (advance fixed.Int26_6, ok bool) |
| |
| // Kern returns the horizontal adjustment for the kerning pair (r0, r1). A |
| // positive kern means to move the glyphs further apart. |
| Kern(r0, r1 rune) fixed.Int26_6 |
| |
| // Metrics returns the metrics for this Face. |
| Metrics() Metrics |
| |
| // TODO: ColoredGlyph for various emoji? |
| // TODO: Ligatures? Shaping? |
| } |
| |
| // 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 Metrics struct { |
| // Height is the recommended amount of vertical space between two lines of |
| // text. |
| Height fixed.Int26_6 |
| |
| // Ascent is the distance from the top of a line to its baseline. |
| Ascent fixed.Int26_6 |
| |
| // Descent is the distance from the bottom of a line to its baseline. The |
| // value is typically positive, even though a descender goes below the |
| // baseline. |
| Descent fixed.Int26_6 |
| |
| // XHeight is the distance from the top of non-ascending lowercase letters |
| // to the baseline. |
| XHeight fixed.Int26_6 |
| |
| // CapHeight is the distance from the top of uppercase letters to the |
| // baseline. |
| CapHeight fixed.Int26_6 |
| |
| // CaretSlope is the slope of a caret as a vector with the Y axis pointing up. |
| // The slope {0, 1} is the vertical caret. |
| CaretSlope image.Point |
| } |
| |
| // Drawer draws text on a destination image. |
| // |
| // A Drawer is not safe for concurrent use by multiple goroutines, since its |
| // Face is not. |
| type Drawer struct { |
| // Dst is the destination image. |
| Dst draw.Image |
| // Src is the source image. |
| Src image.Image |
| // Face provides the glyph mask images. |
| Face Face |
| // Dot is the baseline location to draw the next glyph. The majority of the |
| // affected pixels will be above and to the right of the dot, but some may |
| // be below or to the left. For example, drawing a 'j' in an italic face |
| // may affect pixels below and to the left of the dot. |
| Dot fixed.Point26_6 |
| |
| // TODO: Clip image.Image? |
| // TODO: SrcP image.Point for Src images other than *image.Uniform? How |
| // does it get updated during DrawString? |
| } |
| |
| // TODO: should DrawString return the last rune drawn, so the next DrawString |
| // call can kern beforehand? Or should that be the responsibility of the caller |
| // if they really want to do that, since they have to explicitly shift d.Dot |
| // anyway? What if ligatures span more than two runes? What if grapheme |
| // clusters span multiple runes? |
| // |
| // TODO: do we assume that the input is in any particular Unicode Normalization |
| // Form? |
| // |
| // TODO: have DrawRunes(s []rune)? DrawRuneReader(io.RuneReader)?? If we take |
| // io.RuneReader, we can't assume that we can rewind the stream. |
| // |
| // TODO: how does this work with line breaking: drawing text up until a |
| // vertical line? Should DrawString return the number of runes drawn? |
| |
| // DrawBytes draws s at the dot and advances the dot's location. |
| // |
| // It is equivalent to DrawString(string(s)) but may be more efficient. |
| func (d *Drawer) DrawBytes(s []byte) { |
| prevC := rune(-1) |
| for len(s) > 0 { |
| c, size := utf8.DecodeRune(s) |
| s = s[size:] |
| if prevC >= 0 { |
| d.Dot.X += d.Face.Kern(prevC, c) |
| } |
| dr, mask, maskp, advance, _ := d.Face.Glyph(d.Dot, c) |
| if !dr.Empty() { |
| draw.DrawMask(d.Dst, dr, d.Src, image.Point{}, mask, maskp, draw.Over) |
| } |
| d.Dot.X += advance |
| prevC = c |
| } |
| } |
| |
| // DrawString draws s at the dot and advances the dot's location. |
| func (d *Drawer) DrawString(s string) { |
| prevC := rune(-1) |
| for _, c := range s { |
| if prevC >= 0 { |
| d.Dot.X += d.Face.Kern(prevC, c) |
| } |
| dr, mask, maskp, advance, _ := d.Face.Glyph(d.Dot, c) |
| if !dr.Empty() { |
| draw.DrawMask(d.Dst, dr, d.Src, image.Point{}, mask, maskp, draw.Over) |
| } |
| d.Dot.X += advance |
| prevC = c |
| } |
| } |
| |
| // BoundBytes returns the bounding box of s, drawn at the drawer dot, as well as |
| // the advance. |
| // |
| // It is equivalent to BoundBytes(string(s)) but may be more efficient. |
| func (d *Drawer) BoundBytes(s []byte) (bounds fixed.Rectangle26_6, advance fixed.Int26_6) { |
| bounds, advance = BoundBytes(d.Face, s) |
| bounds.Min = bounds.Min.Add(d.Dot) |
| bounds.Max = bounds.Max.Add(d.Dot) |
| return |
| } |
| |
| // BoundString returns the bounding box of s, drawn at the drawer dot, as well |
| // as the advance. |
| func (d *Drawer) BoundString(s string) (bounds fixed.Rectangle26_6, advance fixed.Int26_6) { |
| bounds, advance = BoundString(d.Face, s) |
| bounds.Min = bounds.Min.Add(d.Dot) |
| bounds.Max = bounds.Max.Add(d.Dot) |
| return |
| } |
| |
| // MeasureBytes returns how far dot would advance by drawing s. |
| // |
| // It is equivalent to MeasureString(string(s)) but may be more efficient. |
| func (d *Drawer) MeasureBytes(s []byte) (advance fixed.Int26_6) { |
| return MeasureBytes(d.Face, s) |
| } |
| |
| // MeasureString returns how far dot would advance by drawing s. |
| func (d *Drawer) MeasureString(s string) (advance fixed.Int26_6) { |
| return MeasureString(d.Face, s) |
| } |
| |
| // BoundBytes returns the bounding box of s with f, drawn at a dot equal to the |
| // origin, as well as the advance. |
| // |
| // It is equivalent to BoundString(string(s)) but may be more efficient. |
| func BoundBytes(f Face, s []byte) (bounds fixed.Rectangle26_6, advance fixed.Int26_6) { |
| prevC := rune(-1) |
| for len(s) > 0 { |
| c, size := utf8.DecodeRune(s) |
| s = s[size:] |
| if prevC >= 0 { |
| advance += f.Kern(prevC, c) |
| } |
| b, a, _ := f.GlyphBounds(c) |
| if !b.Empty() { |
| b.Min.X += advance |
| b.Max.X += advance |
| bounds = bounds.Union(b) |
| } |
| advance += a |
| prevC = c |
| } |
| return |
| } |
| |
| // BoundString returns the bounding box of s with f, drawn at a dot equal to the |
| // origin, as well as the advance. |
| func BoundString(f Face, s string) (bounds fixed.Rectangle26_6, advance fixed.Int26_6) { |
| prevC := rune(-1) |
| for _, c := range s { |
| if prevC >= 0 { |
| advance += f.Kern(prevC, c) |
| } |
| b, a, _ := f.GlyphBounds(c) |
| if !b.Empty() { |
| b.Min.X += advance |
| b.Max.X += advance |
| bounds = bounds.Union(b) |
| } |
| advance += a |
| prevC = c |
| } |
| return |
| } |
| |
| // MeasureBytes returns how far dot would advance by drawing s with f. |
| // |
| // It is equivalent to MeasureString(string(s)) but may be more efficient. |
| func MeasureBytes(f Face, s []byte) (advance fixed.Int26_6) { |
| prevC := rune(-1) |
| for len(s) > 0 { |
| c, size := utf8.DecodeRune(s) |
| s = s[size:] |
| if prevC >= 0 { |
| advance += f.Kern(prevC, c) |
| } |
| a, _ := f.GlyphAdvance(c) |
| advance += a |
| prevC = c |
| } |
| return advance |
| } |
| |
| // MeasureString returns how far dot would advance by drawing s with f. |
| func MeasureString(f Face, s string) (advance fixed.Int26_6) { |
| prevC := rune(-1) |
| for _, c := range s { |
| if prevC >= 0 { |
| advance += f.Kern(prevC, c) |
| } |
| a, _ := f.GlyphAdvance(c) |
| advance += a |
| prevC = c |
| } |
| return advance |
| } |
| |
| // Hinting selects how to quantize a vector font's glyph nodes. |
| // |
| // Not all fonts support hinting. |
| type Hinting int |
| |
| const ( |
| HintingNone Hinting = iota |
| HintingVertical |
| HintingFull |
| ) |
| |
| // Stretch selects a normal, condensed, or expanded face. |
| // |
| // Not all fonts support stretches. |
| type Stretch int |
| |
| const ( |
| StretchUltraCondensed Stretch = -4 |
| StretchExtraCondensed Stretch = -3 |
| StretchCondensed Stretch = -2 |
| StretchSemiCondensed Stretch = -1 |
| StretchNormal Stretch = +0 |
| StretchSemiExpanded Stretch = +1 |
| StretchExpanded Stretch = +2 |
| StretchExtraExpanded Stretch = +3 |
| StretchUltraExpanded Stretch = +4 |
| ) |
| |
| // Style selects a normal, italic, or oblique face. |
| // |
| // Not all fonts support styles. |
| type Style int |
| |
| const ( |
| StyleNormal Style = iota |
| StyleItalic |
| StyleOblique |
| ) |
| |
| // Weight selects a normal, light or bold face. |
| // |
| // Not all fonts support weights. |
| // |
| // The named Weight constants (e.g. WeightBold) correspond to CSS' common |
| // weight names (e.g. "Bold"), but the numerical values differ, so that in Go, |
| // the zero value means to use a normal weight. For the CSS names and values, |
| // see https://developer.mozilla.org/en/docs/Web/CSS/font-weight |
| type Weight int |
| |
| const ( |
| WeightThin Weight = -3 // CSS font-weight value 100. |
| WeightExtraLight Weight = -2 // CSS font-weight value 200. |
| WeightLight Weight = -1 // CSS font-weight value 300. |
| WeightNormal Weight = +0 // CSS font-weight value 400. |
| WeightMedium Weight = +1 // CSS font-weight value 500. |
| WeightSemiBold Weight = +2 // CSS font-weight value 600. |
| WeightBold Weight = +3 // CSS font-weight value 700. |
| WeightExtraBold Weight = +4 // CSS font-weight value 800. |
| WeightBlack Weight = +5 // CSS font-weight value 900. |
| ) |