Re: [ft-devel] FT_Get_Advance() docs

[Werner LEMBERG]

> 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.

:-) Fortunately, it's not me to blame for the design of this API.  And
I haven't written the documentation either.

> 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.

Hehe.  It was a call for help, and behold, a saviour has appeared.
Thanks!

> An attempt at better wording for the quoted text:
>
>   You can set a flag that allows fast retrieval of advance values:
>   [...]

But this is not correct!  If you set the flag, *only* fast retrieval
is tried.  If you don't set it, you get fast retrieval also if
supported.

Below is my proposal for an improved documentation of FT_Get_Advance.


    Werner


======================================================================


  <Function>
     FT_Get_Advance

  <Description>
     Retrieve the advance value of a given glyph outline in an
     @FT_Face.

  <Input>
     face       :: The source @FT_Face handle.

     gindex     :: The glyph index.

     load_flags :: A set of bit flags similar to those used when
                   calling @FT_Load_Glyph.
  <Output>
     padvance   :: The advance value, either in font units if
                   @FT_LOAD_NO_SCALE is used, or in 16.16 format for
                   all other load flags.

                   If @FT_LOAD_VERTICAL_LAYOUT is set, this is the
                   vertical advance corresponding to a vertical layout.
                   Otherwise, it is the horizontal advance in a
                   horizontal layout.

  <Return>
     FreeType error code.  0 means success.

  <Note>
     Quick retrieval of advance widths is possible if a 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),
     and the font backend supports it.  To check these conditions, add
     the @FT_ADVANCE_FLAG_FAST_ONLY flag to `load_flags'; in case of
     failure `FT_Err_Unimplemented_Feature' is returned.

     If the above conditions are met and @FT_LOAD_NO_SCALE isn't set,
     values equal to the `linearHoriAdvance' (or `linearVertAdvance')
     field of a @FT_GlyphSlot structure are returned in `padvance'.

     If the above conditions aren't met and @FT_LOAD_NO_SCALE isn't
     set, @FT_Load_Glyph is called, and values equal to the `advance'
     field of a @FT_GlyphSlot structure are returned in `padvance' (but
     in 16.16 format).

     If the returned advance value gets scaled, the affine
     transformation specified by @FT_Set_Transform is not applied.