1 /****************************************************************************
   2  *
   3  * ftsizes.h
   4  *
   5  *   FreeType size objects management (specification).
   6  *
   7  * Copyright (C) 1996-2019 by
   8  * David Turner, Robert Wilhelm, and Werner Lemberg.
   9  *
  10  * This file is part of the FreeType project, and may only be used,
  11  * modified, and distributed under the terms of the FreeType project
  12  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
  13  * this file you indicate that you have read the license and
  14  * understand and accept it fully.
  15  *
  16  */
  17 
  18 
  19   /**************************************************************************
  20    *
  21    * Typical application would normally not need to use these functions.
  22    * However, they have been placed in a public API for the rare cases where
  23    * they are needed.
  24    *
  25    */
  26 
  27 
  28 #ifndef FTSIZES_H_
  29 #define FTSIZES_H_
  30 
  31 
  32 #include <ft2build.h>
  33 #include FT_FREETYPE_H
  34 
  35 #ifdef FREETYPE_H
  36 #error "freetype.h of FreeType 1 has been loaded!"
  37 #error "Please fix the directory search order for header files"
  38 #error "so that freetype.h of FreeType 2 is found first."
  39 #endif
  40 
  41 
  42 FT_BEGIN_HEADER
  43 
  44 
  45   /**************************************************************************
  46    *
  47    * @section:
  48    *   sizes_management
  49    *
  50    * @title:
  51    *   Size Management
  52    *
  53    * @abstract:
  54    *   Managing multiple sizes per face.
  55    *
  56    * @description:
  57    *   When creating a new face object (e.g., with @FT_New_Face), an @FT_Size
  58    *   object is automatically created and used to store all pixel-size
  59    *   dependent information, available in the `face->size` field.
  60    *
  61    *   It is however possible to create more sizes for a given face, mostly
  62    *   in order to manage several character pixel sizes of the same font
  63    *   family and style.  See @FT_New_Size and @FT_Done_Size.
  64    *
  65    *   Note that @FT_Set_Pixel_Sizes and @FT_Set_Char_Size only modify the
  66    *   contents of the current 'active' size; you thus need to use
  67    *   @FT_Activate_Size to change it.
  68    *
  69    *   99% of applications won't need the functions provided here, especially
  70    *   if they use the caching sub-system, so be cautious when using these.
  71    *
  72    */
  73 
  74 
  75   /**************************************************************************
  76    *
  77    * @function:
  78    *   FT_New_Size
  79    *
  80    * @description:
  81    *   Create a new size object from a given face object.
  82    *
  83    * @input:
  84    *   face ::
  85    *     A handle to a parent face object.
  86    *
  87    * @output:
  88    *   asize ::
  89    *     A handle to a new size object.
  90    *
  91    * @return:
  92    *   FreeType error code.  0~means success.
  93    *
  94    * @note:
  95    *   You need to call @FT_Activate_Size in order to select the new size for
  96    *   upcoming calls to @FT_Set_Pixel_Sizes, @FT_Set_Char_Size,
  97    *   @FT_Load_Glyph, @FT_Load_Char, etc.
  98    */
  99   FT_EXPORT( FT_Error )
 100   FT_New_Size( FT_Face   face,
 101                FT_Size*  size );
 102 
 103 
 104   /**************************************************************************
 105    *
 106    * @function:
 107    *   FT_Done_Size
 108    *
 109    * @description:
 110    *   Discard a given size object.  Note that @FT_Done_Face automatically
 111    *   discards all size objects allocated with @FT_New_Size.
 112    *
 113    * @input:
 114    *   size ::
 115    *     A handle to a target size object.
 116    *
 117    * @return:
 118    *   FreeType error code.  0~means success.
 119    */
 120   FT_EXPORT( FT_Error )
 121   FT_Done_Size( FT_Size  size );
 122 
 123 
 124   /**************************************************************************
 125    *
 126    * @function:
 127    *   FT_Activate_Size
 128    *
 129    * @description:
 130    *   Even though it is possible to create several size objects for a given
 131    *   face (see @FT_New_Size for details), functions like @FT_Load_Glyph or
 132    *   @FT_Load_Char only use the one that has been activated last to
 133    *   determine the 'current character pixel size'.
 134    *
 135    *   This function can be used to 'activate' a previously created size
 136    *   object.
 137    *
 138    * @input:
 139    *   size ::
 140    *     A handle to a target size object.
 141    *
 142    * @return:
 143    *   FreeType error code.  0~means success.
 144    *
 145    * @note:
 146    *   If `face` is the size's parent face object, this function changes the
 147    *   value of `face->size` to the input size handle.
 148    */
 149   FT_EXPORT( FT_Error )
 150   FT_Activate_Size( FT_Size  size );
 151 
 152   /* */
 153 
 154 
 155 FT_END_HEADER
 156 
 157 #endif /* FTSIZES_H_ */
 158 
 159 
 160 /* END */