Documentation

Overview

    Package text implements efficient text drawing for the Pixel library.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var ASCII []rune

      ASCII is a set of all ASCII runes. These runes are codepoints from 32 to 127 inclusive.

      Functions

      func RangeTable

      func RangeTable(table *unicode.RangeTable) []rune

        RangeTable takes a *unicode.RangeTable and generates a set of runes contained within that RangeTable.

        Types

        type Atlas

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

          Atlas is a set of pre-drawn glyphs of a fixed set of runes. This allows for efficient text drawing.

          var Atlas7x13 *Atlas

            Atlas7x13 is an Atlas using basicfont.Face7x13 with the ASCII rune set

            func NewAtlas

            func NewAtlas(face font.Face, runeSets ...[]rune) *Atlas

              NewAtlas creates a new Atlas containing glyphs of the union of the given sets of runes (plus unicode.ReplacementChar) from the given font face.

              Creating an Atlas is rather expensive, do not create a new Atlas each frame.

              Do not destroy or close the font.Face after creating the Atlas. Atlas still uses it.

              func (*Atlas) Ascent

              func (a *Atlas) Ascent() float64

                Ascent returns the distance from the top of the line to the baseline.

                func (*Atlas) Contains

                func (a *Atlas) Contains(r rune) bool

                  Contains reports wheter r in contained within the Atlas.

                  func (*Atlas) Descent

                  func (a *Atlas) Descent() float64

                    Descent returns the distance from the baseline to the bottom of the line.

                    func (*Atlas) DrawRune

                    func (a *Atlas) DrawRune(prevR, r rune, dot pixel.Vec) (rect, frame, bounds pixel.Rect, newDot pixel.Vec)

                      DrawRune returns parameters necessary for drawing a rune glyph.

                      Rect is a rectangle where the glyph should be positioned. Frame is the glyph frame inside the Atlas's Picture. NewDot is the new position of the dot.

                      func (*Atlas) Glyph

                      func (a *Atlas) Glyph(r rune) Glyph

                        Glyph returns the description of r within the Atlas.

                        func (*Atlas) Kern

                        func (a *Atlas) Kern(r0, r1 rune) float64

                          Kern returns the kerning distance between runes r0 and r1. Positive distance means that the glyphs should be further apart.

                          func (*Atlas) LineHeight

                          func (a *Atlas) LineHeight() float64

                            LineHeight returns the recommended vertical distance between two lines of text.

                            func (*Atlas) Picture

                            func (a *Atlas) Picture() pixel.Picture

                              Picture returns the underlying Picture containing an arrangement of all the glyphs contained within the Atlas.

                              type Glyph

                              type Glyph struct {
                              	Dot     pixel.Vec
                              	Frame   pixel.Rect
                              	Advance float64
                              }

                                Glyph describes one glyph in an Atlas.

                                type Text

                                type Text struct {
                                	// Orig specifies the text origin, usually the top-left dot position. Dot is always aligned
                                	// to Orig when writing newlines.
                                	Orig pixel.Vec
                                
                                	// Dot is the position where the next character will be written. Dot is automatically moved
                                	// when writing to a Text object, but you can also manipulate it manually
                                	Dot pixel.Vec
                                
                                	// Color is the color of the text that is to be written. Defaults to white.
                                	Color color.Color
                                
                                	// LineHeight is the vertical distance between two lines of text.
                                	//
                                	// Example:
                                	//   txt.LineHeight = 1.5 * txt.Atlas().LineHeight()
                                	LineHeight float64
                                
                                	// TabWidth is the horizontal tab width. Tab characters will align to the multiples of this
                                	// width.
                                	//
                                	// Example:
                                	//   txt.TabWidth = 8 * txt.Atlas().Glyph(' ').Advance
                                	TabWidth float64
                                	// contains filtered or unexported fields
                                }

                                  Text allows for effiecient and convenient text drawing.

                                  To create a Text object, use the New constructor:

                                  txt := text.New(pixel.ZV, text.NewAtlas(face, text.ASCII))
                                  

                                  As suggested by the constructor, a Text object is always associated with one font face and a fixed set of runes. For example, the Text we created above can draw text using the font face contained in the face variable and is capable of drawing ASCII characters.

                                  Here we create a Text object which can draw ASCII and Katakana characters:

                                  txt := text.New(0, text.NewAtlas(face, text.ASCII, text.RangeTable(unicode.Katakana)))
                                  

                                  Similarly to IMDraw, Text functions as a buffer. It implements io.Writer interface, so writing text to it is really simple:

                                  fmt.Print(txt, "Hello, world!")
                                  

                                  Newlines, tabs and carriage returns are supported.

                                  Finally, if we want the written text to show up on some other Target, we can draw it:

                                  txt.Draw(target)
                                  

                                  Text exports two important fields: Orig and Dot. Dot is the position where the next character will be written. Dot is automatically moved when writing to a Text object, but you can also manipulate it manually. Orig specifies the text origin, usually the top-left dot position. Dot is always aligned to Orig when writing newlines. The Clear method resets the Dot to Orig.

                                  func New

                                  func New(orig pixel.Vec, atlas *Atlas) *Text

                                    New creates a new Text capable of drawing runes contained in the provided Atlas. Orig and Dot will be initially set to orig.

                                    Here we create a Text capable of drawing ASCII characters using the Go Regular font.

                                    ttf, err := truetype.Parse(goregular.TTF)
                                    if err != nil {
                                        panic(err)
                                    }
                                    face := truetype.NewFace(ttf, &truetype.Options{
                                        Size: 14,
                                    })
                                    txt := text.New(orig, text.NewAtlas(face, text.ASCII))
                                    

                                    func (*Text) Atlas

                                    func (txt *Text) Atlas() *Atlas

                                      Atlas returns the underlying Text's Atlas containing all of the pre-drawn glyphs. The Atlas is also useful for getting values such as the recommended line height.

                                      func (*Text) Bounds

                                      func (txt *Text) Bounds() pixel.Rect

                                        Bounds returns the bounding box of the text currently written to the Text excluding whitespace.

                                        If the Text is empty, a zero rectangle is returned.

                                        func (*Text) BoundsOf

                                        func (txt *Text) BoundsOf(s string) pixel.Rect

                                          BoundsOf returns the bounding box of s if it was to be written to the Text right now.

                                          func (*Text) Clear

                                          func (txt *Text) Clear()

                                            Clear removes all written text from the Text. The Dot field is reset to Orig.

                                            func (*Text) Draw

                                            func (txt *Text) Draw(t pixel.Target, matrix pixel.Matrix)

                                              Draw draws all text written to the Text to the provided Target. The text is transformed by the provided Matrix.

                                              This method is equivalent to calling DrawColorMask with nil color mask.

                                              If there's a lot of text written to the Text, changing a matrix or a color mask often might hurt performance. Consider using your Target's SetMatrix or SetColorMask methods if available.

                                              func (*Text) DrawColorMask

                                              func (txt *Text) DrawColorMask(t pixel.Target, matrix pixel.Matrix, mask color.Color)

                                                DrawColorMask draws all text written to the Text to the provided Target. The text is transformed by the provided Matrix and masked by the provided color mask.

                                                If there's a lot of text written to the Text, changing a matrix or a color mask often might hurt performance. Consider using your Target's SetMatrix or SetColorMask methods if available.

                                                func (*Text) Write

                                                func (txt *Text) Write(p []byte) (n int, err error)

                                                  Write writes a slice of bytes to the Text. This method never fails, always returns len(p), nil.

                                                  func (*Text) WriteByte

                                                  func (txt *Text) WriteByte(c byte) error

                                                    WriteByte writes a byte to the Text. This method never fails, always returns nil.

                                                    Writing a multi-byte rune byte-by-byte is perfectly supported.

                                                    func (*Text) WriteRune

                                                    func (txt *Text) WriteRune(r rune) (n int, err error)

                                                      WriteRune writes a rune to the Text. This method never fails, always returns utf8.RuneLen(r), nil.

                                                      func (*Text) WriteString

                                                      func (txt *Text) WriteString(s string) (n int, err error)

                                                        WriteString writes a string to the Text. This method never fails, always returns len(s), nil.