[ft] The docs confused me + Set_Char_Size behaviour

[Massimo DZ8]

Dear Freetype developers,

>From the documentation (I found it a little dispersive I have to say)
http://www.freetype.org/freetype2/docs/tutorial/step1.html
5. Setting the current pixel size

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.

When a new face object is created, all elements are set to 0 during initialization. To populate the structure with sensible values, simply call FT_Set_Char_Size. Here is an example where the character size is set to 16pt for a 300×300dpi device:

...

A value of 0 for the horizontal resolution means ‘same as vertical resolution’, a value of 0 for the vertical resolution means ‘same as horizontal resolution’. If both values are zero, 72 dpi is used for both dimensions.

I am sure this doesn't happen here. I suppose the two calls should give the same results (I have the feeling I still haven't got the terminology right):

FT_Set_Char_Size(face, 72 * 64, 72 * 64, 300, 300 ); (A)
FT_Set_Char_Size(face,  0 * 64,  0 * 64, 300, 300 ); (B)

(B) results in glyphs being rendered at far different size. For example, '+' using (A) delivers 172x171. Using (B) the result is 3x3. It seems mixing (like in the example) causes no problems.

So the questions:
1- Am I understanding the docs correctly? Is there anyone working on the docs? For example, I see some references to FT_RENDER_MODE_DEFAULT, which one guesses to be _NORMAL, but anyway, I had some trouble grasping the lib.

2- What's the rationale of the automatically created size object and the FT_FaceRect::size pointer? If the goal is to just avoid a call to FT_New_Size could the doc put more emphasis on the fact the automatically created size object is unusable? Is it meant to be the active size for the font face or just a nice place to store a Size object?


Thank you,
Massimo