1/* Pango
2 * pango-engine.h: Engines for script and language specific processing
3 *
4 * Copyright (C) 2000,2003 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_ENGINE_H__
23#define __PANGO_ENGINE_H__
24
25#include <pango/pango-types.h>
26#include <pango/pango-item.h>
27#include <pango/pango-font.h>
28#include <pango/pango-glyph.h>
29#include <pango/pango-script.h>
30
31G_BEGIN_DECLS
32
33/* All of this is deprecated and entirely useless for bindings.
34 * Leave it out of the gir file.
35 */
36#ifndef __GI_SCANNER__
37
38#ifndef PANGO_DISABLE_DEPRECATED
39
40/**
41 * PANGO_RENDER_TYPE_NONE:
42 *
43 * A string constant defining the render type
44 * for engines that are not rendering-system specific.
45 *
46 * Deprecated: 1.38
47 */
48#define PANGO_RENDER_TYPE_NONE "PangoRenderNone"
49
50#define PANGO_TYPE_ENGINE (pango_engine_get_type ())
51#define PANGO_ENGINE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE, PangoEngine))
52#define PANGO_IS_ENGINE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE))
53#define PANGO_ENGINE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE, PangoEngineClass))
54#define PANGO_IS_ENGINE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE))
55#define PANGO_ENGINE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE, PangoEngineClass))
56
57typedef struct _PangoEngine PangoEngine;
58typedef struct _PangoEngineClass PangoEngineClass;
59
60/**
61 * PangoEngine:
62 *
63 * `PangoEngine` is the base class for all types of language and
64 * script specific engines. It has no functionality by itself.
65 *
66 * Deprecated: 1.38
67 **/
68struct _PangoEngine
69{
70 /*< private >*/
71 GObject parent_instance;
72};
73
74/**
75 * PangoEngineClass:
76 *
77 * Class structure for `PangoEngine`
78 *
79 * Deprecated: 1.38
80 **/
81struct _PangoEngineClass
82{
83 /*< private >*/
84 GObjectClass parent_class;
85};
86
87PANGO_DEPRECATED_IN_1_38
88GType pango_engine_get_type (void) G_GNUC_CONST;
89
90/**
91 * PANGO_ENGINE_TYPE_LANG:
92 *
93 * A string constant defining the engine type for language engines.
94 * These engines derive from `PangoEngineLang`.
95 *
96 * Deprecated: 1.38
97 */
98#define PANGO_ENGINE_TYPE_LANG "PangoEngineLang"
99
100#define PANGO_TYPE_ENGINE_LANG (pango_engine_lang_get_type ())
101#define PANGO_ENGINE_LANG(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE_LANG, PangoEngineLang))
102#define PANGO_IS_ENGINE_LANG(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE_LANG))
103#define PANGO_ENGINE_LANG_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE_LANG, PangoEngineLangClass))
104#define PANGO_IS_ENGINE_LANG_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE_LANG))
105#define PANGO_ENGINE_LANG_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE_LANG, PangoEngineLangClass))
106
107typedef struct _PangoEngineLangClass PangoEngineLangClass;
108
109/**
110 * PangoEngineLang:
111 *
112 * The `PangoEngineLang` class is implemented by engines that
113 * customize the rendering-system independent part of the
114 * Pango pipeline for a particular script or language. For
115 * instance, a custom `PangoEngineLang` could be provided for
116 * Thai to implement the dictionary-based word boundary
117 * lookups needed for that language.
118 *
119 * Deprecated: 1.38
120 **/
121struct _PangoEngineLang
122{
123 /*< private >*/
124 PangoEngine parent_instance;
125};
126
127/**
128 * PangoEngineLangClass:
129 * @script_break: (nullable): Provides a custom implementation of
130 * pango_break(). If %NULL, pango_default_break() is used instead. If
131 * not %NULL, for Pango versions before 1.16 (module interface version
132 * before 1.6.0), this was called instead of pango_default_break(),
133 * but in newer versions, pango_default_break() is always called and
134 * this is called after that to allow tailoring the breaking results.
135 *
136 * Class structure for `PangoEngineLang`
137 *
138 * Deprecated: 1.38
139 **/
140struct _PangoEngineLangClass
141{
142 /*< private >*/
143 PangoEngineClass parent_class;
144
145 /*< public >*/
146 void (*script_break) (PangoEngineLang *engine,
147 const char *text,
148 int len,
149 PangoAnalysis *analysis,
150 PangoLogAttr *attrs,
151 int attrs_len);
152};
153
154PANGO_DEPRECATED_IN_1_38
155GType pango_engine_lang_get_type (void) G_GNUC_CONST;
156
157/**
158 * PANGO_ENGINE_TYPE_SHAPE:
159 *
160 * A string constant defining the engine type for shaping engines.
161 * These engines derive from `PangoEngineShape`.
162 *
163 * Deprecated: 1.38
164 */
165#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
166
167#define PANGO_TYPE_ENGINE_SHAPE (pango_engine_shape_get_type ())
168#define PANGO_ENGINE_SHAPE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShape))
169#define PANGO_IS_ENGINE_SHAPE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_ENGINE_SHAPE))
170#define PANGO_ENGINE_SHAPE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_ENGINE_SHAPE, PangoEngine_ShapeClass))
171#define PANGO_IS_ENGINE_SHAPE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_ENGINE_SHAPE))
172#define PANGO_ENGINE_SHAPE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_ENGINE_SHAPE, PangoEngineShapeClass))
173
174typedef struct _PangoEngineShapeClass PangoEngineShapeClass;
175
176/**
177 * PangoEngineShape:
178 *
179 * The `PangoEngineShape` class is implemented by engines that
180 * customize the rendering-system dependent part of the
181 * Pango pipeline for a particular script or language.
182 * A `PangoEngineShape` implementation is then specific to both
183 * a particular rendering system or group of rendering systems
184 * and to a particular script. For instance, there is one
185 * `PangoEngineShape` implementation to handle shaping Arabic
186 * for Fontconfig-based backends.
187 *
188 * Deprecated: 1.38
189 **/
190struct _PangoEngineShape
191{
192 PangoEngine parent_instance;
193};
194
195/**
196 * PangoEngineShapeClass:
197 * @script_shape: Given a font, a piece of text, and a `PangoAnalysis`
198 * structure, converts characters to glyphs and positions the
199 * resulting glyphs. The results are stored in the `PangoGlyphString`
200 * that is passed in. (The implementation should resize it
201 * appropriately using pango_glyph_string_set_size()). All fields
202 * of the @log_clusters and @glyphs array must be filled in, with
203 * the exception that Pango will automatically generate
204 * `glyphs->glyphs[i].attr.is_cluster_start`
205 * using the @log_clusters array. Each input character must occur in one
206 * of the output logical clusters;
207 * if no rendering is desired for a character, this may involve
208 * inserting glyphs with the `PangoGlyph` ID %PANGO_GLYPH_EMPTY, which
209 * is guaranteed never to render. If the shaping fails for any reason,
210 * the shaper should return with an empty (zero-size) glyph string.
211 * If the shaper has not set the size on the glyph string yet, simply
212 * returning signals the failure too.
213 * @covers: Returns the characters that this engine can cover
214 * with a given font for a given language. If not overridden, the default
215 * implementation simply returns the coverage information for the
216 * font itself unmodified.
217 *
218 * Class structure for `PangoEngineShape`
219 *
220 * Deprecated: 1.38
221 **/
222struct _PangoEngineShapeClass
223{
224 /*< private >*/
225 PangoEngineClass parent_class;
226
227 /*< public >*/
228 void (*script_shape) (PangoEngineShape *engine,
229 PangoFont *font,
230 const char *item_text,
231 unsigned int item_length,
232 const PangoAnalysis *analysis,
233 PangoGlyphString *glyphs,
234 const char *paragraph_text,
235 unsigned int paragraph_length);
236 PangoCoverageLevel (*covers) (PangoEngineShape *engine,
237 PangoFont *font,
238 PangoLanguage *language,
239 gunichar wc);
240};
241
242PANGO_DEPRECATED_IN_1_38
243GType pango_engine_shape_get_type (void) G_GNUC_CONST;
244
245typedef struct _PangoEngineInfo PangoEngineInfo;
246typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
247
248/**
249 * PangoEngineScriptInfo:
250 * @script: a `PangoScript`. The value %PANGO_SCRIPT_COMMON has
251 * the special meaning here of "all scripts"
252 * @langs: a semicolon separated list of languages that this
253 * engine handles for this script. This may be empty,
254 * in which case the engine is saying that it is a
255 * fallback choice for all languages for this range,
256 * but should not be used if another engine
257 * indicates that it is specific for the language for
258 * a given code point. An entry in this list of "*"
259 * indicates that this engine is specific to all
260 * languages for this range.
261 *
262 * The `PangoEngineScriptInfo` structure contains
263 * information about how the shaper covers a particular script.
264 *
265 * Deprecated: 1.38
266 */
267struct _PangoEngineScriptInfo
268{
269 PangoScript script;
270 const gchar *langs;
271};
272
273/**
274 * PangoEngineInfo:
275 * @id: a unique string ID for the engine.
276 * @engine_type: a string identifying the engine type.
277 * @render_type: a string identifying the render type.
278 * @scripts: array of scripts this engine supports.
279 * @n_scripts: number of items in @scripts.
280 *
281 * The `PangoEngineInfo` structure contains information about a particular
282 * engine. It contains the following fields:
283 *
284 * Deprecated: 1.38
285 */
286struct _PangoEngineInfo
287{
288 const gchar *id;
289 const gchar *engine_type;
290 const gchar *render_type;
291 PangoEngineScriptInfo *scripts;
292 gint n_scripts;
293};
294
295/**
296 * script_engine_list: (skip)
297 * @engines: location to store a pointer to an array of engines.
298 * @n_engines: location to store the number of elements in @engines.
299 *
300 * Do not use.
301 *
302 * Deprecated: 1.38
303 **/
304PANGO_DEPRECATED_IN_1_38
305void script_engine_list (PangoEngineInfo **engines,
306 int *n_engines);
307
308/**
309 * script_engine_init: (skip)
310 * @module: a `GTypeModule` structure used to associate any
311 * GObject types created in this module with the module.
312 *
313 * Do not use.
314 *
315 * Deprecated: 1.38
316 **/
317PANGO_DEPRECATED_IN_1_38
318void script_engine_init (GTypeModule *module);
319
320
321/**
322 * script_engine_exit: (skip)
323 *
324 * Do not use.
325 *
326 * Deprecated: 1.38
327 **/
328PANGO_DEPRECATED_IN_1_38
329void script_engine_exit (void);
330
331/**
332 * script_engine_create: (skip)
333 * @id: the ID of an engine as reported by script_engine_list.
334 *
335 * Do not use.
336 *
337 * Deprecated: 1.38
338 **/
339PANGO_DEPRECATED_IN_1_38
340PangoEngine *script_engine_create (const char *id);
341
342/* Utility macro used by PANGO_ENGINE_LANG_DEFINE_TYPE and
343 * PANGO_ENGINE_LANG_DEFINE_TYPE
344 */
345#define PANGO_ENGINE_DEFINE_TYPE(name, prefix, class_init, instance_init, parent_type) \
346static GType prefix ## _type; \
347static void \
348prefix ## _register_type (GTypeModule *module) \
349{ \
350 const GTypeInfo object_info = \
351 { \
352 sizeof (name ## Class), \
353 (GBaseInitFunc) NULL, \
354 (GBaseFinalizeFunc) NULL, \
355 (GClassInitFunc) class_init, \
356 (GClassFinalizeFunc) NULL, \
357 NULL, /* class_data */ \
358 sizeof (name), \
359 0, /* n_prelocs */ \
360 (GInstanceInitFunc) instance_init, \
361 NULL /* value_table */ \
362 }; \
363 \
364 prefix ## _type = g_type_module_register_type (module, parent_type, \
365 # name, \
366 &object_info, 0); \
367}
368
369/**
370 * PANGO_ENGINE_LANG_DEFINE_TYPE:
371 * @name: Name of the the type to register (for example:, ArabicEngineFc)
372 * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
373 * @class_init: (nullable): Class initialization function for the new type
374 * @instance_init: (nullable): Instance initialization function for the new type
375 *
376 * Outputs the necessary code for GObject type registration for a
377 * `PangoEngineLang` class defined in a module. Two static symbols
378 * are defined.
379 *
380 * <programlisting>
381 * static GType *prefix*_type;
382 * static void *prefix*_register_type (GTypeModule module);
383 *
384 * The *prefix*_register_type()
385 * function should be called in your script_engine_init() function for
386 * each type that your module implements, and then your script_engine_create()
387 * function can create instances of the object as follows:
388 *
389 * ```
390 * PangoEngine *engine = g_object_new (prefix_type, NULL);
391 * ```
392 *
393 * Deprecated: 1.38
394 **/
395#define PANGO_ENGINE_LANG_DEFINE_TYPE(name, prefix, class_init, instance_init) \
396 PANGO_ENGINE_DEFINE_TYPE (name, prefix, \
397 class_init, instance_init, \
398 PANGO_TYPE_ENGINE_LANG)
399
400/**
401 * PANGO_ENGINE_SHAPE_DEFINE_TYPE:
402 * @name: Name of the the type to register (for example:, ArabicEngineFc)
403 * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
404 * @class_init: (nullable): Class initialization function for the new type
405 * @instance_init: (nullable): Instance initialization function for the new type
406 *
407 * Outputs the necessary code for GObject type registration for a
408 * `PangoEngineShape` class defined in a module. Two static symbols
409 * are defined.
410 *
411 * <programlisting>
412 * static GType *prefix*_type;
413 * static void *prefix*_register_type (GTypeModule module);
414 * </programlisting>
415 *
416 * The *prefix*_register_type()
417 * function should be called in your script_engine_init() function for
418 * each type that your module implements, and then your script_engine_create()
419 * function can create instances of the object as follows:
420 *
421 * ```
422 * PangoEngine *engine = g_object_new (prefix_type, NULL);
423 * ```
424 *
425 * Deprecated: 1.38
426 **/
427#define PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init) \
428 PANGO_ENGINE_DEFINE_TYPE (name, prefix, \
429 class_init, instance_init, \
430 PANGO_TYPE_ENGINE_SHAPE)
431
432/* Macro used for possibly builtin Pango modules. Not useful
433 * for externally build modules. If we are compiling a module standalone,
434 * then we name the entry points script_engine_list, etc. But if we
435 * are compiling it for inclusion directly in Pango, then we need them to
436 * to have distinct names for this module, so we prepend a prefix.
437 *
438 * The two intermediate macros are to deal with details of the C
439 * preprocessor; token pasting tokens must be function arguments,
440 * and macro substitution isn't used on function arguments that
441 * are used for token pasting.
442 */
443#ifdef PANGO_MODULE_PREFIX
444#define PANGO_MODULE_ENTRY(func) _PANGO_MODULE_ENTRY2(PANGO_MODULE_PREFIX,func)
445#define _PANGO_MODULE_ENTRY2(prefix,func) _PANGO_MODULE_ENTRY3(prefix,func)
446#define _PANGO_MODULE_ENTRY3(prefix,func) prefix##_script_engine_##func
447#else
448#define PANGO_MODULE_ENTRY(func) script_engine_##func
449#endif
450
451#endif /* PANGO_DISABLE_DEPRECATED */
452
453#endif /* __GI_SCANNER__ */
454
455G_END_DECLS
456
457#endif /* __PANGO_ENGINE_H__ */
458

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