ref: 99a940f84acb1c2adc0f66d3473b5aad14c7c61f
parent: 054782c48ef12988bc278a7667c9368bf74e50d0
author: Alexei Podtelezhnikov <apodtele@gmail.com>
date: Thu Jan 20 10:06:09 EST 2022
* include/freetype/freetype.h: Clarify `FT_Size` life cycle.
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -526,9 +526,11 @@
* functions like @FT_Load_Glyph to determine the scaling transformation
* that in turn is used to load and hint glyphs and metrics.
*
- * You can use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, @FT_Request_Size
+ * A newly created `FT_Size` object contains only meaningless zero values.
+ * You must use @FT_Set_Char_Size, @FT_Set_Pixel_Sizes, @FT_Request_Size
* or even @FT_Select_Size to change the content (i.e., the scaling
- * values) of the active `FT_Size`.
+ * values) of the active `FT_Size`. Otherwise, the scaling and hinting
+ * will not be performed.
*
* You can use @FT_New_Size to create additional size objects for a given
* @FT_Face, but they won't be used by other functions until you activate
@@ -2828,10 +2830,9 @@
*
* @note:
* For proper scaling and hinting, the active @FT_Size object owned by
- * the face has to be meaningfully non-trivially initialized by
- * calling @FT_Set_Char_Size before this function, for example.
- * The loaded glyph may be transformed. See @FT_Set_Transform for the
- * details.
+ * the face has to be meaningfully initialized by calling
+ * @FT_Set_Char_Size before this function, for example. The loaded
+ * glyph may be transformed. See @FT_Set_Transform for the details.
*
* For subsetted CID-keyed fonts, `FT_Err_Invalid_Argument` is returned
* for invalid CID values (this is, for CID values that don't have a