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