docs/xml/pango-engine-shape.xml

   1 <refentry id="PangoEngineShape">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="PangoEngineShape.top_of_page">PangoEngineShape</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>PangoEngineShape</refname>
  10 <refpurpose>Rendering-system dependent script engines</refpurpose>
  11 </refnamediv>
  12 <refsect1 id="PangoEngineShape.stability-level">
  13 <title>Stability Level</title>
  14 Unstable, unless otherwise indicated
  15 </refsect1>
  16
  17 <refsynopsisdiv id="PangoEngineShape.synopsis" role="synopsis">
  18 <title role="synopsis.title">Synopsis</title>
  19
  20 <synopsis>
  21                     <link linkend="PangoEngineShape-struct">PangoEngineShape</link>;
  22                     <link linkend="PangoEngineShapeClass">PangoEngineShapeClass</link>;
  23 #define             <link linkend="PANGO-ENGINE-TYPE-SHAPE--CAPS">PANGO_ENGINE_TYPE_SHAPE</link>
  24 #define             <link linkend="PANGO-ENGINE-SHAPE-DEFINE-TYPE--CAPS">PANGO_ENGINE_SHAPE_DEFINE_TYPE</link>      (name, prefix, class_init, instance_init)
  25 </synopsis>
  26 </refsynopsisdiv>
  27
  28 <refsect1 id="PangoEngineShape.object-hierarchy" role="object_hierarchy">
  29 <title role="object_hierarchy.title">Object Hierarchy</title>
  30 <synopsis>
  31   <link linkend="GObject">GObject</link>
  32    +----<link linkend="PangoEngine">PangoEngine</link>
  33          +----PangoEngineShape
  34 </synopsis>
  35 </refsect1>
  36
  37
  38
  39
  40
  41
  42
  43
  44 <refsect1 id="PangoEngineShape.description" role="desc">
  45 <title role="desc.title">Description</title>
  46 <para>
  47 The <firstterm>shape engines</firstterm> are rendering-system dependent
  48 engines that convert character strings into glyph strings.
  49 These engines are used in <link linkend="pango-shape"><function>pango_shape()</function></link>.
  50 </para>
  51 </refsect1>
  52
  53 <refsect1 id="PangoEngineShape.details" role="details">
  54 <title role="details.title">Details</title>
  55 <refsect2 id="PangoEngineShape-struct" role="struct">
  56 <title>PangoEngineShape</title>
  57 <indexterm zone="PangoEngineShape-struct"><primary sortas="PangoEngineShape">PangoEngineShape</primary></indexterm><programlisting>typedef struct _PangoEngineShape PangoEngineShape;</programlisting>
  58 <para>
  59 The <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> class is implemented by engines that
  60 customize the rendering-system dependent part of the
  61 Pango pipeline for a particular script or language.
  62 A <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> implementation is then specific to both
  63 a particular rendering system or group of rendering systems
  64 and to a particular script. For instance, there is one
  65 <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> implementation to handle shaping Arabic
  66 for Fontconfig-based backends.</para>
  67 <para>
  68 </para></refsect2>
  69 <refsect2 id="PangoEngineShapeClass" role="struct">
  70 <title>PangoEngineShapeClass</title>
  71 <indexterm zone="PangoEngineShapeClass"><primary sortas="PangoEngineShapeClass">PangoEngineShapeClass</primary></indexterm><programlisting>typedef struct {
  72   void (*script_shape) (PangoEngineShape *engine,
  73                         PangoFont        *font,
  74                         const char       *text,
  75                         int               length,
  76                         const PangoAnalysis *analysis,
  77                         PangoGlyphString *glyphs);
  78   PangoCoverageLevel (*covers)   (PangoEngineShape *engine,
  79                                   PangoFont        *font,
  80                                   PangoLanguage    *language,
  81                                   gunichar          wc);
  82 } PangoEngineShapeClass;
  83 </programlisting>
  84 <para>
  85 Class structure for <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link></para>
  86 <para>
  87 </para><variablelist role="struct">
  88 <varlistentry>
  89 <term><structfield>script_shape</structfield>&#160;()</term>
  90 <listitem><simpara> Given a font, a piece of text, and a <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link>
  91   structure, converts characters to glyphs and positions the
  92   resulting glyphs. The results are stored in the <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
  93   that is passed in. (The implementation should resize it
  94   appropriately using <link linkend="pango-glyph-string-set-size"><function>pango_glyph_string_set_size()</function></link>). All fields
  95   of the <parameter>log_clusters</parameter> and <parameter>glyphs</parameter> array must be filled in, with
  96   the exception that Pango will automatically generate
  97   <literal>glyphs->glyphs[i].attr.is_cluster_start</literal>
  98   using the <parameter>log_clusters</parameter> array. Each input character must occur in one
  99   of the output logical clusters;
 100   if no rendering is desired for a character, this may involve
 101   inserting glyphs with the <link linkend="PangoGlyph"><type>PangoGlyph</type></link> ID <link linkend="PANGO-GLYPH-EMPTY--CAPS"><type>PANGO_GLYPH_EMPTY</type></link>, which
 102   is guaranteed never to render. If the shaping fails for any reason,
 103   the shaper should return with an empty (zero-size) glyph string.
 104   If the shaper has not set the size on the glyph string yet, simply
 105   returning signals the failure too.
 106 </simpara></listitem>
 107 </varlistentry>
 108 <varlistentry>
 109 <term><structfield>covers</structfield>&#160;()</term>
 110 <listitem><simpara> Returns the characters that this engine can cover
 111   with a given font for a given language. If not overridden, the default
 112   implementation simply returns the coverage information for the
 113   font itself unmodified.
 114 </simpara></listitem>
 115 </varlistentry>
 116 </variablelist></refsect2>
 117 <refsect2 id="PANGO-ENGINE-TYPE-SHAPE--CAPS" role="macro">
 118 <title>PANGO_ENGINE_TYPE_SHAPE</title>
 119 <indexterm zone="PANGO-ENGINE-TYPE-SHAPE--CAPS"><primary sortas="PANGO_ENGINE_TYPE_SHAPE">PANGO_ENGINE_TYPE_SHAPE</primary></indexterm><programlisting>#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
 120 </programlisting>
 121 <para>
 122 A string constant defining the engine type
 123 for shaping engines.
 124 These engines derive from <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link>.
 125 </para></refsect2>
 126 <refsect2 id="PANGO-ENGINE-SHAPE-DEFINE-TYPE--CAPS" role="macro">
 127 <title>PANGO_ENGINE_SHAPE_DEFINE_TYPE()</title>
 128 <indexterm zone="PANGO-ENGINE-SHAPE-DEFINE-TYPE--CAPS"><primary sortas="PANGO_ENGINE_SHAPE_DEFINE_TYPE">PANGO_ENGINE_SHAPE_DEFINE_TYPE</primary></indexterm><programlisting>#define             PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init)</programlisting>
 129 <para>
 130 Outputs the necessary code for GObject type registration for a
 131 <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> class defined in a module. Two static symbols
 132 are defined.
 133 </para>
 134 <para>
 135 <programlisting>
 136  static GType <replaceable>prefix</replaceable>_type;
 137  static void <replaceable>prefix</replaceable>_register_type (GTypeModule module);
 138 </programlisting>
 139 </para>
 140 <para>
 141 The <function><replaceable>prefix</replaceable><link linkend="register-type"><function>_register_type()</function></link></function>
 142 function should be called in your <link linkend="script-engine-init"><function>script_engine_init()</function></link> function for
 143 each type that your module implements, and then your <link linkend="script-engine-create"><function>script_engine_create()</function></link>
 144 function can create instances of the object as follows:
 145 </para>
 146 <para>
 147 <informalexample><programlisting>
 148  PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL);
 149 </programlisting></informalexample></para>
 150 <para>
 151 </para><variablelist role="params">
 152 <varlistentry><term><parameter>name</parameter>&#160;:</term>
 153 <listitem><simpara> Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
 154 </simpara></listitem></varlistentry>
 155 <varlistentry><term><parameter>prefix</parameter>&#160;:</term>
 156 <listitem><simpara> Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
 157 </simpara></listitem></varlistentry>
 158 <varlistentry><term><parameter>class_init</parameter>&#160;:</term>
 159 <listitem><simpara> Class initialization function for the new type, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 160 </simpara></listitem></varlistentry>
 161 <varlistentry><term><parameter>instance_init</parameter>&#160;:</term>
 162 <listitem><simpara> Instance initialization function for the new type, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 163 </simpara></listitem></varlistentry>
 164 </variablelist></refsect2>
 165
 166 </refsect1>
 167
 168
 169
 170
 171 </refentry>