## Engines

Engines — Language-specific and rendering-system-specific processing

## Synopsis

    struct      PangoEngineInfo;
    struct      PangoEngineRange;
    struct      PangoEngine;
    struct      PangoEngineLang;
    struct      PangoEngineShape;
    #define     PANGO_ENGINE_TYPE_LANG
    #define     PANGO_ENGINE_TYPE_SHAPE
    #define     PANGO_RENDER_TYPE_NONE
    void        script_engine_list              (PangoEngineInfo **engines,
                                                 int *n_engines);
    PangoEngine* script_engine_load             (const char *id);
    void        script_engine_unload            (PangoEngine *engine);

## Description

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 engines. Each engine has an associated engine type and render type. These two types are represented by strings.

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.

## Details

### struct PangoEngineInfo

    struct PangoEngineInfo {

      gchar *id;
      gchar *engine_type;
      gchar *render_type;
      PangoEngineRange *ranges;
      gint n_ranges;
    };

The PangoEngineInfo structure contains information about a particular engine. It contains the following fields:

gchar *`id` | a unique string ID for the engine.
gchar *`engine_type` | a string identifying the engine type.
gchar *`render_type` | a string identifying the render type.
PangoEngineRange *`ranges` | a pointer to an array of PangoEngineRange structures. Each structure contains information about a range of Unicode code points that this engine handles.
gint `n_ranges` | the number of elements in `ranges`.

### struct PangoEngineRange

    struct PangoEngineRange {

      guint32 start;
      guint32 end;
      gchar *langs;
    };

The PangoEngineRange structure contains information about a range of Unicode code points. It contains the following fields:

guint32 `start` | the first code point in the range.
guint32 `end` | the last code point for the range.
gchar *`langs` | 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.

### struct PangoEngine

    struct PangoEngine {

      gchar *id;
      gchar *type;
      gint length;
    };

The PangoEngine structure contains basic information common to all script engines. It contains the following fields:

gchar *`id` | a unique string ID for this language engine.
gchar *`type` | the "type" of the engine. (Is this engine type or render type??).
gint `length` | 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.

### struct PangoEngineLang

    struct PangoEngineLang {

      PangoEngine engine;
      void (*script_break) (const char    *text,
    			int            len,
    			PangoAnalysis *analysis,
    			PangoLogAttr  *attrs,
                            int            attrs_len);
    };

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:

PangoEngine `engine` | a nested structure containing basic engine data.
void (*`script_break`) (const char *text, int len, PangoAnalysis *analysis, PangoLogAttr *attrs, int attrs_len) | a function that provides an implementation for `pango_break()`.

### struct PangoEngineShape

    struct PangoEngineShape {

      PangoEngine engine;
      void (*script_shape) (PangoFont        *font,
    			const char       *text,
    			int               length,
    			PangoAnalysis    *analysis,
    			PangoGlyphString *glyphs);
      PangoCoverage *(*get_coverage) (PangoFont        *font,
    				  PangoLanguage    *language);
    };

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:

PangoEngine `engine` | a nested structure containing basic engine data.
void (*`script_shape`) (PangoFont *font, const char *text, int length, PangoAnalysis *analysis, PangoGlyphString *glyphs) | a function that provides an implementation for pango_shape.
PangoCoverage* (*`get_coverage`) (PangoFont *font, PangoLanguage *language) |

### PANGO_ENGINE_TYPE_LANG

    #define PANGO_ENGINE_TYPE_LANG "PangoEngineLang"

A string constant defining the engine type for language engines. These engines have a engine structure of type PangoEngineLang.

### PANGO_ENGINE_TYPE_SHAPE

    #define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"

A string constant defining the engine type for shaping engines. These engines have a engine structure of type PangoEngineShape.

### PANGO_RENDER_TYPE_NONE

    #define PANGO_RENDER_TYPE_NONE "PangoRenderNone"

A string constant defining the render type for engines that are not rendering-system specific.

### script_engine_list ()

    void        script_engine_list              (PangoEngineInfo **engines,
                                                 int *n_engines);

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.

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

### script_engine_load ()

    PangoEngine* script_engine_load             (const char *id);

Function to be provided by a module to load a particular engine.

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

### script_engine_unload ()

    void        script_engine_unload            (PangoEngine *engine);

Function to be provided by a module to unload an engine loaded with `script_engine_load()`.

`engine` : | the engine to unload.