Re: [ft-devel] FT_Get_Advance() docs

[Werner LEMBERG]

> Testing suggests that [FT_Get_Advance] returns
> glyph->linearHoriAdvance, not glyph->advance.x.  This is
> understandable, but unintuitive and not documented.

Hmm.

> In fact, the following suggests that FT_Get_Advance() may in fact
> take hinting into account:

This is correct.

> But apparently it doesn't.

It does.

> At any rate, would be nice to document what exactly is it that
> FT_Get_Advance() returns, and what tests can the client use to
> determine whether what FT_Get_Advance() returns matches
> glyph->advance.x.

The behaviour depends on `load_flags' and on
FT_ADVANCE_FLAG_FAST_ONLY:

  . If a glyph is unhinted (FT_LOAD_NO_HINTING), or unscaled
    (FT_LOAD_NO_SCALE), or bitmapped, or if the light-hinted rendering
    mode is active (FT_RENDER_MODE_LIGHT), quick retrieval of advance
    widths is possible in general.  However, you can only be sure
    about that if you add FT_ADVANCE_FLAG_FAST_ONLY to `load_flags'
    and assure that you don't get an error.

    Depending on the load flags, you get either advance values in
    FUnits (the sentence about `default' in the description of
    FT_Get_Advance is rather unfortunate) or scaled values which are
    then identical to the glyph->linear{Hori,Vert}Advance values.

  . If the above conditions aren't met, FT_Load_Glyph is called, and
    you get glyph->advance.{x,y} values.

I would be glad if you could suggest a better wording of the
documentation.


    Werner