hb-font.h revision c035812feb0d385a9e8c334631738e4915912c71 
1/*
2 * Copyright (C) 2009  Red Hat, Inc.
3 *
4 *  This is part of HarfBuzz, a text shaping library.
5 *
6 * Permission is hereby granted, without written agreement and without
7 * license or royalty fees, to use, copy, modify, and distribute this
8 * software and its documentation for any purpose, provided that the
9 * above copyright notice and the following two paragraphs appear in
10 * all copies of this software.
11 *
12 * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
13 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
14 * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
15 * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
16 * DAMAGE.
17 *
18 * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
19 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
20 * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
21 * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
22 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
23 *
24 * Red Hat Author(s): Behdad Esfahbod
25 */
26
27#ifndef HB_FONT_H
28#define HB_FONT_H
29
30#include "hb-common.h"
31#include "hb-blob.h"
32
33HB_BEGIN_DECLS
34
35
36typedef struct _hb_face_t hb_face_t;
37typedef struct _hb_font_t hb_font_t;
38
39/*
40 * hb_face_t
41 */
42
43hb_face_t *
44hb_face_create_for_data (hb_blob_t    *blob,
45			 unsigned int  index);
46
47typedef hb_blob_t * (*hb_get_table_func_t)  (hb_tag_t tag, void *user_data);
48
49/* calls destroy() when not needing user_data anymore */
50hb_face_t *
51hb_face_create_for_tables (hb_get_table_func_t  get_table,
52			   void                *user_data,
53			   hb_destroy_func_t    destroy);
54
55hb_face_t *
56hb_face_reference (hb_face_t *face);
57
58void
59hb_face_destroy (hb_face_t *face);
60
61/* XXX
62 *
63 * I have two major concerns about this API as it is right now:
64 *
65 *   - Jonathan Kew convinced me to make it return NULL if table not found (280af1bd),
66 *     however, that is WRONG IMO.  The API should not differentiate between a non-existing
67 *     table vs a zero-length table vs a very short table.  It only leads to implementations
68 *     that check for non-NULL and assume that they've got a usable table going on...  This
69 *     actually happened with Firefox.
70 */
71hb_blob_t *
72hb_face_reference_table (hb_face_t *face,
73			 hb_tag_t   tag);
74
75unsigned int
76hb_face_get_upem (hb_face_t *face);
77
78
79/*
80 * hb_font_funcs_t
81 */
82
83typedef struct _hb_font_funcs_t hb_font_funcs_t;
84
85hb_font_funcs_t *
86hb_font_funcs_create (void);
87
88hb_font_funcs_t *
89hb_font_funcs_reference (hb_font_funcs_t *ffuncs);
90
91void
92hb_font_funcs_destroy (hb_font_funcs_t *ffuncs);
93
94hb_font_funcs_t *
95hb_font_funcs_copy (hb_font_funcs_t *ffuncs);
96
97void
98hb_font_funcs_make_immutable (hb_font_funcs_t *ffuncs);
99
100hb_bool_t
101hb_font_funcs_is_immutable (hb_font_funcs_t *ffuncs);
102
103/* funcs */
104
105typedef struct _hb_glyph_extents_t
106{
107    hb_position_t x_bearing;
108    hb_position_t y_bearing;
109    hb_position_t width;
110    hb_position_t height;
111} hb_glyph_extents_t;
112
113typedef hb_codepoint_t (*hb_font_get_glyph_func_t) (hb_font_t *font, hb_face_t *face, const void *user_data,
114						    hb_codepoint_t unicode, hb_codepoint_t variation_selector);
115typedef void (*hb_font_get_glyph_advance_func_t) (hb_font_t *font, hb_face_t *face, const void *user_data,
116						  hb_codepoint_t glyph,
117						  hb_position_t *x_advance, hb_position_t *y_advance);
118typedef void (*hb_font_get_glyph_extents_func_t) (hb_font_t *font, hb_face_t *face, const void *user_data,
119						  hb_codepoint_t glyph,
120						  hb_glyph_extents_t *extents);
121typedef hb_bool_t (*hb_font_get_contour_point_func_t) (hb_font_t *font, hb_face_t *face, const void *user_data,
122						       unsigned int point_index, hb_codepoint_t glyph,
123						       hb_position_t *x, hb_position_t *y);
124typedef hb_position_t (*hb_font_get_kerning_func_t) (hb_font_t *font, hb_face_t *face, const void *user_data,
125						     hb_codepoint_t first_glyph, hb_codepoint_t second_glyph);
126
127
128void
129hb_font_funcs_set_glyph_func (hb_font_funcs_t *ffuncs,
130			      hb_font_get_glyph_func_t glyph_func);
131
132void
133hb_font_funcs_set_glyph_advance_func (hb_font_funcs_t *ffuncs,
134				      hb_font_get_glyph_advance_func_t glyph_advance_func);
135
136void
137hb_font_funcs_set_glyph_extents_func (hb_font_funcs_t *ffuncs,
138				      hb_font_get_glyph_extents_func_t glyph_extents_func);
139
140void
141hb_font_funcs_set_contour_point_func (hb_font_funcs_t *ffuncs,
142				      hb_font_get_contour_point_func_t contour_point_func);
143
144void
145hb_font_funcs_set_kerning_func (hb_font_funcs_t *ffuncs,
146				hb_font_get_kerning_func_t kerning_func);
147
148
149/* These never return NULL.  Return fallback defaults instead. */
150
151hb_font_get_glyph_func_t
152hb_font_funcs_get_glyph_func (hb_font_funcs_t *ffuncs);
153
154hb_font_get_glyph_advance_func_t
155hb_font_funcs_get_glyph_advance_func (hb_font_funcs_t *ffuncs);
156
157hb_font_get_glyph_extents_func_t
158hb_font_funcs_get_glyph_extents_func (hb_font_funcs_t *ffuncs);
159
160hb_font_get_contour_point_func_t
161hb_font_funcs_get_contour_point_func (hb_font_funcs_t *ffuncs);
162
163hb_font_get_kerning_func_t
164hb_font_funcs_get_kerning_func (hb_font_funcs_t *ffuncs);
165
166
167hb_codepoint_t
168hb_font_get_glyph (hb_font_t *font, hb_face_t *face,
169		   hb_codepoint_t unicode, hb_codepoint_t variation_selector);
170
171void
172hb_font_get_glyph_advance (hb_font_t *font, hb_face_t *face,
173			   hb_codepoint_t glyph,
174			   hb_position_t *x_advance, hb_position_t *y_advance);
175
176void
177hb_font_get_glyph_extents (hb_font_t *font, hb_face_t *face,
178			   hb_codepoint_t glyph,
179			   hb_glyph_extents_t *extents);
180
181hb_bool_t
182hb_font_get_contour_point (hb_font_t *font, hb_face_t *face,
183			   unsigned int point_index, hb_codepoint_t glyph,
184			   hb_position_t *x, hb_position_t *y);
185
186hb_position_t
187hb_font_get_kerning (hb_font_t *font, hb_face_t *face,
188		     hb_codepoint_t first_glyph, hb_codepoint_t second_glyph);
189
190
191/*
192 * hb_font_t
193 */
194
195/* Fonts are very light-weight objects */
196
197hb_font_t *
198hb_font_create (void);
199
200hb_font_t *
201hb_font_reference (hb_font_t *font);
202
203void
204hb_font_destroy (hb_font_t *font);
205
206void
207hb_font_set_funcs (hb_font_t         *font,
208		   hb_font_funcs_t   *klass,
209		   void              *user_data,
210		   hb_destroy_func_t  destroy);
211
212/* Returns what was set and unsets it, but doesn't destroy(user_data).
213 * This is useful for wrapping / chaining font_funcs_t's.
214 *
215 * The client is responsible for:
216 *
217 *   - Take ownership of the reference on the returned klass,
218 *
219 *   - Calling "destroy(user_data)" exactly once if returned destroy func
220 *     is not NULL and the returned info is not needed anymore.
221 */
222void
223hb_font_unset_funcs (hb_font_t          *font,
224		     hb_font_funcs_t   **klass,
225		     void              **user_data,
226		     hb_destroy_func_t  *destroy);
227
228
229/*
230 * We should add support for full matrices.
231 */
232void
233hb_font_set_scale (hb_font_t *font,
234		   unsigned int x_scale,
235		   unsigned int y_scale);
236
237void
238hb_font_get_scale (hb_font_t *font,
239		   unsigned int *x_scale,
240		   unsigned int *y_scale);
241
242/*
243 * A zero value means "no hinting in that direction"
244 */
245void
246hb_font_set_ppem (hb_font_t *font,
247		  unsigned int x_ppem,
248		  unsigned int y_ppem);
249
250void
251hb_font_get_ppem (hb_font_t *font,
252		  unsigned int *x_ppem,
253		  unsigned int *y_ppem);
254
255
256HB_END_DECLS
257
258#endif /* HB_FONT_H */
259