<refentry id="pango-Engines"><refmeta><refentrytitle role="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><!--[<xref linkend="desc" endterm="desc.title"/>]--></refnamediv><refsynopsisdiv 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 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 role="desc"><title role="desc.title">Description</title><para>Pango utilizes a module architecture in which the language-specificand render-system-specific components are provided by loadablemodules. 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 bystrings.</para><para>Each dynamically-loaded module exports several functions which providethe 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 whencreating engines from the module at run time, while the firstfunction is used when building a catalog of all available modules.</para></refsect1><refsect1 role="details"><title role="details.title">Details</title><refsect2><title><anchor id="PangoEngineInfo" role="struct"/>PangoEngineInfo</title><indexterm><primary>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 particularengine. It contains the following fields:</para><variablelist role="struct"><varlistentry><term>const&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<structfield>id</structfield>;</term><listitem><simpara>a unique string ID for the engine.</simpara></listitem></varlistentry><varlistentry><term>const&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<structfield>engine_type</structfield>;</term><listitem><simpara>a string identifying the engine type.</simpara></listitem></varlistentry><varlistentry><term>const&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<structfield>render_type</structfield>;</term><listitem><simpara>a string identifying the render type.</simpara></listitem></varlistentry><varlistentry><term><link linkend="PangoEngineScriptInfo">PangoEngineScriptInfo</link>&nbsp;*<structfield>scripts</structfield>;</term><listitem><simpara>array of scripts this engine supports.</simpara></listitem></varlistentry><varlistentry><term><link linkend="gint">gint</link>&nbsp;<structfield>n_scripts</structfield>;</term><listitem><simpara>number of items in <parameter>scripts</parameter>.</simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="PangoEngineScriptInfo" role="struct"/>PangoEngineScriptInfo</title><indexterm><primary>PangoEngineScriptInfo</primary></indexterm><programlisting>typedef struct {  PangoScript script;  const gchar *langs;} PangoEngineScriptInfo;</programlisting><para>The <link linkend="PangoEngineScriptInfo"><type>PangoEngineScriptInfo</type></link> structure containsinformation about how the shaper covers a particularscript.</para><variablelist role="struct"><varlistentry><term><link linkend="PangoScript">PangoScript</link>&nbsp;<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&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<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><title><anchor id="PangoEngine-struct" role="struct"/>PangoEngine</title><indexterm><primary>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 andscript specific engines. It has no functionality by itself.</para><para></para></refsect2><refsect2><title><anchor id="PangoEngineClass" role="struct"/>PangoEngineClass</title><indexterm><primary>PangoEngineClass</primary></indexterm><programlisting>typedef struct {} PangoEngineClass;</programlisting><para>Class structure for <link linkend="PangoEngine"><type>PangoEngine</type></link></para><para></para></refsect2><refsect2><title><anchor id="PANGO-RENDER-TYPE-NONE:CAPS" role="macro"/>PANGO_RENDER_TYPE_NONE</title><indexterm><primary>PANGO_RENDER_TYPE_NONE</primary></indexterm><programlisting>#define PANGO_RENDER_TYPE_NONE "PangoRenderNone"</programlisting><para>A string constant defining the render typefor engines that are not rendering-system specific.</para></refsect2><refsect2><title><anchor id="script-engine-list" role="function"/>script_engine_list ()</title><indexterm><primary>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 themodule supplies. The function stores a pointer to an arrayof <link linkend="PangoEngineInfo"><type>PangoEngineInfo</type></link> structures and the length of that array inthe given location.</para><para>Note that <link linkend="script-engine-init"><function>script_engine_init()</function></link> will not be called before thisfunction.</para><para></para><variablelist role="params"><varlistentry><term><parameter>engines</parameter>&nbsp;:</term><listitem><simpara> location to store a pointer to an array of engines.</simpara></listitem></varlistentry><varlistentry><term><parameter>n_engines</parameter>&nbsp;:</term><listitem><simpara> location to store the number of elements in <parameter>engines</parameter>.</simpara></listitem></varlistentry></variablelist></refsect2><refsect2><title><anchor id="script-engine-init" role="function"/>script_engine_init ()</title><indexterm><primary>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 anyGObject types in the module.</para><para></para><variablelist role="params"><varlistentry><term><parameter>module</parameter>&nbsp;:</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><title><anchor id="script-engine-exit" role="function"/>script_engine_exit ()</title><indexterm><primary>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 calledwhen the module is unloading. Frequently does nothing.</para><para></para></refsect2><refsect2><title><anchor id="script-engine-create" role="function"/>script_engine_create ()</title><indexterm><primary>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 instanceof one of the engines implemented by the module.</para><para></para><variablelist role="params"><varlistentry><term><parameter>id</parameter>&nbsp;:</term><listitem><simpara> the ID of an engine as reported by script_engine_list.</simpara></listitem></varlistentry><varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</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>