libraries/freetype-2.0.5/include/freetype/ftsizes.h

   1 /***************************************************************************/
   2 /*                                                                         */
   3 /*  ftsizes.h                                                              */
   4 /*                                                                         */
   5 /*    FreeType size objects management (specification).                    */
   6 /*                                                                         */
   7 /*  Copyright 1996-2001 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
  36 FT_BEGIN_HEADER
  37
  38
  39   /*************************************************************************/
  40   /*                                                                       */
  41   /* <Section>                                                             */
  42   /*    sizes_management                                                   */
  43   /*                                                                       */
  44   /* <Title>                                                               */
  45   /*    Size management                                                    */
  46   /*                                                                       */
  47   /* <Abstract>                                                            */
  48   /*    Managing multiple sizes per face                                   */
  49   /*                                                                       */
  50   /* <Description>                                                         */
  51   /*    When creating a new face object (e.g. with @FT_New_Face), an       */
  52   /*    @FT_Size object is automatically created and used to store all     */
  53   /*    pixel-size dependent information, available in the "face->size"    */
  54   /*    field.                                                             */
  55   /*                                                                       */
  56   /*    It is however possible to create more sizes for a given face,      */
  57   /*    mostly in order to manage several character pixel sizes of the     */
  58   /*    same font family and style.  See @FT_New_Size and @FT_Done_Size.   */
  59   /*                                                                       */
  60   /*    Note that @FT_Set_Pixel_Sizes and @FT_Set_Character_Size only      */
  61   /*    modify the contents of the current "active" size; you thus need    */
  62   /*    to use @FT_Activate_Size to change it.                             */
  63   /*                                                                       */
  64   /*    99% of applications won't need the functions provided here,        */
  65   /*    especially if they use the caching sub-system, so be cautious      */
  66   /*    when using these.                                                  */
  67   /*                                                                       */
  68   /*************************************************************************/
  69
  70
  71   /*************************************************************************/
  72   /*                                                                       */
  73   /* <Function>                                                            */
  74   /*    FT_New_Size                                                        */
  75   /*                                                                       */
  76   /* <Description>                                                         */
  77   /*    Creates a new size object from a given face object.                */
  78   /*                                                                       */
  79   /* <Input>                                                               */
  80   /*    face :: A handle to a parent face object.                          */
  81   /*                                                                       */
  82   /* <Output>                                                              */
  83   /*    asize :: A handle to a new size object.                            */
  84   /*                                                                       */
  85   /* <Return>                                                              */
  86   /*    FreeType error code.  0 means success.                             */
  87   /*                                                                       */
  88   /* <Note>                                                                */
  89   /*    You need to call @FT_Activate_Size in order to select the new size */
  90   /*    for upcoming calls to @FT_Set_Pixel_Sizes, @FT_Set_Char_Size,      */
  91   /*    @FT_Load_Glyph, @FT_Load_Char, etc.                                */
  92   /*                                                                       */
  93   FT_EXPORT( FT_Error )
  94   FT_New_Size( FT_Face   face,
  95                FT_Size*  size );
  96
  97
  98   /*************************************************************************/
  99   /*                                                                       */
 100   /* <Function>                                                            */
 101   /*    FT_Done_Size                                                       */
 102   /*                                                                       */
 103   /* <Description>                                                         */
 104   /*    Discards a given size object.                                      */
 105   /*                                                                       */
 106   /* <Input>                                                               */
 107   /*    size :: A handle to a target size object.                          */
 108   /*                                                                       */
 109   /* <Return>                                                              */
 110   /*    FreeType error code.  0 means success.                             */
 111   /*                                                                       */
 112   FT_EXPORT( FT_Error )
 113   FT_Done_Size( FT_Size  size );
 114
 115
 116   /*************************************************************************/
 117   /*                                                                       */
 118   /* <Function>                                                            */
 119   /*    FT_Activate_Size                                                   */
 120   /*                                                                       */
 121   /* <Description>                                                         */
 122   /*    Even though it is possible to create several size objects for a    */
 123   /*    given face (see @FT_New_Size for details), functions like          */
 124   /*    @FT_Load_Glyph or @FT_Load_Char only use the last-created one to   */
 125   /*    determine the "current character pixel size".                      */
 126   /*                                                                       */
 127   /*    This function can be used to "activate" a previously created size  */
 128   /*    object.                                                            */
 129   /*                                                                       */
 130   /* <Input>                                                               */
 131   /*    size :: A handle to a target size object.                          */
 132   /*                                                                       */
 133   /* <Return>                                                              */
 134   /*    FreeType error code.  0 means success.                             */
 135   /*                                                                       */
 136   /* <Note>                                                                */
 137   /*    If "face" is the size's parent face object, this function changes  */
 138   /*    the value of "face->size" to the input size handle.                */
 139   /*                                                                       */
 140   FT_EXPORT( FT_Error )
 141   FT_Activate_Size( FT_Size  size );
 142
 143   /* */
 144
 145
 146 FT_END_HEADER
 147
 148 #endif /* __FTSIZES_H__ */
 149
 150
 151 /* END */