pango-engine-shape.xml

Pango is a library for layout and rendering of text, with an emphasis on internationalization. Pang

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

<refnamediv>
<refname>PangoEngineShape</refname>
<refpurpose>Rendering-system dependent script engines</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>
<refsect1 id="PangoEngineShape.stability-level">
<title>Stability Level</title>
Unstable, unless otherwise indicated
</refsect1>

<refsynopsisdiv id="PangoEngineShape.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
                    <link linkend="PangoEngineShape-struct">PangoEngineShape</link>;
                    <link linkend="PangoEngineShapeClass">PangoEngineShapeClass</link>;
#define             <link linkend="PANGO-ENGINE-TYPE-SHAPE:CAPS">PANGO_ENGINE_TYPE_SHAPE</link>
#define             <link linkend="PANGO-ENGINE-SHAPE-DEFINE-TYPE:CAPS">PANGO_ENGINE_SHAPE_DEFINE_TYPE</link>      (name, prefix, class_init, instance_init)
</synopsis>
</refsynopsisdiv>

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

</refsect1>








<refsect1 id="PangoEngineShape.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <firstterm>shape engines</firstterm> are rendering-system dependent
engines that convert character strings into glyph strings.
These engines are used in <link linkend="pango-shape"><function>pango_shape()</function></link>.
</para>
</refsect1>

<refsect1 id="PangoEngineShape.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="PangoEngineShape-struct" role="struct">
<title>PangoEngineShape</title>
<indexterm zone="PangoEngineShape-struct"><primary>PangoEngineShape</primary></indexterm><programlisting>typedef struct _PangoEngineShape PangoEngineShape;</programlisting>
<para>
The <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> class is implemented by engines that
customize the rendering-system dependent part of the
Pango pipeline for a particular script or language.
A <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> implementation is then specific to both
a particular rendering system or group of rendering systems
and to a particular script. For instance, there is one
<link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> implementation to handle shaping Arabic
for Fontconfig-based backends.</para>
<para>
</para></refsect2>
<refsect2 id="PangoEngineShapeClass" role="struct">
<title>PangoEngineShapeClass</title>
<indexterm zone="PangoEngineShapeClass"><primary>PangoEngineShapeClass</primary></indexterm><programlisting>typedef struct {
  void (*script_shape) (PangoEngineShape *engine,
			PangoFont        *font,
			const char       *text,
			int               length,
			const PangoAnalysis *analysis,
			PangoGlyphString *glyphs);
  PangoCoverageLevel (*covers)   (PangoEngineShape *engine,
				  PangoFont        *font,
				  PangoLanguage    *language,
				  gunichar          wc);
} PangoEngineShapeClass;
</programlisting>
<para>
Class structure for <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link></para>
<para>

</para><variablelist role="struct">
<varlistentry>
<term><structfield>script_shape</structfield>&nbsp;()</term>
<listitem><simpara> Given a font, a piece of text, and a <link linkend="PangoAnalysis"><type>PangoAnalysis</type></link>
  structure, converts characters to glyphs and positions the
  resulting glyphs. The results are stored in the <link linkend="PangoGlyphString"><type>PangoGlyphString</type></link>
  that is passed in. (The implementation should resize it
  appropriately using <link linkend="pango-glyph-string-set-size"><function>pango_glyph_string_set_size()</function></link>). All fields
  of the <parameter>log_clusters</parameter> and <parameter>glyphs</parameter> array must be filled in, with
  the exception that Pango will automatically generate
  <literal>glyphs->glyphs[i].attr.is_cluster_start</literal>
  using the <parameter>log_clusters</parameter> array. Each input character must occur in one
  of the output logical clusters;
  if no rendering is desired for a character, this may involve
  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
  is guaranteed never to render. If the shaping fails for any reason,
  the shaper should return with an empty (zero-size) glyph string.
  If the shaper has not set the size on the glyph string yet, simply
  returning signals the failure too.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>covers</structfield>&nbsp;()</term>
<listitem><simpara> Returns the characters that this engine can cover
  with a given font for a given language. If not overridden, the default
  implementation simply returns the coverage information for the
  font itself unmodified.
</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2 id="PANGO-ENGINE-TYPE-SHAPE:CAPS" role="macro">
<title>PANGO_ENGINE_TYPE_SHAPE</title>
<indexterm zone="PANGO-ENGINE-TYPE-SHAPE:CAPS"><primary>PANGO_ENGINE_TYPE_SHAPE</primary></indexterm><programlisting>#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
</programlisting>
<para>
A string constant defining the engine type
for shaping engines.
These engines derive from <link linkend="PangoEngineShape"><type>PangoEngineShape</type></link>.
</para></refsect2>
<refsect2 id="PANGO-ENGINE-SHAPE-DEFINE-TYPE:CAPS" role="macro">
<title>PANGO_ENGINE_SHAPE_DEFINE_TYPE()</title>
<indexterm zone="PANGO-ENGINE-SHAPE-DEFINE-TYPE:CAPS"><primary>PANGO_ENGINE_SHAPE_DEFINE_TYPE</primary></indexterm><programlisting>#define             PANGO_ENGINE_SHAPE_DEFINE_TYPE(name, prefix, class_init, instance_init)</programlisting>
<para>
Outputs the necessary code for GObject type registration for a
<link linkend="PangoEngineShape"><type>PangoEngineShape</type></link> class defined in a module. Two static symbols
are defined.
</para>
<para>
<programlisting>
 static GType <replaceable>prefix</replaceable>_type;
 static void <replaceable>prefix</replaceable>_register_type (GTypeModule module);
</programlisting>
</para>
<para>
The <function><replaceable>prefix</replaceable><link linkend="register-type"><function>_register_type()</function></link></function>
function should be called in your <link linkend="script-engine-init"><function>script_engine_init()</function></link> function for
each type that your module implements, and then your <link linkend="script-engine-create"><function>script_engine_create()</function></link>
function can create instances of the object as follows:
</para>
<para>
<informalexample><programlisting>
 PangoEngine *engine = g_object_new (<replaceable>prefix</replaceable>_type, NULL);
</programlisting></informalexample></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
<listitem><simpara> Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prefix</parameter>&nbsp;:</term>
<listitem><simpara> Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>class_init</parameter>&nbsp;:</term>
<listitem><simpara> Class initialization function for the new type, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>instance_init</parameter>&nbsp;:</term>
<listitem><simpara> Instance initialization function for the new type, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>