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