Confusion with stbtt_GetFontBoundingBox functionality or documentation

[Atridas]

First a bit of context, I'm implementing the "print "Hello World!" banner, with bugs" example, but without the bugs, to learn the API. I'm trying to create an offscreen buffer to render the characters too, and for that I'm using stbtt_GetFontBoundingBox

If I am to believe the documentation, y0 gives the maximum offset from the cursor to the TOP of any glyph, while y1 goes from the cursor to the bottom.

//    SF*-y0 will be the distance in pixels
//    that the worst-case character could extend above the baseline

In the example I'm doing (loading "c:/windows/fonts/times.ttf"), y0 = -628 and y1 = 2129.

Now, in stbtt_GetGlyphBitmapBoxSubpixel, when asking for an "H" for the exact same font with a scaling of 1.0 I'm getting y0 = -1356 and y1 = 0, which immediately places them out of bounds.

My question would be, I am assuming something wrong here? Or is really stbtt_GetFontBoundingBox returning y0 and y1 in reverse of what I'm expecting?

[nothings]

stb_truetype doesn't compute a font bounding box itself. The font bounding box returned by that function is just exposing 4 numbers stored in the font file which are not used anywhere else in the code. It is possible I misunderstood the spec, or it is possible you have a bad font file with incorrect values stored for those 4 numbers (possible since they're not used anywhere else in the file, so this would have no other bad effects). The "bad font file" scenario is more likely to happen for a random fun font off the internet rather than a standard well-used font like those shipped with an operating system.

Because I wrote the code in 2009 I don't remember how much testing/validation I did on this function specifically.

STBTT_DEF void stbtt_GetFontBoundingBox(const stbtt_fontinfo *info, int *x0, int *y0, int *x1, int *y1)
{
   *x0 = ttSHORT(info->data + info->head + 36);
   *y0 = ttSHORT(info->data + info->head + 38);
   *x1 = ttSHORT(info->data + info->head + 40);
   *y1 = ttSHORT(info->data + info->head + 42);
}

[Atridas]

I'm looking at the documentation

Here is the header table (I think this is the one read at stbtt_GetFontBoundingBox):
https://learn.microsoft.com/ca-es/typography/opentype/spec/head

And here the glyph table (I think this is the one read at stbtt_GetGlyphBox):
https://learn.microsoft.com/ca-es/typography/opentype/spec/glyf

For what I understand, they return coordinates in "font space", that is y goes bottom up, while functions like stbtt_GetGlyphBitmapBoxSubpixel return coordinates in "image space", with y going up to bottom (the code negates the y coordinate).

In this sense, stbtt_GetFontBoundingBox functionality seems to be coherent with the rest of the library, so only the docs would need to be updated (shall I do a pull request for this?)

Oh, researching this I found there is also a broken link in that file (http://developer.apple.com/textfonts/TTRefMan/RM06/Chap6name.html, line 1041), this is why I was looking at the microsoft ones. It seems to have been moved to https://developer.apple.com/fonts/TrueType-Reference-Manual/RM06/Chap6name.html. It was annoyingly difficult to find the docs because half the internet point to the old apple ones, and they don't seem to learn they shouldn't be moving stuff around.

[nothings]

Yes, we're saying it sounds like the comment should say "SF*y1" is the distance above the baseline?

[Atridas]

yes, that's how I understand it. I've done some tests with some .ttf files that windows comes with and y0 is always close to descent and y1 is close to ascent. They're not equal, and they can actually be bigger, because ascent and descent are values the designer chooses, not hard limits.

[nothings]

yeah, feel free to make a documentation PR then, so I don't forget