1/***************************************************************************/
2/*                                                                         */
3/*  ftsizes.h                                                              */
4/*                                                                         */
5/*    FreeType size objects management (specification).                    */
6/*                                                                         */
7/*  Copyright 1996-2001, 2003, 2004, 2006, 2009 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 "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 which 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