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

<refnamediv>
<refname>Coverage Maps</refname>
<refpurpose>Unicode character range coverage storage</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>



enum                <link linkend="PangoCoverageLevel">PangoCoverageLevel</link>;
#define             <link linkend="PANGO-TYPE-COVERAGE-LEVEL:CAPS">PANGO_TYPE_COVERAGE_LEVEL</link>
                    <link linkend="PangoCoverage">PangoCoverage</link>;

<link linkend="PangoCoverage">PangoCoverage</link>*      <link linkend="pango-coverage-new">pango_coverage_new</link>                  (void);
<link linkend="PangoCoverage">PangoCoverage</link>*      <link linkend="pango-coverage-ref">pango_coverage_ref</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);
<link linkend="void">void</link>                <link linkend="pango-coverage-unref">pango_coverage_unref</link>                (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);
<link linkend="PangoCoverage">PangoCoverage</link>*      <link linkend="pango-coverage-copy">pango_coverage_copy</link>                 (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);
<link linkend="PangoCoverageLevel">PangoCoverageLevel</link>  <link linkend="pango-coverage-get">pango_coverage_get</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="int">int</link> index_);
<link linkend="void">void</link>                <link linkend="pango-coverage-max">pango_coverage_max</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="PangoCoverage">PangoCoverage</link> *other);
<link linkend="void">void</link>                <link linkend="pango-coverage-set">pango_coverage_set</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="int">int</link> index_,
                                                         <link linkend="PangoCoverageLevel">PangoCoverageLevel</link> level);
<link linkend="void">void</link>                <link linkend="pango-coverage-to-bytes">pango_coverage_to_bytes</link>             (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="guchar">guchar</link> **bytes,
                                                         <link linkend="int">int</link> *n_bytes);
<link linkend="PangoCoverage">PangoCoverage</link>*      <link linkend="pango-coverage-from-bytes">pango_coverage_from_bytes</link>           (<link linkend="guchar">guchar</link> *bytes,
                                                         <link linkend="int">int</link> n_bytes);

</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
It is often necessary in Pango to determine if a particular font can
represent a particular character, and also how well it can represent
that character. The <link linkend="PangoCoverage"><type>PangoCoverage</type></link> is a data structure that is used
to represent that information.
</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="PangoCoverageLevel" role="enum"/>enum PangoCoverageLevel</title>
<indexterm><primary>PangoCoverageLevel</primary></indexterm><programlisting>typedef enum {
  PANGO_COVERAGE_NONE,
  PANGO_COVERAGE_FALLBACK,
  PANGO_COVERAGE_APPROXIMATE,
  PANGO_COVERAGE_EXACT
} PangoCoverageLevel;
</programlisting>
<para>
Used to indicate how well a font can represent a particular Unicode
character point for a particular script.
</para><variablelist role="enum">
<varlistentry>
<term><anchor id="PANGO-COVERAGE-NONE:CAPS" role="constant"/><literal>PANGO_COVERAGE_NONE</literal></term>
<listitem><simpara>The character is not representable with the font.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="PANGO-COVERAGE-FALLBACK:CAPS" role="constant"/><literal>PANGO_COVERAGE_FALLBACK</literal></term>
<listitem><simpara>The character is represented in a way that may be
                          comprehensible but is not the correct graphical form.
                          For instance, a Hangul character represented as a
                          a sequence of Jamos, or a Latin transliteration of
                          a Cyrillic word.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="PANGO-COVERAGE-APPROXIMATE:CAPS" role="constant"/><literal>PANGO_COVERAGE_APPROXIMATE</literal></term>
<listitem><simpara>The character is represented as basically the correct
                             graphical form, but with a stylistic variant inappropriate for
                             the current script.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><anchor id="PANGO-COVERAGE-EXACT:CAPS" role="constant"/><literal>PANGO_COVERAGE_EXACT</literal></term>
<listitem><simpara>The character is represented as the correct graphical form.

</simpara></listitem>
</varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="PANGO-TYPE-COVERAGE-LEVEL:CAPS" role="macro"/>PANGO_TYPE_COVERAGE_LEVEL</title>
<indexterm><primary>PANGO_TYPE_COVERAGE_LEVEL</primary></indexterm><programlisting>#define PANGO_TYPE_COVERAGE_LEVEL (pango_coverage_level_get_type())
</programlisting>
<para>
The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoCoverageLevel"><type>PangoCoverageLevel</type></link>.
</para></refsect2>
<refsect2>
<title><anchor id="PangoCoverage" role="struct"/>PangoCoverage</title>
<indexterm><primary>PangoCoverage</primary></indexterm><programlisting>typedef struct _PangoCoverage PangoCoverage;</programlisting>
<para>
The <link linkend="PangoCoverage"><type>PangoCoverage</type></link> structure represents a map from Unicode characters
to <link linkend="PangoCoverageLevel"><type>PangoCoverageLevel</type></link>. It is an opaque structure with no public fields.
</para></refsect2>
<refsect2>
<title><anchor id="pango-coverage-new" role="function"/>pango_coverage_new ()</title>
<indexterm><primary>pango_coverage_new</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link>*      pango_coverage_new                  (void);</programlisting>
<para>
Create a new <link linkend="PangoCoverage"><type>PangoCoverage</type></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the newly allocated <link linkend="PangoCoverage"><type>PangoCoverage</type></link>,
              initialized to <link linkend="PANGO-COVERAGE-NONE:CAPS"><literal>PANGO_COVERAGE_NONE</literal></link>
              with a reference count of one, which
              should be freed with <link linkend="pango-coverage-unref"><function>pango_coverage_unref()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-ref" role="function"/>pango_coverage_ref ()</title>
