-
Notifications
You must be signed in to change notification settings - Fork 245
Typing text on the screen
In this part, we're going to learn how to draw text using various fonts and how to get text input from the user.
In order to draw any text, a font is required. You might have already noticed, that Pixel tries to be very compatible with standard Go packages, such as "image"
, "image/color"
, "time"
, and so on. Unfortunately, there's no font package in the Go standard library.
However, there's a semi-standard package called "golang.org/x/image/font"
. I must say, this package deserves to be considered standard, it's remarkably well designed and easy to use. It defines one important interface: font.Face. Anything implementing this interface is a font object. There are many implementations of this interface found, for example, in "golang.org/x/image/font/basicfont"
, "golang.org/x/image/font/inconsolata"
and "github.com/golang/freetype/truetype"
.
As you can see, Go community has already done a great deal of work regarding fonts. Pixel makes use of this work, thus supporting large variety of fonts out of the box. Let's see how we do it!
Pixel has a text, which we can use to draw text to any Target. Let's take a look and use it! As usual, we'll start off with the basic Pixel boilerplate:
package main
import (
"github.com/faiface/pixel"
"github.com/faiface/pixel/pixelgl"
)
func run() {
cfg := pixelgl.WindowConfig{
Title: "Pixel Rocks!",
Bounds: pixel.R(0, 0, 1024, 768),
VSync: true,
}
win, err := pixelgl.NewWindow(cfg)
if err != nil {
panic(err)
}
for !win.Closed() {
win.Update()
}
}
func main() {
pixelgl.Run(run)
}
Now, we need to import the "github.com/faiface/pixel/text"
package:
import (
"github.com/faiface/pixel"
"github.com/faiface/pixel/pixelgl"
"github.com/faiface/pixel/text"
)
Before we can draw any text, we need to create a font atlas. What is that? To achieve the maximum performance, it's best to pre-draw the characters we want to use to an off-screen picture and then draw the characters straight from that picture. Drawing directly from the font.Face
object would be too slow. This is exactly what Atlas is. It's a collection of pre-drawn characters, ready to use for drawing.
An Atlas
is created by the text.NewAtlas constructor. The constructor takes a font.Face
, that's obvious. Then is takes an arbitrary number of, so called "rune sets". A rune set is just a slice of runes. The Atlas
will contain all of the runes provided in all of the sets. This might be a bit confusing, so let's see an example:
atlas := text.NewAtlas(
basicfont.Face7x13,
[]rune{'0', '1', '2', '3', '4', '5', '6', '7', '8', '9'},
)
Here we create an Atlas
from the basicfont.Face7x13 font face, which contains all digits. So, with this atlas, we're able to draw digits. Simple? Let's take a look at another example:
atlas := text.NewAtlas(
basicfont.Face7x13,
[]rune{'a', 'b', 'c'},
[]rune{'A', 'B', 'C'},
)
Here we supply two rune sets instead of one. The atlas will contain both lower-case a
, b
, c
letters, as well as upper-case ones. Here's another example:
atlas := text.NewAtlas(basicfont.Face7x13, text.ASCII)
This time, we use text.ASCII, which is the set of all ASCII runes defined in the text
package. One more example:
atlas := text.NewAtlas(face, text.ASCII, text.RangeTable(unicode.Latin))
This time, we don't use the basicfont.Face7x13
face, instead we use a font contained in some face
variable, which could be an arbitrary truetype font for example (we'll see how to load truetype fonts in a minute). Now, our atlas contains not only ASCII characters, but also all Latin characters. Function text.RangeTable converts an arbitrary unicode.RangeTable to a set of runes. The standard unicode package contains a large variety of useful Unicode range tables.
Now that we understand all of this, let's go ahead and create an atlas!
cfg := pixelgl.WindowConfig{
Title: "Pixel Rocks!",
Bounds: pixel.R(0, 0, 1024, 768),
VSync: true,
}
win, err := pixelgl.NewWindow(cfg)
if err != nil {
panic(err)
}
basicAtlas := text.NewAtlas(basicfont.Face7x13, text.ASCII)
For now, we'll use the font defined in the basicfont package, because it's the most accessible one, as we can see.
Now, how do we actually draw a text? For that we have the Text type. You can think of the Text
type as a sprite containing text. Contrary to a sprite, we can dynamically write new text to a Text
object as we'll see. So, without further ado, let's create a `Text object using the text.New constructor.
basicAtlas := text.NewAtlas(basicfont.Face7x13, text.ASCII)
basicTxt := text.New(pixel.V(100, 500), basicAtlas)
The text.New
constructor takes two arguments: the orig
position and an atlas. The atlas is obvious. What is the "orig" position? It's the position where we want to start drawing our text. We chose pixel.V(100, 500)
, so the text will start at that position. So, let's write some text:
basicAtlas := text.NewAtlas(basicfont.Face7x13, text.ASCII)
basicTxt := text.New(pixel.V(100, 500), basicAtlas)
fmt.Fprintln(basicTxt, "Hello, text!")
fmt.Fprintln(basicTxt, "I support multiple lines!")
fmt.Fprintf(basicTxt, "And I'm an %s, yay!", "io.Writer")
And draw the result to the screen:
for !win.Closed() {
win.Clear(colornames.Black)
basicTxt.Draw(win, pixel.IM)
win.Update()
}
And heya, here we go!
That text is a bit small, let's scale it up!
for !win.Closed() {
win.Clear(colornames.Black)
basicTxt.Draw(win, pixel.IM.Scaled(basicTxt.Orig, 4))
win.Update()
}
Much better!
We've got something running, we see text on the screen, but we don't fully understand how it works. In the constructor, we were setting a mysterious orig
argument:
basicTxt := text.New(pixel.V(100, 500), basicAtlas)
If we a look at the documentation of the Text struct, we see that it actually has an Orig
field. If we check the value of this field, we find that it's equal to the value we passed in the constructor.
Before we fully explain what this field does, we need to take a look at another important field: Dot
. Dot
is simple: it's the position of the next character. When we write some string to the Text
object, Dot
will be automatically moved accordingly. Initially, Dot
is set to the same value as Orig
. As we write text, Dot
moves. We can also adjust it manually, if we so desire.
To understand Dot
better, try writing small chunks of text to the Text
object and print the value of Dot
after each chunk.
What happens when we write a newline? Easy, Dot
moves one line down and aligns with Orig
. This is the most important use of Orig
. Notice, that only Orig
's X coordinate is used to align after newline. In fact, Text
never really uses it's Y coordinate.
Try changing the value of Orig
after each newline.
Another important use of Orig
is this:
txt.Clear()
txt.Dot = txt.Orig
This is the reset. First, we remove all text written to txt
, then we reset it's Dot
to Orig
. This is useful when we want to fully change the content of a Text
object. Reseting the Dot
is necessary (if wanted), txt.Clear()
does not do it for us.
Aside from Orig
and Dot
, there are several other things we can adjust when writing text. Let's take a look at those!
The first one is Color
. It's a simple field, we can assign it and whatever we write after will have that color. Let's see! Replace this:
fmt.Fprintln(basicTxt, "Hello, text!")
fmt.Fprintln(basicTxt, "I support multiple lines!")
fmt.Fprintf(basicTxt, "And I'm an %s, yay!", "io.Writer")
With this:
basicTxt.Color = colornames.Red
fmt.Fprintln(basicTxt, "Hello, text!")
basicTxt.Color = colornames.Green
fmt.Fprintln(basicTxt, "I support multiple lines!")
basicTxt.Color = colornames.Blue
fmt.Fprintf(basicTxt, "And I'm an %s, yay!", "io.Writer")
And here we go!
Another property that we can set it LineHeight
. This property is simply the number of pixels Dot
travels downwards when it encounters a newline. We could set it to a fixed number of pixels, or we could set it to a multiple of the standard line height of the atlas, like this:
basicAtlas := text.NewAtlas(basicfont.Face7x13, text.ASCII)
basicTxt := text.New(pixel.V(100, 500), basicAtlas)
basicTxt.LineHeight = basicAtlas.LineHeight() * 1.5
basicTxt.Color = colornames.Red
fmt.Fprintln(basicTxt, "Hello, text!")
And take a look, wider line spacing!
The last property is TabWidth
, you can tell what it does. Experiment with it yourself!
Now that we know how Text
works, we obviously need better fonts to get better results! I've got a beautiful font up in my sleeves that I downloaded from fontlibrary.org, download it here:
Now, the main question is, how do we load such a font? We know that the text.NewAtlas
constructor wants font.Face
, so we need to create one. If we take a look at the documentation of the truetype package, we see this function:
func NewFace(f *Font, opts *Options) font.Face
Good, that's were we get the font.Face
from. But, this function wants a truetype.Font
, how do we get that? The answer is the truetype.Parse, which just takes a slice of bytes (the file) and returns a truetype.Font
. Great, with this knowledge, let's create ourselves a TTF font loading function:
func loadTTF(path string, size float64) (font.Face, error) {
file, err := os.Open(path)
if err != nil {
return nil, err
}
defer file.Close()
bytes, err := ioutil.ReadAll(file)
if err != nil {
return nil, err
}
font, err := truetype.Parse(bytes)
if err != nil {
return nil, err
}
return truetype.NewFace(font, &truetype.Options{
Size: size,
GlyphCacheEntries: 1,
}), nil
}
Let's break it down! First, we simply open the TTF file. Next, we read all of the bytes from it to a single slice of bytes. Then, we use the truetype.Parse
function to parse the byte slice and create a truetype.Font
object. Finally, we convert this truetype.Font
object to font.Face
object, which is what we need.
One thing, that deserves attention is the truetype.Options
struct. Here we say the size of the font we want to use. The GlyphCacheEntries
field says, how many characters (glyphs) should the font.Face
object remember in it's cache to speed up the text drawing. Since we don't use the font.Face
object directly when drawing text (we create an Atlas
instead), we don't really need this cache. So, we just set it to 1. This avoids a lot of memory consumption. I advice you always set this value to 1 when dealing with Pixel.
So, let's replace our basicfont.Face7x13
with the beautiful Truetype font! First, we need to load it.
win, err := pixelgl.NewWindow(cfg)
if err != nil {
panic(err)
}
face, err := loadTTF("intuitive.ttf", 52)
if err != nil {
panic(err)
}
Now, we rename basicAtlas
and basicTxt
to atlas
and txt
, since they're not basic anymore. Then, we pass the new font to the atlas
.
atlas := text.NewAtlas(face, text.ASCII)
txt := text.New(pixel.V(100, 500), atlas)
Finally, we get rid of the scaling, this text needs to be crisp! Replace this:
for !win.Closed() {
win.Clear(colornames.Black)
txt.Draw(win, pixel.IM.Scaled(txt.Orig, 4))
win.Update()
}
with this:
for !win.Closed() {
win.Clear(colornames.Black)
txt.Draw(win, pixel.IM)
win.Update()
}
Just look at it! Isn't it beautiful?