public Class STBTruetype

This library processes TrueType files:

• parse files
• extract glyph metrics
• extract glyph shapes
• render glyphs to one-channel bitmaps with antialiasing (box filter)

ADDITIONAL DOCUMENTATION

Some important concepts to understand to use this library:

Codepoint

Characters are defined by unicode codepoints, e.g. 65 is uppercase A, 231 is lowercase c with a cedilla, 0x7e30 is the hiragana for "ma".

Glyph

A visual character shape (every codepoint is rendered as some glyph)

Glyph index

A font-specific integer ID representing a glyph

Baseline

Glyph shapes are defined relative to a baseline, which is the bottom of uppercase characters. Characters extend both above and below the baseline.

Current Point

As you draw text to the screen, you keep track of a "current point" which is the origin of each character. The current point's vertical position is the baseline. Even "baked fonts" use this model.

Vertical Font Metrics

The vertical qualities of the font, used to vertically position and space the characters. See docs for GetFontVMetrics.

Font Size in Pixels or Points

The preferred interface for specifying font sizes in stb_truetype is to specify how tall the font's vertical extent should be in pixels. If that sounds good enough, skip the next paragraph.

Most font APIs instead use "points", which are a common typographic measurement for describing font size, defined as 72 points per inch. stb_truetype provides a point API for compatibility. However, true "per inch" conventions don't make much sense on computer displays since different monitors have different number of pixels per inch. For example, Windows traditionally uses a convention that there are 96 pixels per inch, thus making 'inch' measurements have nothing to do with inches, and thus effectively defining a point to be 1.333 pixels. Additionally, the TrueType font data provides an explicit scale factor to scale a given font's glyphs to points, but the author has observed that this scale factor is often wrong for non-commercial fonts, thus making fonts scaled in points according to the TrueType spec incoherently sized in practice.

DETAILED USAGE

Scale:

Select how high you want the font to be, in points or pixels. Call #()ScaleForPixelHeight or ScaleForMappingEmToPixels to compute a scale factor SF that will be used by all other functions.

Baseline:

You need to select a y-coordinate that is the baseline of where your text will appear. Call GetFontBoundingBox to get the baseline-relative bounding box for all characters. SF*-y0 will be the distance in pixels that the worst-case character could extend above the baseline, so if you want the top edge of characters to appear at the top of the screen where y=0, then you would set the baseline to SF*-y0.

Current point:

Set the current point where the first character will appear. The first character could extend left of the current point; this is font dependent. You can either choose a current point that is the leftmost point and hope, or add some padding, or check the bounding box or left-side-bearing of the first character to be displayed and set the current point based on that.

Displaying a character:

Compute the bounding box of the character. It will contain signed values relative to <current_point, baseline>. I.e. if it returns x0,y0,x1,y1, then the character should be displayed in the rectangle from <current_point+SF*x0, baseline+SF*y0> to <current_point+SF*x1,baseline+SF*y1).

Advancing for the next character:

Call GetGlyphHMetrics, and compute current_point += SF * advance.

ADVANCED USAGE

Quality:

• Use the functions with Subpixel at the end to allow your characters to have subpixel positioning. Since the font is anti-aliased, not hinted, this is very important for quality. (This is not possible with baked fonts.)
• Kerning is now supported, and if you're supporting subpixel rendering then kerning is worth using to give your text a polished look.

Performance:

• Convert Unicode codepoints to glyph indexes and operate on the glyphs; if you don't do this, stb_truetype is forced to do the conversion on every call.
• There are a lot of memory allocations. We should modify it to take a temp buffer and allocate from the temp buffer (without freeing), should help performance a lot.

NOTES

The system uses the raw data found in the .ttf file without changing it and without building auxiliary data structures. This is a bit inefficient on little-endian systems (the data is big-endian), but assuming you're caching the bitmaps or glyph shapes this shouldn't be a big deal.

It appears to be very hard to programmatically determine what font a given file is in a general way. I provide an API for this, but I don't recommend it.

SAMPLE PROGRAMS

Incomplete text-in-3d-api example, which draws quads properly aligned to be lossless:

unsigned char ttf_buffer[1<<20];
unsigned char temp_bitmap[512*512];

stbtt_bakedchar cdata[96]; // ASCII 32..126 is 95 glyphs
GLuint ftex;

void my_stbtt_initfont(void)
{
   fread(ttf_buffer, 1, 1<<20, fopen("c:/windows/fonts/times.ttf", "rb"));
   stbtt_BakeFontBitmap(ttf_buffer,0, 32.0, temp_bitmap,512,512, 32,96, cdata); // no guarantee this fits!
   // can free ttf_buffer at this point
   glGenTextures(1, &ftex);
   glBindTexture(GL_TEXTURE_2D, ftex);
   glTexImage2D(GL_TEXTURE_2D, 0, GL_ALPHA, 512,512, 0, GL_ALPHA, GL_UNSIGNED_BYTE, temp_bitmap);
   // can free temp_bitmap at this point
   glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
}

