docs: Add text quality information (#3620)

* docs: Add text quality information

* add another playground

* add mount visible

Author: eonarheim

site/docs/04-graphics/04.1-text.mdx

@@ -4,6 +4,9 @@ slug: /text
 section: Graphics
 ---
 
+import FontQuality from '!!raw-loader!./examples/font-quality.ts';
+import FontLabel from '!!raw-loader!./examples/font.ts';
+
 You may want to display [[Text]] in your game, this can be achieved with the [[Text]], [[Font]], and [[SpriteFont]].
 
 ## Text
@@ -53,6 +56,8 @@ const label = new ex.Label({
 });
 ```
 
+
+
 ## Font
 
 A [[Font]] is a traditional system or loaded web font.
@@ -98,9 +103,36 @@ var text = new ex.Text({
 });
 ```
 
+<PlaygroundEmbed
+  title="Font"
+  code={FontLabel}
+  mount="visible"
+/>
+
+### Loading External Fonts
+
+
 It is recommended you load any font important to your game and not rely on any pre-installed system fonts, those will be different from computer to computer.
 
-For example the [google fonts](https://fonts.google.com/) loader is a common way to do this.
+```typescript
+const fontSource = new ex.FontSource('./Gorgeous Pixel.ttf', 'Gorgeous Pixel');
+
+// load the font in ex.Loader or directly with .load()
+await fontSource.load();
+
+const font = fontSource.toFont({
+  family: 'Gorgeous Pixel',
+  color: ex.Color.White,
+  size: 30,
+  shadow: {
+    blur: 15,
+    color: ex.Color.Black
+  }
+});
+
+```
+
+It is also possible to use the [google fonts](https://fonts.google.com/) loader to do this.
 
 ```html
 <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -119,7 +151,7 @@ const font = new ex.Font({
 })
 ```
 
-One potential issue with using web fonts is they won't render correctly until loaded see [article for details](https://erikonarheim.com/posts/dont-test-fonts/).
+One potential issue with using web fonts from google is they won't render correctly until loaded see [article for details](https://erikonarheim.com/posts/dont-test-fonts/).
 
 ```typescript
 async function waitForFontLoad(font, timeout = 2000, interval = 100) {
@@ -147,6 +179,25 @@ const game = new ex.Engine({...})
 await game.start();
 ```
 
+## Text Quality
+
+Depending on your game you may run into a situation where you have blurry looking text, this can be caused by a few reasons and fixed by adjusting a few settings.
+
+Most of the strategies involve artificially giving the text more pixels to work with to render a more crisp result.
+
+1. Increase the `quality` (default 2), this works by upscaling the bitmap the text is drawn to internally, more pixels can yield higher fidelity.
+2. Increase the "resolution" of your game using the `pixelRatio`, this is especially necessary if you have a very low resolutions (less than 500x500).
+3. If you cannot upscale (or don't want to) you need to line up your font glyphs to align with pixels in the canvas.
+4. Reach for a sprite font tailored for the resolution you're working in (often this is useful in low res situations)>
+
+
+<PlaygroundEmbed
+  title="FontQuality"
+  code={FontQuality}
+  mount="visible"
+/>
+
+
 ## SpriteFont
 
 Sometimes you want to use a custom font based on your [spritesheet](#spritesheet) of character glyphs

site/docs/04-graphics/examples/font-quality.ts

@@ -0,0 +1,39 @@
+import * as ex from 'excalibur';
+
+const game = new ex.Engine({
+  canvasElementId: 'preview-canvas',
+  displayMode: ex.DisplayMode.FitContainer,
+  width: 200, // <-- Low res game (< 500x500)
+  height: 200, // logical resolution remains at 200x200
+  pixelRatio: 4, // <-- Upscale to something bigger than 500x500, in this case 800x800
+});
+
+const loader = new ex.Loader();
+
+const fontSource = new ex.FontSource(
+  'https://fonts.gstatic.com/s/pixelifysans/v3/CHylV-3HFUT7aC4iv1TxGDR9Jn0Eiw.woff2',
+  'Pixelify Sans'
+);
+loader.addResource(fontSource);
+
+const font = fontSource.toFont({
+  padding: 10,
+  lineHeight: 25,
+  color: ex.Color.White,
+  quality: 4, // <-- Increase quality scales up the backing image used to draw text (default 2)
+  size: 30,
+  shadow: {
+    blur: 15,
+    color: ex.Color.Black
+  }
+});
+
+const label = new ex.Label({
+  pos: ex.vec(0, 0),
+  text: 'Some Pixel text can fill up the screen a whole bunch with nice quality!!!!',
+  maxWidth: 220,
+  font
+});
+
+game.add(label);
+game.start(loader);

site/docs/04-graphics/examples/font.ts

@@ -0,0 +1,25 @@
+import * as ex from 'excalibur';
+
+const game = new ex.Engine({
+  canvasElementId: 'preview-canvas',
+  displayMode: ex.DisplayMode.FitContainer,
+  width: 200,
+  height: 200,
+  pixelRatio: 4
+});
+
+const label = new ex.Label({
+    text: 'Some Default\nSans Serif',
+    pos: ex.vec(100, 100),
+    font: new ex.Font({
+        family: 'sans-serif',
+        size: 24,
+        color: ex.Color.Red,
+        baseAlign: ex.BaseAlign.Middle,
+        textAlign: ex.TextAlign.Center,
+        unit: ex.FontUnit.Px
+    })
+});
+game.add(label);
+
+game.start();