1/****************************************************************************
2 *
3 * ftsizes.h
4 *
5 * FreeType size objects management (specification).
6 *
7 * Copyright (C) 1996-2021 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
41FT_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
154FT_END_HEADER
155
156#endif /* FTSIZES_H_ */
157
158
159/* END */
160

source code of include/freetype2/freetype/ftsizes.h