include/freetype/ftadvanc.h

/****************************************************************************
 *
 * ftadvanc.h
 *
 *   Quick computation of advance widths (specification only).
 *
 * Copyright 2008-2018 by
 * David Turner, Robert Wilhelm, and Werner Lemberg.
 *
 * This file is part of the FreeType project, and may only be used,
 * modified, and distributed under the terms of the FreeType project
 * license, LICENSE.TXT.  By continuing to use, modify, or distribute
 * this file you indicate that you have read the license and
 * understand and accept it fully.
 *
 */


#ifndef FTADVANC_H_
#define FTADVANC_H_


#include <ft2build.h>
#include FT_FREETYPE_H

#ifdef FREETYPE_H
#error "freetype.h of FreeType 1 has been loaded!"
#error "Please fix the directory search order for header files"
#error "so that freetype.h of FreeType 2 is found first."
#endif


FT_BEGIN_HEADER


  /**************************************************************************
   *
   * @section:
   *   quick_advance
   *
   * @title:
   *   Quick retrieval of advance values
   *
   * @abstract:
   *   Retrieve horizontal and vertical advance values without processing
   *   glyph outlines, if possible.
   *
   * @description:
   *   This section contains functions to quickly extract advance values
   *   without handling glyph outlines, if possible.
   *
   * @order:
   *   FT_Get_Advance
   *   FT_Get_Advances
   *
   */


  /**************************************************************************
   *
   * @enum:
   *   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 that are either unscaled, unhinted, bitmapped,
   *   or light-hinted can have their advance width computed very
   *   quickly.
   *
   *   Normal and bytecode hinted modes that require loading, scaling,
   *   and hinting of the glyph outline, are extremely slow by
   *   comparison.
   */
#define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000L


  /**************************************************************************
   *
   * @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, used to determine what kind
   *     of advances you need.
   * @output:
   *   padvance ::
   *     The advance value.  If scaling is performed (based on
   *     the value of `load_flags'), the advance value is in
   *     16.16 format.  Otherwise, it is in font units.
   *
   *     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:
   *   This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and
   *   if the corresponding font backend doesn't have a quick way to
   *   retrieve the advances.
   *
   *   A scaled advance is returned in 16.16 format but isn't transformed
   *   by the affine transformation specified by @FT_Set_Transform.
   */
  FT_EXPORT( FT_Error )
  FT_Get_Advance( FT_Face    face,
                  FT_UInt    gindex,
                  FT_Int32   load_flags,
                  FT_Fixed  *padvance );


  /**************************************************************************
   *
   * @function:
   *   FT_Get_Advances
   *
   * @description:
   *   Retrieve the advance values of several glyph outlines in an
   *   @FT_Face.
   *
   * @input:
   *   face ::
   *     The source @FT_Face handle.
   *
   *   start ::
   *     The first glyph index.
   *
   *   count ::
   *     The number of advance values you want to retrieve.
   *
   *   load_flags ::
   *     A set of bit flags similar to those used when
   *     calling @FT_Load_Glyph.
   *
   * @output:
   *   padvance ::
   *     The advance values.  This array, to be provided by the
   *     caller, must contain at least `count' elements.
   *
   *     If scaling is performed (based on the value of
   *     `load_flags'), the advance values are in 16.16 format.
   *     Otherwise, they are in font units.
   *
   *     If @FT_LOAD_VERTICAL_LAYOUT is set, these are the
   *     vertical advances corresponding to a vertical layout.
   *     Otherwise, they are the horizontal advances in a
   *     horizontal layout.
   *
   * @return:
   *   FreeType error code.  0 means success.
   *
   * @note:
   *   This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and
   *   if the corresponding font backend doesn't have a quick way to
   *   retrieve the advances.
   *
   *   Scaled advances are returned in 16.16 format but aren't
   *   transformed by the affine transformation specified by
   *   @FT_Set_Transform.
   */
  FT_EXPORT( FT_Error )
  FT_Get_Advances( FT_Face    face,
                   FT_UInt    start,
                   FT_UInt    count,
                   FT_Int32   load_flags,
                   FT_Fixed  *padvances );

  /* */


FT_END_HEADER

#endif /* FTADVANC_H_ */


/* END */