void my_stbtt_print(float x, float y, char *text)
{
   // assume orthographic projection with units = screen pixels, origin at top left
   glEnable(GL_TEXTURE_2D);
   glBindTexture(GL_TEXTURE_2D, ftex);
   glBegin(GL_QUADS);
   while (*text) {
      if (*text ≥ 32 && *text < 128) {
         stbtt_aligned_quad q;
         stbtt_GetBakedQuad(cdata, 512,512, *text-32, &x,&y,&q,1);//1=opengl & d3d10+,0=d3d9
         glTexCoord2f(q.s0,q.t1); glVertex2f(q.x0,q.y0);
         glTexCoord2f(q.s1,q.t1); glVertex2f(q.x1,q.y0);
         glTexCoord2f(q.s1,q.t0); glVertex2f(q.x1,q.y1);
         glTexCoord2f(q.s0,q.t0); glVertex2f(q.x0,q.y1);
      }
      ++text;
   }
   glEnd();
}

Complete program (this compiles): get a single bitmap, print as ASCII art:

char ttf_buffer[1<<25];

int main(int argc, char **argv)
{
   stbtt_fontinfo font;
   unsigned char *bitmap;
   int w,h,i,j,c = (argc > 1 ? atoi(argv[1]) : 'a'), s = (argc > 2 ? atoi(argv[2]) : 20);

   fread(ttf_buffer, 1, 1<<25, fopen(argc > 3 ? argv[3] : "c:/windows/fonts/arialbd.ttf", "rb"));

   stbtt_InitFont(&font, ttf_buffer, stbtt_GetFontOffsetForIndex(ttf_buffer,0));
   bitmap = stbtt_GetCodepointBitmap(&font, 0,stbtt_ScaleForPixelHeight(&font, s), c, &w, &h, 0,0);

   for (j=0; j < h; ++j) {
      for (i=0; i < w; ++i)
         putchar(" .:ioVM@"[bitmap[j*w+i]>>5]);
      putchar('\n');
   }
   return 0;
}

Complete program: print "Hello World!" banner, with bugs:

char buffer[24<<20];
unsigned char screen[20][79];

int main(int arg, char **argv)
{
   stbtt_fontinfo font;
   int i,j,ascent,baseline,ch=0;
   float scale, xpos=2; // leave a little padding in case the character extends left
   char *text = "Heljo World!";

   fread(buffer, 1, 1000000, fopen("c:/windows/fonts/arialbd.ttf", "rb"));
   stbtt_InitFont(&font, buffer, 0);

   scale = stbtt_ScaleForPixelHeight(&font, 15);
   stbtt_GetFontVMetrics(&font, &ascent,0,0);
   baseline = (int) (ascent*scale);

   while (text[ch]) {
      int advance,lsb,x0,y0,x1,y1;
      float x_shift = xpos - (float) floor(xpos);
      stbtt_GetCodepointHMetrics(&font, text[ch], &advance, &lsb);
      stbtt_GetCodepointBitmapBoxSubpixel(&font, text[ch], scale,scale,x_shift,0, &x0,&y0,&x1,&y1);
      stbtt_MakeCodepointBitmapSubpixel(&font, &screen[baseline + y0][(int) xpos + x0], x1-x0,y1-y0, 79, scale,scale,x_shift,0, text[ch]);
      // note that this stomps the old data, so where character boxes overlap (e.g. 'lj') it's wrong
      // because this API is really for baking character bitmaps into textures. if you want to render
      // a sequence of characters, you really need to render each bitmap to a temp buffer, then
      // "alpha blend" that into the working buffer
      xpos += (advance * scale);
      if (text[ch+1])
         xpos += scale*stbtt_GetCodepointKernAdvance(&font, text[ch],text[ch+1]);
      ++ch;
   }

   for (j=0; j < 20; ++j) {
      for (i=0; i < 78; ++i)
         putchar(" .:ioVM@"[screen[j][i]>>5]);
      putchar('\n');
   }

   return 0;
}

Finding the right font...

You should really just solve this offline, keep your own tables of what font is what, and don't try to get it out of the .ttf file. That's because getting it out of the .ttf file is really hard, because the names in the file can appear in many possible encodings, in many possible languages, and e.g. if you need a case-insensitive comparison, the details of that depend on the encoding & language in a complex way (actually underspecified in truetype, but also gigantic).

But you can use the provided functions in two possible ways:

• FindMatchingFont will use *case-sensitive* comparisons on unicode-encoded names to try to find the font you want; you can run this before calling InitFont
• GetFontNameString lets you get any of the various strings from the file yourself and do your own comparisons on them. You have to have called InitFont first.