1/***************************************************************************/
2/* */
3/* ftsizes.h */
4/* */
5/* FreeType size objects management (specification). */
6/* */
7/* Copyright 1996-2018 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 */
23 /* where 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
42FT_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 */
58 /* @FT_Size object is automatically created and used to store all */
59 /* pixel-size dependent information, available in the `face->size' */
60 /* field. */
61 /* */
62 /* It is however possible to create more sizes for a given face, */
63 /* mostly in order to manage several character pixel sizes of the */
64 /* same font family and style. See @FT_New_Size and @FT_Done_Size. */
65 /* */
66 /* Note that @FT_Set_Pixel_Sizes and @FT_Set_Char_Size only */
67 /* modify the contents of the current `active' size; you thus need */
68 /* to use @FT_Activate_Size to change it. */
69 /* */
70 /* 99% of applications won't need the functions provided here, */
71 /* especially if they use the caching sub-system, so be cautious */
72 /* when using these. */
73 /* */
74 /*************************************************************************/
75
76
77 /*************************************************************************/
78 /* */
79 /* <Function> */
80 /* FT_New_Size */
81 /* */
82 /* <Description> */
83 /* Create a new size object from a given face object. */
84 /* */
85 /* <Input> */
86 /* face :: A handle to a parent face object. */
87 /* */
88 /* <Output> */
89 /* asize :: 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 */
96 /* for 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 */
111 /* automatically discards all size objects allocated with */
112 /* @FT_New_Size. */
113 /* */
114 /* <Input> */
115 /* size :: 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 */
131 /* given face (see @FT_New_Size for details), functions like */
132 /* @FT_Load_Glyph or @FT_Load_Char only use the one that has been */
133 /* activated last to 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 :: 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 */
146 /* the 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