include/harfbuzz/hb-ft.h

0001 /*
0002  * Copyright © 2009  Red Hat, Inc.
0003  * Copyright © 2015  Google, Inc.
0004  *
0005  *  This is part of HarfBuzz, a text shaping library.
0006  *
0007  * Permission is hereby granted, without written agreement and without
0008  * license or royalty fees, to use, copy, modify, and distribute this
0009  * software and its documentation for any purpose, provided that the
0010  * above copyright notice and the following two paragraphs appear in
0011  * all copies of this software.
0012  *
0013  * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
0014  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
0015  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
0016  * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
0017  * DAMAGE.
0018  *
0019  * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
0020  * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
0021  * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
0022  * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
0023  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
0024  *
0025  * Red Hat Author(s): Behdad Esfahbod
0026  * Google Author(s): Behdad Esfahbod
0027  */
0028
0029 #ifndef HB_FT_H
0030 #define HB_FT_H
0031
0032 #include "hb.h"
0033
0034 #include <ft2build.h>
0035 #include FT_FREETYPE_H
0036
0037 HB_BEGIN_DECLS
0038
0039 /*
0040  * Note: FreeType is not thread-safe.
0041  * Hence, these functions are not either.
0042  */
0043
0044 /*
0045  * hb-face from ft-face.
0046  */
0047
0048 /* This one creates a new hb-face for given ft-face.
0049  * When the returned hb-face is destroyed, the destroy
0050  * callback is called (if not NULL), with the ft-face passed
0051  * to it.
0052  *
0053  * The client is responsible to make sure that ft-face is
0054  * destroyed after hb-face is destroyed.
0055  *
0056  * Most often you don't want this function.  You should use either
0057  * hb_ft_face_create_cached(), or hb_ft_face_create_referenced().
0058  * In particular, if you are going to pass NULL as destroy, you
0059  * probably should use (the more recent) hb_ft_face_create_referenced()
0060  * instead.
0061  */
0062 HB_EXTERN hb_face_t *
0063 hb_ft_face_create (FT_Face           ft_face,
0064            hb_destroy_func_t destroy);
0065
0066 /* This version is like hb_ft_face_create(), except that it caches
0067  * the hb-face using the generic pointer of the ft-face.  This means
0068  * that subsequent calls to this function with the same ft-face will
0069  * return the same hb-face (correctly referenced).
0070  *
0071  * Client is still responsible for making sure that ft-face is destroyed
0072  * after hb-face is.
0073  */
0074 HB_EXTERN hb_face_t *
0075 hb_ft_face_create_cached (FT_Face ft_face);
0076
0077 /* This version is like hb_ft_face_create(), except that it calls
0078  * FT_Reference_Face() on ft-face, as such keeping ft-face alive
0079  * as long as the hb-face is.
0080  *
0081  * This is the most convenient version to use.  Use it unless you have
0082  * very good reasons not to.
0083  */
0084 HB_EXTERN hb_face_t *
0085 hb_ft_face_create_referenced (FT_Face ft_face);
0086
0087 HB_EXTERN hb_face_t *
0088 hb_ft_face_create_from_file_or_fail (const char   *file_name,
0089                      unsigned int  index);
0090
0091 HB_EXTERN hb_face_t *
0092 hb_ft_face_create_from_blob_or_fail (hb_blob_t    *blob,
0093                      unsigned int  index);
0094
0095 /*
0096  * hb-font from ft-face.
0097  */
0098
0099 /*
0100  * Note:
0101  *
0102  * Set face size on ft-face before creating hb-font from it.
0103  * Otherwise hb-ft would NOT pick up the font size correctly.
0104  */
0105
0106 /* See notes on hb_ft_face_create().  Same issues re lifecycle-management
0107  * apply here.  Use hb_ft_font_create_referenced() if you can. */
0108 HB_EXTERN hb_font_t *
0109 hb_ft_font_create (FT_Face           ft_face,
0110            hb_destroy_func_t destroy);
0111
0112 /* See notes on hb_ft_face_create_referenced() re lifecycle-management
0113  * issues. */
0114 HB_EXTERN hb_font_t *
0115 hb_ft_font_create_referenced (FT_Face ft_face);
0116
0117 HB_EXTERN FT_Face
0118 hb_ft_font_get_ft_face (hb_font_t *font);
0119
0120 HB_EXTERN FT_Face
0121 hb_ft_font_lock_face (hb_font_t *font);
0122
0123 HB_EXTERN void
0124 hb_ft_font_unlock_face (hb_font_t *font);
0125
0126 HB_EXTERN void
0127 hb_ft_font_set_load_flags (hb_font_t *font, int load_flags);
0128
0129 HB_EXTERN int
0130 hb_ft_font_get_load_flags (hb_font_t *font);
0131
0132 /* Call when size or variations settings on underlying FT_Face changed,
0133  * and you want to update the hb_font_t from it. */
0134 HB_EXTERN void
0135 hb_ft_font_changed (hb_font_t *font);
0136
0137 /* Call when size or variations settings on underlying hb_font_t may have
0138  * changed, and you want to update the FT_Face from it.  This call is fast
0139  * if nothing changed on hb_font_t. Returns true if changed. */
0140 HB_EXTERN hb_bool_t
0141 hb_ft_hb_font_changed (hb_font_t *font);
0142
0143 /* Makes an hb_font_t use FreeType internally to implement font functions.
0144  * Note: this internally creates an FT_Face.  Use it when you create your
0145  * hb_face_t using hb_face_create(). */
0146 HB_EXTERN void
0147 hb_ft_font_set_funcs (hb_font_t *font);
0148
0149 #ifndef HB_DISABLE_DEPRECATED
0150
0151 HB_DEPRECATED_FOR (hb_ft_font_get_ft_face)
0152 HB_EXTERN FT_Face
0153 hb_ft_font_get_face (hb_font_t *font);
0154
0155 #endif
0156
0157 HB_END_DECLS
0158
0159 #endif /* HB_FT_H */