doc: Improve Fonts section.

1 files changed, 13 insertions, 36 deletions

diff --git a/doc/api.texi b/doc/api.texi
index 8254b13..b1881bd 100644
--- a/doc/api.texi
+++ b/doc/api.texi
@@ -1510,47 +1510,24 @@ arguments.
 @node Fonts
 @subsection Fonts
 
-Unlike the traditional TrueType font format that many are accustomed
-to, Chickadee loads and renders bitmap fonts in the
+Printing text to the screen is quite easy:
+
+@example
+(draw-text "Hello, world" (vec2 100.0 100.0))
+@end example
+
+Chickadee loads and renders bitmap fonts in the
 @url{http://www.angelcode.com/products/bmfont/doc/file_format.html,
-Angel Code format}.  But why use this seemingly obscure format?  It's
-easy to find TTFs but not easy to find FNTs (the canonical file
-extension used for Angel Code fonts) and bitmap fonts don't scale
-well.  The reason is efficiency.
-
-If all of the glyphs of a font are pre-rendered and packed into an
-image file then it becomes possible to use a texture atlas
-(@pxref{Textures}) and a sprite batch (@pxref{Sprites}) when
-rendering, which is a more efficient way to render fonts than using,
-say, @url{https://www.libsdl.org/projects/SDL_ttf/, SDL_ttf} or other
-solutions that involve using the FreeType library directly.
-
-Now what about scaling?  In libraries that use TTF fonts, one must
-choose the size that the glyphs will be rasterized at up front.  To
-use @code{n} sizes of the same font, one must load @code{n} variants
-of that font.  If the size of the text is dynamic, some kind of
-texture scaling algorithm must be used and the text will inevitably
-look blurry.  At first glance, using bitmap fonts seem to have an even
-worse issue.  Instead of just loading the same font @code{n} times at
-different sizes, one would need to generate @code{n} image files for
-each font size needed.  This is where the ``signed distance field''
-rendering technique comes in.  Introduced by
-@url{http://www.valvesoftware.com/.../2007/SIGGRAPH2007_AlphaTestedMagnification.pdf,
-Valve} in 2007, signed distance field fonts can be efficiently stored
-in a bitmap and be rendered at arbitrary scale factors with good
-results.
-
-While Chickadee does not yet offer a tool for converting TTF fonts
-into FNT fonts, tools such as
-@url{https://github.com/libgdx/libgdx/wiki/Hiero, Hiero} may be used
-in the meantime.
+Angel Code format}.  A default font named ``Good Neighbors'' is
+built-in to Chickadee and is used for all text rendering operations
+where a font is not specified, as is the case in the above example.
 
 The following procedures can be found in the @code{(chickadee render
-font)} module.
+font)} module:
 
 @deffn {Procedure} load-font @var{file}
-Load the Angel Code formatted XML document in @var{file} and return a
-new font object.
+Load the Angel Code font (in either XML or FNT format) in @var{file}
+and return a new font object.
 @end deffn
 
 @deffn {Procedure} font? @var{obj}