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 <w...@gnu.org>
To: beh...@behdad.org
Cc: freetype-devel@nongnu.org
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
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel_______________________________________________
Freetype-devel mailing list
Freetype-devel@nongnu.org
https://lists.nongnu.org/mailman/listinfo/freetype-devel