<indexterm><primary>pango_coverage_ref</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link>*      pango_coverage_ref                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);</programlisting>
<para>
Increase the reference count on the <link linkend="PangoCoverage"><type>PangoCoverage</type></link> by one</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <parameter>coverage</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-unref" role="function"/>pango_coverage_unref ()</title>
<indexterm><primary>pango_coverage_unref</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_unref                (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);</programlisting>
<para>
Increase the reference count on the <link linkend="PangoCoverage"><type>PangoCoverage</type></link> by one.
if the result is zero, free the coverage and all associated memory.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-copy" role="function"/>pango_coverage_copy ()</title>
<indexterm><primary>pango_coverage_copy</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link>*      pango_coverage_copy                 (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);</programlisting>
<para>
Copy an existing <link linkend="PangoCoverage"><type>PangoCoverage</type></link>. (This function may now be unnecessary
since we refcount the structure. File a bug if you use it.)</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the newly allocated <link linkend="PangoCoverage"><type>PangoCoverage</type></link>,
              with a reference count of one, which
              should be freed with <link linkend="pango-coverage-unref"><function>pango_coverage_unref()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-get" role="function"/>pango_coverage_get ()</title>
<indexterm><primary>pango_coverage_get</primary></indexterm><programlisting><link linkend="PangoCoverageLevel">PangoCoverageLevel</link>  pango_coverage_get                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="int">int</link> index_);</programlisting>
<para>
Determine whether a particular index is covered by <parameter>coverage</parameter></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
<listitem><simpara> the index to check
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the coverage level of <parameter>coverage</parameter> for character <parameter>index_</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-max" role="function"/>pango_coverage_max ()</title>
<indexterm><primary>pango_coverage_max</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_max                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="PangoCoverage">PangoCoverage</link> *other);</programlisting>
<para>
Set the coverage for each index in <parameter>coverage</parameter> to be the max (better)
value of the current coverage for the index and the coverage for
the corresponding index in <parameter>other</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>other</parameter>&nbsp;:</term>
<listitem><simpara> another <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-set" role="function"/>pango_coverage_set ()</title>
<indexterm><primary>pango_coverage_set</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_set                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="int">int</link> index_,
                                                         <link linkend="PangoCoverageLevel">PangoCoverageLevel</link> level);</programlisting>
<para>
Modify a particular index within <parameter>coverage</parameter></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>index_</parameter>&nbsp;:</term>
<listitem><simpara> the index to modify
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>level</parameter>&nbsp;:</term>
<listitem><simpara> the new level for <parameter>index_</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-to-bytes" role="function"/>pango_coverage_to_bytes ()</title>
<indexterm><primary>pango_coverage_to_bytes</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_to_bytes             (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
                                                         <link linkend="guchar">guchar</link> **bytes,
                                                         <link linkend="int">int</link> *n_bytes);</programlisting>
<para>
Convert a <link linkend="PangoCoverage"><type>PangoCoverage</type></link> structure into a flat binary format</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>coverage</parameter>&nbsp;:</term>
<listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> location to store result (must be freed with <link linkend="g-free"><function>g_free()</function></link>)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_bytes</parameter>&nbsp;:</term>
<listitem><simpara> location to store size of result
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-coverage-from-bytes" role="function"/>pango_coverage_from_bytes ()</title>
<indexterm><primary>pango_coverage_from_bytes</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link>*      pango_coverage_from_bytes           (<link linkend="guchar">guchar</link> *bytes,
                                                         <link linkend="int">int</link> n_bytes);</programlisting>
<para>
Convert data generated from <link linkend="pango-converage-to-bytes"><function>pango_converage_to_bytes()</function></link> back
to a <link linkend="PangoCoverage"><type>PangoCoverage</type></link></para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
<listitem><simpara> binary data representing a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_bytes</parameter>&nbsp;:</term>
<listitem><simpara> the size of <parameter>bytes</parameter> in bytes
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated <link linkend="PangoCoverage"><type>PangoCoverage</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
              the data was invalid.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
