include/freetype/ftmac.h

   1 /****************************************************************************
   2  *
   3  * ftmac.h
   4  *
   5  *   Additional Mac-specific API.
   6  *
   7  * Copyright (C) 1996-2020 by
   8  * Just van Rossum, 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  * NOTE: Include this file after `FT_FREETYPE_H` and after any
  22  *       Mac-specific headers (because this header uses Mac types such as
  23  *       'Handle', 'FSSpec', 'FSRef', etc.)
  24  *
  25  */
  26
  27
  28 #ifndef FTMAC_H_
  29 #define FTMAC_H_
  30
  31
  32
  33
  34 FT_BEGIN_HEADER
  35
  36
  37   /* gcc-3.1 and later can warn about functions tagged as deprecated */
  38 #ifndef FT_DEPRECATED_ATTRIBUTE
  39 #if defined( __GNUC__ )                                     && \
  40     ( ( __GNUC__ >= 4 )                                  ||    \
  41       ( ( __GNUC__ == 3 ) && ( __GNUC_MINOR__ >= 1 ) ) )
  42 #define FT_DEPRECATED_ATTRIBUTE  __attribute__(( deprecated ))
  43 #else
  44 #define FT_DEPRECATED_ATTRIBUTE
  45 #endif
  46 #endif
  47
  48
  49   /**************************************************************************
  50    *
  51    * @section:
  52    *   mac_specific
  53    *
  54    * @title:
  55    *   Mac Specific Interface
  56    *
  57    * @abstract:
  58    *   Only available on the Macintosh.
  59    *
  60    * @description:
  61    *   The following definitions are only available if FreeType is compiled
  62    *   on a Macintosh.
  63    *
  64    */
  65
  66
  67   /**************************************************************************
  68    *
  69    * @function:
  70    *   FT_New_Face_From_FOND
  71    *
  72    * @description:
  73    *   Create a new face object from a FOND resource.
  74    *
  75    * @inout:
  76    *   library ::
  77    *     A handle to the library resource.
  78    *
  79    * @input:
  80    *   fond ::
  81    *     A FOND resource.
  82    *
  83    *   face_index ::
  84    *     Only supported for the -1 'sanity check' special case.
  85    *
  86    * @output:
  87    *   aface ::
  88    *     A handle to a new face object.
  89    *
  90    * @return:
  91    *   FreeType error code.  0~means success.
  92    *
  93    * @example:
  94    *   This function can be used to create @FT_Face objects from fonts that
  95    *   are installed in the system as follows.
  96    *
  97    *   ```
  98    *     fond  = GetResource( 'FOND', fontName );
  99    *     error = FT_New_Face_From_FOND( library, fond, 0, &face );
 100    *   ```
 101    */
 102   FT_EXPORT( FT_Error )
 103   FT_New_Face_From_FOND( FT_Library  library,
 104                          Handle      fond,
 105                          FT_Long     face_index,
 106                          FT_Face    *aface )
 107                        FT_DEPRECATED_ATTRIBUTE;
 108
 109
 110   /**************************************************************************
 111    *
 112    * @function:
 113    *   FT_GetFile_From_Mac_Name
 114    *
 115    * @description:
 116    *   Return an FSSpec for the disk file containing the named font.
 117    *
 118    * @input:
 119    *   fontName ::
 120    *     Mac OS name of the font (e.g., Times New Roman Bold).
 121    *
 122    * @output:
 123    *   pathSpec ::
 124    *     FSSpec to the file.  For passing to @FT_New_Face_From_FSSpec.
 125    *
 126    *   face_index ::
 127    *     Index of the face.  For passing to @FT_New_Face_From_FSSpec.
 128    *
 129    * @return:
 130    *   FreeType error code.  0~means success.
 131    */
 132   FT_EXPORT( FT_Error )
 133   FT_GetFile_From_Mac_Name( const char*  fontName,
 134                             FSSpec*      pathSpec,
 135                             FT_Long*     face_index )
 136                           FT_DEPRECATED_ATTRIBUTE;
 137
 138
 139   /**************************************************************************
 140    *
 141    * @function:
 142    *   FT_GetFile_From_Mac_ATS_Name
 143    *
 144    * @description:
 145    *   Return an FSSpec for the disk file containing the named font.
 146    *
 147    * @input:
 148    *   fontName ::
 149    *     Mac OS name of the font in ATS framework.
 150    *
 151    * @output:
 152    *   pathSpec ::
 153    *     FSSpec to the file. For passing to @FT_New_Face_From_FSSpec.
 154    *
 155    *   face_index ::
 156    *     Index of the face. For passing to @FT_New_Face_From_FSSpec.
 157    *
 158    * @return:
 159    *   FreeType error code.  0~means success.
 160    */
 161   FT_EXPORT( FT_Error )
 162   FT_GetFile_From_Mac_ATS_Name( const char*  fontName,
 163                                 FSSpec*      pathSpec,
 164                                 FT_Long*     face_index )
 165                               FT_DEPRECATED_ATTRIBUTE;
 166
 167
 168   /**************************************************************************
 169    *
 170    * @function:
 171    *   FT_GetFilePath_From_Mac_ATS_Name
 172    *
 173    * @description:
 174    *   Return a pathname of the disk file and face index for given font name
 175    *   that is handled by ATS framework.
 176    *
 177    * @input:
 178    *   fontName ::
 179    *     Mac OS name of the font in ATS framework.
 180    *
 181    * @output:
 182    *   path ::
 183    *     Buffer to store pathname of the file.  For passing to @FT_New_Face.
 184    *     The client must allocate this buffer before calling this function.
 185    *
 186    *   maxPathSize ::
 187    *     Lengths of the buffer `path` that client allocated.
 188    *
 189    *   face_index ::
 190    *     Index of the face.  For passing to @FT_New_Face.
 191    *
 192    * @return:
 193    *   FreeType error code.  0~means success.
 194    */
 195   FT_EXPORT( FT_Error )
 196   FT_GetFilePath_From_Mac_ATS_Name( const char*  fontName,
 197                                     UInt8*       path,
 198                                     UInt32       maxPathSize,
 199                                     FT_Long*     face_index )
 200                                   FT_DEPRECATED_ATTRIBUTE;
 201
 202
 203   /**************************************************************************
 204    *
 205    * @function:
 206    *   FT_New_Face_From_FSSpec
 207    *
 208    * @description:
 209    *   Create a new face object from a given resource and typeface index
 210    *   using an FSSpec to the font file.
 211    *
 212    * @inout:
 213    *   library ::
 214    *     A handle to the library resource.
 215    *
 216    * @input:
 217    *   spec ::
 218    *     FSSpec to the font file.
 219    *
 220    *   face_index ::
 221    *     The index of the face within the resource.  The first face has
 222    *     index~0.
 223    * @output:
 224    *   aface ::
 225    *     A handle to a new face object.
 226    *
 227    * @return:
 228    *   FreeType error code.  0~means success.
 229    *
 230    * @note:
 231    *   @FT_New_Face_From_FSSpec is identical to @FT_New_Face except it
 232    *   accepts an FSSpec instead of a path.
 233    */
 234   FT_EXPORT( FT_Error )
 235   FT_New_Face_From_FSSpec( FT_Library     library,
 236                            const FSSpec  *spec,
 237                            FT_Long        face_index,
 238                            FT_Face       *aface )
 239                          FT_DEPRECATED_ATTRIBUTE;
 240
 241
 242   /**************************************************************************
 243    *
 244    * @function:
 245    *   FT_New_Face_From_FSRef
 246    *
 247    * @description:
 248    *   Create a new face object from a given resource and typeface index
 249    *   using an FSRef to the font file.
 250    *
 251    * @inout:
 252    *   library ::
 253    *     A handle to the library resource.
 254    *
 255    * @input:
 256    *   spec ::
 257    *     FSRef to the font file.
 258    *
 259    *   face_index ::
 260    *     The index of the face within the resource.  The first face has
 261    *     index~0.
 262    * @output:
 263    *   aface ::
 264    *     A handle to a new face object.
 265    *
 266    * @return:
 267    *   FreeType error code.  0~means success.
 268    *
 269    * @note:
 270    *   @FT_New_Face_From_FSRef is identical to @FT_New_Face except it accepts
 271    *   an FSRef instead of a path.
 272    */
 273   FT_EXPORT( FT_Error )
 274   FT_New_Face_From_FSRef( FT_Library    library,
 275                           const FSRef  *ref,
 276                           FT_Long       face_index,
 277                           FT_Face      *aface )
 278                         FT_DEPRECATED_ATTRIBUTE;
 279
 280   /* */
 281
 282
 283 FT_END_HEADER
 284
 285
 286 #endif /* FTMAC_H_ */
 287
 288
 289 /* END */