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
0088 /*
0089  * hb-font from ft-face.
0090  */
0091
0092 /*
0093  * Note:
0094  *
0095  * Set face size on ft-face before creating hb-font from it.
0096  * Otherwise hb-ft would NOT pick up the font size correctly.
0097  */
0098
0099 /* See notes on hb_ft_face_create().  Same issues re lifecycle-management
0100  * apply here.  Use hb_ft_font_create_referenced() if you can. */
0101 HB_EXTERN hb_font_t *
0102 hb_ft_font_create (FT_Face           ft_face,
0103            hb_destroy_func_t destroy);
0104
0105 /* See notes on hb_ft_face_create_referenced() re lifecycle-management
0106  * issues. */
0107 HB_EXTERN hb_font_t *
0108 hb_ft_font_create_referenced (FT_Face ft_face);
0109
0110 HB_EXTERN FT_Face
0111 hb_ft_font_get_face (hb_font_t *font);
0112
0113 HB_EXTERN FT_Face
0114 hb_ft_font_lock_face (hb_font_t *font);
0115
0116 HB_EXTERN void
0117 hb_ft_font_unlock_face (hb_font_t *font);
0118
0119 HB_EXTERN void
0120 hb_ft_font_set_load_flags (hb_font_t *font, int load_flags);
0121
0122 HB_EXTERN int
0123 hb_ft_font_get_load_flags (hb_font_t *font);
0124
0125 /* Call when size or variations settings on underlying FT_Face changed,
0126  * and you want to update the hb_font_t from it. */
0127 HB_EXTERN void
0128 hb_ft_font_changed (hb_font_t *font);
0129
0130 /* Call when size or variations settings on underlying hb_font_t may have
0131  * changed, and you want to update the FT_Face from it.  This call is fast
0132  * if nothing changed on hb_font_t. Returns true if changed. */
0133 HB_EXTERN hb_bool_t
0134 hb_ft_hb_font_changed (hb_font_t *font);
0135
0136 /* Makes an hb_font_t use FreeType internally to implement font functions.
0137  * Note: this internally creates an FT_Face.  Use it when you create your
0138  * hb_face_t using hb_face_create(). */
0139 HB_EXTERN void
0140 hb_ft_font_set_funcs (hb_font_t *font);
0141
0142
0143 HB_END_DECLS
0144
0145 #endif /* HB_FT_H */