include/freetype/ftsizes.h

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