Re: [Freetype] Errors (and problems) in the documentation

[David Turner]

Hello Peter,

Peter Montgomery a écrit :
> 
> Hi,
> 
>     I am just starting to use FreeType 2.0.4 (yes, I know 2.0.5 is out,
> but I already had 2.0.4 working on my system.  I used the tutorial part
> one and got working text rendering working.  However, part 2 of the
> tutorial is another matter.  I encountered a number of errors in the
> sample code in the tutorial.  Here's a list:
> 
>  In the section on rendering using kerning and centering, the 3rd
> parameter is wrong.  It's shown as a pointer to a vector component, but
> it should be a pointer to a vector.
> 
>   error = FT_Glyph_To_Bitmap( &image,
>                 ft_render_mode_normal,
>                 &pen.x, // This should be "&pen", not "&pen.x"
>                 0 );
>
Yes, thanks for pointing this out :-)

 
> A little later, the mythical "my_draw_bitmap()" is called.  I'm not sure
> what all is going on here.  First, there is an FT_BitmapGlyph  created
> called "bit" which is never used.   Second, there is no such thing (that
> I can find) called an FT_BitmapGlyph .  There is an FT_BitmapGlyphRec.
> Is that what this is supposed to be?
>
Well, there is a FT_BitmapGlyph, it's a pointer to a FT_BitmapGlyphRec.
Have a look at the definition of this structure in the API reference.

It's true that the documentation didn't include a section for
FT_BitmapGlyph (or FT_Glyph and FT_OutlineGlyph) itself, and that
you cannot find it in the index. I just fixed that in the CVS..

 
> FT_BitmapGlyph  bit = (FT_BitmapGlyph)image;
> 
>           my_draw_bitmap( bitmap->bitmap,
>                           bitmap->left,
>                           my_target_height - bitmap->top );
> 
>           FT_Done_Glyph( image );
>
This should really read:

           my_draw_bitmap( bit->bitmap,
                           bit->left,
                           my_target_height - bit->top );

since we're accessing the FT_BitmapGlyphRec fields "left", "top" and
"bitmap".. sorry for the error..
 
> In the section on filling the glyph array, there is this line which has
> no terminating semi-colon:
> 
>   // record current glyph index
>   previous = glyph_index
>
Thanks :-)
 
> In the section on computing the Box, this line is missing the second
> parameter.  Since the parameter is quite critical, this is a very tricky
> omission.  I am assuming it should be "ft_glyph_bbox_subpixels" but that
> is just a guess.
> 
> FT_Glyph_Get_CBox( glyphs[n], &glyph_bbox );
>
it should read:

  FT_Glyph_Get_CBox( glyphs[n], ft_glyph_bbox_pixels, &glyph_bbox );

we're using integer pixels here. that's easy to guess because we're
later adding integer pixel position (the pos[n].x and pos[n].y values)
to the box's edges..

thanks for pointing this out..

 
> Later in the same routine is this line.  Notice that instead of a
> comparison, there is some strange characters.  It should say ">", not
> "&gy;".  Well, I think it should be ">", but then I'm just guessing
> based on the surrounding code:
> 
>   if (glyph_bbox.yMax &gy; bbox.yMax)
>    bbox.yMax = glyph_bbox.yMax;
>
Yep, it should be ">". This is fixed..

> So, this is all making it extremely hard to use the docs to actually
> create code that centers and kerns text.  As I mentioned before, I was
> able to use the sample code in tutorial 1 without any problems.  The 2nd
> tutorial is much harder due to the problems.  In fact, I still don't
> have it working.  I am quite confused by this section of the code that
> renders the text:
> 
> // compute string dimensions in integer pixels
>       string_width  = (string_bbox.xMax - string_bbox.xMin)/64;
>       string_height = (string_bbox.yMax - string_bbox.yMin)/64;
> 
>       // compute start pen position in 26.6 cartesian pixels
>       start_x = (( my_target_width  - string_width )/2)*64;
>       start_y = (( my_target_height - string_height)/2)*64;
> 
> 1 - I find no mention anywhere of what data type "string_width" is, nor
> "start_x".
>
some of this code is buggy too, it should read:

   // compute string dimensions in integer pixels
   string_width  = (string_bbox.xMax - string_bbox.xMin);
   string_height = (string_bbox.yMax - string_bbox.yMin);
 
   // compute start pen position in 26.6 cartesian pixels
   start_x = (( my_target_width  - string_width )/2)*64;
   start_y = (( my_target_height - string_height)/2)*64;

since the string bbox is computed in integer pixels. the dimensions
are integers, and the start coordinates are 32-bit numbers (use FT_Pos
for them..)

> 2 -  I just want to use the code to create the smallest bitmap with my
> text on it.  I intend to then BLT that onto a larger bitmap to create
> multiple sentences, etc.  How do I compute "start_x" and "start_y" then?
> 3 - What do I use for "my_target_width" and "my_target_height".  The
> values of "string_width" and "string_width"?
>
to do that:

  - compute "string_width" and "string_height" as above, and
    use the values to allocate a bitmap buffer of the corresponding
    dimensions..

  - use:
          start_x = -string_bbox.xMin*64;
          start_y = -string_bbox.yMin*64;

    for the start position

  - render the text into your string buffer
     

> I know there are sample projects.  However, they tend to be a lot more
> complicated and the way to use FreeType is lost in all the noise.
> Since the ability to kern and center text into the smallest bitmap
> possible are probably at the heart of all uses of FreeType, it seems
> that it's pretty important that these tutorials be accurate.  Can you
> shed some light here?
>
I don't know, I simply hope that the above comments and corrections will
help you succeed..

Cheers,

- David