fix SDF documentation and add example code

stb_truetype.h

@@ -878,7 +878,7 @@ STBTT_DEF unsigned char * stbtt_GetGlyphSDF(const stbtt_fontinfo *info, float sc
 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.
+// larger than some 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
@@ -886,6 +886,7 @@ STBTT_DEF unsigned char * stbtt_GetCodepointSDF(const stbtt_fontinfo *info, floa
 //                                 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)
+//                                 if positive, > onedge_value is inside; if negative, < onedge_value is inside
 //        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
@@ -895,29 +896,32 @@ STBTT_DEF unsigned char * stbtt_GetCodepointSDF(const stbtt_fontinfo *info, floa
 // and special effects. SDF values outside the range 0..255 are clamped to 0..255.
 //
 // Example:
-//      scale = stbtt_ScaleForPixelHeight(12)
+//      scale = stbtt_ScaleForPixelHeight(22)
 //      padding = 5
-//      onedge_value = 60
+//      onedge_value = 180
-//      pixel_dist_scale = (255-60) / 5.0 = 39.0
+//      pixel_dist_scale = 180/5.0 = 36.0
 //
-//      This will create an SDF bitmap in which the character is about 12 pixels
+//      This will create an SDF bitmap in which the character is about 22 pixels
-//      high but the whole bitmap is about 22 pixels high. To produce a filled
+//      high but the whole bitmap is about 22+5+5=32 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,
+//      is greater than or equal to 180/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
+//      or only outside). For example, to fill outside the character up to 3 SDF
-//      pixels, you would compare against (60+39.0*3)/255 = 177/255. The above
+//      pixels, you would compare against (180-36.0*3)/255 = 72/255. The above
-//      choice of variables maps a range from 1.5 pixels inside the shape to
+//      choice of variables maps a range from 5 pixels outside the shape to
-//      5 pixels outside the shape; this is intended primarily for apply outside
+//      2 pixels inside the shape to 0..255; this is intended primarily for apply
-//      effects only (the interior range is to allow accurate antialiasing etc)
+//      outside effects only (the interior range is needed to allow proper
+//      antialiasing of the font at *smaller* sizes)
 //
 // 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
+// building a higher-res bitmap and approximating it. In theory the quality
-// be as high as possible for an SDF of this size & representation. The algorithm
+// should be as high as possible for an SDF of this size & representation, but
-// has not been optimized at all, so expect it to be slow if computing lots of
+// unclear if this is true in practice (perhaps building a higher-res bitmap
-// characters or very large sizes. 
+// and computing from that can allow drop-out prevention).
-
+//
+// The algorithm has not been optimized at all, so expect it to be slow
+// if computing lots of characters or very large sizes. 
 
 
 

tests/sdf/sdf_test.c

@@ -0,0 +1,152 @@
+#define STB_DEFINE
+#include "stb.h"
+
+#define STB_TRUETYPE_IMPLEMENTATION
+#include "stb_truetype.h"
+
+#define STB_IMAGE_WRITE_IMPLEMENTATION
+#include "stb_image_write.h"
+
+// used both to compute SDF and in 'shader'
+float sdf_size = 32.0;          // the larger this is, the better large font sizes look
+float pixel_dist_scale = 64.0;  // trades off precision w/ ability to handle *smaller* sizes
+int onedge_value = 128;
+int padding = 3; // not used in shader
+
+typedef struct
+{
+   float advance;
+   signed char xoff;
+   signed char yoff;
+   unsigned char w,h;
+   unsigned char *data;
+} fontchar;
+
+fontchar fdata[128];
+
+#define BITMAP_W  1200
+#define BITMAP_H  800
+unsigned char bitmap[BITMAP_H][BITMAP_W][3];
+
+char *sample = "This is goofy text, size %d!";
+char *small_sample = "This is goofy text, size %d! Really needs in-shader supersampling to look good.";
+
+void blend_pixel(int x, int y, int color, float alpha)
+{
+   int i;
+   for (i=0; i < 3; ++i)
+      bitmap[y][x][i] = (unsigned char) (stb_lerp(alpha, bitmap[y][x][i], color)+0.5); // round
+}
+
+void draw_char(float px, float py, char c, float relative_scale)
+{
+   int x,y;
+   fontchar *fc = &fdata[c];
+   float fx0 = px + fc->xoff*relative_scale;
+   float fy0 = py + fc->yoff*relative_scale;
+   float fx1 = fx0 + fc->w*relative_scale;
+   float fy1 = fy0 + fc->h*relative_scale;
+   int ix0 = (int) floor(fx0);
+   int iy0 = (int) floor(fy0);
+   int ix1 = (int) ceil(fx1);
+   int iy1 = (int) ceil(fy1);
+   // clamp to viewport
+   if (ix0 < 0) ix0 = 0;
+   if (iy0 < 0) iy0 = 0;
+   if (ix1 > BITMAP_W) ix1 = BITMAP_W;
+   if (iy1 > BITMAP_H) iy1 = BITMAP_H;
+
+   for (y=iy0; y < iy1; ++y) {
+      for (x=ix0; x < ix1; ++x) {
+         float sdf_dist, pix_dist;
+         float bmx = stb_linear_remap(x, fx0, fx1, 0, fc->w);
+         float bmy = stb_linear_remap(y, fy0, fy1, 0, fc->h);
+         int v00,v01,v10,v11;
+         float v0,v1,v;
+         int sx0 = (int) bmx;
+         int sx1 = sx0+1;
+         int sy0 = (int) bmy;
+         int sy1 = sy0+1;
+         // compute lerp weights
+         bmx = bmx - sx0;
+         bmy = bmy - sy0;
+         // clamp to edge
+         sx0 = stb_clamp(sx0, 0, fc->w-1);
+         sx1 = stb_clamp(sx1, 0, fc->w-1);
+         sy0 = stb_clamp(sy0, 0, fc->h-1);
+         sy1 = stb_clamp(sy1, 0, fc->h-1);
+         // bilinear texture sample
+         v00 = fc->data[sy0*fc->w+sx0];
+         v01 = fc->data[sy0*fc->w+sx1];
+         v10 = fc->data[sy1*fc->w+sx0];
+         v11 = fc->data[sy1*fc->w+sx1];
+         v0 = stb_lerp(bmx,v00,v01);
+         v1 = stb_lerp(bmx,v10,v11);
+         v  = stb_lerp(bmy,v0 ,v1 );
+         #if 0
+         // non-anti-aliased
+         if (v > onedge_value)
+            blend_pixel(x,y,0,1.0);
+         #else
+         // Following math can be greatly simplified
+
+         // convert distance in SDF value to distance in SDF bitmap
+         sdf_dist = stb_linear_remap(v, onedge_value, onedge_value+pixel_dist_scale, 0, 1);
+         // convert distance in SDF bitmap to distance in output bitmap
+         pix_dist = sdf_dist * relative_scale;
+         // anti-alias by mapping 1/2 pixel around contour from 0..1 alpha
+         v = stb_linear_remap(pix_dist, -0.5f, 0.5f, 0, 1);
+         if (v > 1) v = 1;
+         if (v > 0)
+            blend_pixel(x,y,0,v);
+         #endif
+      }
+   }
+}
+
+
+void print_text(float x, float y, char *text, float scale)
+{
+   int i;
+   for (i=0; text[i]; ++i) {
+      if (fdata[text[i]].data)
+         draw_char(x,y,text[i],scale);
+      x += fdata[text[i]].advance * scale;
+   }
+}
+
+int main(int argc, char **argv)
+{
+   int ch;
+   float scale, ypos;
+   stbtt_fontinfo font;
+   void *data = stb_file("c:/windows/fonts/times.ttf", NULL);
+   stbtt_InitFont(&font, data, 0);
+
+   scale = stbtt_ScaleForPixelHeight(&font, sdf_size);
+
+   for (ch=32; ch < 127; ++ch) {
+      fontchar fc;
+      int xoff,yoff,w,h, advance;
+      fc.data = stbtt_GetCodepointSDF(&font, scale, ch, padding, onedge_value, pixel_dist_scale, &w, &h, &xoff, &yoff);
+      fc.xoff = xoff;
+      fc.yoff = yoff;
+      fc.w = w;
+      fc.h = h;
+      stbtt_GetCodepointHMetrics(&font, ch, &advance, NULL);
+      fc.advance = advance * scale;
+      fdata[ch] = fc;
+   }
+
+   ypos = 60;
+   memset(bitmap, 255, sizeof(bitmap));
+   print_text(400, ypos+30, stb_sprintf("sdf bitmap height %d", (int) sdf_size), 30/sdf_size);
+   ypos += 80;
+   for (scale = 8.0; scale < 120.0; scale *= 1.33f) {
+      print_text(80, ypos+scale, stb_sprintf(scale == 8.0 ? small_sample : sample, (int) scale), scale / sdf_size);
+      ypos += scale*1.05f + 20;
+   }
+
+   stbi_write_png("sdf_test.png", BITMAP_W, BITMAP_H, 3, bitmap, 0);
+   return 0;
+}