1  /*
       2   * Copyright © 2009  Red Hat, Inc.
       3   * Copyright © 2015  Google, Inc.
       4   *
       5   *  This is part of HarfBuzz, a text shaping library.
       6   *
       7   * Permission is hereby granted, without written agreement and without
       8   * license or royalty fees, to use, copy, modify, and distribute this
       9   * software and its documentation for any purpose, provided that the
      10   * above copyright notice and the following two paragraphs appear in
      11   * all copies of this software.
      12   *
      13   * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
      14   * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
      15   * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
      16   * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
      17   * DAMAGE.
      18   *
      19   * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
      20   * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
      21   * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
      22   * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
      23   * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
      24   *
      25   * Red Hat Author(s): Behdad Esfahbod
      26   * Google Author(s): Behdad Esfahbod
      27   */
      28  
      29  #ifndef HB_FT_H
      30  #define HB_FT_H
      31  
      32  #include "hb.h"
      33  
      34  #include <ft2build.h>
      35  #include FT_FREETYPE_H
      36  
      37  HB_BEGIN_DECLS
      38  
      39  /*
      40   * Note: FreeType is not thread-safe.
      41   * Hence, these functions are not either.
      42   */
      43  
      44  /*
      45   * hb-face from ft-face.
      46   */
      47  
      48  /* This one creates a new hb-face for given ft-face.
      49   * When the returned hb-face is destroyed, the destroy
      50   * callback is called (if not NULL), with the ft-face passed
      51   * to it.
      52   *
      53   * The client is responsible to make sure that ft-face is
      54   * destroyed after hb-face is destroyed.
      55   *
      56   * Most often you don't want this function.  You should use either
      57   * hb_ft_face_create_cached(), or hb_ft_face_create_referenced().
      58   * In particular, if you are going to pass NULL as destroy, you
      59   * probably should use (the more recent) hb_ft_face_create_referenced()
      60   * instead.
      61   */
      62  HB_EXTERN hb_face_t *
      63  hb_ft_face_create (FT_Face           ft_face,
      64  		   hb_destroy_func_t destroy);
      65  
      66  /* This version is like hb_ft_face_create(), except that it caches
      67   * the hb-face using the generic pointer of the ft-face.  This means
      68   * that subsequent calls to this function with the same ft-face will
      69   * return the same hb-face (correctly referenced).
      70   *
      71   * Client is still responsible for making sure that ft-face is destroyed
      72   * after hb-face is.
      73   */
      74  HB_EXTERN hb_face_t *
      75  hb_ft_face_create_cached (FT_Face ft_face);
      76  
      77  /* This version is like hb_ft_face_create(), except that it calls
      78   * FT_Reference_Face() on ft-face, as such keeping ft-face alive
      79   * as long as the hb-face is.
      80   *
      81   * This is the most convenient version to use.  Use it unless you have
      82   * very good reasons not to.
      83   */
      84  HB_EXTERN hb_face_t *
      85  hb_ft_face_create_referenced (FT_Face ft_face);
      86  
      87  
      88  /*
      89   * hb-font from ft-face.
      90   */
      91  
      92  /*
      93   * Note:
      94   *
      95   * Set face size on ft-face before creating hb-font from it.
      96   * Otherwise hb-ft would NOT pick up the font size correctly.
      97   */
      98  
      99  /* See notes on hb_ft_face_create().  Same issues re lifecycle-management
     100   * apply here.  Use hb_ft_font_create_referenced() if you can. */
     101  HB_EXTERN hb_font_t *
     102  hb_ft_font_create (FT_Face           ft_face,
     103  		   hb_destroy_func_t destroy);
     104  
     105  /* See notes on hb_ft_face_create_referenced() re lifecycle-management
     106   * issues. */
     107  HB_EXTERN hb_font_t *
     108  hb_ft_font_create_referenced (FT_Face ft_face);
     109  
     110  HB_EXTERN FT_Face
     111  hb_ft_font_get_face (hb_font_t *font);
     112  
     113  HB_EXTERN FT_Face
     114  hb_ft_font_lock_face (hb_font_t *font);
     115  
     116  HB_EXTERN void
     117  hb_ft_font_unlock_face (hb_font_t *font);
     118  
     119  HB_EXTERN void
     120  hb_ft_font_set_load_flags (hb_font_t *font, int load_flags);
     121  
     122  HB_EXTERN int
     123  hb_ft_font_get_load_flags (hb_font_t *font);
     124  
     125  /* Call when size or variations settings on underlying FT_Face changed,
     126   * and you want to update the hb_font_t from it. */
     127  HB_EXTERN void
     128  hb_ft_font_changed (hb_font_t *font);
     129  
     130  /* Call when size or variations settings on underlying hb_font_t may have
     131   * changed, and you want to update the FT_Face from it.  This call is fast
     132   * if nothing changed on hb_font_t. Returns true if changed. */
     133  HB_EXTERN hb_bool_t
     134  hb_ft_hb_font_changed (hb_font_t *font);
     135  
     136  /* Makes an hb_font_t use FreeType internally to implement font functions.
     137   * Note: this internally creates an FT_Face.  Use it when you create your
     138   * hb_face_t using hb_face_create(). */
     139  HB_EXTERN void
     140  hb_ft_font_set_funcs (hb_font_t *font);
     141  
     142  
     143  HB_END_DECLS
     144  
     145  #endif /* HB_FT_H */