docs/html/harfbuzz-hb-ot-name.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>hb-ot-name: HarfBuzz Manual</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="index.html" title="HarfBuzz Manual">
   8 <link rel="up" href="opentype-api.html" title="OpenType API">
   9 <link rel="prev" href="harfbuzz-hb-ot-metrics.html" title="hb-ot-metrics">
  10 <link rel="next" href="harfbuzz-hb-ot-shape.html" title="hb-ot-shape">
  11 <meta name="generator" content="GTK-Doc V1.32 (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">
  17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span>
  18                   <a href="#harfbuzz-hb-ot-name.description" class="shortcut">Description</a></span>
  19 </td>
  20 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
  21 <td><a accesskey="u" href="opentype-api.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
  22 <td><a accesskey="p" href="harfbuzz-hb-ot-metrics.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
  23 <td><a accesskey="n" href="harfbuzz-hb-ot-shape.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
  24 </tr></table>
  25 <div class="refentry">
  26 <a name="harfbuzz-hb-ot-name"></a><div class="titlepage"></div>
  27 <div class="refnamediv"><table width="100%"><tr>
  28 <td valign="top">
  29 <h2><span class="refentrytitle"><a name="harfbuzz-hb-ot-name.top_of_page"></a>hb-ot-name</span></h2>
  30 <p>hb-ot-name — OpenType font name information</p>
  31 </td>
  32 <td class="gallery_image" valign="top" align="right"></td>
  33 </tr></table></div>
  34 <div class="refsect1">
  35 <a name="harfbuzz-hb-ot-name.functions"></a><h2>Functions</h2>
  36 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  37 <colgroup>
  38 <col width="150px" class="functions_proto_type">
  39 <col class="functions_proto_name">
  40 </colgroup>
  41 <tbody>
  42 <tr>
  43 <td class="function_type">const <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-entry-t" title="hb_ot_name_entry_t"><span class="returnvalue">hb_ot_name_entry_t</span></a> *
  44 </td>
  45 <td class="function_name">
  46 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-list-names" title="hb_ot_name_list_names ()">hb_ot_name_list_names</a> <span class="c_punctuation">()</span>
  47 </td>
  48 </tr>
  49 <tr>
  50 <td class="function_type">unsigned <span class="returnvalue">int</span>
  51 </td>
  52 <td class="function_name">
  53 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-get-utf16" title="hb_ot_name_get_utf16 ()">hb_ot_name_get_utf16</a> <span class="c_punctuation">()</span>
  54 </td>
  55 </tr>
  56 <tr>
  57 <td class="function_type">unsigned <span class="returnvalue">int</span>
  58 </td>
  59 <td class="function_name">
  60 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-get-utf32" title="hb_ot_name_get_utf32 ()">hb_ot_name_get_utf32</a> <span class="c_punctuation">()</span>
  61 </td>
  62 </tr>
  63 <tr>
  64 <td class="function_type">unsigned <span class="returnvalue">int</span>
  65 </td>
  66 <td class="function_name">
  67 <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-get-utf8" title="hb_ot_name_get_utf8 ()">hb_ot_name_get_utf8</a> <span class="c_punctuation">()</span>
  68 </td>
  69 </tr>
  70 </tbody>
  71 </table></div>
  72 </div>
  73 <div class="refsect1">
  74 <a name="harfbuzz-hb-ot-name.other"></a><h2>Types and Values</h2>
  75 <div class="informaltable"><table class="informaltable" width="100%" border="0">
  76 <colgroup>
  77 <col width="150px" class="other_proto_type">
  78 <col class="other_proto_name">
  79 </colgroup>
  80 <tbody>
  81 <tr>
  82 <td class="typedef_keyword">typedef</td>
  83 <td class="function_name"><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t">hb_ot_name_id_t</a></td>
  84 </tr>
  85 <tr>
  86 <td class="datatype_keyword"> </td>
  87 <td class="function_name"><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-entry-t" title="hb_ot_name_entry_t">hb_ot_name_entry_t</a></td>
  88 </tr>
  89 </tbody>
  90 </table></div>
  91 </div>
  92 <div class="refsect1">
  93 <a name="harfbuzz-hb-ot-name.includes"></a><h2>Includes</h2>
  94 <pre class="synopsis">#include &lt;hb-ot.h&gt;
  95 </pre>
  96 </div>
  97 <div class="refsect1">
  98 <a name="harfbuzz-hb-ot-name.description"></a><h2>Description</h2>
  99 <p>Functions for fetching name strings from OpenType fonts.</p>
 100 </div>
 101 <div class="refsect1">
 102 <a name="harfbuzz-hb-ot-name.functions_details"></a><h2>Functions</h2>
 103 <div class="refsect2">
 104 <a name="hb-ot-name-list-names"></a><h3>hb_ot_name_list_names ()</h3>
 105 <pre class="programlisting">const <a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-entry-t" title="hb_ot_name_entry_t"><span class="returnvalue">hb_ot_name_entry_t</span></a> *
 106 hb_ot_name_list_names (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 107                        <em class="parameter"><code>unsigned <span class="type">int</span> *num_entries</code></em>);</pre>
 108 <p>Enumerates all available name IDs and language combinations. Returned
 109 array is owned by the <em class="parameter"><code>face</code></em>
 110  and should not be modified.  It can be
 111 used as long as <em class="parameter"><code>face</code></em>
 112  is alive.</p>
 113 <div class="refsect3">
 114 <a name="hb-ot-name-list-names.parameters"></a><h4>Parameters</h4>
 115 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 116 <colgroup>
 117 <col width="150px" class="parameters_name">
 118 <col class="parameters_description">
 119 <col width="200px" class="parameters_annotations">
 120 </colgroup>
 121 <tbody>
 122 <tr>
 123 <td class="parameter_name"><p>face</p></td>
 124 <td class="parameter_description"><p>font face.</p></td>
 125 <td class="parameter_annotations"> </td>
 126 </tr>
 127 <tr>
 128 <td class="parameter_name"><p>num_entries</p></td>
 129 <td class="parameter_description"><p>number of returned entries. </p></td>
 130 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>][<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>]</span></td>
 131 </tr>
 132 </tbody>
 133 </table></div>
 134 </div>
 135 <div class="refsect3">
 136 <a name="hb-ot-name-list-names.returns"></a><h4>Returns</h4>
 137 <p>Array of available name entries. </p>
 138 <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=num_entries]</span></p>
 139 </div>
 140 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 141 </div>
 142 <hr>
 143 <div class="refsect2">
 144 <a name="hb-ot-name-get-utf16"></a><h3>hb_ot_name_get_utf16 ()</h3>
 145 <pre class="programlisting">unsigned <span class="returnvalue">int</span>
 146 hb_ot_name_get_utf16 (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 147                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> name_id</code></em>,
 148                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> language</code></em>,
 149                       <em class="parameter"><code>unsigned <span class="type">int</span> *text_size</code></em>,
 150                       <em class="parameter"><code><span class="type">uint16_t</span> *text</code></em>);</pre>
 151 <p>Fetches a font name from the OpenType 'name' table.
 152 If <em class="parameter"><code>language</code></em>
 153  is <a class="link" href="harfbuzz-hb-common.html#HB-LANGUAGE-INVALID:CAPS" title="HB_LANGUAGE_INVALID"><span class="type">HB_LANGUAGE_INVALID</span></a>, English ("en") is assumed.
 154 Returns string in UTF-16 encoding. A NUL terminator is always written
 155 for convenience, and isn't included in the output <em class="parameter"><code>text_size</code></em>
 156 .</p>
 157 <div class="refsect3">
 158 <a name="hb-ot-name-get-utf16.parameters"></a><h4>Parameters</h4>
 159 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 160 <colgroup>
 161 <col width="150px" class="parameters_name">
 162 <col class="parameters_description">
 163 <col width="200px" class="parameters_annotations">
 164 </colgroup>
 165 <tbody>
 166 <tr>
 167 <td class="parameter_name"><p>face</p></td>
 168 <td class="parameter_description"><p>font face.</p></td>
 169 <td class="parameter_annotations"> </td>
 170 </tr>
 171 <tr>
 172 <td class="parameter_name"><p>name_id</p></td>
 173 <td class="parameter_description"><p>OpenType name identifier to fetch.</p></td>
 174 <td class="parameter_annotations"> </td>
 175 </tr>
 176 <tr>
 177 <td class="parameter_name"><p>language</p></td>
 178 <td class="parameter_description"><p>language to fetch the name for.</p></td>
 179 <td class="parameter_annotations"> </td>
 180 </tr>
 181 <tr>
 182 <td class="parameter_name"><p>text_size</p></td>
 183 <td class="parameter_description"><p>input size of <em class="parameter"><code>text</code></em>
 184 buffer, and output size of
 185 text written to buffer. </p></td>
 186 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>]</span></td>
 187 </tr>
 188 <tr>
 189 <td class="parameter_name"><p>text</p></td>
 190 <td class="parameter_description"><p>buffer to write fetched name into. </p></td>
 191 <td class="parameter_annotations"><span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=text_size]</span></td>
 192 </tr>
 193 </tbody>
 194 </table></div>
 195 </div>
 196 <div class="refsect3">
 197 <a name="hb-ot-name-get-utf16.returns"></a><h4>Returns</h4>
 198 <p> full length of the requested string, or 0 if not found.</p>
 199 </div>
 200 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 201 </div>
 202 <hr>
 203 <div class="refsect2">
 204 <a name="hb-ot-name-get-utf32"></a><h3>hb_ot_name_get_utf32 ()</h3>
 205 <pre class="programlisting">unsigned <span class="returnvalue">int</span>
 206 hb_ot_name_get_utf32 (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 207                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> name_id</code></em>,
 208                       <em class="parameter"><code><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> language</code></em>,
 209                       <em class="parameter"><code>unsigned <span class="type">int</span> *text_size</code></em>,
 210                       <em class="parameter"><code><span class="type">uint32_t</span> *text</code></em>);</pre>
 211 <p>Fetches a font name from the OpenType 'name' table.
 212 If <em class="parameter"><code>language</code></em>
 213  is <a class="link" href="harfbuzz-hb-common.html#HB-LANGUAGE-INVALID:CAPS" title="HB_LANGUAGE_INVALID"><span class="type">HB_LANGUAGE_INVALID</span></a>, English ("en") is assumed.
 214 Returns string in UTF-32 encoding. A NUL terminator is always written
 215 for convenience, and isn't included in the output <em class="parameter"><code>text_size</code></em>
 216 .</p>
 217 <div class="refsect3">
 218 <a name="hb-ot-name-get-utf32.parameters"></a><h4>Parameters</h4>
 219 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 220 <colgroup>
 221 <col width="150px" class="parameters_name">
 222 <col class="parameters_description">
 223 <col width="200px" class="parameters_annotations">
 224 </colgroup>
 225 <tbody>
 226 <tr>
 227 <td class="parameter_name"><p>face</p></td>
 228 <td class="parameter_description"><p>font face.</p></td>
 229 <td class="parameter_annotations"> </td>
 230 </tr>
 231 <tr>
 232 <td class="parameter_name"><p>name_id</p></td>
 233 <td class="parameter_description"><p>OpenType name identifier to fetch.</p></td>
 234 <td class="parameter_annotations"> </td>
 235 </tr>
 236 <tr>
 237 <td class="parameter_name"><p>language</p></td>
 238 <td class="parameter_description"><p>language to fetch the name for.</p></td>
 239 <td class="parameter_annotations"> </td>
 240 </tr>
 241 <tr>
 242 <td class="parameter_name"><p>text_size</p></td>
 243 <td class="parameter_description"><p>input size of <em class="parameter"><code>text</code></em>
 244 buffer, and output size of
 245 text written to buffer. </p></td>
 246 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>]</span></td>
 247 </tr>
 248 <tr>
 249 <td class="parameter_name"><p>text</p></td>
 250 <td class="parameter_description"><p>buffer to write fetched name into. </p></td>
 251 <td class="parameter_annotations"><span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=text_size]</span></td>
 252 </tr>
 253 </tbody>
 254 </table></div>
 255 </div>
 256 <div class="refsect3">
 257 <a name="hb-ot-name-get-utf32.returns"></a><h4>Returns</h4>
 258 <p> full length of the requested string, or 0 if not found.</p>
 259 </div>
 260 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 261 </div>
 262 <hr>
 263 <div class="refsect2">
 264 <a name="hb-ot-name-get-utf8"></a><h3>hb_ot_name_get_utf8 ()</h3>
 265 <pre class="programlisting">unsigned <span class="returnvalue">int</span>
 266 hb_ot_name_get_utf8 (<em class="parameter"><code><a class="link" href="harfbuzz-hb-face.html#hb-face-t" title="hb_face_t"><span class="type">hb_face_t</span></a> *face</code></em>,
 267                      <em class="parameter"><code><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> name_id</code></em>,
 268                      <em class="parameter"><code><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> language</code></em>,
 269                      <em class="parameter"><code>unsigned <span class="type">int</span> *text_size</code></em>,
 270                      <em class="parameter"><code><span class="type">char</span> *text</code></em>);</pre>
 271 <p>Fetches a font name from the OpenType 'name' table.
 272 If <em class="parameter"><code>language</code></em>
 273  is <a class="link" href="harfbuzz-hb-common.html#HB-LANGUAGE-INVALID:CAPS" title="HB_LANGUAGE_INVALID"><span class="type">HB_LANGUAGE_INVALID</span></a>, English ("en") is assumed.
 274 Returns string in UTF-8 encoding. A NUL terminator is always written
 275 for convenience, and isn't included in the output <em class="parameter"><code>text_size</code></em>
 276 .</p>
 277 <div class="refsect3">
 278 <a name="hb-ot-name-get-utf8.parameters"></a><h4>Parameters</h4>
 279 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 280 <colgroup>
 281 <col width="150px" class="parameters_name">
 282 <col class="parameters_description">
 283 <col width="200px" class="parameters_annotations">
 284 </colgroup>
 285 <tbody>
 286 <tr>
 287 <td class="parameter_name"><p>face</p></td>
 288 <td class="parameter_description"><p>font face.</p></td>
 289 <td class="parameter_annotations"> </td>
 290 </tr>
 291 <tr>
 292 <td class="parameter_name"><p>name_id</p></td>
 293 <td class="parameter_description"><p>OpenType name identifier to fetch.</p></td>
 294 <td class="parameter_annotations"> </td>
 295 </tr>
 296 <tr>
 297 <td class="parameter_name"><p>language</p></td>
 298 <td class="parameter_description"><p>language to fetch the name for.</p></td>
 299 <td class="parameter_annotations"> </td>
 300 </tr>
 301 <tr>
 302 <td class="parameter_name"><p>text_size</p></td>
 303 <td class="parameter_description"><p>input size of <em class="parameter"><code>text</code></em>
 304 buffer, and output size of
 305 text written to buffer. </p></td>
 306 <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for input and for returning results. Default is transfer full."><span class="acronym">inout</span></acronym>][<acronym title="NULL may be passed instead of a pointer to a location."><span class="acronym">optional</span></acronym>]</span></td>
 307 </tr>
 308 <tr>
 309 <td class="parameter_name"><p>text</p></td>
 310 <td class="parameter_description"><p>buffer to write fetched name into. </p></td>
 311 <td class="parameter_annotations"><span class="annotation">[<acronym title="Out parameter, where caller must allocate storage."><span class="acronym">out caller-allocates</span></acronym>][<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym> length=text_size]</span></td>
 312 </tr>
 313 </tbody>
 314 </table></div>
 315 </div>
 316 <div class="refsect3">
 317 <a name="hb-ot-name-get-utf8.returns"></a><h4>Returns</h4>
 318 <p> full length of the requested string, or 0 if not found.</p>
 319 </div>
 320 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 321 </div>
 322 </div>
 323 <div class="refsect1">
 324 <a name="harfbuzz-hb-ot-name.other_details"></a><h2>Types and Values</h2>
 325 <div class="refsect2">
 326 <a name="hb-ot-name-id-t"></a><h3>hb_ot_name_id_t</h3>
 327 <pre class="programlisting">typedef unsigned int hb_ot_name_id_t;
 328 </pre>
 329 <p>An integral type representing an OpenType 'name' table name identifier.
 330 There are predefined name IDs, as well as name IDs return from other
 331 API.  These can be used to fetch name strings from a font face.</p>
 332 <p>For more information on these fields, see the
 333 <a class="ulink" href="https://docs.microsoft.com/en-us/typography/opentype/spec/name#name-ids" target="_top">OpenType spec</a>.</p>
 334 <p class="since">Since: <a class="link" href="api-index-2-0-0.html#api-index-2.0.0">2.0.0</a></p>
 335 </div>
 336 <hr>
 337 <div class="refsect2">
 338 <a name="hb-ot-name-entry-t"></a><h3>hb_ot_name_entry_t</h3>
 339 <pre class="programlisting">typedef struct {
 340   hb_ot_name_id_t name_id;
 341   hb_language_t   language;
 342 } hb_ot_name_entry_t;
 343 </pre>
 344 <p>Structure representing a name ID in a particular language.</p>
 345 <div class="refsect3">
 346 <a name="hb-ot-name-entry-t.members"></a><h4>Members</h4>
 347 <div class="informaltable"><table class="informaltable" width="100%" border="0">
 348 <colgroup>
 349 <col width="300px" class="struct_members_name">
 350 <col class="struct_members_description">
 351 <col width="200px" class="struct_members_annotations">
 352 </colgroup>
 353 <tbody>
 354 <tr>
 355 <td class="struct_member_name"><p><a class="link" href="harfbuzz-hb-ot-name.html#hb-ot-name-id-t" title="hb_ot_name_id_t"><span class="type">hb_ot_name_id_t</span></a> <em class="structfield"><code><a name="hb-ot-name-entry-t.name-id"></a>name_id</code></em>;</p></td>
 356 <td class="struct_member_description"><p>name ID</p></td>
 357 <td class="struct_member_annotations"> </td>
 358 </tr>
 359 <tr>
 360 <td class="struct_member_name"><p><a class="link" href="harfbuzz-hb-common.html#hb-language-t" title="hb_language_t"><span class="type">hb_language_t</span></a> <em class="structfield"><code><a name="hb-ot-name-entry-t.language"></a>language</code></em>;</p></td>
 361 <td class="struct_member_description"><p>language</p></td>
 362 <td class="struct_member_annotations"> </td>
 363 </tr>
 364 </tbody>
 365 </table></div>
 366 </div>
 367 <p class="since">Since: <a class="link" href="api-index-2-1-0.html#api-index-2.1.0">2.1.0</a></p>
 368 </div>
 369 </div>
 370 </div>
 371 <div class="footer">
 372 <hr>Generated by GTK-Doc V1.32</div>
 373 </body>
 374 </html>