From 9a2e92e81803d11163f769da78f0c6062e73eda7 Mon Sep 17 00:00:00 2001
From: Sean Barrett <sean@nothings.org>
Date: Wed, 12 Jul 2017 07:10:13 -0700
Subject: [PATCH] SDF documentation

---
 stb_truetype.h | 53 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/stb_truetype.h b/stb_truetype.h
index 25f8b7f..73653e5 100644
--- a/stb_truetype.h
+++ b/stb_truetype.h
@@ -867,10 +867,56 @@ STBTT_DEF void stbtt_Rasterize(stbtt__bitmap *result,        // 1-channel bitmap
 
 //////////////////////////////////////////////////////////////////////////////
 //
-// Signed Distance Function rendering
+// Signed Distance Function (or Field) rendering
+
+STBTT_DEF void stbtt_FreeSDF(unsigned char *bitmap, void *userdata);
+// frees the SDF bitmap allocated below
 
 STBTT_DEF unsigned char * stbtt_GetGlyphSDF(const stbtt_fontinfo *info, float scale, int glyph, int padding, unsigned char onedge_value, float pixel_dist_scale, int *width, int *height, int *xoff, int *yoff);
 STBTT_DEF unsigned char * stbtt_GetCodepointSDF(const stbtt_fontinfo *info, float scale, int codepoint, int padding, unsigned char onedge_value, float pixel_dist_scale, int *width, int *height, int *xoff, int *yoff);
+// These functions compute a discretized SDF field for a single character, suitable for storing
+// in a single-channel texture, sampling with bilinear filtering, and testing against
+// a threshhold to produce scalable fonts.
+//        info              --  the font
+//        scale             --  controls the size of the resulting SDF bitmap, same as it would be creating a regular bitmap
+//        glyph/codepoint   --  the character to generate the SDF for
+//        padding           --  extra "pixels" around the character which are filled with the distance to the character (not 0),
+//                                 which allows effects like bit outlines
+//        onedge_value      --  value 0-255 to test the SDF against to reconstruct the character (i.e. the isocontour of the character)
+//        pixel_dist_scale  --  what value the SDF should increase by when moving one SDF "pixel" away from the edge (on the 0..255 scale)
+//        width,height      --  output height & width of the SDF bitmap (including padding)
+//        xoff,yoff         --  output origin of the character
+//        return value      --  a 2D array of bytes 0..255, width*height in size
+//
+// pixel_dist_scale & onedge_value are a scale & bias that allows you to make
+// optimal use of the limited 0..255 for your application, trading off precision
+// and special effects. SDF values outside the range 0..255 are clamped to 0..255.
+//
+// Example:
+//      scale = stbtt_ScaleForPixelHeight(12)
+//      padding = 5
+//      onedge_value = 60
+//      pixel_dist_scale = (255-60) / 5.0 = 39.0
+//
+//      This will create an SDF bitmap in which the character is about 12 pixels
+//      high but the whole bitmap is about 22 pixels high. To produce a filled
+//      shape, sample the SDF at each pixel and fill the pixel if the SDF value
+//      is less than or equal to 60/255. (You'll actually want to antialias,
+//      which is beyond the scope of this example.) Additionally, you can compute
+//      offset outlines (e.g. to stroke the character border inside & outside,
+//      or only outside). For example, to fill outside the character up to 3
+//      pixels, you would compare against (60+39.0*3)/255 = 177/255. The above
+//      choice of variables maps a range from 1.5 pixels inside the shape to
+//      5 pixels outside the shape; this is intended primarily for apply outside
+//      effects only (the interior range is to allow accurate antialiasing etc)
+//
+// The function computes the SDF analytically at each SDF pixel, not by e.g.
+// building a higher-res bitmap and approximating it. So the quality should
+// be as high as possible for an SDF of this size & representation. The algorithm
+// has not been optimized at all, so expect it to be slow if computing lots of
+// characters or very large sizes. 
+
+
 
 
 //////////////////////////////////////////////////////////////////////////////
@@ -4187,6 +4233,11 @@ STBTT_DEF unsigned char * stbtt_GetCodepointSDF(const stbtt_fontinfo *info, floa
    return stbtt_GetGlyphSDF(info, scale, stbtt_FindGlyphIndex(info, codepoint), padding, onedge_value, pixel_dist_scale, width, height, xoff, yoff);
 }
 
+STBTT_DEF void stbtt_FreeSDF(unsigned char *bitmap, void *userdata)
+{
+   STBTT_free(bitmap, userdata);
+}
+
 //////////////////////////////////////////////////////////////////////////////
 //
 // font name matching -- recommended not to use this