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 */
161