<refentry id="pango-Engines">
<refmeta>
<refentrytitle role="top_of_page" id="pango-Engines.top_of_page">Engines</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>PANGO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Engines</refname>
<refpurpose>Language-specific and rendering-system-specific processing</refpurpose>
</refnamediv>

<refsynopsisdiv id="pango-Engines.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>
<anchor id="PangoEngine"/>
<synopsis>
                    <link linkend="PangoEngineInfo">PangoEngineInfo</link>;
                    <link linkend="PangoEngineScriptInfo">PangoEngineScriptInfo</link>;
                    <link linkend="PangoEngine-struct">PangoEngine</link>;
                    <link linkend="PangoEngineClass">PangoEngineClass</link>;
#define             <link linkend="PANGO-RENDER-TYPE-NONE--CAPS">PANGO_RENDER_TYPE_NONE</link>
<link linkend="void">void</link>                <link linkend="script-engine-list">script_engine_list</link>                  (<link linkend="PangoEngineInfo">PangoEngineInfo</link> **engines,
                                                         <link linkend="int">int</link> *n_engines);
<link linkend="void">void</link>                <link linkend="script-engine-init">script_engine_init</link>                  (<link linkend="GTypeModule">GTypeModule</link> *module);
<link linkend="void">void</link>                <link linkend="script-engine-exit">script_engine_exit</link>                  (void);
<link linkend="PangoEngine">PangoEngine</link> *       <link linkend="script-engine-create">script_engine_create</link>                (const <link linkend="char">char</link> *id);
</synopsis>
</refsynopsisdiv>

<refsect1 id="pango-Engines.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----PangoEngine
         +----<link linkend="PangoEngineLang">PangoEngineLang</link>
         +----<link linkend="PangoEngineShape">PangoEngineShape</link>
</synopsis>
</refsect1>








<refsect1 id="pango-Engines.description" role="desc">
<title role="desc.title">Description</title>
<para>
Pango utilizes a module architecture in which the language-specific
and render-system-specific components are provided by loadable
modules. Each loadable module supplies one or more
<firstterm>engines</firstterm>.  Each <firstterm>engine</firstterm>
has an associated <firstterm>engine type</firstterm> and
<firstterm>render type</firstterm>. These two types are represented by
strings.
</para>
<para>
Each dynamically-loaded module exports several functions which provide
the public API. These functions are <link linkend="script-engine-list"><function>script_engine_list()</function></link>,
<link linkend="script-engine-init"><function>script_engine_init()</function></link> and script_engine_exit, and
<link linkend="script-engine-create"><function>script_engine_create()</function></link>. The latter three functions are used when
creating engines from the module at run time, while the first
function is used when building a catalog of all available modules.
</para>
</refsect1>

<refsect1 id="pango-Engines.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="PangoEngineInfo" role="struct">
<title>PangoEngineInfo</title>
<indexterm zone="PangoEngineInfo"><primary sortas="PangoEngineInfo">PangoEngineInfo</primary></indexterm><programlisting>typedef struct {
  const gchar *id;
  const gchar *engine_type;
  const gchar *render_type;
  PangoEngineScriptInfo *scripts;
  gint n_scripts;
} PangoEngineInfo;
</programlisting>
<para>
The <link linkend="PangoEngineInfo"><type>PangoEngineInfo</type></link> structure contains information about a particular
engine. It contains the following fields:
</para><variablelist role="struct">
<varlistentry>
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>id</structfield>;</term>
<listitem><simpara>a unique string ID for the engine.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>engine_type</structfield>;</term>
<listitem><simpara>a string identifying the engine type.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>render_type</structfield>;</term>
<listitem><simpara>a string identifying the render type.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="PangoEngineScriptInfo">PangoEngineScriptInfo</link>&#160;*<structfield>scripts</structfield>;</term>
<listitem><simpara>array of scripts this engine supports.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><link linkend="gint">gint</link>&#160;<structfield>n_scripts</structfield>;</term>
<listitem><simpara>number of items in <parameter>scripts</parameter>.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="PangoEngineScriptInfo" role="struct">
<title>PangoEngineScriptInfo</title>
<indexterm zone="PangoEngineScriptInfo"><primary sortas="PangoEngineScriptInfo">PangoEngineScriptInfo</primary></indexterm><programlisting>typedef struct {
  PangoScript script;
  const gchar *langs;
} PangoEngineScriptInfo;
</programlisting>
<para>
The <link linkend="PangoEngineScriptInfo"><type>PangoEngineScriptInfo</type></link> structure contains
information about how the shaper covers a particular
script.
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="PangoScript">PangoScript</link>&#160;<structfield>script</structfield>;</term>
<listitem><simpara>a <link linkend="PangoScript"><type>PangoScript</type></link>. The value <link linkend="PANGO-SCRIPT-COMMON--CAPS"><literal>PANGO_SCRIPT_COMMON</literal></link> has
        the special meaning here of "all scripts"
