subsys/win32k/freetype/docs/design/index.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="Author" content="David Turner">
   6    <meta name="GENERATOR" content="Mozilla/4.5 [fr] (Win98; I) [Netscape]">
   7    <title>FreeType 2 Internals</title>
   8 </head>
   9 <body>
  10
  11 <body text="#000000"
  12       bgcolor="#FFFFFF"
  13       link="#0000EF"
  14       vlink="#51188E"
  15       alink="#FF0000">
  16
  17 <center>
  18 <h1>
  19 FreeType 2.0 Internals</h1></center>
  20
  21 <center>
  22 <h2>
  23 Version 1.2</h2></center>
  24
  25 <center>
  26 <h3>
  27 &copy; 1999-2000 David Turner (<a href="fichier :///david@freetype.org">david@freetype.org</a>)<br>
  28 &copy; 1999-2000 The FreeType Development Team (<a href="fichier :///devel@freetype.org">devel@freetype.org</a>)</h3></center>
  29
  30 <p><br>
  31 <hr WIDTH="100%">
  32 <br>&nbsp;
  33 <h2>Introduction:</h2>
  34
  35 <p>This document describes in great deatils the internals of FreeType 2.
  36    It is a must read for porters and developers alike. Its purpose is to
  37
  38    present the
  39 <blockquote>This document describes in great details the internals of the
  40 FreeType 2.0 library. It is a must read for porters and developers alike.
  41 Its purpose is to present the engine's objects, their roles and interactions.
  42 It is assumed that the <b><i>FreeType Glyph Conventions</i></b> document
  43 has been read.
  44 <p>We advise porters to also read the <b><i>FreeType Porting Guide</i></b>
  45 after this document. Would-be hackers and maintainers are of course encouraged
  46 to read the <b><i>FreeType Coding Conventions</i></b> document too. The
  47 development of a new driver is described in more details in the <b><i>FreeType
  48 Driver HowTo</i></b> document.</blockquote>
  49
  50 <p><br>
  51 <hr WIDTH="100%">
  52 <h2>
  53 I. Overview :</h2>
  54
  55 <blockquote>
  56 <h3>
  57 1. Features (and what's new) :</h3>
  58
  59 <blockquote>FreeType 2.0 has a number of important new features that were
  60 not found in the 1.x releases :
  61 <br>&nbsp;
  62 <blockquote><b>font-format independent API</b>
  63 <br>FreeType 2.0 is able to support any kind of font format, be it fixed
  64 or scalable, through the use of pluggable "font drivers". These drivers
  65 can be added or replaced at run time, while applications use a new font
  66 format-independent API.
  67 <p><b>advanced stream caching</b>
  68 <br>2.0 is able to control the number of concurrently opened streams when
  69 using fonts. It is thus possible to open dozens or hundreds of font faces
  70 without running out of system resources.
  71 <p><b>real reentrancy support</b>
  72 <br>It is now possible to use FreeType as a shared library with no static
  73 data in a multi-threaded environment. The synchronization model has also
  74 been simplified in order to make font driver writing easier. Of course,
  75 you can build FreeType with no thread support to get a smaller library.
  76 <p><b>support for cubic beziers and 17-levels anti-aliasing</b>
  77 <br>The FreeType scan-line converter (a.k.a. raster) now supports cubic
  78 bezier arcs seamlessly. It also provides a new anti-aliasing mode which
  79 uses a palette of 17 levels of grays.
  80 <br>&nbsp;</blockquote>
  81 It also features the following :
  82 <blockquote><b>performance improvements :</b>
  83 <br>The FreeType raster has been optimized, and the generation of anti-aliased
  84 pixmaps is now 60% faster than in the 1.x release. Moreover, the TrueType
  85 bytecode interpreter has been profiled and greatly optimised.
  86 <p><b>easier portability</b>
  87 <br>Porting and configuring FreeType is now much easier. A single file
  88 must be provided for system-specific operations (like memory, i/o, thread
  89 management), and a single configuration header is used to select the build
  90 you need.
  91 <br>&nbsp;</blockquote>
  92 </blockquote>
  93
  94 <h3>
  95 2. Architecture :</h3>
  96
  97 <blockquote>The engine is now split in several parts, which are :
  98 <h4>
  99 a. The base layer :</h4>
 100
 101 <blockquote>This part contains all the font-format independent features
 102 of the engine which are :
 103 <ul>
 104 <li>
 105 computations/scaling</li>
 106
 107 <li>
 108 list processing</li>
 109
 110 <li>
 111 outline processing</li>
 112
 113 <li>
 114 scan-line converter</li>
 115
 116 <li>
 117 stream manager</li>
 118
 119 <li>
 120 base object classes</li>
 121
 122 <li>
 123 debugging &amp; traces</li>
 124
 125 <li>
 126 high-level API functions</li>
 127
 128 <li>
 129 low-level system object (memory, i/o, threads)</li>
 130 </ul>
 131 </blockquote>
 132
 133 <h4>
 134 b. The font drivers :</h4>
 135
 136 <blockquote>Each font format is managed with the use of a single font driver
 137 object. The base layer is able to manage several drivers, and these can
 138 be easily added, removed or upgraded at runtime. Each driver has the following
 139 features and functions :
 140 <ul>
 141 <li>
 142 auto-check font format when opening a font resource (i.e. file)</li>
 143
 144 <li>
 145 access, load and/or extract all tables and data from the font file</li>
 146
 147 <li>
 148 grid-fit/hint the glyph outlines (in the case of scalable formats like
 149 TrueType or Type1)</li>
 150
 151 <li>
 152 provide extensions to access font format-specific data and tables from
 153 the font file</li>
 154 </ul>
 155 Note that FreeType 2.0 is a font service. Its purpose is to provide a unified
 156 API for all kinds of fonts and extract individual glyph images and metrics.
 157 However, it does not render text itself, as this operation is left to the
 158 developer, or to higher-level libraries built on top of FreeType. Here
 159 are a few features that are thus not implemented :
 160 <blockquote>1) Text string rendering
 161 <br>2) Glyph bitmap/outline caching for improved performance
 162 <br>3) Synthetic fonts (i.e. italicising, emboldening, underlining)
 163 <br>4) Contextual glyph substitution and other advanced layout processes</blockquote>
 164 Note that features 1 through 3 should be provided by the SemTex library,
 165 which may soon become part of the standard FreeType distribution.</blockquote>
 166 </blockquote>
 167 </blockquote>
 168
 169 <p><br>
 170 <hr WIDTH="100%">
 171 <h2>
 172 II. Design :</h2>
 173
 174 <blockquote>
 175 <h3>
 176 1. Objects :</h3>
 177
 178 <blockquote>They are several kinds of objects in FreeType, which can be
 179 described as follows :
 180 <blockquote><b>Base objects</b>
 181 <br>These objects do not relate directly to font data, but to the way it
 182 is organised and managed. It is the basic core and provides functions that
 183 are heavily used by each font driver. Examples are the resource objects,
 184 used to describe font files, the system object used to manage low-level
 185 system operations, or the raster object, used to convert vector outlines
 186 into bitmaps or anti-aliased pixmaps. Most of the base objects are not
 187 directly visible for client applications of FreeType.
 188 <p><b>Font objects</b>
 189 <br>The font objects directly model the data as it is found in font files.
 190 The root classes implemented in the base layer like <tt>FT_Face</tt>, <tt>FT_Size</tt>,
 191 <tt>FT_GlyphSlot</tt>,
 192 must be derived in each font driver.</blockquote>
 193 Objects are defined in the files "<tt>base/freetype.h</tt>" and "<tt>base/ftobjs.h</tt>".
 194 The former contains all the public object definitions usable by client
 195 applications. The latter contains private definitions used by the rest
 196 of the base layer and each font driver.</blockquote>
 197
 198 <h3>
 199 2. List management</h3>
 200
 201 <blockquote>The "<tt>base/ftlist.c</tt>" component a very simple doubly-linked
 202 list facility which is used by the rest of the engine to create and process
 203 lists, including iteration and finalisation. The definition of the list
 204 node and functions are placed in the "<tt>base/freetype.h</tt>" to let
 205 client applications access listed objects as they like.
 206 <p>The base list type is <tt>FT_List</tt>, which links nodes of type <tt>FT_ListNode</tt>
 207 together.
 208 <br>&nbsp;</blockquote>
 209
 210 <h3>
 211 3. Limited encapsulation</h3>
 212
 213 <blockquote>Unlike what happened in the 1.x releases, the <tt>FT_Face</tt>,
 214 <tt>FT_Size</tt>,
 215 <tt>FT_GlyphSlot</tt> and <tt>FT_CharMap</tt> types are no longer blind
 216 pointers to opaque types. Rather, the corresponding structures are now
 217 public (and defined in "<tt>base/freetype.h</tt>", see <tt>FT_FaceRec</tt>,
 218 <tt>FT_SizeRec</tt>,
 219 etc..) in order to let client applications read directly the various object
 220 attributes they're interested in.
 221 <p>This breaks encapsulation of implementation, famed by OOP, but was chosen
 222 because:
 223 <br>&nbsp;
 224 <ul>
 225 <li>
 226 it simplifies a lot the work of client applications and libraries which
 227 don't need to perform a function call everytime they want to read one important
 228 object attribute (nor does it force them to cache these attributes in their
 229 own structures).</li>
 230 </ul>
 231
 232 <ul>
 233 <li>
 234 It reduces greatly the API, as many <tt>FT_Get_XXX</tt> functions are avoided.</li>
 235 </ul>
 236
 237 <ul>
 238 <li>
 239 Higher-level libraries are able to&nbsp; access data directly. When it
 240 is used frequently, they don't need to cache it in their own structures.</li>
 241 </ul>
 242
 243 <ul>
 244 <li>
 245 It is possible to tightly link FreeType objects with higher-level ones,
 246 in a clearer and more efficient way. This is very important when one wants
 247 to write a C++ wrapper or a text rendering library on top of FreeType (actually,
 248 both projects were performed in an earlier version of FreeType 2.0 which
 249 featured classic encapsulation through get/set methods. The resulting code
 250 was ugly and slow. Moving to a limited encapsulation approach simplified
 251 so many things that the compiled code size was reduced by a factor of two
 252 !).</li>
 253 </ul>
 254
 255 <ul>
 256 <li>
 257 Finally, the API and font object structures were designed after the creation
 258 of two scalable font drivers and one bitmap font driver. They are now very
 259 stable and the public (visible) attributes are not going to change.</li>
 260 </ul>
 261 </blockquote>
 262 </blockquote>
 263
 264 <p><br>
 265 <hr WIDTH="100%">
 266 <h2>
 267 III. Base objects :</h2>
 268
 269 <blockquote>This section describes the FreeType base object classes :
 270 <br>&nbsp;
 271 <h3>
 272 1. System objects :</h3>
 273
 274 <blockquote>The system class is in charge of managing all low-level and
 275 system-specific operations. This means simply memory management, i/o access
 276 and thread synchronisation. It is implemented by the "<tt>ftsys.c</tt>"
 277 component, whose source must be located in the configuration directory
 278 when building FreeType. (e.g. "<tt>lib/arch/ansi/ftsys.c</tt>" for an ANSI
 279 build, "<tt>lib/arch/unix/ftsys.c</tt>" for a Unix one, etc..).
 280 <p>Porting FreeType 2.0 really means providing a new implementation of
 281 <tt>ftsys</tt>
 282 (along with a few configuration file changes). Note however that its interface
 283 is common to all ports, and located in "<tt>base/ftsys.h</tt>".</blockquote>
 284
 285 <h3>
 286 2. Resources and Streams:</h3>
 287
 288 <blockquote>The concepts of files as storages, and files as streams has
 289 been separated for FreeType 2.0. The "<b><i>resource</i></b>" concept was
 290 introduced while the "<b><i>stream</i></b>" one has been redefined. Here
 291 is how they work together :
 292 <ul>
 293 <li>
 294 a "<b>resource</b>" is an object which models a file, seen as a storage.
 295 There are several classes of resources, which differ usually in two ways
 296 : the way their data is accessed by applications, and the way they're named
 297 within the system.</li>
 298 </ul>
 299
 300 <ul>For example, when parsing files with the ANSI C library, data has to
 301 be read (through fseek/fread) into intermediate buffers before it can be
 302 decoded. This scheme is highly portable, but rather inefficient; when using
 303 it, we'll describe the file as a disk-based resource.
 304 <p>As most modern operating systems now provide memory-mapped files, which
 305 allow direct access while improving performance and reducing memory usage.
 306 Because data can be read directly in memory, we'll speak of a memory-based
 307 resource in this case. For embedded systems (like printers, PDAs, etc..),
 308 ROM-fonts fit into this category as well.
 309 <p>Regarding naming, most systems use a string to name files in their storage
 310 hierarchy. Though a typical pathname is an ASCII string (<tt>'c:\windows\fonts\times.ttf'</tt>
 311 on Windows, <tt>'/home/fonts/times.ttf'</tt> on Unix), some OSes use different
 312 schemes, varying from Unicode character strings to file i-node numbers.
 313 These details are platform-specific and must be hidden to the rest of the
 314 library in resource objects.
 315 <p>A resource encapsulates the lowest details regarding a file, though
 316 it should have NO STATE. Note that the nature or type of a resource (i.e.
 317 disk or memory based) is important to the "stream" component only. The
 318 rest of the library and font drivers work transparently from their implementation.
 319 <p>Note also that it is perfectly possible to mix resources of distinct
 320 natures in a single build</ul>
 321
 322 <ul>
 323 <li>
 324 a "<b>stream</b>" is an object which is used to extract bytes from a resource.
 325 Only resource objects can create streams, through its <i><tt>Open_Stream()</tt></i>
 326 method. A stream has state, which typically consist of a file "cursor",
 327 some intermediate buffers, a "current frame" and, of course, methods used
 328 to extract the data from streams, resolving endianess and alignement issues.</li>
 329 </ul>
 330 Data can be extracted from streams through direct reads, or through the
 331 use of <b>frames</b>. A frame models <i>a run of contiguous bytes</i> starting
 332 from the current stream position, and of liberal size.
 333 <p>Methods exist to extract successive integers of any sizes, while resolving
 334 endianess and alignement issues. Rather than a long rethorical explanation,
 335 here's how frames are typically used :
 336 <blockquote><tt>{</tt>
 337 <br><tt>&nbsp; \85</tt>
 338 <br><tt>&nbsp; FT_Error&nbsp; error;</tt>
 339 <p><tt>&nbsp; error = FT_Access_Frame( stream, 14 );</tt>
 340 <br><tt>&nbsp; if (error) goto Fail;</tt>
 341 <p><tt>&nbsp; val1 = FT_Get_Short(stream);</tt>
 342 <br><tt>&nbsp; val2 = FT_Get_Long(stream);</tt>
 343 <br><tt>&nbsp; val3 = FT_Get_Long(stream);</tt>
 344 <br><tt>&nbsp; val4 = FT_Get_Long(stream);</tt>
 345 <p><tt>&nbsp; FT_Forget_Frame(stream);</tt>
 346 <br><tt>&nbsp; \85</tt>
 347 <br><tt>}</tt></blockquote>
 348 This code does the following :
 349 <blockquote>
 350 <ol>
 351 <li>
 352 &nbsp;first, it "loads" the next 14 bytes from the current cursor position
 353 into the stream's frame, using the <tt>FT_Access_Frame</tt> API. An error
 354 is returned if, for example, less than 14 bytes are left in the stream
 355 when the call occurs..</li>
 356 </ol>
 357
 358 <ol>
 359 <li>
 360 &nbsp;it extract four integers (one 16-bit short, three 32-bit longs) from
 361 the frame using <tt>FT_Get_Short</tt> and <tt>FT_Get_Long</tt>. These function
 362 increment the frame's cursor finally, it "releases" the stream's frame.</li>
 363 </ol>
 364
 365 <ol>
 366 <li>
 367 &nbsp;Each stream has its own frame which can be accessed independently,
 368 however, nested frame accesses are not allowed. Note also that the bytes
 369 are effectively read from the stream on the call to <tt>FT_Access_Frame</tt>.
 370 Any subsequent read will occur after these 14 bytes, even if less are extracted
 371 through <tt>FT_Get_xxxx</tt> functions.</li>
 372 </ol>
 373 </blockquote>
 374 The implementation of the resource class is located in the system component
 375 (i.e. "<tt>arch/<i>&lt;system></i>/ftsys.c</tt>") and can thus be tailored
 376 for a specific port of the engine.
 377 <p>A resource can be created through the <tt>FT_New_Resource</tt> API;
 378 however this function only accepts an 8-bit pathname to name the target
 379 font file, which may be inappropriate for systems using a different naming
 380 scheme (e.g. UTF-16 pathname, i-node number, etc..). It's up to the porter
 381 then to provide its own resource creation function (like. <tt>FT_New_UTF16_Resource</tt>,
 382 for example) in its version of "<tt>ftsys.c</tt>".
 383 <p>Note that <tt>FT_New_Resource</tt> will fail and return an error code
 384 if the font file cannot be found, or when its font format isn't recognized
 385 by one of the drivers installed in the library. The list or resources created
 386 for a given library instance is thus the list of "installed font files".
 387 <br>&nbsp;</blockquote>
 388
 389 <h3>
 390 3. Stream Manager :</h3>
 391
 392 <blockquote>As said before, resources do not bear states, while streams
 393 do. Stream creation is also a very lengthy process, depending on the target
 394 operating system (e.g. "<tt>fopen</tt>" is usually very slow).
 395 <p>Because a typical font driver will want to use a new stream on each
 396 access to individual glyphs, being able to cache the most recently used
 397 streams is a requirement in order to avoid considerable performance penalties.
 398 <p>Stream caching is thus implemented in the "<tt>ftstream</tt>" component.
 399 It maintains a simple LRU list of the least recently used streams. Each
 400 stream in the cache is still opened and available for immediate processing.
 401 When a resource is destroyed, the stream cache is parsed to remove all
 402 related cached streams.
 403 <p>Stream caching can also be disabled with a configuration macro when
 404 using only ROM based resources (where stream opening is really quick).
 405 It is implemented through a Stream Manager object (see <tt>ftstream.c</tt>).
 406 <br>&nbsp;</blockquote>
 407
 408 <h3>
 409 4. Raster :</h3>
 410
 411 <blockquote>The raster is the component is charge of generating bitmaps
 412 and anti-aliased pixmaps from vectorial outline definitions. It is also
 413 sometimes called the scan-line converter. It has been completely rewritten
 414 for FreeType 2.0 in order to support third-order bezier arcs, 17-levels
 415 anti-aliasing (through 4x4 sub-sampling), improved performance, as well
 416 as stand-alone compilation (in order to include it in other graphics package
 417 without requiring the rest of the FreeType engine).
 418 <p>Because it was designed for easy re-use and embedded systems, the raster
 419 is a rtaher 'unusual' piece of code, because it doesn't perform a single
 420 memory allocation, nor contain any static or global variable. Rather, it
 421 is up to client applications to allocate a raster object in their own heap
 422 or memory space.
 423 <p>Each raster object also needs a rather large block of memory called
 424 its render pool. The pool is used during rendering (and only during it)
 425 in order to perform the scan-line conversion. Because it accesses and manages
 426 data directly within the pool, the raster yelds impressive performance
 427 as well as bounded memory consumption. It can also automatically decompose
 428 large requests into smaller individual sub-tasks.
 429 <p>Finally, it never creates bitmaps or pixmaps, but simply renders into
 430 them (providing clipping too). These must be described to the raster with
 431 the help of a <tt>FT_Raster_Map</tt> structure (a very simple bitmap/pixmap
 432 descriptor).
 433 <p>Note that when rendering anti-aliased pixmaps, the raster doesn't use
 434 an intermediate bitmap buffer, as filtering is part of the scan-line conversion
 435 process.
 436 <br>&nbsp;</blockquote>
 437
 438 <h3>
 439 5. Library objects :</h3>
 440
 441 <blockquote>A library object models a single instance of the FreeType engine.
 442 This is useful when FreeType is compiled as a shared object (DLL), as it
 443 can then be used by several applications, each with its own resources and
 444 objects.
 445 <p>The <tt>FT_Library</tt> type is an opaque handle to a library object.
 446 Such an object is created through a call&nbsp; to <tt>FT_Init_FreeType</tt>.
 447 Once you don't need it anymore, one can destroy a library object through
 448 <tt>FT_Done_FreeType</tt>.
 449 <p>Note that in reentrant builds, several threads can access a single library
 450 object concurrently. Such a build can be chosen by switching one configuration
 451 macro in the file '<tt>arch/<i>&lt;system></i>/ftconfig.h</tt>'</blockquote>
 452
 453 <h3>
 454 6. Driver objects :</h3>
 455
 456 <blockquote>A driver object models an instance of a given font driver,
 457 i.e. an element of FreeType code in charge of handling a given font format,
 458 like TrueType, Type1, FNT, PCF, etc..
 459 <p>Each library object contains a given set of driver objects when it is
 460 created through FT_Init_FreeType, this set being determined at compile
 461 time (see the file 'base/ftapi.c'). However, removing or adding drivers
 462 is possible at run-time, in order to make upgrades easy.</blockquote>
 463
 464 <h3>
 465 7. Diagram</h3>
 466
 467 <blockquote>This diagram show the object relationships for the sole base
 468 layer. The library object is the root of the object graph :
 469 <center>
 470 <p><img SRC="objects_diagram.png" height=300 width=562></center>
 471
 472 <p>It can be read as follows :
 473 <br>&nbsp;
 474 <ul>
 475 <li>
 476 Each library object has one system, one raster and one stream manager objects.
 477 These objects can only belong to one given library.</li>
 478 </ul>
 479
 480 <ul>
 481 <li>
 482 Each library contains one list of 0 or more resources, as well as one list
 483 of 0 or more driver objects.</li>
 484 </ul>
 485
 486 <ul>
 487 <li>
 488 Each stream manager holds a bounded list ("0..n" where 'n' is the stream
 489 cache's size) of stream objects. Each stream is related to one given resource
 490 object. Each resource may be related to zero or one stream.</li>
 491 </ul>
 492
 493 <ul>
 494 <li>
 495 Each resource is related to one driver object. A driver is related to 0
 496 or more resources.</li>
 497 </ul>
 498 </blockquote>
 499 </blockquote>
 500
 501 <p><br>
 502 <hr WIDTH="100%">
 503 <h2>
 504 IV. Font objects :</h2>
 505
 506 <blockquote>Font objects are used to directly map the information found
 507 in font files into several categories :
 508 <br>&nbsp;
 509 <h3>
 510 1. Face objects :</h3>
 511
 512 <blockquote>Face objects are used to model individual font faces. They
 513 encapsulate data which isn't related to a specific character size, or a
 514 specific glyph or glyph set. Usually, this means :
 515 <ul>
 516 <li>
 517 the font face's family and style names (e.g. "Palatino" + "Regular")</li>
 518
 519 <li>
 520 some flags indicating which kind of font this is (scalable or fixed ? fixed-width
 521 or proportional ? horizontal or vertical ? etc\85)</li>
 522
 523 <li>
 524 the number of glyphs, charmaps and eventually fixed character sizes (for
 525 bitmap formats) found in the font face.</li>
 526
 527 <li>
 528 for scalable formats, some important metrics like the ascender, descender,
 529 global font bounding box, maximum advance width, etc.. expressed in notional
 530 font/grid units (as well as the number of units on the EM grid).</li>
 531 </ul>
 532 A face is created from a resource object, with the <tt>FT_New_Face</tt>
 533 API. Each driver contains a list of opened face objects for the resources
 534 it manages. When a driver is removed or destroyed, all its child faces
 535 are discarded automatically with it.</blockquote>
 536
 537 <h3>
 538 2. Size objects :</h3>
 539
 540 <blockquote>Size objects are used to model a given character dimension
 541 for a given device resolution (which really means a given character pixel
 542 dimensions).
 543 <p>Each size object is created from a parent face object. The object can
 544 be reset to new dimensions at any time. Each face object holds a list of
 545 all its child sizes, these are destroyed automatically when the face object
 546 is discarded.
 547 <p>The metrics contains metrics, expressed in pixels, for the ascender,
 548 descender, maximum advance width, etc..
 549 <br>&nbsp;</blockquote>
 550
 551 <h3>
 552 3. Glyph Slot objects :</h3>
 553
 554 <blockquote>A glyph slot is a container where one can load individual glyphs,
 555 be they in vector of bitmap format. Each slot also contains metrics for
 556 the glyph it contains.
 557 <p>Each face object contains one or more glyph slot object : the first
 558 glyph slot is created automatically with its parent face, and it is possible
 559 to add new glyph slots (this is rarely used outside of debugging purposes).
 560 <br>&nbsp;</blockquote>
 561
 562 <h3>
 563 4. CharMap objects :</h3>
 564
 565 <blockquote>A charmap object is a sort of dictionary whose task is to translate
 566 character codes in a given character encoding (like ShiftJIS, Unicode,
 567 ANSI, etc..) into glyph indexes in a given font face.
 568 <p>A face object contains one or more charmap objects. All charmap objects
 569 are created when the parent face is created, though they're not directly
 570 visible to client applications (rather, they can be enumerated through
 571 FT_Get_First_CharMap and FT_Get_Next_CharMap, or more simply picked adequately
 572 with FT_Find_CharMap for a set of given encodings).
 573 <br>&nbsp;</blockquote>
 574
 575 <h3>
 576 5. Diagram</h3>
 577
 578 <blockquote>The following diagram illustrates the relationships between
 579 font objects :
 580 <center>
 581 <p><img SRC="objects_diagram2.png" height=327 width=561></center>
 582
 583 <p>Which can be read as :
 584 <br>&nbsp;
 585 <ul>
 586 <li>
 587 each resource may have zero or more child face objects "opened" for it.
 588 The number of faces is bounded by the number of font faces within the font
 589 resource.</li>
 590 </ul>
 591
 592 <ul>
 593 <li>
 594 each driver holds a list of all the faces opened for the resources it manages.
 595 When the driver is removed, its child faces are discarded automatically.</li>
 596 </ul>
 597
 598 <ul>
 599 <li>
 600 each face object has one single parent resource, and one single driver.</li>
 601 </ul>
 602
 603 <ul>
 604 <li>
 605 each face has one or more charmaps, and one or more glyph slots</li>
 606 </ul>
 607
 608 <ul>
 609 <li>
 610 each face holds a list of zero or more child size objects</li>
 611 </ul>
 612
 613 <ul>
 614 <li>
 615 each charmap, glyph slot and size is related to one given parent face.
 616 These objects are destroyed automatically when the parent face is discarded.</li>
 617 </ul>
 618 </blockquote>
 619 </blockquote>
 620
 621 <p><br>
 622 <hr WIDTH="100%">
 623 <h2>
 624 V. Driver Interface :</h2>
 625
 626 <blockquote>A font driver is added to a given library object through the
 627 <tt>FT_Add_Driver</tt>
 628 API. This function receives a structure known as a <tt>FT_DriverInterface</tt>,
 629 which describes the driver's basic properties.
 630 <p>The <tt>FT_DriverInterface</tt> contains a set of function pointers
 631 used for the base FreeType functionalities. However, each driver can also
 632 provide a font-format-specific extended interface to allow client applications
 633 to use more advanced features.
 634 <br>&nbsp;
 635 <h3>
 636 1. Common Interface</h3>
 637
 638 <blockquote>The structure of <tt>FT_DriverInterface</tt> is rather simple,
 639 and defined in "<tt>base/ftdriver.h</tt>". It must be well known by any
 640 developer who wants to write a new driver for the engine. We advise reading
 641 the <b><i>FreeType Driver HowTo</i></b> as well as the source code of existing
 642 drivers. Source comments.</blockquote>
 643
 644 <h3>
 645 2. Driver-specific extensions</h3>
 646
 647 <blockquote>The field of the <tt>FT_DriverInterface</tt> structure is a
 648 typeless pointer to a format-specific interface. This extended interface
 649 is usually a structure containing function pointers as well as other kind
 650 of information related to the driver.
 651 <p>It is assumed that client applications that wish to use the driver-specific
 652 extensions are able to <tt>#include</tt> the relevant header files to understand
 653 the format-specific interface structure.</blockquote>
 654 </blockquote>
 655
 656 <hr WIDTH="100%">
 657 <h2>
 658 VI. Configuration:</h2>
 659
 660 <blockquote>This section relates to the configuration of the FreeType library.
 661 By configuration, we mean selection of build options as well as the choice
 662 of font drivers to be used for each new library object.
 663 <br>&nbsp;
 664 <h3>
 665 1. Configuration files :</h3>
 666
 667 <blockquote>A single file is used to configure the FreeType base engine.
 668 As it is considered system-specific, it is located in the architecture
 669 directories of the library, under the name "arch/&lt;system>/ftconfig.h".
 670 Note that the same directory should also contain a platform-specific implementation
 671 of "ftsys.c".
 672 <p>The configuration files is a simple C header which is included by the
 673 engine's sources during compilation. It is not included in "freetype.h",
 674 and hence doesn't need to be copied when installing the FreeType headers
 675 on your system.
 676 <p>It is made of a series of #define or #undef statements, which are used
 677 to select or turn off a specific option. Each option is documented with
 678 heavy comments, and some of them are explained below.</blockquote>
 679
 680 <h3>
 681 2. Building and Makefiles :</h3>
 682
 683 <blockquote>FreeType 2.0 is more complex than its 1.x release. In order
 684 to facilitate maintenance, as well as ease considerably the writing of
 685 new font drivers, <b><i>only GNU Make is supported with FreeType 2.0</i></b>.
 686 However, it is possible to use any compiler, as well as any object or library
 687 prefix (<tt>.o, .obj, .a, .lib</tt> etc..) with them.
 688 <p>To build FreeType 2.0, one has to be in the library directory, then
 689 invoke its platform-specific makefile. For a Unix system, this would be
 690 :
 691 <blockquote>
 692 <blockquote><tt>% cd freetype2/lib</tt>
 693 <br><tt>% make -f arch/unix/Makefile</tt>
 694 <p>where '<tt>make</tt>' is really GNU Make !</blockquote>
 695 </blockquote>
 696 The system-specific <tt>Makefile</tt> located in '<tt>arch/<i>&lt;system></i></tt>'
 697 is a tiny file used to define several variables. It then includes the file
 698 <tt>freetype2/lib/Makefile.lib</tt>,
 699 which contains all the gory details about library compilation. The system-specific
 700 <tt>Makefile</tt> can be very easily modified to accomodate a new compiler/platform
 701 (see the comments within one of these files).
 702 <p>Each font driver is located in a directory like "<tt>freetype2/lib/drivers/<i>&lt;formatdir></i></tt>".
 703 For example, the TrueType driver is located in "<tt>drivers/truetype</tt>".
 704 Each driver directory must contain a <tt>Makefile</tt> which will be included
 705 by <tt>Makefile.lib</tt>. The former is used to define and build driver
 706 object files.
 707 <br>&nbsp;
 708 <p><br>
 709 <center>
 710 <p><img SRC="build_diagram.png" height=284 width=559></center>
 711 </blockquote>
 712
 713 <h3>
 714 3. Make options :</h3>
 715
 716 <blockquote>The base layer, as well as each font driver, are made up of
 717 several C sources. Traditionally, one compiles each source (i.e. '<tt>.c</tt>'
 718 file) into an object ('<tt>.o</tt>' or '<tt>.obj</tt>') file, and all of
 719 them are grouped into a library file (i.e. '<tt>.a</tt>' or '<tt>.lib</tt>').
 720 <p>By default, FreeType takes a slightly different approach when it comes
 721 to compiling each part of the engine. Usually, a single tiny source is
 722 compiled, which includes all other component sources. This results in a
 723 single object files, with the benefits or reduced code size, usually better
 724 compilation as well as a drastic reduction of the number of symbols exported
 725 by the library. Of course, it is made possible through the use of specific
 726 declaration macros in the FreeType source (see the definition of <tt>LOCAL_DEF</tt>
 727 and <tt>LOCAL_FUNC</tt> in <tt>ftconfig.h</tt> for details).
 728 <p>For a concrete example, see the source code in "<tt>base/ftbase.c</tt>"
 729 which generates the whole base layer in a single object file. The same
 730 build process is applied to font drivers, in order to generate one single
 731 object file per given font format (e.g. <tt>truetype.o</tt>, <tt>type1.o</tt>,
 732 etc..).
 733 <p>Compiling the library and drivers in "normal" mode is possible, through
 734 the use of the '<tt>multi</tt>' target (which really means &laquo; multiple
 735 objects &raquo;). For example, calling :
 736 <blockquote><tt>% make -f arch/ansi/Makefile multi</tt></blockquote>
 737 Will build the FreeType library by compiling each source file to an individual
 738 object, then linking them together. You'll notice that the library is significantly
 739 bigger in this case. Creating a shared dll from a 'multi' build is certainly
 740 a very poor idea, as this will export a huge quantity of symbols that aren't
 741 useful to any client application.</blockquote>
 742
 743 <h3>
 744 4. Adding a driver at compile time</h3>
 745
 746 <blockquote>A driver can be included very easily in the build process by
 747 including its <tt>Makefile</tt> in <tt>Makefile.lib</tt>. For example,
 748 the TrueType driver is simply included with the following lines (see <tt>Makefile.lib</tt>):
 749 <blockquote><tt># TrueType driver rules</tt>
 750 <br><tt>#</tt>
 751 <br><tt>include $(DRIVERS_DIR)/truetype/Makefile</tt></blockquote>
 752
 753 <p><br>Where <tt>DRIVERS_DIR</tt> really is "<tt>freetype2/lib/drivers</tt>",
 754 though this can be redefined. You can, of course specify a different path
 755 if you want to place your driver sources in another location.
 756 <p>Note that this only adds the driver's object files to the generated
 757 library file. A few more steps are needed to make your <tt>FT_Library</tt>
 758 objects use the driver. They consist in modifying the file "<tt>base/ftinit.c</tt>",
 759 whose sole purpose is to define the set of driver objects that are to be
 760 created with each new library object.
 761 <br>&nbsp;</blockquote>
 762
 763 <h3>
 764 5. Adding a driver at run time</h3>
 765
 766 <blockquote>New driver objects can be added at run-time through the <tt>FT_Add_Driver</tt>
 767 API. This function takes a handle to an existing library object, as well
 768 as a pointer to a given driver interface. This interface is used to create
 769 a new driver object and register it within the library.
 770 <p>Similarly, a single driver can be removed from a library anytime through
 771 <tt>FT_Remove_Driver</tt>.
 772 This will automatically discard the resources and face objects managed
 773 by the driver.</blockquote>
 774
 775 <h3>
 776 6. Custom library objects :</h3>
 777
 778 <blockquote>Finally, it is possible to build custom library objects. You
 779 need to pass a handle to a valid <tt>FT_System</tt> object to the <tt>FT_Build_Library</tt>
 780 API. The function will return a handle to the new fresh library object.
 781 Note that the library has no registered drivers after the call, developers
 782 have to add them by hand with <tt>FT_Add_Driver</tt>.
 783 <p>It is thus possible to create two distinct library objects with distinct
 784 <tt>FT_System</tt>
 785 implementations in the same session, which can be useful for debugging
 786 purpose.</blockquote>
 787
 788 <br>&nbsp;</blockquote>
 789
 790 </body>
 791 </html>