docs/xml/coverage-maps.xml

   1 <refentry id="pango-Coverage-Maps">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="pango-Coverage-Maps.top_of_page">Coverage Maps</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Coverage Maps</refname>
  10 <refpurpose>Unicode character range coverage storage</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="pango-Coverage-Maps.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15
  16 <synopsis>
  17 enum                <link linkend="PangoCoverageLevel">PangoCoverageLevel</link>;
  18 #define             <link linkend="PANGO-TYPE-COVERAGE-LEVEL--CAPS">PANGO_TYPE_COVERAGE_LEVEL</link>
  19                     <link linkend="PangoCoverage">PangoCoverage</link>;
  20
  21 <link linkend="PangoCoverage">PangoCoverage</link> *     <link linkend="pango-coverage-new">pango_coverage_new</link>                  (void);
  22 <link linkend="PangoCoverage">PangoCoverage</link> *     <link linkend="pango-coverage-ref">pango_coverage_ref</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);
  23 <link linkend="void">void</link>                <link linkend="pango-coverage-unref">pango_coverage_unref</link>                (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);
  24 <link linkend="PangoCoverage">PangoCoverage</link> *     <link linkend="pango-coverage-copy">pango_coverage_copy</link>                 (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);
  25 <link linkend="PangoCoverageLevel">PangoCoverageLevel</link>  <link linkend="pango-coverage-get">pango_coverage_get</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
  26                                                          <link linkend="int">int</link> index_);
  27 <link linkend="void">void</link>                <link linkend="pango-coverage-max">pango_coverage_max</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
  28                                                          <link linkend="PangoCoverage">PangoCoverage</link> *other);
  29 <link linkend="void">void</link>                <link linkend="pango-coverage-set">pango_coverage_set</link>                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
  30                                                          <link linkend="int">int</link> index_,
  31                                                          <link linkend="PangoCoverageLevel">PangoCoverageLevel</link> level);
  32 <link linkend="void">void</link>                <link linkend="pango-coverage-to-bytes">pango_coverage_to_bytes</link>             (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
  33                                                          <link linkend="guchar">guchar</link> **bytes,
  34                                                          <link linkend="int">int</link> *n_bytes);
  35 <link linkend="PangoCoverage">PangoCoverage</link> *     <link linkend="pango-coverage-from-bytes">pango_coverage_from_bytes</link>           (<link linkend="guchar">guchar</link> *bytes,
  36                                                          <link linkend="int">int</link> n_bytes);
  37 </synopsis>
  38 </refsynopsisdiv>
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48 <refsect1 id="pango-Coverage-Maps.description" role="desc">
  49 <title role="desc.title">Description</title>
  50 <para>
  51 It is often necessary in Pango to determine if a particular font can
  52 represent a particular character, and also how well it can represent
  53 that character. The <link linkend="PangoCoverage"><type>PangoCoverage</type></link> is a data structure that is used
  54 to represent that information.
  55 </para>
  56 </refsect1>
  57
  58 <refsect1 id="pango-Coverage-Maps.details" role="details">
  59 <title role="details.title">Details</title>
  60 <refsect2 id="PangoCoverageLevel" role="enum">
  61 <title>enum PangoCoverageLevel</title>
  62 <indexterm zone="PangoCoverageLevel"><primary sortas="PangoCoverageLevel">PangoCoverageLevel</primary></indexterm><programlisting>typedef enum {
  63   PANGO_COVERAGE_NONE,
  64   PANGO_COVERAGE_FALLBACK,
  65   PANGO_COVERAGE_APPROXIMATE,
  66   PANGO_COVERAGE_EXACT
  67 } PangoCoverageLevel;
  68 </programlisting>
  69 <para>
  70 Used to indicate how well a font can represent a particular Unicode
  71 character point for a particular script.
  72 </para><variablelist role="enum">
  73 <varlistentry id="PANGO-COVERAGE-NONE--CAPS" role="constant">
  74 <term><literal>PANGO_COVERAGE_NONE</literal></term>
  75 <listitem><simpara>The character is not representable with the font.
  76 </simpara></listitem>
  77 </varlistentry>
  78 <varlistentry id="PANGO-COVERAGE-FALLBACK--CAPS" role="constant">
  79 <term><literal>PANGO_COVERAGE_FALLBACK</literal></term>
  80 <listitem><simpara>The character is represented in a way that may be
  81                           comprehensible but is not the correct graphical form.
  82                           For instance, a Hangul character represented as a
  83                           a sequence of Jamos, or a Latin transliteration of
  84                           a Cyrillic word.
  85 </simpara></listitem>
  86 </varlistentry>
  87 <varlistentry id="PANGO-COVERAGE-APPROXIMATE--CAPS" role="constant">
  88 <term><literal>PANGO_COVERAGE_APPROXIMATE</literal></term>
  89 <listitem><simpara>The character is represented as basically the correct
  90                              graphical form, but with a stylistic variant inappropriate for
  91                              the current script.
  92 </simpara></listitem>
  93 </varlistentry>
  94 <varlistentry id="PANGO-COVERAGE-EXACT--CAPS" role="constant">
  95 <term><literal>PANGO_COVERAGE_EXACT</literal></term>
  96 <listitem><simpara>The character is represented as the correct graphical form.
  97 </simpara></listitem>
  98 </varlistentry>
  99 </variablelist></refsect2>
 100 <refsect2 id="PANGO-TYPE-COVERAGE-LEVEL--CAPS" role="macro">
 101 <title>PANGO_TYPE_COVERAGE_LEVEL</title>
 102 <indexterm zone="PANGO-TYPE-COVERAGE-LEVEL--CAPS"><primary sortas="PANGO_TYPE_COVERAGE_LEVEL">PANGO_TYPE_COVERAGE_LEVEL</primary></indexterm><programlisting>#define PANGO_TYPE_COVERAGE_LEVEL (pango_coverage_level_get_type())
 103 </programlisting>
 104 <para>
 105 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoCoverageLevel"><type>PangoCoverageLevel</type></link>.
 106 </para></refsect2>
 107 <refsect2 id="PangoCoverage" role="struct">
 108 <title>PangoCoverage</title>
 109 <indexterm zone="PangoCoverage"><primary sortas="PangoCoverage">PangoCoverage</primary></indexterm><programlisting>typedef struct _PangoCoverage PangoCoverage;</programlisting>
 110 <para>
 111 The <link linkend="PangoCoverage"><type>PangoCoverage</type></link> structure represents a map from Unicode characters
 112 to <link linkend="PangoCoverageLevel"><type>PangoCoverageLevel</type></link>. It is an opaque structure with no public fields.
 113 </para></refsect2>
 114 <refsect2 id="pango-coverage-new" role="function">
 115 <title>pango_coverage_new ()</title>
 116 <indexterm zone="pango-coverage-new"><primary sortas="pango_coverage_new">pango_coverage_new</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link> *     pango_coverage_new                  (void);</programlisting>
 117 <para>
 118 Create a new <link linkend="PangoCoverage"><type>PangoCoverage</type></link></para>
 119 <para>
 120 </para><variablelist role="params">
 121 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoCoverage"><type>PangoCoverage</type></link>,
 122               initialized to <link linkend="PANGO-COVERAGE-NONE--CAPS"><literal>PANGO_COVERAGE_NONE</literal></link>
 123               with a reference count of one, which
 124               should be freed with <link linkend="pango-coverage-unref"><function>pango_coverage_unref()</function></link>.
 125 </simpara></listitem></varlistentry>
 126 </variablelist></refsect2>
 127 <refsect2 id="pango-coverage-ref" role="function">
 128 <title>pango_coverage_ref ()</title>
 129 <indexterm zone="pango-coverage-ref"><primary sortas="pango_coverage_ref">pango_coverage_ref</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link> *     pango_coverage_ref                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);</programlisting>
 130 <para>
 131 Increase the reference count on the <link linkend="PangoCoverage"><type>PangoCoverage</type></link> by one</para>
 132 <para>
 133 </para><variablelist role="params">
 134 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 135 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 136 </simpara></listitem></varlistentry>
 137 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <parameter>coverage</parameter>
 138 </simpara></listitem></varlistentry>
 139 </variablelist></refsect2>
 140 <refsect2 id="pango-coverage-unref" role="function">
 141 <title>pango_coverage_unref ()</title>
 142 <indexterm zone="pango-coverage-unref"><primary sortas="pango_coverage_unref">pango_coverage_unref</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_unref                (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);</programlisting>
 143 <para>
 144 Decrease the reference count on the <link linkend="PangoCoverage"><type>PangoCoverage</type></link> by one.
 145 If the result is zero, free the coverage and all associated memory.</para>
 146 <para>
 147 </para><variablelist role="params">
 148 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 149 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 150 </simpara></listitem></varlistentry>
 151 </variablelist></refsect2>
 152 <refsect2 id="pango-coverage-copy" role="function">
 153 <title>pango_coverage_copy ()</title>
 154 <indexterm zone="pango-coverage-copy"><primary sortas="pango_coverage_copy">pango_coverage_copy</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link> *     pango_coverage_copy                 (<link linkend="PangoCoverage">PangoCoverage</link> *coverage);</programlisting>
 155 <para>
 156 Copy an existing <link linkend="PangoCoverage"><type>PangoCoverage</type></link>. (This function may now be unnecessary
 157 since we refcount the structure. File a bug if you use it.)</para>
 158 <para>
 159 </para><variablelist role="params">
 160 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 161 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 162 </simpara></listitem></varlistentry>
 163 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoCoverage"><type>PangoCoverage</type></link>,
 164               with a reference count of one, which
 165               should be freed with <link linkend="pango-coverage-unref"><function>pango_coverage_unref()</function></link>.
 166 </simpara></listitem></varlistentry>
 167 </variablelist></refsect2>
 168 <refsect2 id="pango-coverage-get" role="function">
 169 <title>pango_coverage_get ()</title>
 170 <indexterm zone="pango-coverage-get"><primary sortas="pango_coverage_get">pango_coverage_get</primary></indexterm><programlisting><link linkend="PangoCoverageLevel">PangoCoverageLevel</link>  pango_coverage_get                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
 171                                                          <link linkend="int">int</link> index_);</programlisting>
 172 <para>
 173 Determine whether a particular index is covered by <parameter>coverage</parameter></para>
 174 <para>
 175 </para><variablelist role="params">
 176 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 177 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 178 </simpara></listitem></varlistentry>
 179 <varlistentry><term><parameter>index_</parameter>&#160;:</term>
 180 <listitem><simpara> the index to check
 181 </simpara></listitem></varlistentry>
 182 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the coverage level of <parameter>coverage</parameter> for character <parameter>index_</parameter>.
 183 </simpara></listitem></varlistentry>
 184 </variablelist></refsect2>
 185 <refsect2 id="pango-coverage-max" role="function">
 186 <title>pango_coverage_max ()</title>
 187 <indexterm zone="pango-coverage-max"><primary sortas="pango_coverage_max">pango_coverage_max</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_max                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
 188                                                          <link linkend="PangoCoverage">PangoCoverage</link> *other);</programlisting>
 189 <para>
 190 Set the coverage for each index in <parameter>coverage</parameter> to be the max (better)
 191 value of the current coverage for the index and the coverage for
 192 the corresponding index in <parameter>other</parameter>.</para>
 193 <para>
 194 </para><variablelist role="params">
 195 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 196 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 197 </simpara></listitem></varlistentry>
 198 <varlistentry><term><parameter>other</parameter>&#160;:</term>
 199 <listitem><simpara> another <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 200 </simpara></listitem></varlistentry>
 201 </variablelist></refsect2>
 202 <refsect2 id="pango-coverage-set" role="function">
 203 <title>pango_coverage_set ()</title>
 204 <indexterm zone="pango-coverage-set"><primary sortas="pango_coverage_set">pango_coverage_set</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_set                  (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
 205                                                          <link linkend="int">int</link> index_,
 206                                                          <link linkend="PangoCoverageLevel">PangoCoverageLevel</link> level);</programlisting>
 207 <para>
 208 Modify a particular index within <parameter>coverage</parameter></para>
 209 <para>
 210 </para><variablelist role="params">
 211 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 212 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 213 </simpara></listitem></varlistentry>
 214 <varlistentry><term><parameter>index_</parameter>&#160;:</term>
 215 <listitem><simpara> the index to modify
 216 </simpara></listitem></varlistentry>
 217 <varlistentry><term><parameter>level</parameter>&#160;:</term>
 218 <listitem><simpara> the new level for <parameter>index_</parameter>
 219 </simpara></listitem></varlistentry>
 220 </variablelist></refsect2>
 221 <refsect2 id="pango-coverage-to-bytes" role="function">
 222 <title>pango_coverage_to_bytes ()</title>
 223 <indexterm zone="pango-coverage-to-bytes"><primary sortas="pango_coverage_to_bytes">pango_coverage_to_bytes</primary></indexterm><programlisting><link linkend="void">void</link>                pango_coverage_to_bytes             (<link linkend="PangoCoverage">PangoCoverage</link> *coverage,
 224                                                          <link linkend="guchar">guchar</link> **bytes,
 225                                                          <link linkend="int">int</link> *n_bytes);</programlisting>
 226 <para>
 227 Convert a <link linkend="PangoCoverage"><type>PangoCoverage</type></link> structure into a flat binary format</para>
 228 <para>
 229 </para><variablelist role="params">
 230 <varlistentry><term><parameter>coverage</parameter>&#160;:</term>
 231 <listitem><simpara> a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 232 </simpara></listitem></varlistentry>
 233 <varlistentry><term><parameter>bytes</parameter>&#160;:</term>
 234 <listitem><simpara> location to store result (must be freed with <link linkend="g-free"><function>g_free()</function></link>)
 235 </simpara></listitem></varlistentry>
 236 <varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
 237 <listitem><simpara> location to store size of result
 238 </simpara></listitem></varlistentry>
 239 </variablelist></refsect2>
 240 <refsect2 id="pango-coverage-from-bytes" role="function">
 241 <title>pango_coverage_from_bytes ()</title>
 242 <indexterm zone="pango-coverage-from-bytes"><primary sortas="pango_coverage_from_bytes">pango_coverage_from_bytes</primary></indexterm><programlisting><link linkend="PangoCoverage">PangoCoverage</link> *     pango_coverage_from_bytes           (<link linkend="guchar">guchar</link> *bytes,
 243                                                          <link linkend="int">int</link> n_bytes);</programlisting>
 244 <para>
 245 Convert data generated from <link linkend="pango-converage-to-bytes"><function>pango_converage_to_bytes()</function></link> back
 246 to a <link linkend="PangoCoverage"><type>PangoCoverage</type></link></para>
 247 <para>
 248 </para><variablelist role="params">
 249 <varlistentry><term><parameter>bytes</parameter>&#160;:</term>
 250 <listitem><simpara> binary data representing a <link linkend="PangoCoverage"><type>PangoCoverage</type></link>
 251 </simpara></listitem></varlistentry>
 252 <varlistentry><term><parameter>n_bytes</parameter>&#160;:</term>
 253 <listitem><simpara> the size of <parameter>bytes</parameter> in bytes
 254 </simpara></listitem></varlistentry>
 255 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated <link linkend="PangoCoverage"><type>PangoCoverage</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
 256               the data was invalid.
 257 </simpara></listitem></varlistentry>
 258 </variablelist></refsect2>
 259
 260 </refsect1>
 261
 262
 263
 264
 265 </refentry>