[ft-devel] FT_Get_Advance() docs

[Behdad Esfahbod]

Hi,

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

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

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.                                                        */
  /*                                                                       */
#define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000UL


But apparently it doesn't.

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.

Cheers,
behdad