</simpara></listitem>
</varlistentry>
<varlistentry>
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>langs</structfield>;</term>
<listitem><simpara>a semicolon separated list of languages that this
        engine handles for this script. This may be empty,
        in which case the engine is saying that it is a
        fallback choice for all languages for this range,
        but should not be used if another engine
        indicates that it is specific for the language for
        a given code point. An entry in this list of "*"
        indicates that this engine is specific to all
        languages for this range.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="PangoEngine-struct" role="struct">
<title>PangoEngine</title>
<indexterm zone="PangoEngine-struct"><primary sortas="PangoEngine">PangoEngine</primary></indexterm><programlisting>typedef struct _PangoEngine PangoEngine;</programlisting>
<para>
<link linkend="PangoEngine"><type>PangoEngine</type></link> is the base class for all types of language and
script specific engines. It has no functionality by itself.</para>
<para>
</para></refsect2>
<refsect2 id="PangoEngineClass" role="struct">
<title>PangoEngineClass</title>
<indexterm zone="PangoEngineClass"><primary sortas="PangoEngineClass">PangoEngineClass</primary></indexterm><programlisting>typedef struct {
} PangoEngineClass;
</programlisting>
<para>
Class structure for <link linkend="PangoEngine"><type>PangoEngine</type></link></para>
<para>
</para></refsect2>
<refsect2 id="PANGO-RENDER-TYPE-NONE--CAPS" role="macro">
<title>PANGO_RENDER_TYPE_NONE</title>
<indexterm zone="PANGO-RENDER-TYPE-NONE--CAPS"><primary sortas="PANGO_RENDER_TYPE_NONE">PANGO_RENDER_TYPE_NONE</primary></indexterm><programlisting>#define PANGO_RENDER_TYPE_NONE "PangoRenderNone"
</programlisting>
<para>
A string constant defining the render type
for engines that are not rendering-system
specific.
</para></refsect2>
<refsect2 id="script-engine-list" role="function">
<title>script_engine_list ()</title>
<indexterm zone="script-engine-list"><primary sortas="script_engine_list">script_engine_list</primary></indexterm><programlisting><link linkend="void">void</link>                script_engine_list                  (<link linkend="PangoEngineInfo">PangoEngineInfo</link> **engines,
                                                         <link linkend="int">int</link> *n_engines);</programlisting>
<para>
Function to be provided by a module to list the engines that the
module supplies. The function stores a pointer to an array
of <link linkend="PangoEngineInfo"><type>PangoEngineInfo</type></link> structures and the length of that array in
the given location.
</para>
<para>
Note that <link linkend="script-engine-init"><function>script_engine_init()</function></link> will not be called before this
function.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>engines</parameter>&#160;:</term>
<listitem><simpara> location to store a pointer to an array of engines.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_engines</parameter>&#160;:</term>
<listitem><simpara> location to store the number of elements in <parameter>engines</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="script-engine-init" role="function">
<title>script_engine_init ()</title>
<indexterm zone="script-engine-init"><primary sortas="script_engine_init">script_engine_init</primary></indexterm><programlisting><link linkend="void">void</link>                script_engine_init                  (<link linkend="GTypeModule">GTypeModule</link> *module);</programlisting>
<para>
Function to be provided by a module to register any
GObject types in the module.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>module</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTypeModule"><type>GTypeModule</type></link> structure used to associate any
 GObject types created in this module with the module.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="script-engine-exit" role="function">
<title>script_engine_exit ()</title>
<indexterm zone="script-engine-exit"><primary sortas="script_engine_exit">script_engine_exit</primary></indexterm><programlisting><link linkend="void">void</link>                script_engine_exit                  (void);</programlisting>
<para>
Function to be provided by the module that is called
when the module is unloading. Frequently does nothing.</para>
<para>
</para></refsect2>
<refsect2 id="script-engine-create" role="function">
<title>script_engine_create ()</title>
<indexterm zone="script-engine-create"><primary sortas="script_engine_create">script_engine_create</primary></indexterm><programlisting><link linkend="PangoEngine">PangoEngine</link> *       script_engine_create                (const <link linkend="char">char</link> *id);</programlisting>
<para>
Function to be provided by the module to create an instance
of one of the engines implemented by the module.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>id</parameter>&#160;:</term>
<listitem><simpara> the ID of an engine as reported by script_engine_list.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly created <link linkend="PangoEngine"><type>PangoEngine</type></link> of the specified
 type, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if an error occurred. (In normal operation,
 a module should not return <link linkend="NULL--CAPS"><literal>NULL</literal></link>. A <link linkend="NULL--CAPS"><literal>NULL</literal></link> return is only
 acceptable in the case where system misconfiguration or
 bugs in the driver routine are encountered.)
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
