1/* Pango
2 * pango-glyph.h: Glyph storage
3 *
4 * Copyright (C) 2000 Red Hat Software
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
20 */
21
22#ifndef __PANGO_GLYPH_H__
23#define __PANGO_GLYPH_H__
24
25#include <pango/pango-types.h>
26#include <pango/pango-item.h>
27#include <pango/pango-break.h>
28
29G_BEGIN_DECLS
30
31typedef struct _PangoGlyphGeometry PangoGlyphGeometry;
32typedef struct _PangoGlyphVisAttr PangoGlyphVisAttr;
33typedef struct _PangoGlyphInfo PangoGlyphInfo;
34typedef struct _PangoGlyphString PangoGlyphString;
35
36/* 1024ths of a device unit */
37/**
38 * PangoGlyphUnit:
39 *
40 * The `PangoGlyphUnit` type is used to store dimensions within
41 * Pango.
42 *
43 * Dimensions are stored in 1/PANGO_SCALE of a device unit.
44 * (A device unit might be a pixel for screen display, or
45 * a point on a printer.) PANGO_SCALE is currently 1024, and
46 * may change in the future (unlikely though), but you should not
47 * depend on its exact value.
48 *
49 * The PANGO_PIXELS() macro can be used to convert from glyph units
50 * into device units with correct rounding.
51 */
52typedef gint32 PangoGlyphUnit;
53
54/* Positioning information about a glyph
55 */
56/**
57 * PangoGlyphGeometry:
58 * @width: the logical width to use for the the character.
59 * @x_offset: horizontal offset from nominal character position.
60 * @y_offset: vertical offset from nominal character position.
61 *
62 * The `PangoGlyphGeometry` structure contains width and positioning
63 * information for a single glyph.
64 *
65 * Note that @width is not guaranteed to be the same as the glyph
66 * extents. Kerning and other positioning applied during shaping will
67 * affect both the @width and the @x_offset for the glyphs in the
68 * glyph string that results from shaping.
69 *
70 * The information in this struct is intended for rendering the glyphs,
71 * as follows:
72 *
73 * 1. Assume the current point is (x, y)
74 * 2. Render the current glyph at (x + x_offset, y + y_offset),
75 * 3. Advance the current point to (x + width, y)
76 * 4. Render the next glyph
77 */
78struct _PangoGlyphGeometry
79{
80 PangoGlyphUnit width;
81 PangoGlyphUnit x_offset;
82 PangoGlyphUnit y_offset;
83};
84
85/* Visual attributes of a glyph
86 */
87/**
88 * PangoGlyphVisAttr:
89 * @is_cluster_start: set for the first logical glyph in each cluster.
90 * @is_color: set if the the font will render this glyph with color. Since 1.50
91 *
92 * A `PangoGlyphVisAttr` structure communicates information between
93 * the shaping and rendering phases.
94 *
95 * Currently, it contains cluster start and color information.
96 * More attributes may be added in the future.
97 *
98 * Clusters are stored in visual order, within the cluster, glyphs
99 * are always ordered in logical order, since visual order is meaningless;
100 * that is, in Arabic text, accent glyphs follow the glyphs for the
101 * base character.
102 */
103struct _PangoGlyphVisAttr
104{
105 guint is_cluster_start : 1;
106 guint is_color : 1;
107};
108
109/* A single glyph
110 */
111/**
112 * PangoGlyphInfo:
113 * @glyph: the glyph itself.
114 * @geometry: the positional information about the glyph.
115 * @attr: the visual attributes of the glyph.
116 *
117 * A `PangoGlyphInfo` structure represents a single glyph with
118 * positioning information and visual attributes.
119 */
120struct _PangoGlyphInfo
121{
122 PangoGlyph glyph;
123 PangoGlyphGeometry geometry;
124 PangoGlyphVisAttr attr;
125};
126
127/**
128 * PangoGlyphString:
129 * @num_glyphs: number of glyphs in this glyph string
130 * @glyphs: (array length=num_glyphs): array of glyph information
131 * @log_clusters: logical cluster info, indexed by the byte index
132 * within the text corresponding to the glyph string
133 *
134 * A `PangoGlyphString` is used to store strings of glyphs with geometry
135 * and visual attribute information.
136 *
137 * The storage for the glyph information is owned by the structure
138 * which simplifies memory management.
139 */
140struct _PangoGlyphString {
141 int num_glyphs;
142
143 PangoGlyphInfo *glyphs;
144 int *log_clusters;
145
146 /*< private >*/
147 int space;
148};
149
150#define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
151
152PANGO_AVAILABLE_IN_ALL
153GType pango_glyph_string_get_type (void) G_GNUC_CONST;
154
155PANGO_AVAILABLE_IN_ALL
156PangoGlyphString * pango_glyph_string_new (void);
157PANGO_AVAILABLE_IN_ALL
158void pango_glyph_string_set_size (PangoGlyphString *string,
159 int new_len);
160
161PANGO_AVAILABLE_IN_ALL
162PangoGlyphString * pango_glyph_string_copy (PangoGlyphString *string);
163PANGO_AVAILABLE_IN_ALL
164void pango_glyph_string_free (PangoGlyphString *string);
165
166PANGO_AVAILABLE_IN_ALL
167void pango_glyph_string_extents (PangoGlyphString *glyphs,
168 PangoFont *font,
169 PangoRectangle *ink_rect,
170 PangoRectangle *logical_rect);
171PANGO_AVAILABLE_IN_1_14
172int pango_glyph_string_get_width (PangoGlyphString *glyphs);
173
174PANGO_AVAILABLE_IN_ALL
175void pango_glyph_string_extents_range (PangoGlyphString *glyphs,
176 int start,
177 int end,
178 PangoFont *font,
179 PangoRectangle *ink_rect,
180 PangoRectangle *logical_rect);
181
182PANGO_AVAILABLE_IN_ALL
183void pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
184 const char *text,
185 int length,
186 int embedding_level,
187 int *logical_widths);
188
189PANGO_AVAILABLE_IN_ALL
190void pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
191 const char *text,
192 int length,
193 PangoAnalysis *analysis,
194 int index_,
195 gboolean trailing,
196 int *x_pos);
197PANGO_AVAILABLE_IN_ALL
198void pango_glyph_string_x_to_index (PangoGlyphString *glyphs,
199 const char *text,
200 int length,
201 PangoAnalysis *analysis,
202 int x_pos,
203 int *index_,
204 int *trailing);
205
206PANGO_AVAILABLE_IN_1_50
207void pango_glyph_string_index_to_x_full (PangoGlyphString *glyphs,
208 const char *text,
209 int length,
210 PangoAnalysis *analysis,
211 PangoLogAttr *attrs,
212 int index_,
213 gboolean trailing,
214 int *x_pos);
215
216/* Shaping */
217
218/**
219 * PangoShapeFlags:
220 * @PANGO_SHAPE_NONE: Default value
221 * @PANGO_SHAPE_ROUND_POSITIONS: Round glyph positions and widths to whole device units
222 * This option should be set if the target renderer can't do subpixel positioning of glyphs
223 *
224 * Flags influencing the shaping process.
225 *
226 * `PangoShapeFlags` can be passed to [func@Pango.shape_with_flags].
227 *
228 * Since: 1.44
229 */
230typedef enum {
231 PANGO_SHAPE_NONE = 0,
232 PANGO_SHAPE_ROUND_POSITIONS = 1 << 0,
233} PangoShapeFlags;
234
235PANGO_AVAILABLE_IN_ALL
236void pango_shape (const char *text,
237 int length,
238 const PangoAnalysis *analysis,
239 PangoGlyphString *glyphs);
240
241PANGO_AVAILABLE_IN_1_32
242void pango_shape_full (const char *item_text,
243 int item_length,
244 const char *paragraph_text,
245 int paragraph_length,
246 const PangoAnalysis *analysis,
247 PangoGlyphString *glyphs);
248
249PANGO_AVAILABLE_IN_1_44
250void pango_shape_with_flags (const char *item_text,
251 int item_length,
252 const char *paragraph_text,
253 int paragraph_length,
254 const PangoAnalysis *analysis,
255 PangoGlyphString *glyphs,
256 PangoShapeFlags flags);
257
258
259PANGO_AVAILABLE_IN_1_50
260void pango_shape_item (PangoItem *item,
261 const char *paragraph_text,
262 int paragraph_length,
263 PangoLogAttr *log_attrs,
264 PangoGlyphString *glyphs,
265 PangoShapeFlags flags);
266
267
268G_END_DECLS
269
270#endif /* __PANGO_GLYPH_H__ */
271

source code of include/pango-1.0/pango/pango-glyph.h