|
|
|
@ -12,7 +12,7 @@ |
|
|
|
|
HarfBuzz features two kinds of data types: non-opaque, |
|
|
|
|
pass-by-value types and opaque, heap-allocated types. This kind |
|
|
|
|
of separation is common in C libraries that have to provide |
|
|
|
|
API/ABI compatibility (almost) indefinitely. |
|
|
|
|
API/ABI compatibility (almost) indefinitely. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
<emphasis>Value types:</emphasis> The non-opaque, pass-by-value |
|
|
|
@ -32,8 +32,8 @@ |
|
|
|
|
possible future members. As such, it’s important to provide |
|
|
|
|
<function>equal()</function>, and <function>hash()</function> |
|
|
|
|
methods for such structs, allowing users of the API do |
|
|
|
|
effectively deal with the type without having to |
|
|
|
|
adapt their code to future changes. |
|
|
|
|
effectively deal with the type without having to |
|
|
|
|
adapt their code to future changes. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
Important value types provided by HarfBuzz include the structs |
|
|
|
@ -42,7 +42,7 @@ |
|
|
|
|
OpenType properties. |
|
|
|
|
</para> |
|
|
|
|
</section> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section id="object-model-object-types"> |
|
|
|
|
<title>Objects in HarfBuzz</title> |
|
|
|
|
<para> |
|
|
|
@ -63,7 +63,7 @@ |
|
|
|
|
the <literal>hb_buffer_t</literal> object has |
|
|
|
|
<function>hb_buffer_create()</function> as its constructor, |
|
|
|
|
<function>hb_buffer_reference()</function> to reference, and |
|
|
|
|
<function>hb_buffer_destroy()</function> to dereference. |
|
|
|
|
<function>hb_buffer_destroy()</function> to dereference. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
After construction, each object's properties are accessible only |
|
|
|
@ -110,11 +110,11 @@ |
|
|
|
|
</para> |
|
|
|
|
</listitem> |
|
|
|
|
</itemizedlist> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</section> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section id="object-model-lifecycle"> |
|
|
|
|
<title>Object lifecycle management</title> |
|
|
|
|
<para> |
|
|
|
@ -131,7 +131,7 @@ |
|
|
|
|
<literal>1</literal>. Client programs can increase the reference |
|
|
|
|
count on an object by calling its |
|
|
|
|
<function>reference()</function> method. Whenever a client |
|
|
|
|
program is finished with an object, it should call its |
|
|
|
|
program is finished with an object, it should call its |
|
|
|
|
corresponding <function>destroy()</function> method. The destroy |
|
|
|
|
method will decrease the reference count on the object and, |
|
|
|
|
whenever the reference count reaches zero, it will also destroy |
|
|
|
@ -141,8 +141,8 @@ |
|
|
|
|
All of HarfBuzz's object-lifecycle-management APIs are |
|
|
|
|
thread-safe (unless you compiled HarfBuzz from source with the |
|
|
|
|
<literal>HB_NO_MT</literal> configuration flag), even when the |
|
|
|
|
object as a whole is not thread-safe. |
|
|
|
|
It is also permissible to <function>reference()</function> or to |
|
|
|
|
object as a whole is not thread-safe. |
|
|
|
|
It is also permissible to <function>reference()</function> or to |
|
|
|
|
<function>destroy()</function> the <literal>NULL</literal> |
|
|
|
|
value. |
|
|
|
|
</para> |
|
|
|
@ -160,7 +160,7 @@ |
|
|
|
|
as immutable and <function>is_immutable()</function> methods to |
|
|
|
|
test whether or not an object is immutable. Attempts to use |
|
|
|
|
setter functions on immutable objects will fail silently; see the API |
|
|
|
|
Reference manual for specifics. |
|
|
|
|
Reference manual for specifics. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
Note also that there are no "make mutable" methods. If client |
|
|
|
@ -187,7 +187,7 @@ |
|
|
|
|
</para> |
|
|
|
|
</section> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section id="object-model-user-data"> |
|
|
|
|
<title>User data</title> |
|
|
|
|
<para> |
|
|
|
@ -195,7 +195,7 @@ |
|
|
|
|
offer a "user data" mechanism that can be used to attach |
|
|
|
|
arbitrary data to the object. User-data attachment can be |
|
|
|
|
useful for tying the lifecycles of various pieces of data |
|
|
|
|
together, or for creating language bindings. |
|
|
|
|
together, or for creating language bindings. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
Each object type has a <function>set_user_data()</function> |
|
|
|
@ -220,10 +220,10 @@ |
|
|
|
|
existing <literal>user_data</literal> |
|
|
|
|
associated with the specified key. |
|
|
|
|
</para> |
|
|
|
|
</section> |
|
|
|
|
</section> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<section id="object-model-blobs"> |
|
|
|
|
<title>Blobs</title> |
|
|
|
|
<para> |
|
|
|
@ -238,9 +238,9 @@ |
|
|
|
|
you do so in a <literal>hb_blob_t</literal> wrapper. |
|
|
|
|
</para> |
|
|
|
|
<para> |
|
|
|
|
This allows you to take advantage of HarffBuzz's |
|
|
|
|
This allows you to take advantage of HarfBuzz's |
|
|
|
|
reference-counting and <function>destroy</function> |
|
|
|
|
callbacks. If you allocated the memory for the data using |
|
|
|
|
callbacks. If you allocated the memory for the data using |
|
|
|
|
<function>malloc()</function>, you would create the blob using |
|
|
|
|
</para> |
|
|
|
|
<programlisting language="C"> |
|
|
|
@ -251,8 +251,8 @@ |
|
|
|
|
allocated memory whenever the blob drops its last reference and |
|
|
|
|
is deconstructed. Consequently, the user code can stop worrying |
|
|
|
|
about freeing memory and let the reference-counting machinery |
|
|
|
|
take care of that. |
|
|
|
|
take care of that. |
|
|
|
|
</para> |
|
|
|
|
</section> |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</chapter> |
|
|
|
|