freetype2/freetype/ftmac.h

0001 /****************************************************************************
0002  *
0003  * ftmac.h
0004  *
0005  *   Additional Mac-specific API.
0006  *
0007  * Copyright (C) 1996-2023 by
0008  * Just van Rossum, David Turner, Robert Wilhelm, and Werner Lemberg.
0009  *
0010  * This file is part of the FreeType project, and may only be used,
0011  * modified, and distributed under the terms of the FreeType project
0012  * license, LICENSE.TXT.  By continuing to use, modify, or distribute
0013  * this file you indicate that you have read the license and
0014  * understand and accept it fully.
0015  *
0016  */
0017
0018
0019 /****************************************************************************
0020  *
0021  * NOTE: Include this file after `FT_FREETYPE_H` and after any
0022  *       Mac-specific headers (because this header uses Mac types such as
0023  *       'Handle', 'FSSpec', 'FSRef', etc.)
0024  *
0025  */
0026
0027
0028 #ifndef FTMAC_H_
0029 #define FTMAC_H_
0030
0031
0032
0033
0034 FT_BEGIN_HEADER
0035
0036
0037   /* gcc-3.1 and later can warn about functions tagged as deprecated */
0038 #ifndef FT_DEPRECATED_ATTRIBUTE
0039 #if defined( __GNUC__ )                                     && \
0040     ( ( __GNUC__ >= 4 )                                  ||    \
0041       ( ( __GNUC__ == 3 ) && ( __GNUC_MINOR__ >= 1 ) ) )
0042 #define FT_DEPRECATED_ATTRIBUTE  __attribute__(( deprecated ))
0043 #else
0044 #define FT_DEPRECATED_ATTRIBUTE
0045 #endif
0046 #endif
0047
0048
0049   /**************************************************************************
0050    *
0051    * @section:
0052    *   mac_specific
0053    *
0054    * @title:
0055    *   Mac Specific Interface
0056    *
0057    * @abstract:
0058    *   Only available on the Macintosh.
0059    *
0060    * @description:
0061    *   The following definitions are only available if FreeType is compiled
0062    *   on a Macintosh.
0063    *
0064    */
0065
0066
0067   /**************************************************************************
0068    *
0069    * @function:
0070    *   FT_New_Face_From_FOND
0071    *
0072    * @description:
0073    *   Create a new face object from a FOND resource.
0074    *
0075    * @inout:
0076    *   library ::
0077    *     A handle to the library resource.
0078    *
0079    * @input:
0080    *   fond ::
0081    *     A FOND resource.
0082    *
0083    *   face_index ::
0084    *     Only supported for the -1 'sanity check' special case.
0085    *
0086    * @output:
0087    *   aface ::
0088    *     A handle to a new face object.
0089    *
0090    * @return:
0091    *   FreeType error code.  0~means success.
0092    *
0093    * @example:
0094    *   This function can be used to create @FT_Face objects from fonts that
0095    *   are installed in the system as follows.
0096    *
0097    *   ```
0098    *     fond  = GetResource( 'FOND', fontName );
0099    *     error = FT_New_Face_From_FOND( library, fond, 0, &face );
0100    *   ```
0101    */
0102   FT_EXPORT( FT_Error )
0103   FT_New_Face_From_FOND( FT_Library  library,
0104                          Handle      fond,
0105                          FT_Long     face_index,
0106                          FT_Face    *aface )
0107                        FT_DEPRECATED_ATTRIBUTE;
0108
0109
0110   /**************************************************************************
0111    *
0112    * @function:
0113    *   FT_GetFile_From_Mac_Name
0114    *
0115    * @description:
0116    *   Return an FSSpec for the disk file containing the named font.
0117    *
0118    * @input:
0119    *   fontName ::
0120    *     Mac OS name of the font (e.g., Times New Roman Bold).
0121    *
0122    * @output:
0123    *   pathSpec ::
0124    *     FSSpec to the file.  For passing to @FT_New_Face_From_FSSpec.
0125    *
0126    *   face_index ::
0127    *     Index of the face.  For passing to @FT_New_Face_From_FSSpec.
0128    *
0129    * @return:
0130    *   FreeType error code.  0~means success.
0131    */
0132   FT_EXPORT( FT_Error )
0133   FT_GetFile_From_Mac_Name( const char*  fontName,
0134                             FSSpec*      pathSpec,
0135                             FT_Long*     face_index )
0136                           FT_DEPRECATED_ATTRIBUTE;
0137
0138
0139   /**************************************************************************
0140    *
0141    * @function:
0142    *   FT_GetFile_From_Mac_ATS_Name
0143    *
0144    * @description:
0145    *   Return an FSSpec for the disk file containing the named font.
0146    *
0147    * @input:
0148    *   fontName ::
0149    *     Mac OS name of the font in ATS framework.
0150    *
0151    * @output:
0152    *   pathSpec ::
0153    *     FSSpec to the file. For passing to @FT_New_Face_From_FSSpec.
0154    *
0155    *   face_index ::
0156    *     Index of the face. For passing to @FT_New_Face_From_FSSpec.
0157    *
0158    * @return:
0159    *   FreeType error code.  0~means success.
0160    */
0161   FT_EXPORT( FT_Error )
0162   FT_GetFile_From_Mac_ATS_Name( const char*  fontName,
0163                                 FSSpec*      pathSpec,
0164                                 FT_Long*     face_index )
0165                               FT_DEPRECATED_ATTRIBUTE;
0166
0167
0168   /**************************************************************************
0169    *
0170    * @function:
0171    *   FT_GetFilePath_From_Mac_ATS_Name
0172    *
0173    * @description:
0174    *   Return a pathname of the disk file and face index for given font name
0175    *   that is handled by ATS framework.
0176    *
0177    * @input:
0178    *   fontName ::
0179    *     Mac OS name of the font in ATS framework.
0180    *
0181    * @output:
0182    *   path ::
0183    *     Buffer to store pathname of the file.  For passing to @FT_New_Face.
0184    *     The client must allocate this buffer before calling this function.
0185    *
0186    *   maxPathSize ::
0187    *     Lengths of the buffer `path` that client allocated.
0188    *
0189    *   face_index ::
0190    *     Index of the face.  For passing to @FT_New_Face.
0191    *
0192    * @return:
0193    *   FreeType error code.  0~means success.
0194    */
0195   FT_EXPORT( FT_Error )
0196   FT_GetFilePath_From_Mac_ATS_Name( const char*  fontName,
0197                                     UInt8*       path,
0198                                     UInt32       maxPathSize,
0199                                     FT_Long*     face_index )
0200                                   FT_DEPRECATED_ATTRIBUTE;
0201
0202
0203   /**************************************************************************
0204    *
0205    * @function:
0206    *   FT_New_Face_From_FSSpec
0207    *
0208    * @description:
0209    *   Create a new face object from a given resource and typeface index
0210    *   using an FSSpec to the font file.
0211    *
0212    * @inout:
0213    *   library ::
0214    *     A handle to the library resource.
0215    *
0216    * @input:
0217    *   spec ::
0218    *     FSSpec to the font file.
0219    *
0220    *   face_index ::
0221    *     The index of the face within the resource.  The first face has
0222    *     index~0.
0223    * @output:
0224    *   aface ::
0225    *     A handle to a new face object.
0226    *
0227    * @return:
0228    *   FreeType error code.  0~means success.
0229    *
0230    * @note:
0231    *   @FT_New_Face_From_FSSpec is identical to @FT_New_Face except it
0232    *   accepts an FSSpec instead of a path.
0233    */
0234   FT_EXPORT( FT_Error )
0235   FT_New_Face_From_FSSpec( FT_Library     library,
0236                            const FSSpec  *spec,
0237                            FT_Long        face_index,
0238                            FT_Face       *aface )
0239                          FT_DEPRECATED_ATTRIBUTE;
0240
0241
0242   /**************************************************************************
0243    *
0244    * @function:
0245    *   FT_New_Face_From_FSRef
0246    *
0247    * @description:
0248    *   Create a new face object from a given resource and typeface index
0249    *   using an FSRef to the font file.
0250    *
0251    * @inout:
0252    *   library ::
0253    *     A handle to the library resource.
0254    *
0255    * @input:
0256    *   spec ::
0257    *     FSRef to the font file.
0258    *
0259    *   face_index ::
0260    *     The index of the face within the resource.  The first face has
0261    *     index~0.
0262    * @output:
0263    *   aface ::
0264    *     A handle to a new face object.
0265    *
0266    * @return:
0267    *   FreeType error code.  0~means success.
0268    *
0269    * @note:
0270    *   @FT_New_Face_From_FSRef is identical to @FT_New_Face except it accepts
0271    *   an FSRef instead of a path.
0272    */
0273   FT_EXPORT( FT_Error )
0274   FT_New_Face_From_FSRef( FT_Library    library,
0275                           const FSRef  *ref,
0276                           FT_Long       face_index,
0277                           FT_Face      *aface )
0278                         FT_DEPRECATED_ATTRIBUTE;
0279
0280   /* */
0281
0282
0283 FT_END_HEADER
0284
0285
0286 #endif /* FTMAC_H_ */
0287
0288
0289 /* END */