2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4 <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
5 <!ENTITY version SYSTEM "version.xml">
7 <chapter id="object-model">
8 <title>The HarfBuzz object model</title>
9 <section id="object-model-intro">
10 <title>An overview of data types in HarfBuzz</title>
12 HarfBuzz features two kinds of data types: non-opaque,
13 pass-by-value types and opaque, heap-allocated types. This kind
14 of separation is common in C libraries that have to provide
15 API/ABI compatibility (almost) indefinitely.
18 <emphasis>Value types:</emphasis> The non-opaque, pass-by-value
19 types include integer types, enums, and small structs. Exposing
20 a struct in the public API makes it impossible to expand the
21 struct in the future. As such, exposing structs is reserved for
22 cases where it’s extremely inefficient to do otherwise.
25 In HarfBuzz, several structs, like <literal>hb_glyph_info_t</literal> and
26 <literal>hb_glyph_position_t</literal>, fall into that efficiency-sensitive
27 category and are non-opaque.
30 For all non-opaque structs where future extensibility may be
31 necessary, reserved members are included to hold space for
32 possible future members. As such, it’s important to provide
33 <function>equal()</function>, and <function>hash()</function>
34 methods for such structs, allowing users of the API do
35 effectively deal with the type without having to
36 adapt their code to future changes.
39 Important value types provided by HarfBuzz include the structs
40 for working with Unicode code points, glyphs, and tags for font
41 tables and features, as well as the enums for many Unicode and
46 <section id="object-model-object-types">
47 <title>Objects in HarfBuzz</title>
49 <emphasis>Object types:</emphasis> Opaque struct types are used
50 for what HarfBuzz loosely calls "objects." This doesn’t have
51 much to do with the terminology from object-oriented programming
52 (OOP), although some of the concepts are similar.
55 In HarfBuzz, all object types provide certain
56 lifecycle-management APIs. Objects are reference-counted, and
57 constructed with various <function>create()</function> methods, referenced via
58 <function>reference()</function> and dereferenced using
59 <function>destroy()</function>.
63 the <literal>hb_buffer_t</literal> object has
64 <function>hb_buffer_create()</function> as its constructor,
65 <function>hb_buffer_reference()</function> to reference, and
66 <function>hb_buffer_destroy()</function> to dereference.
69 After construction, each object's properties are accessible only
70 through the setter and getter functions described in the API
74 Key object types provided by HarfBuzz include:
76 <itemizedlist spacing="compact">
79 <emphasis>blobs</emphasis>, which act as low-level wrappers around binary
80 data. Blobs are typically used to hold the contents of a
86 <emphasis>faces</emphasis>, which represent typefaces from a
87 font file, but without specific parameters (such as size) set.
92 <emphasis>fonts</emphasis>, which represent instances of a
93 face with all of their parameters specified.
98 <emphasis>buffers</emphasis>, which hold Unicode code points
99 for characters (before shaping) and the shaped glyph output
105 <emphasis>shape plans</emphasis>, which store the settings
106 that HarfBuzz will use when shaping a particular text
107 segment. Shape plans are not generally used by client
108 programs directly, but as we will see in a later chapter,
109 they are still valuable to understand.
118 <section id="object-model-lifecycle">
119 <title>Object lifecycle management</title>
121 Each object type in HarfBuzz provides a
122 <function>create()</function> method. Some object types provide
123 additional variants of <function>create()</function> to handle
124 special cases or to speed up common tasks; those variants are
125 documented in the API reference. For example,
126 <function>hb_blob_create_from_file()</function> constructs a new
127 blob directly from the contents of a file.
130 All objects are created with an initial reference count of
131 <literal>1</literal>. Client programs can increase the reference
132 count on an object by calling its
133 <function>reference()</function> method. Whenever a client
134 program is finished with an object, it should call its
135 corresponding <function>destroy()</function> method. The destroy
136 method will decrease the reference count on the object and,
137 whenever the reference count reaches zero, it will also destroy
138 the object and free all of the associated memory.
141 All of HarfBuzz's object-lifecycle-management APIs are
142 thread-safe (unless you compiled HarfBuzz from source with the
143 <literal>HB_NO_MT</literal> configuration flag), even when the
144 object as a whole is not thread-safe.
145 It is also permissible to <function>reference()</function> or to
146 <function>destroy()</function> the <literal>NULL</literal>
150 Some objects are thread-safe after they have been constructed
151 and set up. The general pattern is to
152 <function>create()</function> the object, make a few
153 <function>set_*()</function> calls to set up the
154 object, and then use it without further modification.
157 To ensure that such an object is not modified, client programs
158 can explicitly mark an object as immutable. HarfBuzz provides
159 <function>make_immutable()</function> methods to mark an object
160 as immutable and <function>is_immutable()</function> methods to
161 test whether or not an object is immutable. Attempts to use
162 setter functions on immutable objects will fail silently; see the API
163 Reference manual for specifics.
166 Note also that there are no "make mutable" methods. If client
167 programs need to alter an object previously marked as immutable,
168 they will need to make a duplicate of the original.
171 Finally, object constructors (and, indeed, as much of the
172 shaping API as possible) will never return
173 <literal>NULL</literal>. Instead, if there is an allocation
174 error, each constructor will return an “empty” object
178 These empty-object singletons are inert and safe (although
179 typically useless) to pass around. This design choice avoids
180 having to check for <literal>NULL</literal> pointers all
184 In addition, this “empty” object singleton can also be accessed
185 using the <function>get_empty()</function> method of the object
191 <section id="object-model-user-data">
192 <title>User data</title>
194 To better integrate with client programs, HarfBuzz's objects
195 offer a "user data" mechanism that can be used to attach
196 arbitrary data to the object. User-data attachment can be
197 useful for tying the lifecycles of various pieces of data
198 together, or for creating language bindings.
201 Each object type has a <function>set_user_data()</function>
202 method and a <function>get_user_data()</function> method. The
203 <function>set_user_data()</function> methods take a client-provided
204 <literal>key</literal> and a pointer,
205 <literal>user_data</literal>, pointing to the data itself. Once
206 the key-data pair has been attached to the object, the
207 <function>get_user_data()</function> method can be called with
208 the key, returning the <function>user_data</function> pointer.
211 The <function>set_user_data()</function> methods also support an
212 optional <function>destroy</function> callback. Client programs
213 can set the <function>destroy</function> callback and receive
214 notification from HarfBuzz whenever the object is destructed.
217 Finally, each <function>set_user_data()</function> method allows
218 the client program to set a <literal>replace</literal> Boolean
219 indicating whether or not the function call should replace any
220 existing <literal>user_data</literal>
221 associated with the specified key.
227 <section id="object-model-blobs">
230 While most of HarfBuzz's object types are specific to the
231 shaping process, <emphasis>blobs</emphasis> are somewhat
235 Blobs are an abstraction desgined to negotiate lifecycle and
236 permissions for raw pieces of data. For example, when you load
237 the raw font data into memory and want to pass it to HarfBuzz,
238 you do so in a <literal>hb_blob_t</literal> wrapper.
241 This allows you to take advantage of HarffBuzz's
242 reference-counting and <function>destroy</function>
243 callbacks. If you allocated the memory for the data using
244 <function>malloc()</function>, you would create the blob using
246 <programlisting language="C">
247 hb_blob_create (data, length, HB_MEMORY_MODE_WRITABLE, data, free)
250 That way, HarfBuzz will call <function>free()</function> on the
251 allocated memory whenever the blob drops its last reference and
252 is deconstructed. Consequently, the user code can stop worrying
253 about freeing memory and let the reference-counting machinery