|
-
- - - - Introduction -- -This short tutorial will teach you how to use the FreeType 2 - library in your own applications. - -- - - 1. Header files -- -To include the main FreeType header file, simply say - - -- #include <freetype/freetype.h>- - - in your application code. Note that other files are available in the - FreeType include directory, most of them being included by - "freetype.h". They will be described later in this - tutorial. - -- - - 2. Initialize the library -- -Simply create a variable of type FT_Library named, for - example, library, and call the function - FT_Init_FreeType() as in - - -
- #include <freetype/freetype.h>
-
- FT_Library library;
-
- ...
-
- {
- ...
- error = FT_Init_FreeType( &library );
- if ( error )
- {
- ... an error occurred during library initialization ...
- }
- }
-
-
- This function is in charge of the following: - -
As you can see, the function returns an error code, like most others - in the FreeType API. An error code of 0 always means that - the operation was successful; otherwise, the value describes the error, - and library is set to NULL. - -- - - 3. Load a font face -- -- a. From a font file -- -Create a new face object by calling FT_New_Face. - A face describes a given typeface and style. For example, - "Times New Roman Regular" and "Times New Roman Italic" correspond to - two different faces. - - -
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
-
- error = FT_Init_FreeType( &library );
- if ( error ) { ... }
-
- error = FT_New_Face( library,
- "/usr/share/fonts/truetype/arial.ttf",
- 0,
- &face );
- if ( error == FT_Err_Unknown_File_Format )
- {
- ... the font file could be opened and read, but it appears
- ... that its font format is unsupported
- }
- else if ( error )
- {
- ... another error code means that the font file could not
- ... be opened or read, or simply that it is broken...
- }
-
-
- As you can certainly imagine, FT_New_Face opens a font - file, then tries to extract one face from it. Its parameters are - -
To know how many faces a given font file contains, simply load its - first face (use face_index=0), then see the value of - face->num_faces which indicates how many faces are embedded - in the font file. - -- b. From memory -- -In the case where you have already loaded the font file in memory, - you can similarly create a new face object for it by calling - FT_New_Memory_Face as in - - -
- FT_Library library; /* handle to library */
- FT_Face face; /* handle to face object */
-
- error = FT_Init_FreeType( &library );
- if ( error ) { ... }
-
- error = FT_New_Memory_Face( library,
- buffer, /* first byte in memory */
- size, /* size in bytes */
- 0, /* face_index */
- &face );
- if ( error ) { ... }
-
-
- As you can see, FT_New_Memory_Face() simply takes a - pointer to the font file buffer and its size in bytes instead of a - file pathname. Other than that, it has exactly the same semantics as - FT_New_Face(). - -- c. From other sources (compressed files, network, etc.) -- -There are cases where using a file pathname or preloading the file - in memory is simply not enough. With FreeType 2, it is possible - to provide your own implementation of i/o routines. - -This is done through the FT_Open_Face() function, which - can be used to open a new font face with a custom input stream, select - a specific driver for opening, or even pass extra parameters to the - font driver when creating the object. We advise you to refer to the - FreeType 2 reference manual in order to learn how to use it. - -Note that providing a custom stream might also be used to access a - TrueType font embedded in a Postscript Type 42 wrapper. - -- - - 4. Accessing face content -- -A face object models all information that globally describes - the face. Usually, this data can be accessed directly by dereferencing - a handle, like - -
For a complete listing of all face properties and fields, please read - the FreeType 2 API Reference. - - - - - 5. Setting the current pixel size -- -FreeType 2 uses "size objects" to model all - information related to a given character size for a given face. - For example, a size object will hold the value of certain metrics - like the ascender or text height, expressed in 1/64th of a pixel, - for a character size of 12 points. - -When the FT_New_Face function is called (or one of its - cousins), it automatically creates a new size object for - the returned face. This size object is directly accessible as - face->size. - -NOTA BENE: a single face object can deal with one or more size - objects at a time, however, this is something that few programmers - really need to do. We have thus have decided to simplify the API for - the most common use (i.e. one size per face), while keeping this - feature available through additional fuctions. - -When a new face object is created, its size object defaults to the - character size of 10 pixels (both horizontally and vertically) for - scalable formats. For fixed-sizes formats, the size is more or less - undefined, which is why you must set it before trying to load a - glyph. - -To do that, simply call FT_Set_Char_Size(). Here is an - example where the character size is set to 16pt for a 300x300 dpi - device: - - -- error = FT_Set_Char_Size( - face, /* handle to face object */ - 0, /* char_width in 1/64th of points */ - 16*64, /* char_height in 1/64th of points */ - 300, /* horizontal device resolution */ - 300 ); /* vertical device resolution */- - - You will notice that: - -
This function computes the character pixel size that corresponds to - the character width and height and device resolutions. However, if you - want to specify the pixel sizes yourself, you can simply call - FT_Set_Pixel_Sizes(), as in - - -- error = FT_Set_Pixel_Sizes( - face, /* handle to face object */ - 0, /* pixel_width */ - 16 ); /* pixel_height */- - - This example will set the character pixel sizes to 16x16 pixels. - As previously, a value of 0 for one of the dimensions means - "same as the other". - -Note that both functions return an error code. Usually, an error - occurs with a fixed-size font format (like FNT or PCF) when trying to - set the pixel size to a value that is not listed in the - face->fixed_sizes array. - -- - - 6. Loading a glyph image -- -- a. Converting a character code into a glyph index -- -Usually, an application wants to load a glyph image based on its - character code, which is a unique value that defines the - character for a given encoding. For example, the character - code 65 represents the `A' in ASCII encoding. - -A face object contains one or more tables, called - charmaps, that are used to convert character codes to glyph - indices. For example, most TrueType fonts contain two charmaps. One - is used to convert Unicode character codes to glyph indices, the other - is used to convert Apple Roman encoding into glyph indices. Such - fonts can then be used either on Windows (which uses Unicode) and - Macintosh (which uses Apple Roman, bwerk). Note also that a given - charmap might not map to all the glyphs present in the font. - -By default, when a new face object is created, it lists all the - charmaps contained in the font face and selects the one that supports - Unicode character codes if it finds one. Otherwise, it tries to find - support for Latin-1, then ASCII. - -We will describe later how to look for specific charmaps in a face. - For now, we will assume that the face contains at least a Unicode - charmap that was selected during FT_New_Face(). To convert a - Unicode character code to a font glyph index, we use - FT_Get_Char_Index() as in - - -- glyph_index = FT_Get_Char_Index( face, charcode );- - - This will look the glyph index corresponding to the given - charcode in the charmap that is currently selected for the - face. If charmap is selected, the function simply returns the - charcode. - -Note that this is one of the rare FreeType functions that do not - return an error code. However, when a given character code has no - glyph image in the face, the value 0 is returned. By convention, - it always correspond to a special glyph image called the missing - glyph, which usually is represented as a box or a space. - -- b. Loading a glyph from the face -- -Once you have a glyph index, you can load the corresponding glyph - image. Note that the glyph image can be in several formats. For - example, it will be a bitmap for fixed-size formats like FNT, FON, or - PCF. It will also be a scalable vector outline for formats like - TrueType or Type 1. The glyph image can also be stored in an - alternate way that is not known at the time of writing this - documentation. - -The glyph image is always stored in a special object called a - glyph slot. As its name suggests, a glyph slot is simply a - container that is able to hold one glyph image at a time, be it a - bitmap, an outline, or something else. Each face object has a single - glyph slot object that can be accessed as - face->glyph. - -Loading a glyph image into the slot is performed by calling - FT_Load_Glyph() as in - - -- error = FT_Load_Glyph( - face, /* handle to face object */ - glyph_index, /* glyph index */ - load_flags ); /* load flags, see below */- - - The load_flags value is a set of bit flags used to - indicate some special operations. The default value - FT_LOAD_DEFAULT is 0. - -This function will try to load the corresponding glyph image - from the face. Basically, this means that: - -
The field glyph->format describe the format - used to store the glyph image in the slot. If it is not - ft_glyph_format_bitmap, one can immediately - convert it to a bitmap through FT_Render_Glyph, - as in: - - -- error = FT_Render_Glyph( - face->glyph, /* glyph slot */ - render_mode ); /* render mode */ -- - - The parameter render_mode is a set of bit flags used - to specify how to render the glyph image. Set it to 0 to render - a monochrome bitmap, or to ft_render_mode_antialias to - generate a high-quality (256 gray levels) anti-aliased bitmap - from the glyph image. - -Once you have a bitmap glyph image, you can access it directly - through glyph->bitmap (a simple bitmap descriptor), - and position it through glyph->bitmap_left and - glyph->bitmap_top. - -Note that bitmap_left is the horizontal distance from the - current pen position to the left-most border of the glyph bitmap, - while bitmap_top is the vertical distance from the - pen position (on the baseline) to the top-most border of the - glyph bitmap. It is positive to indicate an upwards - distance. - -The next section will detail the content of a glyph slot and - how to access specific glyph information (including metrics). - -- c. Using other charmaps -- -As said before, when a new face object is created, it will look for - a Unicode, Latin-1, or ASCII charmap and select it. The currently - selected charmap is accessed via face->charmap. This - field is NULL when no charmap is selected, which typically happens - when you create a new FT_Face object from a font file that - doesn't contain an ASCII, Latin-1, or Unicode charmap (rare - stuff). - -There are two ways to select a different charmap with FreeType 2. - The easiest is when the encoding you need already has a corresponding - enumeration defined in <freetype/freetype.h>, as - ft_encoding_big5. In this case, you can simply call - FT_Select_CharMap as in: - -- error = FT_Select_CharMap( - face, /* target face object */ - ft_encoding_big5 ); /* encoding.. */ -- - Another way is to manually parse the list of charmaps for the - face, this is accessible through the fields - num_charmaps and charmaps - (notice the 's') of the face object. As you could expect, - the first is the number of charmaps in the face, while the - second is a table of pointers to the charmaps - embedded in the face. - -Each charmap has a few visible fields used to describe it more - precisely. Mainly, one will look at - charmap->platform_id and - charmap->encoding_id that define a pair of - values that can be used to describe the charmap in a rather - generic way. - -Each value pair corresponds to a given encoding. For example, - the pair (3,1) corresponds to Unicode. Their list is - defined in the TrueType specification but you can also use the - file <freetype/ftnameid.h> which defines several - helpful constants to deal with them.. - -To look for a specific encoding, you need to find a corresponding - value pair in the specification, then look for it in the charmaps - list. Don't forget that some encoding correspond to several - values pair (yes it's a real mess, but blame Apple and Microsoft - on such stupidity..). Here's some code to do it: - - -
- FT_CharMap found = 0;
- FT_CharMap charmap;
- int n;
-
- for ( n = 0; n < face->num_charmaps; n++ )
- {
- charmap = face->charmaps[n];
- if ( charmap->platform_id == my_platform_id &&
- charmap->encoding_id == my_encoding_id )
- {
- found = charmap;
- break;
- }
- }
-
- if ( !found ) { ... }
-
- /* now, select the charmap for the face object */
- error = FT_Set_CharMap( face, found );
- if ( error ) { ... }
-
-
- Once a charmap has been selected, either through - FT_Select_CharMap or FT_Set_CharMap, - it is used by all subsequent calls to - FT_Get_Char_Index(). - - -- d. Glyph Transforms: -- -It is possible to specify an affine transformation to be applied - to glyph images when they're loaded. Of course, this will only - work for scalable (vectorial) font formats. - -To do that, simply call FT_Set_Transform, as in: - -- error = FT_Set_Transform( - face, /* target face object */ - &matrix, /* pointer to 2x2 matrix */ - &delta ); /* pointer to 2d vector */ -- - This function will set the current transform for a given face - object. Its second parameter is a pointer to a simple - FT_Matrix structure that describes a 2x2 affine matrix. - The third parameter is a pointer to a FT_Vector structure - that describe a simple 2d vector. - -Note that the matrix pointer can be set to NULL, (in which case - the identity transform will be used). Coefficients of the matrix - are in 16.16 fixed float units. - -The vector pointer can also be set to NULL (in which case a delta - of (0,0) will be used). The vector coordinates are expressed in - 1/64th of a pixel (also known as 26.6 fixed floats). - -NOTA BENE: The transform is applied every glyph that is loaded - through FT_Load_Glyph. Note that loading a glyph bitmap - with a non-trivial transform will produce an error.. - -- - - 7. Accessing glyph image data -- -Glyph image data is accessible through face->glyph. - See the definition of the FT_GlyphSlot type for more details. - As stated previously, each face has a single glyph slot, where - one glyph image at a time can be loaded. Each time - you call FT_Load_Glyph(), you erase the content of the glyph - slot with a new glyph image. - -Note however that the glyph slot object itself doesn't change, only - its content, which means that you can perfectly create a "shortcut" to - access it as in - - -
- {
- /* shortcut to glyph slot */
- FT_GlyphSlot glyph = face->glyph;
-
- for ( n = 0; n < face->num_glyphs; n++ )
- {
- ... load glyph n ...
- ... access glyph data as glyph->xxxx
- }
- }
-
-
- The glyph variable will be valid until its parent - face is destroyed. Here are a few important fields of the - glyph slot: - -
- 8. Rendering glyph outlines into bitmaps -- -You can easily test the format of the glyph image by inspecting the - face->glyph->format variable. If its value is - ft_glyph_format_bitmap, the glyph image that was loaded is a - bitmap that can be directly blit to your own surfaces through your - favorite graphics library (FreeType 2 doesn't provide bitmap - blitting routines, as you may imagine :-) - -If the format is ft_glyph_format_outline or something else, - the library provides a means to convert such glyph images to bitmaps - through what are called rasters. - -On the other hand, if the image is a scalable outline or something - else, FreeType provides a function to convert the glyph image into a - pre-existing bitmap that you will handle to it, named - FT_Get_Glyph_Bitmap. Here's a simple example code - that renders an outline into a monochrome bitmap: - - -
- {
- FT_GlyphSlot glyph;
-
- ... load glyph ...
-
- glyph = face->glyph; /* shortcut to glyph data */
- if ( glyph->format == ft_glyph_format_outline )
- {
- FT_Bitmap bit;
-
- /* set-up a bitmap descriptor for our target bitmap */
- bit.rows = bitmap_height;
- bit.width = bitmap_width;
- bit.pitch = bitmap_row_bytes;
- /* render into a mono bitmap */
- bit.pixel_mode = ft_pixel_mode_mono;
- bit.buffer = bitmap_buffer;
-
- /* render the outline directly into the bitmap */
- error = FT_Get_Glyph_Bitmap( face, &bit );
- if ( error ) { ... }
- }
- }
-
-
- You should note that FT_Get_Glyph_Bitmap() doesn't - create the bitmap. It only needs a descriptor, of type - FT_Bitmap, and writes directly into it. - -Note that the FreeType scan-converter for outlines can also generate - anti-aliased glyph bitmaps with 128 level of grays. For now, it is - restricted to rendering to 8-bit gray-level bitmaps, though this may - change in the future. Here is some code to do just that: - - -
- {
- FT_GlyphSlot glyph;
-
- ... load glyph ...
-
- glyph = face->glyph; /* shortcut to glyph data */
- if ( glyph->format == ft_glyph_format_outline )
- {
- FT_Bitmap bit;
-
- /* set-up a bitmap descriptor for our target bitmap */
- bit.rows = bitmap_height;
- bit.width = bitmap_width;
- bit.pitch = bitmap_row_bytes;
- /* 8-bit gray-level bitmap */
- bit.pixel_mode = ft_pixel_mode_gray;
- /* MUST be 128 for now */
- bit.grays = 128;
- bit.buffer = bitmap_buffer;
-
- /* clean the bitmap - IMPORTANT */
- memset( bit.buffer, 0, bit.rows*bit.pitch );
-
- /* render the outline directly into the bitmap */
- error = FT_Get_Glyph_Bitmap( face, &bit );
- if ( error ) { ... }
- }
- }
-
-
- You will notice that - -
|