From cfea7a23bb19525eaa839673fd3f868dbfb13795 Mon Sep 17 00:00:00 2001 From: David Thompson Date: Fri, 14 Dec 2018 07:59:08 -0500 Subject: doc: Improve Fonts section. --- doc/api.texi | 49 +++++++++++++------------------------------------ 1 file 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} -- cgit v1.2.3