update harfbuzz to 10.1.0

libs/harfbuzz/docs/usermanual-integration.xml

@@ -174,7 +174,9 @@
     <para>
       HarfBuzz provides integration points with FreeType at the
       face-object and font-object level and for the font-functions
-      virtual-method structure of a font object. To use the
+      virtual-method structure of a font object. These functions
+      make it easy for clients that use FreeType for rasterization
+      or font-loading, to use HarfBuzz for shaping. To use the
       FreeType-integration API, include the
       <filename>hb-ft.h</filename> header.
     </para>
@@ -245,7 +247,7 @@
     </para>
     <para>
       HarfBuzz also provides a utility function called
-      <function>hb_ft_font_has_changed()</function> that you should
+      <function>hb_ft_font_changed()</function> that you should
       call whenever you have altered the properties of your underlying
       <type>FT_Face</type>, as well as a
       <function>hb_ft_get_face()</function> that you can call on an
@@ -308,7 +310,49 @@
       it when it is unneeded.
     </para>
   </section>
-  
+
+  <section id="integration-cairo">
+    <title>Cairo integration</title>
+
+    <para>
+      Cairo is a 2D graphics library that is frequently used together
+      with GTK and Pango. Cairo supports rendering text using FreeType, or
+      by using callback-based 'user fonts'.
+    </para>
+    <para>
+      HarfBuzz provides integration points with cairo for fonts as well as
+      for buffers. To use the Cairo-integration API, link against libharfbuzz-cairo,
+      and include the <filename>hb-cairo.h</filename> header. For easy buildsystem
+      integration, HarfBuzz comes with a <filename>harfbuzz-cairo.pc</filename>
+      pkg-config file.
+    </para>
+    <para>
+      To create a <type>cairo_scaled_font_t</type> font from a HarfBuzz
+      <type>hb_font_t</type>, you can use <function>hb_cairo_font_face_create_for_font()</function>
+      or <function>hb_cairo_font_face_create_for_face()</function>. The former API
+      applies variations and synthetic slant from the <type>hb_font_t</type> when
+      rendering, the latter takes them from the <type>cairo_font_options_t</type>
+      that were passed when creating the <type>cairo_scaled_font_t</type>.
+    </para>
+    <para>
+      The Cairo fonts created in this way make use of Cairo's user-font facilities.
+      They can be used to render on any Cairo context, and provide full support for
+      font rendering features, including color. One current limitation of the
+      implementation is that it does not support hinting for glyph outlines.
+    </para>
+    <para>
+      When using color fonts with this API, the color palette index is taken from
+      the <type>cairo_font_options_t</type> (with new enough Cairo), and the foreground
+      color is extracted from the source of the Cairo context.
+    </para>
+    <para>
+      To render the results of shaping a piece of text, use
+      <function>hb_cairo_glyphs_from_buffer()</function> to obtain the glyphs in
+      a form that can be passed to <function>cairo_show_text_glyphs()</function> or
+      <function>cairo_show_glyphs()</function>.
+    </para>
+  </section>
+
   <section id="integration-uniscribe">
     <title>Uniscribe integration</title>
     <para>