minhngoc25a
/
freetype2
mirror of git://git.savannah.gnu.org/freetype/freetype2.git
2
1
Fork 2
Code Issues 4 Releases Wiki Activity

Introduce `@example:' subsections.

This commit is contained in:
Werner Lemberg 2018-06-18 10:08:17 +02:00
parent fc40469a6f
commit 877d80944b
5 changed files with 104 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
include/freetype/freetype.h
View File

@ -2391,6 +2391,7 @@ FT_BEGIN_HEADER
* See the discussion of reference counters in the description of * See the discussion of reference counters in the description of
* @FT_Reference_Face. * @FT_Reference_Face.
* *
* @example:
* To loop over all faces, use code similar to the following snippet * To loop over all faces, use code similar to the following snippet
* (omitting the error handling). * (omitting the error handling).
* *
@ -4008,7 +4009,7 @@ FT_BEGIN_HEADER
* @return: * @return:
* FreeType error code. 0~means success. * FreeType error code. 0~means success.
* *
* @note: * @example:
* Here an example that sets three properties. You must define * Here an example that sets three properties. You must define
* FT_CONFIG_OPTION_SUBPIXEL_RENDERING to make the LCD filter examples * FT_CONFIG_OPTION_SUBPIXEL_RENDERING to make the LCD filter examples
* work. * work.

178
include/freetype/ftdriver.h
View File

@ -371,6 +371,13 @@ FT_BEGIN_HEADER
* `freetype' if T1_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe' * `freetype' if T1_CONFIG_OPTION_OLD_ENGINE is defined, and `adobe'
* otherwise. * otherwise.
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values `adobe' or `freetype').
*
* @example:
* The following example code demonstrates how to select Adobe's hinting * The following example code demonstrates how to select Adobe's hinting
* engine for the `cff' module (omitting the error handling). * engine for the `cff' module (omitting the error handling).
* *
@ -385,12 +392,6 @@ FT_BEGIN_HEADER
* "hinting-engine", &hinting_engine ); * "hinting-engine", &hinting_engine );
* } * }
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values `adobe' or `freetype').
*
* @since: * @since:
* 2.4.12 (for `cff' module) * 2.4.12 (for `cff' module)
* *
@ -442,6 +443,15 @@ FT_BEGIN_HEADER
* Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is * Note that stem darkening is never applied if @FT_LOAD_NO_SCALE is
* set. * set.
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values 1 and 0 for `on' and `off', respectively).
* It can also be set per face using @FT_Face_Properties with
* @FT_PARAM_TAG_STEM_DARKENING.
*
* @example:
* { * {
* FT_Library library; * FT_Library library;
* FT_Bool no_stem_darkening = TRUE; * FT_Bool no_stem_darkening = TRUE;
@ -453,14 +463,6 @@ FT_BEGIN_HEADER
* "no-stem-darkening", &no_stem_darkening ); * "no-stem-darkening", &no_stem_darkening );
* } * }
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values 1 and 0 for `on' and `off', respectively).
* It can also be set per face using @FT_Face_Properties with
* @FT_PARAM_TAG_STEM_DARKENING.
*
* @since: * @since:
* 2.4.12 (for `cff' module) * 2.4.12 (for `cff' module)
* *
@ -492,22 +494,8 @@ FT_BEGIN_HEADER
* control points can be set with the macro * control points can be set with the macro
* `CFF_CONFIG_OPTION_DARKENING_PARAMETERS'; the CFF, Type~1, and CID * `CFF_CONFIG_OPTION_DARKENING_PARAMETERS'; the CFF, Type~1, and CID
* drivers share these values. At runtime, the control points can be * drivers share these values. At runtime, the control points can be
* changed using the `darkening-parameters' property, as the following * changed using the `darkening-parameters' property (see the example
* example demonstrates for the Type~1 driver. * below that demonstrates this for the Type~1 driver).
*
* {
* FT_Library library;
* FT_Int darken_params[8] = { 500, 300, // x1, y1
* 1000, 200, // x2, y2
* 1500, 100, // x3, y3
* 2000, 0 }; // x4, y4
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "type1",
* "darkening-parameters", darken_params );
* }
* *
* The x~values give the stem width, and the y~values the darkening * The x~values give the stem width, and the y~values the darkening
* amount. The unit is 1000th of pixels. All coordinate values must be * amount. The unit is 1000th of pixels. All coordinate values must be
@ -531,6 +519,21 @@ FT_BEGIN_HEADER
* type1:darkening-parameters=500,300,1000,200,1500,100,2000,0 * type1:darkening-parameters=500,300,1000,200,1500,100,2000,0
* } * }
* *
* @example:
* {
* FT_Library library;
* FT_Int darken_params[8] = { 500, 300, // x1, y1
* 1000, 200, // x2, y2
* 1500, 100, // x3, y3
* 2000, 0 }; // x4, y4
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "type1",
* "darkening-parameters", darken_params );
* }
*
* @since: * @since:
* 2.5.1 (for `cff' module) * 2.5.1 (for `cff' module)
* *
@ -594,6 +597,13 @@ FT_BEGIN_HEADER
* *
* If `no-long-family-names' is set, this feature gets switched off. * If `no-long-family-names' is set, this feature gets switched off.
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values 1 and 0 for `on' and `off', respectively).
*
* @example:
* { * {
* FT_Library library; * FT_Library library;
* FT_Bool no_long_family_names = TRUE; * FT_Bool no_long_family_names = TRUE;
@ -606,12 +616,6 @@ FT_BEGIN_HEADER
* &no_long_family_names ); * &no_long_family_names );
* } * }
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values 1 and 0 for `on' and `off', respectively).
*
* @since: * @since:
* 2.8 * 2.8
*/ */
@ -778,6 +782,13 @@ FT_BEGIN_HEADER
* chosen interpreter, it simply ignores instructions on vertical stems * chosen interpreter, it simply ignores instructions on vertical stems
* to arrive at very similar results. * to arrive at very similar results.
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values `35', `38', or `40').
*
* @example:
* The following example code demonstrates how to deactivate subpixel * The following example code demonstrates how to deactivate subpixel
* hinting (omitting the error handling). * hinting (omitting the error handling).
* *
@ -794,12 +805,6 @@ FT_BEGIN_HEADER
* &interpreter_version ); * &interpreter_version );
* } * }
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* This property can be set via the `FREETYPE_PROPERTIES' environment
* variable (using values `35', `38', or `40').
*
* @since: * @since:
* 2.5 * 2.5
*/ */
@ -834,6 +839,7 @@ FT_BEGIN_HEADER
* the auto-hinter so that the global analysis of the font shapes * the auto-hinter so that the global analysis of the font shapes
* actually uses the modified mapping. * actually uses the modified mapping.
* *
* @example:
* The following example code demonstrates how to access it (omitting * The following example code demonstrates how to access it (omitting
* the error handling). * the error handling).
* *
@ -1026,17 +1032,6 @@ FT_BEGIN_HEADER
* @FT_AUTOHINTER_SCRIPT_CJK. Using the `fallback-script' property, * @FT_AUTOHINTER_SCRIPT_CJK. Using the `fallback-script' property,
* this fallback value can be changed. * this fallback value can be changed.
* *
* {
* FT_Library library;
* FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "autofitter",
* "fallback-script", &fallback_script );
* }
*
* @note: * @note:
* This property can be used with @FT_Property_Get also. * This property can be used with @FT_Property_Get also.
* *
@ -1048,6 +1043,18 @@ FT_BEGIN_HEADER
* an @FT_Face structure but not loaded any glyph (using the * an @FT_Face structure but not loaded any glyph (using the
* auto-hinter), a change of the fallback script will affect this face. * auto-hinter), a change of the fallback script will affect this face.
* *
* @example:
* {
* FT_Library library;
* FT_UInt fallback_script = FT_AUTOHINTER_SCRIPT_NONE;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "autofitter",
* "fallback-script", &fallback_script );
* }
*
* @since: * @since:
* 2.4.11 * 2.4.11
* *
@ -1074,17 +1081,6 @@ FT_BEGIN_HEADER
* By default, this is @FT_AUTOHINTER_SCRIPT_LATIN. Using the * By default, this is @FT_AUTOHINTER_SCRIPT_LATIN. Using the
* `default-script' property, this default value can be changed. * `default-script' property, this default value can be changed.
* *
* {
* FT_Library library;
* FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "autofitter",
* "default-script", &default_script );
* }
*
* @note: * @note:
* This property can be used with @FT_Property_Get also. * This property can be used with @FT_Property_Get also.
* *
@ -1096,6 +1092,18 @@ FT_BEGIN_HEADER
* an @FT_Face structure but not loaded any glyph (using the * an @FT_Face structure but not loaded any glyph (using the
* auto-hinter), a change of the default script will affect this face. * auto-hinter), a change of the default script will affect this face.
* *
* @example:
* {
* FT_Library library;
* FT_UInt default_script = FT_AUTOHINTER_SCRIPT_NONE;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "autofitter",
* "default-script", &default_script );
* }
*
* @since: * @since:
* 2.5.3 * 2.5.3
* *
@ -1114,6 +1122,13 @@ FT_BEGIN_HEADER
* this property to improve the legibility of small font sizes if * this property to improve the legibility of small font sizes if
* necessary. * necessary.
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* Set this value right after calling @FT_Set_Char_Size, but before
* loading any glyph (using the auto-hinter).
*
* @example:
* { * {
* FT_Library library; * FT_Library library;
* FT_Face face; * FT_Face face;
@ -1131,12 +1146,6 @@ FT_BEGIN_HEADER
* "increase-x-height", &prop ); * "increase-x-height", &prop );
* } * }
* *
* @note:
* This property can be used with @FT_Property_Get also.
*
* Set this value right after calling @FT_Set_Char_Size, but before
* loading any glyph (using the auto-hinter).
*
* @since: * @since:
* 2.4.11 * 2.4.11
* *
@ -1179,20 +1188,7 @@ FT_BEGIN_HEADER
* To find out a glyph's optimal scaling and shifting value, various * To find out a glyph's optimal scaling and shifting value, various
* parameter combinations are tried and scored. * parameter combinations are tried and scored.
* *
* By default, warping is off. The example below shows how to switch on * By default, warping is off.
* warping (omitting the error handling).
*
* {
* FT_Library library;
* FT_Bool warping = 1;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "autofitter",
* "warping", &warping );
* }
*
* @note: * @note:
* This property can be used with @FT_Property_Get also. * This property can be used with @FT_Property_Get also.
* *
@ -1207,6 +1203,20 @@ FT_BEGIN_HEADER
* change its value before rendering any face. Otherwise, you should * change its value before rendering any face. Otherwise, you should
* reload all faces that get auto-hinted in `normal' hinting mode. * reload all faces that get auto-hinted in `normal' hinting mode.
* *
* @example:
* This example shows how to switch on warping (omitting the error
* handling).
*
* {
* FT_Library library;
* FT_Bool warping = 1;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "autofitter", "warping", &warping );
* }
*
* @since: * @since:
* 2.6 * 2.6
* *

