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