Re: [ft-devel] FT_Get_Advance() docs

[GRAHAM ASHER]

I know this isn't a welcome remark, but I'm going to say it anyway, because it's a rule I apply to myself: if an API is difficult to explain then it should be changed. Yes, I know you can't do that - but it's an argument for carefully documenting something as it is written, and changing it before release if the documentation gets too hard to write. And rather than saying a wording is unfortunate, just change it.

An attempt at better wording for the quoted text:

You can set a flag that allows fast retrieval of advance values: FT_ADVANCE_FLAG_FAST_ONLY. To use it, combine it with any other flags you're passing to FT_Get_Advance or FT_Get_Advances. But it works only if the glyph is unhinted (FT_LOAD_NO_HINTING), or unscaled (FT_LOAD_NO_SCALE), or bitmapped, or if light hinting is used (FT_RENDER_MODE_LIGHT). If none of these conditions is met, FT_Get_Advance or FT_Get_Advances will fail with FT_Err_Unimplemented_Feature.

Graham

---

From: Werner LEMBERG <address@hidden>
To: address@hidden
Cc: address@hidden
Sent: Wednesday, 30 November 2011, 14:30
Subject: Re: [ft-devel] FT_Get_Advance() docs


> 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

_______________________________________________
Freetype-devel mailing list
address@hidden
https://lists.nongnu.org/mailman/listinfo/freetype-devel