4
include/freetype/ftmac.h
View File

@ -92,12 +92,12 @@ FT_BEGIN_HEADER
* @return: * @return:
* FreeType error code. 0~means success. * FreeType error code. 0~means success.
* *
* @note: * @example:
* This function can be used to create @FT_Face objects from fonts * This function can be used to create @FT_Face objects from fonts
* that are installed in the system as follows. * that are installed in the system as follows.
* *
* { * {
* fond = GetResource( 'FOND', fontName ); * fond = GetResource( 'FOND', fontName );
* error = FT_New_Face_From_FOND( library, fond, 0, &face ); * error = FT_New_Face_From_FOND( library, fond, 0, &face );
* } * }
*/ */

7
include/freetype/ftoutln.h
View File

@ -376,16 +376,17 @@ FT_BEGIN_HEADER
* If you need `better' metrics values you should call * If you need `better' metrics values you should call
* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. * @FT_Outline_Get_CBox or @FT_Outline_Get_BBox.
* *
* Example call: * To get meaningful results, font scaling values must be set with
* functions like @FT_Set_Char_Size before calling FT_Render_Glyph.
* *
* @example:
* { * {
* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); * FT_Load_Glyph( face, index, FT_LOAD_DEFAULT );
*
* if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) * if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE )
* FT_Outline_Embolden( &face->glyph->outline, strength ); * FT_Outline_Embolden( &face->glyph->outline, strength );
* } * }
* *
* To get meaningful results, font scaling values must be set with
* functions like @FT_Set_Char_Size before calling FT_Render_Glyph.
*/ */
FT_EXPORT( FT_Error ) FT_EXPORT( FT_Error )
FT_Outline_Embolden( FT_Outline* outline, FT_Outline_Embolden( FT_Outline* outline,

3
include/freetype/tttables.h
View File

@ -719,7 +719,8 @@ FT_BEGIN_HEADER
* by the sfnt, truetype, and opentype drivers. See @FT_Sfnt_Tag for * by the sfnt, truetype, and opentype drivers. See @FT_Sfnt_Tag for
* a list. * a list.
* *
* Here an example how to access the `vhea' table: * @example:
* Here an example how to access the `vhea' table.
* *
* { * {
* TT_VertHeader* vert_header; * TT_VertHeader* vert_header;