path: root/docs/tmpl/engines.sgml

<!-- ##### SECTION Title ##### -->
Engines

<!-- ##### SECTION Short_Description ##### -->
Language-specific and rendering-system-specific processing

<!-- ##### SECTION Long_Description ##### -->
<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 script_engine_list(),
script_engine_load() and script_engine_unload().  The latter two
functions are used for loading and unloading modules, while the first
function is used when building a catalog of all available modules.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT PangoEngineInfo ##### -->
<para>
The #PangoEngineInfo structure contains information about a particular
engine. It contains the following fields:

<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>

<row>
<entry>gchar *id;</entry>
<entry>a unique string ID for the engine.</entry>
</row>
<row>
<entry>gchar *engine_type;</entry>
<entry>a string identifying the engine type.</entry>
</row>

<row>
<entry>gchar *render type;</entry>
<entry>a string identifying the render type.</entry>
</row>

<row>
<entry>#PangoEngineRange *ranges;</entry>
<entry>a pointer to an array of #PangoEngineRange
       structures. Each structure contains information
       about a range of Unicode code points that
       this engine handles.</entry>
</row>

<row>
<entry>gint n_ranges;</entry>
<entry>the number of elements in <structfield>ranges</structfield>.</entry>
</row>

</tbody></tgroup></informaltable>
</para>

@id: 
@engine_type: 
@render_type: 
@ranges: 
@n_ranges: 

<!-- ##### STRUCT PangoEngineRange ##### -->
<para>
The PangoEngineRange structure contains
information about a range of Unicode code
points. It contains the following fields:

<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>

<row>
<entry>guint32 start;</entry>
<entry>the first code point in the range.</entry>
</row>

<row>
<entry>guint32 end;</entry>
<entry>the last code point for the range.</entry>
</row>

<row>
<entry>gchar *langs;</entry>
<entry>A semicolon separated list of languages that this
       engine handles for this range. 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.</entry>
</row>

</tbody></tgroup></informaltable>
</para>

@start: 
@end: 
@langs: 

<!-- ##### STRUCT PangoEngine ##### -->
<para>
The #PangoEngine structure contains basic
information common to all script engines. It
contains the following fields:

<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>

<row>
<entry>gchar *id;</entry>
<entry>a unique string ID for this language engine.</entry>
</row>

<row>
<entry>gchar *type;</entry>
<entry>The "type" of the engine. (Is this engine type or render type??).</entry>
</row>

<row>
<entry>gint length;</entry>
<entry>the length of the entire structure in bytes. This is 
       provided so that new functions can be added at the
       end of subtypes of #PangoEngine without breaking
       older modules.</entry>
</row>

</tbody></tgroup></informaltable>
</para>

@id: 
@type: 
@length: 

<!-- ##### STRUCT PangoEngineLang ##### -->
<para>
The #PangoEngineLang structure extends the
basic #PangoEngine structure to engines that
deal with the rendering-system independent part
of of the rendering pipeline. It contains the following fields:

<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>

<row>
<entry>#PangoEngine engine;</entry>
<entry>A nested structure containing basic engine data.</entry>
</row>

<row>
<entry>void (*script_break) (...);</entry>
<entry>A function that provides an implementation
       for pango_break().</entry>
</row>

</tbody></tgroup></informaltable>
</para>

@engine: 
@script_break: 

<!-- ##### STRUCT PangoEngineShape ##### -->
<para>
The #PangoEngineShape structure extends the
basic #PangoEngine structure to engines that
deal with the rendering-system dependent part
of of the rendering pipeline. It contains the following fields:

<informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
<tbody>

<row>
<entry>#PangoEngine engine;</entry>
<entry>A nested structure containing basic engine data.</entry>
</row>

<row>
<entry> void (*script_shape) (...);</entry>
<entry>A function that provides an implementation
       for pango_shape.</entry>
</row>

</tbody></tgroup></informaltable>
</para>

@engine: 
@script_shape: 
@get_coverage: 

<!-- ##### MACRO PANGO_ENGINE_TYPE_LANG ##### -->
<para>
A string constant defining the engine type
for <firstterm>language engines</firstterm>.
These engines have a engine structure of 
type #PangoEngineLang.
</para>



<!-- ##### MACRO PANGO_ENGINE_TYPE_SHAPE ##### -->
<para>
A string constant defining the engine type
for <firstterm>shaping engines</firstterm>.
These engines have a engine structure of 
type #PangoEngineShape.
</para>



<!-- ##### MACRO PANGO_RENDER_TYPE_NONE ##### -->
<para>
A string constant defining the render type
for engines that are not rendering-system 
specific.
</para>



<!-- ##### FUNCTION script_engine_list ##### -->
<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 #PangoEngineInfo structures and the length of that array in
the given location.
</para>

@engines: location to store a pointer to an array of engines.
@n_engines: location to store the number of elements in @engines.


<!-- ##### FUNCTION script_engine_load ##### -->
<para>
Function to be provided by a module to load a particular engine.
</para>

@id: the ID from the #PangoEngineInfo structure of the
     module to load.
@Returns: the newly created script engine.


<!-- ##### FUNCTION script_engine_unload ##### -->
<para>
Function to be provided by a module to unload an engine loaded
with script_engine_load().
</para>

@engine: the engine to unload.


<!-- Local Variables: -->
<!-- sgml-parent-document: ("../pango-docs.sgml" "book" "refsect2") -->
<!-- End: -->