Re: [ft-devel] FT_Get_Advance() docs

[Antoine Leca]

Behdad Esfahbod wrote:
> In Chromium, there's a bug being discussed right now about what the expected
> return value of FT_Get_Advance() is:
>
> http://code.google.com/p/chromium/issues/detail?id=66073

If I understand correctly the bug report, particularly the advance.cc
snippet (and without peeking at the Chromium and Webkit codes itself), I
got the impression you are using FT_LOAD_TARGET_LIGHT, ain't you?

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

The documentation as it stands now reads as
  /*    Retrieve the advance value of a given glyph outline in
an          */
  /*    @FT_Face.  By default, the unhinted advance is returned in
font    */
  /*   
units.                                                             */
which strongly suggests to me that it is NOT safe to use against hinted
glyphs (OK, I assume one knows also that hinting is the default
behaviour unless overridden.)

Also, the documentation for FT_GlyphSlotRec reads as
  /*    linearHoriAdvance :: The advance width of the unhinted
glyph.      */
and
  /*    advance           :: This shorthand is, [...] , the
transformed    */
  /*                         advance width for the glyph (in
26.6          */
  /*                         fractional pixel format).  As specified
with  */
which seems to me in agreement with your tests, albeit not your
expectations (and also mine when I first read your message, before
diving deep into the headers of the library.)

> In fact, the following suggests that FT_Get_Advance() may in fact take hinting
> into account:
>
>   /*************************************************************************/
>   /*                                                                       */
>   /* <Const>                                                               */
>   /*    FT_ADVANCE_FLAG_FAST_ONLY                                          */
>   /*                                                                       */
>   /* <Description>                                                         */
>   /*    A bit-flag to be OR-ed with the `flags' parameter of the           */
>   /*    @FT_Get_Advance and @FT_Get_Advances functions.                    */
>   /*                                                                       */
>   /*    If set, it indicates that you want these functions to fail if the  */
>   /*    corresponding hinting mode or font driver doesn't allow for very   */
>   /*    quick advance computation.                                         */
>   /*                                                                       */
>   /*    Typically, glyphs which are either unscaled, unhinted, bitmapped,  */
>   /*    or light-hinted can have their advance width computed very         */
>   /*    quickly.                                                           */
>   /*                                                                       */
>   /*    Normal and bytecode hinted modes, which require loading, scaling,  */
>   /*    and hinting of the glyph outline, are extremely slow by            */
>   /*    comparison.                                                        */
>   /*                                                                       */

If I understand your point, you really would like to get quickly the
advances, even if --or when-- some hinting is involved (which seems a
reasonable quest, even if the current documentation hints otherwise.)
Another point can be made that the "default" behaviour (when
load_flags=0) for FT_Get_Advance is to return the *hinted* advances :-( 
Some can even be see it as a bug, but I cannot decide if either of
documentation or of code.
Even stranger is that the /documented/ behaviour has been /applied/ to
CFF fonts, in
http://git.savannah.gnu.org/cgit/freetype/freetype2.git/commit/?id=14de111f
(last hunk, replacing advance.[xy] with linear{Hori,Vert}Advance.) To
adjust the code to the documentation, the same change ought to be done
at the end of base/ftadvance.c as well.
 

I am not sure (so comment are welcome), but also I remember that a
property of "light rendering" was to not change the advance (i.e.,
enforce AF_SCALER_FLAG_NO_ADVANCE); see also
http://lists.nongnu.org/archive/html/freetype-devel/2008-09/msg00000.html;
under such a constraint/compromise, it does make sense to take the quick
path to compute the advances.

On the other side, if advances could be modified by "light" hinting in
the same way as it can with "normal" hinting, then I believe the
FT_Get_Advance() function should not take the quick way in the former
case but not the later, should it?
Does something changed on this area since September 2008?


Also on a related point, in TrueType there is a way to get the hinted
advances quicker than executing the full bytecode program, even if it is
not alluded above: when the requested ppem has an associated hdmx/VDMX
table within the font. Why it is not currently available in Freetype I
do not know. If memory serves, a number of [bad] fonts out there have
this data wrong, which could be a problem (it certainly was seen as a
real problem for Microsoft a few years ago.) Also, perhaps the Freetype
byte code interpreter does not exactly issue the same results as the
patented one (read Apple, S. Kaasila, and Microsoft), so perhaps we can
have unwelcome differences here. Or perhaps it is just lack of time
which prevented the add of a 'fast loading' version for
TrueType-with-bytecode (see David's comment dated 2008-09-01 in
Changelog.23)


Finally, after that whole area has been cleaned up, we should revisit
the FAQ: http://www.freetype.org/freetype2/docs/ft2faq.html#other-bbox
is out of phase.


Antoine