freetype2/freetype/ftadvanc.h

0001 /****************************************************************************
0002  *
0003  * ftadvanc.h
0004  *
0005  *   Quick computation of advance widths (specification only).
0006  *
0007  * Copyright (C) 2008-2023 by
0008  * David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 #ifndef FTADVANC_H_
0020 #define FTADVANC_H_
0021
0022
0023 #include <freetype/freetype.h>
0024
0025 #ifdef FREETYPE_H
0026 #error "freetype.h of FreeType 1 has been loaded!"
0027 #error "Please fix the directory search order for header files"
0028 #error "so that freetype.h of FreeType 2 is found first."
0029 #endif
0030
0031
0032 FT_BEGIN_HEADER
0033
0034
0035   /**************************************************************************
0036    *
0037    * @section:
0038    *   quick_advance
0039    *
0040    * @title:
0041    *   Quick retrieval of advance values
0042    *
0043    * @abstract:
0044    *   Retrieve horizontal and vertical advance values without processing
0045    *   glyph outlines, if possible.
0046    *
0047    * @description:
0048    *   This section contains functions to quickly extract advance values
0049    *   without handling glyph outlines, if possible.
0050    *
0051    * @order:
0052    *   FT_Get_Advance
0053    *   FT_Get_Advances
0054    *
0055    */
0056
0057
0058   /**************************************************************************
0059    *
0060    * @enum:
0061    *   FT_ADVANCE_FLAG_FAST_ONLY
0062    *
0063    * @description:
0064    *   A bit-flag to be OR-ed with the `flags` parameter of the
0065    *   @FT_Get_Advance and @FT_Get_Advances functions.
0066    *
0067    *   If set, it indicates that you want these functions to fail if the
0068    *   corresponding hinting mode or font driver doesn't allow for very quick
0069    *   advance computation.
0070    *
0071    *   Typically, glyphs that are either unscaled, unhinted, bitmapped, or
0072    *   light-hinted can have their advance width computed very quickly.
0073    *
0074    *   Normal and bytecode hinted modes that require loading, scaling, and
0075    *   hinting of the glyph outline, are extremely slow by comparison.
0076    */
0077 #define FT_ADVANCE_FLAG_FAST_ONLY  0x20000000L
0078
0079
0080   /**************************************************************************
0081    *
0082    * @function:
0083    *   FT_Get_Advance
0084    *
0085    * @description:
0086    *   Retrieve the advance value of a given glyph outline in an @FT_Face.
0087    *
0088    * @input:
0089    *   face ::
0090    *     The source @FT_Face handle.
0091    *
0092    *   gindex ::
0093    *     The glyph index.
0094    *
0095    *   load_flags ::
0096    *     A set of bit flags similar to those used when calling
0097    *     @FT_Load_Glyph, used to determine what kind of advances you need.
0098    *
0099    * @output:
0100    *   padvance ::
0101    *     The advance value.  If scaling is performed (based on the value of
0102    *     `load_flags`), the advance value is in 16.16 format.  Otherwise, it
0103    *     is in font units.
0104    *
0105    *     If @FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance
0106    *     corresponding to a vertical layout.  Otherwise, it is the horizontal
0107    *     advance in a horizontal layout.
0108    *
0109    * @return:
0110    *   FreeType error code.  0 means success.
0111    *
0112    * @note:
0113    *   This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if
0114    *   the corresponding font backend doesn't have a quick way to retrieve
0115    *   the advances.
0116    *
0117    *   A scaled advance is returned in 16.16 format but isn't transformed by
0118    *   the affine transformation specified by @FT_Set_Transform.
0119    */
0120   FT_EXPORT( FT_Error )
0121   FT_Get_Advance( FT_Face    face,
0122                   FT_UInt    gindex,
0123                   FT_Int32   load_flags,
0124                   FT_Fixed  *padvance );
0125
0126
0127   /**************************************************************************
0128    *
0129    * @function:
0130    *   FT_Get_Advances
0131    *
0132    * @description:
0133    *   Retrieve the advance values of several glyph outlines in an @FT_Face.
0134    *
0135    * @input:
0136    *   face ::
0137    *     The source @FT_Face handle.
0138    *
0139    *   start ::
0140    *     The first glyph index.
0141    *
0142    *   count ::
0143    *     The number of advance values you want to retrieve.
0144    *
0145    *   load_flags ::
0146    *     A set of bit flags similar to those used when calling
0147    *     @FT_Load_Glyph.
0148    *
0149    * @output:
0150    *   padvance ::
0151    *     The advance values.  This array, to be provided by the caller, must
0152    *     contain at least `count` elements.
0153    *
0154    *     If scaling is performed (based on the value of `load_flags`), the
0155    *     advance values are in 16.16 format.  Otherwise, they are in font
0156    *     units.
0157    *
0158    *     If @FT_LOAD_VERTICAL_LAYOUT is set, these are the vertical advances
0159    *     corresponding to a vertical layout.  Otherwise, they are the
0160    *     horizontal advances in a horizontal layout.
0161    *
0162    * @return:
0163    *   FreeType error code.  0 means success.
0164    *
0165    * @note:
0166    *   This function may fail if you use @FT_ADVANCE_FLAG_FAST_ONLY and if
0167    *   the corresponding font backend doesn't have a quick way to retrieve
0168    *   the advances.
0169    *
0170    *   Scaled advances are returned in 16.16 format but aren't transformed by
0171    *   the affine transformation specified by @FT_Set_Transform.
0172    */
0173   FT_EXPORT( FT_Error )
0174   FT_Get_Advances( FT_Face    face,
0175                    FT_UInt    start,
0176                    FT_UInt    count,
0177                    FT_Int32   load_flags,
0178                    FT_Fixed  *padvances );
0179
0180   /* */
0181
0182
0183 FT_END_HEADER
0184
0185 #endif /* FTADVANC_H_ */
0186
0187
0188 /* END */