docs/html/integration-uniscribe.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Uniscribe integration: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="integration.html" title="Platform Integration Guide">
   9 <link rel="prev" href="integration-freetype.html" title="FreeType integration">
  10 <link rel="next" href="integration-coretext.html" title="Core Text integration">
  11 <meta name="generator" content="GTK-Doc V1.32.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
  16 <td width="100%" align="left" class="shortcuts"></td>
  17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  18 <td><a accesskey="u" href="integration.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  19 <td><a accesskey="p" href="integration-freetype.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  20 <td><a accesskey="n" href="integration-coretext.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="section">
  23 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  24 <a name="integration-uniscribe"></a>Uniscribe integration</h2></div></div></div>
  25 <p>
  26       If your client program is running on Windows, HarfBuzz offers
  27       an additional API that can help integrate with Microsoft's
  28       Uniscribe engine and the Windows GDI.
  29     </p>
  30 <p>
  31       Overall, the Uniscribe API covers a broader set of typographic
  32       layout functions than HarfBuzz implements, but HarfBuzz's
  33       shaping API can serve as a drop-in replacement for Uniscribe's shaping
  34       functionality. In fact, one of HarfBuzz's design goals is to
  35       accurately reproduce the same output for shaping a given text
  36       segment that Uniscribe produces — even to the point of
  37       duplicating known shaping bugs or deviations from the
  38       specification — so you can be confident that your users'
  39       documents with their existing fonts will not be affected adversely by
  40       switching to HarfBuzz.
  41     </p>
  42 <p>
  43       At a basic level, HarfBuzz's <code class="function">hb_shape()</code>
  44       function replaces both the <a class="ulink" href="" target="_top"><code class="function">ScriptShape()</code></a>
  45       and <a class="ulink" href="https://docs.microsoft.com/en-us/windows/desktop/api/Usp10/nf-usp10-scriptplace" target="_top"><code class="function">ScriptPlace()</code></a>
  46       functions from Uniscribe.
  47     </p>
  48 <p>
  49       However, whereas <code class="function">ScriptShape()</code> returns the
  50       glyphs and clusters for a shaped sequence and
  51       <code class="function">ScriptPlace()</code> returns the advances and
  52       offsets for those glyphs, <code class="function">hb_shape()</code>
  53       handles both. After <code class="function">hb_shape()</code> shapes a
  54       buffer, the output glyph IDs and cluster IDs are returned as
  55       an array of <span class="structname">hb_glyph_info_t</span> structures, and the
  56       glyph advances and offsets are returned as an array of
  57       <span class="structname">hb_glyph_position_t</span> structures.
  58     </p>
  59 <p>
  60       Your client program only needs to ensure that it coverts
  61       correctly between HarfBuzz's low-level data types (such as
  62       <span class="type">hb_position_t</span>) and Windows's corresponding types
  63       (such as <span class="type">GOFFSET</span> and <span class="type">ABC</span>). Be sure you
  64       read the <a class="xref" href="buffers-language-script-and-direction.html" title="Buffers, language, script and direction"><i>Buffers, language, script and direction</i></a>
  65       chapter for a full explanation of how HarfBuzz input buffers are
  66       used, and see <a class="xref" href="shaping-and-shape-plans.html#shaping-buffer-output" title="Shaping and buffer output">the section called “Shaping and buffer output”</a> for the
  67       details of what <code class="function">hb_shape()</code> returns in the
  68       output buffer when shaping is complete.
  69     </p>
  70 <p>
  71       Although <code class="function">hb_shape()</code> itself is functionally
  72       equivalent to Uniscribe's shaping routines, there are two
  73       additional HarfBuzz functions you may want to use to integrate
  74       the libraries in your code. Both are used to link HarfBuzz font
  75       objects to the equivalent Windows structures.
  76     </p>
  77 <p>
  78       The <code class="function">hb_uniscribe_font_get_logfontw()</code>
  79       function takes a <span class="type">hb_font_t</span> font object and returns
  80       a pointer to the <a class="ulink" href="https://docs.microsoft.com/en-us/windows/desktop/api/wingdi/ns-wingdi-logfontw" target="_top"><span class="type">LOGFONTW</span></a>
  81       "logical font" that corresponds to it. A <span class="type">LOGFONTW</span>
  82       structure holds font-wide attributes, including metrics, size,
  83       and style information.
  84     </p>
  85 <p>
  86       The <code class="function">hb_uniscribe_font_get_hfont()</code> function
  87       also takes a <span class="type">hb_font_t</span> font object, but it returns
  88       an <span class="type">HFONT</span> — a handle to the underlying logical
  89       font — instead.
  90     </p>
  91 <p>
  92       <span class="type">LOGFONTW</span>s and <span class="type">HFONT</span>s are both needed
  93       by other Uniscribe functions.
  94     </p>
  95 <p>
  96       As a final note, you may notice a reference to an optional
  97       <code class="literal">uniscribe</code> shaper back-end in the <a class="xref" href="building.html#configuration" title="Configuration options">the section called “Configuration options”</a> section of the HarfBuzz manual. This
  98       option is not a Uniscribe-integration facility.
  99     </p>
 100 <p>
 101       Instead, it is a internal code path used in the
 102       <span class="command"><strong>hb-shape</strong></span> command-line utility, which hands
 103       shaping functionality over to Uniscribe entirely, when run on a
 104       Windows system. That allows testing HarfBuzz's native output
 105       against the Uniscribe engine, for tracking compatibility and
 106       debugging.
 107     </p>
 108 <p>
 109       Because this back-end is only used when testing HarfBuzz
 110       functionality, it is disabled by default when building the
 111       HarfBuzz binaries.
 112     </p>
 113 </div>
 114 <div class="footer">
 115 <hr>Generated by GTK-Doc V1.32.1</div>
 116 </body>
 117 </html>