pango/pango-engine.h

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