Document coordinate system

[djeedai]

Hi-

Could you please document the coordinate system? I'm trying to figure out how to use Glyph::position, and the values coming out of the call make sense horizontally but not vertically. I assume there's a subtlety like the Y position being the distance from the current origin (pen position) to the top of the glyph (so, maybe equal to the ascent?), but that would mean that Y is upward, while Rect::min is documented as being the top left corner, hinting at Y being downward.

Thanks!

[alexheretic]

Thanks for raising this, I agree we should improve the Glyph::position docs. Probably other docs too as currently upstream font concepts like ascent, descent etc are not explained.

There are some docs on Font::glyph_bounds. Glyph::position returns the point on the glyph's baseline before applying h_advance or -h_side_bearing. So generally the point on the left of the glyph at the baseline.

x coords go right, y coords go down.

[djeedai]

Thanks @alexheretic!

I'm a bit confused though. I use glyph_brush_layout and the position I get is something like position = (-23.64, 24.93) for a font scale of 32. The x = -23.64 makes sense because it's centered and there's 3 letters "Run", so this is about half the total text size. But vertically, if we say y = 24.93 is the position from the baseline, that means the glyph is located about 25 pixels below the baseline, yet the font scale is 32? How is that possible for the letter "R"? Unless I interpret that 24.93 as the ascent, which is the only thing that makes sense.

[alexheretic]

Glyph::position gives the position of the baseline. So using glyph_brush VerticalAlign::Top rendering from screen-position (0,0) you would expect the y position of each glyph in the first line to be equal to the ascent yes.

[djeedai]

So Glyph::position is the position of the glyph origin (pen position; at the baseline) relative to the top left corner of the text section?

What I don't understand here is that normally when you render text, the baseline is where you start from (see e.g. in Inkscape or whatnot, you position the baseline origin when you align some text). Then each glyph is positioned relative to it (the bounding rect of the glyph's raster is expressed relative to that point, starting at -h_side_bearing on the left and ascent on the top, etc.). So I'm not understanding what's the reference point being used here to position the baseline itself? Is that the top left corner of the glyph_brush_layout::SectionGeometry?

[alexheretic]

That isn't actually determined by this crate, Glyph::position is simply as described. It is up to the use case to determine the reference origin of the vector.

In glyph_brush's case glyph positions are all screen positions. You layout text at some screen position & bounds and the glyph screen positions are calculated.

Where the baselines end up depends on the VerticalAlign.

[djeedai]

Ok I think I start to understand. I'm looking at Bevy's code and there it passes the text justification as the h_align(), and nothing as v_align() (so it defaults to VerticalAlign as you said). That sounded wrong at first, but now I think the issue is that HorizontalAlign / h_align() conflates the alignment of the rendering (so, draw glyphs from the render position toward the right, or centered, or up to the right) with the text justification (how lines are aligned with respect to each other within a multi-line text; has no effect on single-line text nor on the overall bounds of a text section). So I think Bevy does that because it recomputes the alignment on its own manually, base on some anchor concept (which only defines how the section bounds are aligned relative to the render position), and only uses glyph_brush's h_align() to get the proper multi-line justification. Indeed Bevy's alignment was renamed to justification recently, and is documented to not affect single-line text. Does that make sense? Is it worth logging an issue in bevy_glyph itself?

[alexheretic]

Hmm glyph_brush h_align & v_align both affect single or multiline layouts as documented. They affect where the bounds go too. I can't help with how bevy uses it though.

[alexheretic]

I added new docs in f6eb81a let me know if you have further suggestions