| <!doctype html public "-//w3c//dtd html 4.0 transitional//en" |
| "http://www.w3.org/TR/REC-html40/loose.dtd"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" |
| content="text/html; charset=iso-8859-1"> |
| <meta name="Author" |
| content="David Turner"> |
| <title>The Design of FreeType 2 - Public Objects</title> |
| </head> |
| |
| <body text="#000000" |
| bgcolor="#ffffff"> |
| |
| <h1 align=center> |
| The Design of FreeType 2 |
| </h1> |
| |
| <center> |
| <table width="650"> |
| <tr><td> |
| |
| <center><table width="100%" border=0 cellpadding=5><tr bgcolor="#CCFFCC" valign=center> |
| <td align=center width="30%"> |
| <a href="design-2.html">Previous</a> |
| </td> |
| <td align=center width="30%"> |
| <a href="index.html">Contents</a> |
| </td> |
| <td align=center width="30%"> |
| <a href="design-4.html">Next</a> |
| </td> |
| </tr></table></center> |
| |
| <table width="100%"> |
| <tr bgcolor="#ccccee"><td> |
| <h1> |
| II. Public Objects and Classes |
| </h1> |
| </td></tr> |
| </table> |
| |
| <p>We will now explain the abstractions provided by FreeType 2 to |
| client applications to manage font files and data. As you would normally |
| expect, these are implemented through objects/classes.</p> |
| |
| <h2> |
| 1. Object Orientation in FreeType 2 |
| </h2> |
| |
| <p>Though written in ANSI C, the library employs a few techniques, |
| inherited from object-oriented programming, to make it easy to extend. |
| Hence, the following conventions apply in the FreeType 2 source |
| code:</p> |
| |
| <ol> |
| <li> |
| <p>Each object type/class has a corresponding <em>structure |
| type</em> <b>and</b> a corresponding <em>structure pointer |
| type</em>. The latter is called the <em>handle type</em> for the |
| type/class.</p> |
| |
| <p>Consider that we need to manage objects of type "foo" in |
| FreeType 2. We would define the following structure and handle |
| types as follows:</p> |
| |
| <font color="blue"><pre> |
| typedef struct FT_FooRec_* FT_Foo; |
| |
| typedef struct FT_FooRec_ |
| { |
| // fields for the "foo" class |
| ... |
| |
| } FT_FooRec;</pre> |
| </font> |
| |
| <p>As a convention, handle types use simple but meaningful |
| identifiers beginning with <tt>FT_</tt>, as in <tt>FT_Foo</tt>, |
| while structures use the same name with a <tt>Rec</tt> suffix |
| appended to it ("Rec" is short for "record"). <em>Note that each |
| class type has a corresponding handle type</em>.</p> |
| </li> |
| <li> |
| <p>Class derivation is achieved internally by wrapping base class |
| structures into new ones. As an example, we define a "foobar" class |
| that is derived from "foo". We would do something like:</p> |
| |
| <font color="blue"><pre> |
| typedef struct FT_FooBarRec_* FT_FooBar; |
| |
| typedef struct FT_FooBarRec_ |
| { |
| // the base "foo" class fields |
| FT_FooRec root; |
| |
| // fields proper to the "foobar" class |
| ... |
| } FT_FooBarRec;</pre> |
| </font> |
| |
| <p>As you can see, we ensure that a "foobar" object is also a "foo" |
| object by placing a <tt>FT_FooRec</tt> at the start of the |
| <tt>FT_FooBarRec</tt> definition. It is called <b>root</b> by |
| convention.</p> |
| |
| <p>Note that a <tt>FT_FooBar</tt> handle also points to a "foo" |
| object and can be typecasted to <tt>FT_Foo</tt>. Similarly, when |
| the library returns a <tt>FT_Foo</tt> handle to client applications, |
| the object can be really implemented as a <tt>FT_FooBar</tt> or any |
| derived class from "foo".</p> |
| </li> |
| </ol> |
| |
| <p>In the following sections of this chapter, we will refer to "the |
| <tt>FT_Foo</tt> class" to indicate the type of objects handled through |
| <tt>FT_Foo</tt> pointers, be they implemented as "foo" or "foobar".</p> |
| |
| <hr> |
| |
| <h2> |
| 2. The <tt>FT_Library</tt> class |
| </h2> |
| |
| <p>This type corresponds to a handle to a single instance of the |
| library. Note that the corresponding structure <tt>FT_LibraryRec</tt> |
| is not defined in public header files, making client applications unable |
| to access its internal fields.</p> |
| |
| <p>The library object is the <em>parent</em> of all other objects in |
| FreeType 2. You need to create a new library instance before doing |
| anything else with the library. Similarly, destroying it will |
| automatically destroy all its children (i.e. faces and modules).</p> |
| |
| <p>Typical client applications should call <tt>FT_Init_FreeType()</tt> |
| in order to create a new library object, ready to be used for further |
| actions.</p> |
| |
| <p>Another alternative is to create a fresh new library instance by |
| calling the function <tt>FT_New_Library()</tt>, defined in the |
| <tt><freetype/ftmodule.h></tt> public header file. This function |
| will however return an "empty" library instance with no module |
| registered in it. You can "install" modules in the instance by calling |
| <tt>FT_Add_Module()</tt> manually.</p> |
| |
| <p>Calling <tt>FT_Init_FreeType()</tt> is a lot more convenient, because |
| this function basically registers a set of default modules into each new |
| library instance. The way this list is accessed and/or computed is |
| determined at build time, and depends on the content of the |
| <tt>ftinit</tt> component. This process is explained in details later |
| in this document.</p> |
| |
| <p>For now, one should consider that library objects are created with |
| <tt>FT_Init_FreeType()</tt>, and destroyed along with all children with |
| <tt>FT_Done_FreeType()</tt>.</p> |
| |
| <hr> |
| |
| <h2> |
| 3. The <tt>FT_Face</tt> class |
| </h2> |
| |
| <p>A face object corresponds to a single <em>font face</em>, i.e., a |
| specific typeface with a specific style. For example, "Arial" and |
| "Arial Italic" correspond to two distinct faces.</p> |
| |
| <p>A face object is normally created through <tt>FT_New_Face()</tt>. |
| This function takes the following parameters: an <tt>FT_Library</tt> |
| handle, a C file pathname used to indicate which font file to open, an |
| index used to decide which face to load from the file (a single file may |
| contain several faces in certain cases), and the address of a |
| <tt>FT_Face</tt> handle. It returns an error code:</p> |
| |
| <font color="blue"><pre> |
| FT_Error FT_New_Face( FT_Library library, |
| const char* filepathname, |
| FT_Long face_index, |
| FT_Face* face );</pre> |
| </font> |
| |
| <p>In case of success, the function will return 0, and the handle |
| pointed to by the <tt>face</tt> parameter will be set to a non-NULL |
| value.</p> |
| |
| <p>Note that the face object contains several fields used to describe |
| global font data that can be accessed directly by client applications. |
| For example, the total number of glyphs in the face, the face's family |
| name, style name, the EM size for scalable formats, etc. For more |
| details, look at the <tt>FT_FaceRec</tt> definition in the |
| FreeType 2 API Reference.</p> |
| |
| <hr> |
| |
| <h2> |
| 4. The <tt>FT_Size</tt> class |
| </h2> |
| |
| <p>Each <tt>FT_Face</tt> object <em>has</em> one or more |
| <tt>FT_Size</tt> objects. A <em>size object</em> is used to store data |
| specific to a given character width and height. Each newly created face |
| object has one size, which is directly accessible as |
| <tt>face->size</tt>.</p> |
| |
| <p>The contents of a size object can be changed by calling either |
| <tt>FT_Set_Pixel_Sizes()</tt> or <tt>FT_Set_Char_Size()</tt>.</p> |
| |
| <p>A new size object can be created with <tt>FT_New_Size()</tt>, and |
| destroyed manually with </tt>FT_Done_Size()</tt>. Note that typical |
| applications don't need to do this normally: they tend to use the |
| default size object provided with each <tt>FT_Face</tt>.</p> |
| |
| <p>The public fields of <tt>FT_Size</tt> objects are defined in a very |
| small structure named <tt>FT_SizeRec</tt>. However, it is important to |
| understand that some font drivers define their own derivatives of |
| <tt>FT_Size</tt> to store important internal data that is re-computed |
| each time the character size changes. Most of the time, these are |
| size-specific <em>font hints</em>./p> |
| |
| <p>For example, the TrueType driver stores the scaled CVT table that |
| results from the execution of the "cvt" program in a <tt>TT_Size</tt> |
| structure, while the Type 1 driver stores scaled global metrics |
| (like blue zones) in a <tt>T1_Size</tt> object. Don't worry if you |
| don't understand the current paragraph; most of this stuff is highly |
| font format specific and doesn't need to be explained to client |
| developers :-)</p> |
| |
| <hr> |
| |
| <h2> |
| 5. The <tt>FT_GlyphSlot</tt> class |
| </h2> |
| |
| <p>The purpose of a glyph slot is to provide a place where glyph images |
| can be loaded one by one easily, independently of the glyph image format |
| (bitmap, vector outline, or anything else).</p> |
| |
| <p>Ideally, once a glyph slot is created, any glyph image can be loaded |
| into it without additional memory allocation. In practice, this is only |
| possible with certain formats like TrueType which explicitly provide |
| data to compute a slot's maximum size.</p> |
| |
| <p>Another reason for glyph slots is that they are also used to hold |
| format-specific hints for a given glyphs as well as all other data |
| necessary to correctly load the glyph.</p> |
| |
| <p>The base <tt>FT_GlyphSlotRec</tt> structure only presents glyph |
| metrics and images to client applications, while actual implementation |
| may contain more sophisticated data.</p> |
| |
| <p>As an example, the TrueType-specific <tt>TT_GlyphSlotRec</tt> |
| structure contains additional fields to hold glyph-specific bytecode, |
| transient outlines used during the hinting process, and a few other |
| things. |
| |
| The Type 1-specific <tt>T1_GlyphSlotRec</tt> structure holds glyph |
| hints during glyph loading, as well as additional logic used to properly |
| hint the glyphs when a native Type 1 hinter is used.</p> |
| |
| <p>Finally, each face object has a single glyph slot that is directly |
| accessible as <tt>face->glyph</tt>.</p> |
| |
| <hr> |
| |
| <h2> |
| 6. The <tt>FT_CharMap</tt> class |
| </h2> |
| |
| <p>The <tt>FT_CharMap</tt> type is used as a handle to character map |
| objects, or <em>charmaps</em>. A charmap is simply some sort of table |
| or dictionary which is used to translate character codes in a given |
| encoding into glyph indices for the font.</p> |
| |
| <p>A single face may contain several charmaps. Each one of them |
| corresponds to a given character repertoire, like Unicode, Apple Roman, |
| Windows codepages, and other encodings.</p> |
| |
| <p>Each <tt>FT_CharMap</tt> object contains a "platform" and an |
| "encoding" field used to identify precisely the character repertoire |
| corresponding to it.</p> |
| |
| <p>Each font format provides its own derivative of |
| <tt>FT_CharMapRec</tt> and thus needs to implement these objects.</p> |
| |
| <hr> |
| |
| <h2> |
| 7. Objects relationships |
| </h2> |
| |
| <p>The following diagram summarizes what we have just said regarding the |
| public objects managed by the library, as well as explicitely describes |
| their relationships</p> |
| |
| <center> |
| <img src="simple-model.png" |
| width=453 height=378 |
| alt="Simple library model"> |
| </center> |
| |
| <p>Note that this picture will be updated at the end of the next |
| chapter, related to <em>internal objects</em>.</p> |
| |
| <center><table width="100%" border=0 cellpadding=5><tr bgcolor="#CCFFCC" valign=center> |
| <td align=center width="30%"> |
| <a href="design-2.html">Previous</a> |
| </td> |
| <td align=center width="30%"> |
| <a href="index.html">Contents</a> |
| </td> |
| <td align=center width="30%"> |
| <a href="design-4.html">Next</a> |
| </td> |
| </tr></table></center> |
| |
| </td></tr> |
| </table> |
| </center> |
| </body> |
| </html> |