Commit 08e2e311ef0d59e45f845fbd24cc20bea6e2e72d
2017-10-08T10:37:50
Document global size metrics needed for native bytecode hinting (#52165).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index 113f682..b4e6627 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -1063,6 +1063,9 @@ FT_BEGIN_HEADER
/* `descender', `height', `underline_position', and */
/* `underline_thickness'. */
/* */
+ /* Especially for TrueType fonts see also the documentation for */
+ /* @FT_Size_Metrics. */
+ /* */
typedef struct FT_FaceRec_
{
FT_Long num_faces;
@@ -1582,7 +1585,7 @@ FT_BEGIN_HEADER
/* to the following. */
/* */
/* { */
- /* scaled_ascender = FT_MulFix( face->root.ascender, */
+ /* scaled_ascender = FT_MulFix( face->ascender, */
/* size_metrics->y_scale ); */
/* } */
/* */
@@ -1596,6 +1599,43 @@ FT_BEGIN_HEADER
/* */
/* The `FT_Size_Metrics' structure is valid for bitmap fonts also. */
/* */
+ /* */
+ /* *TrueType* *fonts* *with* *native* *bytecode* *hinting* */
+ /* */
+ /* All applications that handle TrueType fonts with native hinting */
+ /* must be aware that TTFs expect different rounding of vertical font */
+ /* dimensions. The application has to cater for this, especially if */
+ /* it wants to rely on a TTF's vertical data (for example, to */
+ /* properly align box characters vertically). */
+ /* */
+ /* Only the application knows _in_ _advance_ that it is going to use */
+ /* native hinting for TTFs! FreeType, on the other hand, selects the */
+ /* hinting mode not at the time of creating an @FT_Size object but */
+ /* much later, namely while calling @FT_Load_Glyph. */
+ /* */
+ /* Here is some pseudo code that illustrates a possible solution. */
+ /* */
+ /* { */
+ /* font_format = FT_Get_Font_Format( face ); */
+ /* */
+ /* if ( !strcmp( font_format, "TrueType" ) && */
+ /* do_native_bytecode_hinting ) */
+ /* { */
+ /* ascender = ROUND( FT_MulFix( face->ascender, */
+ /* size_metrics->y_scale ) ); */
+ /* descender = ROUND( FT_MulFix( face->descender, */
+ /* size_metrics->y_scale ) ); */
+ /* } */
+ /* else */
+ /* { */
+ /* ascender = size_metrics->ascender; */
+ /* descender = size_metrics->descender; */
+ /* } */
+ /* */
+ /* height = size_metrics->height; */
+ /* max_advance = size_metrics->max_advance; */
+ /* } */
+ /* */
typedef struct FT_Size_Metrics_
{
FT_UShort x_ppem; /* horizontal pixels per EM */