From 63e3c3b529558d159b05ce3019a55897a575e8a3 Mon Sep 17 00:00:00 2001 From: David Turner Date: Thu, 29 Jun 2000 00:39:30 +0000 Subject: [PATCH] some real updates to the tutorial, more to come soon --- docs/tutorial/index.html | 226 ++++++++++++++++++++++++++++----------- 1 file changed, 161 insertions(+), 65 deletions(-) diff --git a/docs/tutorial/index.html b/docs/tutorial/index.html index b09b696f8..fb8a5b3ae 100644 --- a/docs/tutorial/index.html +++ b/docs/tutorial/index.html @@ -321,20 +321,32 @@ 5. Setting the current pixel size -

A face object also holds a handle to a size object in its - face->size field. The size object is used to model - all information for the face that is relative to a given character - 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 horizontall 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.

+ 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:

+ example where the character size is set to 16pt for a 300x300 dpi + device:

@@ -351,12 +363,15 @@
     
    
       
  • 
         
    The character width and heights are specified in 1/64th of
-        points.
    
+        points. A point is a physical distance, equaling 1/72th
+	of an inch, it's not a pixel..
    
       
    • 
       
  • 
         
    The horizontal and vertical device resolutions are expressed in
         dots-per-inch, or dpi. You can use 72 or
-        96 dpi for display devices like the screen.
    
+        96 dpi for display devices like the screen. The resolution
+	is used to compute the character pixel size from the character
+	point size.
    
       
    • 
       
  • 
         
    A value of 0 for the character width means "same as
@@ -368,6 +383,10 @@
         
    Using a value of 0 for the horizontal or vertical resolution means
         72 dpi, which is the default.
    
       
    • 
+      
  • 
+        
    The first argument is a handle to a face object, not a size
+	   object. That's normal, and must be seen as a convenience.
    
+      
    • 
     

 
     
This function computes the character pixel size that corresponds to
@@ -475,45 +494,62 @@
 
       
The load_flags value is a set of bit flags used to
       indicate some special operations.  The default value
-      FT_LOAD_DEFAULT is 0.  The function performs the
-      following:

-
+      FT_LOAD_DEFAULT is 0.

+      
+      
This function will try to load the corresponding glyph image
+         from the face. Basically, this means that:

+	 
       
    
         
  • 
-          
    If there is a bitmap for the corresponding glyph and size, load
-          it in the glyph slot, unless the FT_LOAD_NO_BITMAP flag
-          is set.  This is even true for scalable formats (embedded
-          bitmaps are favored over outlines as they usually correspond to
-          higher-quality images of the same glyph).
    
-        
    • 
-        
  • 
-          
    If there is a glyph image in another format (e.g. a vectorial
-          outline), load it in the glyph slot.  Then, scale it to the
-          current size, unless the FT_LOAD_NO_SCALE flag is
-          set.
    
-        
    • 
-        
  • 
-          
    If the glyph image was loaded and scaled, try to grid-fit it
-          (which dramatically improves its quality) unless the flag
-          FT_LOAD_NO_HINTING is set.
    
-        
    • 
-        
  • 
-          
    If the glyph image is scalable, transform it through the
-          current transform (which can be set with
-          FT_Set_Transform()).
    
-        
    • 
-        
  • 
-          
    Finally, if the FT_LOAD_RENDER flag is set, convert
-          the glyph image into a bitmap.  By default, this means a 1-bit
-          monochrome bitmap, unless FT_LOAD_ANTI_ALIAS is set,
-          in which case an 8-bit 256-gray-levels anti-aliased bitmap is
-          generated.
    
+	  
    If a bitmap is found for the corresponding glyph and pixel
+	     size, it will in the slot (embedded bitmaps are always
+	     favored over native image formats, because we assume that
+	     they are higher-quality versions of the same image. This
+	     can be ignored by using the FT_LOAD_NO_BITMAP flag)
    
+	
    • 
+	
+	
  • 
+	  
    Otherwise, a native image for the glyph will be loaded.
+	     It will also be scaled to the current pixel size, as
+	     well as hinted for certain formats like TrueType and
+	     Type1.
    
         
    • 
       

+      
+      
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:

 
-      
There are a few others FT_LOAD_xxx flags defined.  For
-      more details see the FreeType 2 API
-      Reference.

+      
+      
+   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
@@ -526,25 +562,46 @@
       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).

-    
-      
The fields face->num_charmaps and
-      face->charmaps (notice the `s') can be used by client
-      applications to check which charmaps are available in a given
-      face.

 
-      
face->charmaps is an array of pointers to
-      the face->num_charmaps charmaps contained in the font
-      face.

+      
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 charmap has a few visible fields used to describe it in more
-      detail.  For example, charmap->encoding is an
-      enumeration type that describes the charmap with FreeType codes.  One
-      can also look at charmap->platform_id and
-      charmap->encoding_id for more exotic needs.

-
-      
Here's an example code that looks for a Chinese Big 5 charmap,
-      then selects it via FT_Set_CharMap():

+      
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;
@@ -554,7 +611,8 @@
     for ( n = 0; n < face->num_charmaps; n++ )
     {
       charmap = face->charmaps[n];
-      if ( charmap->encoding == ft_encoding_big5 )
+      if ( charmap->platform_id == my_platform_id &&
+           charmap->encoding_id == my_encoding_id )
       {
         found = charmap;
         break;
@@ -568,9 +626,47 @@
     if ( error ) { ... }

       
 
-      
One might now call FT_Get_Char_Index() with Big 5
-      character codes to retrieve glyph indices.

+     
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..

+