summaryrefslogtreecommitdiff
path: root/Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h')
-rw-r--r--Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h278
1 files changed, 240 insertions, 38 deletions
diff --git a/Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h b/Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h
index f6c66b94aee..aa1a4fe3891 100644
--- a/Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h
+++ b/Build/source/libs/freetype2/freetype-src/include/freetype/freetype.h
@@ -4,7 +4,7 @@
*
* FreeType high-level API and common types (specification only).
*
- * Copyright (C) 1996-2021 by
+ * Copyright (C) 1996-2022 by
* David Turner, Robert Wilhelm, and Werner Lemberg.
*
* This file is part of the FreeType project, and may only be used,
@@ -153,6 +153,9 @@ FT_BEGIN_HEADER
* FT_FACE_FLAG_GLYPH_NAMES
* FT_FACE_FLAG_EXTERNAL_STREAM
* FT_FACE_FLAG_HINTER
+ * FT_FACE_FLAG_SVG
+ * FT_FACE_FLAG_SBIX
+ * FT_FACE_FLAG_SBIX_OVERLAY
*
* FT_HAS_HORIZONTAL
* FT_HAS_VERTICAL
@@ -161,6 +164,9 @@ FT_BEGIN_HEADER
* FT_HAS_GLYPH_NAMES
* FT_HAS_COLOR
* FT_HAS_MULTIPLE_MASTERS
+ * FT_HAS_SVG
+ * FT_HAS_SBIX
+ * FT_HAS_SBIX_OVERLAY
*
* FT_IS_SFNT
* FT_IS_SCALABLE
@@ -225,6 +231,7 @@ FT_BEGIN_HEADER
* FT_LOAD_NO_SCALE
* FT_LOAD_NO_HINTING
* FT_LOAD_NO_BITMAP
+ * FT_LOAD_SBITS_ONLY
* FT_LOAD_NO_AUTOHINT
* FT_LOAD_COLOR
*
@@ -522,13 +529,15 @@ FT_BEGIN_HEADER
* size.
*
* @note:
- * An @FT_Face has one _active_ @FT_Size object that is used by functions
- * like @FT_Load_Glyph to determine the scaling transformation that in
- * turn is used to load and hint glyphs and metrics.
+ * An @FT_Face has one _active_ `FT_Size` object that is used by
+ * 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
@@ -1228,6 +1237,19 @@ FT_BEGIN_HEADER
* altered with @FT_Set_MM_Design_Coordinates,
* @FT_Set_Var_Design_Coordinates, or @FT_Set_Var_Blend_Coordinates.
* This flag is unset by a call to @FT_Set_Named_Instance.
+ *
+ * FT_FACE_FLAG_SVG ::
+ * [Since 2.12] The face has an 'SVG~' OpenType table.
+ *
+ * FT_FACE_FLAG_SBIX ::
+ * [Since 2.12] The face has an 'sbix' OpenType table *and* outlines.
+ * For such fonts, @FT_FACE_FLAG_SCALABLE is not set by default to
+ * retain backward compatibility.
+ *
+ * FT_FACE_FLAG_SBIX_OVERLAY ::
+ * [Since 2.12] The face has an 'sbix' OpenType table where outlines
+ * should be drawn on top of bitmap strikes.
+ *
*/
#define FT_FACE_FLAG_SCALABLE ( 1L << 0 )
#define FT_FACE_FLAG_FIXED_SIZES ( 1L << 1 )
@@ -1245,6 +1267,9 @@ FT_BEGIN_HEADER
#define FT_FACE_FLAG_TRICKY ( 1L << 13 )
#define FT_FACE_FLAG_COLOR ( 1L << 14 )
#define FT_FACE_FLAG_VARIATION ( 1L << 15 )
+#define FT_FACE_FLAG_SVG ( 1L << 16 )
+#define FT_FACE_FLAG_SBIX ( 1L << 17 )
+#define FT_FACE_FLAG_SBIX_OVERLAY ( 1L << 18 )
/**************************************************************************
@@ -1487,6 +1512,124 @@ FT_BEGIN_HEADER
/**************************************************************************
*
+ * @macro:
+ * FT_HAS_SVG
+ *
+ * @description:
+ * A macro that returns true whenever a face object contains an 'SVG~'
+ * OpenType table.
+ *
+ * @since:
+ * 2.12
+ */
+#define FT_HAS_SVG( face ) \
+ ( !!( (face)->face_flags & FT_FACE_FLAG_SVG ) )
+
+
+ /**************************************************************************
+ *
+ * @macro:
+ * FT_HAS_SBIX
+ *
+ * @description:
+ * A macro that returns true whenever a face object contains an 'sbix'
+ * OpenType table *and* outline glyphs.
+ *
+ * Currently, FreeType only supports bitmap glyphs in PNG format for this
+ * table (i.e., JPEG and TIFF formats are unsupported, as are
+ * Apple-specific formats not part of the OpenType specification).
+ *
+ * @note:
+ * For backward compatibility, a font with an 'sbix' table is treated as
+ * a bitmap-only face. Using @FT_Open_Face with
+ * @FT_PARAM_TAG_IGNORE_SBIX, an application can switch off 'sbix'
+ * handling so that the face is treated as an ordinary outline font with
+ * scalable outlines.
+ *
+ * Here is some pseudo code that roughly illustrates how to implement
+ * 'sbix' handling according to the OpenType specification.
+ *
+ * ```
+ * if ( FT_HAS_SBIX( face ) )
+ * {
+ * // open font as a scalable one without sbix handling
+ * FT_Face face2;
+ * FT_Parameter param = { FT_PARAM_TAG_IGNORE_SBIX, NULL };
+ * FT_Open_Args args = { FT_OPEN_PARAMS | ...,
+ * ...,
+ * 1, &param };
+ *
+ *
+ * FT_Open_Face( library, &args, 0, &face2 );
+ *
+ * <sort `face->available_size` as necessary into
+ * `preferred_sizes`[*]>
+ *
+ * for ( i = 0; i < face->num_fixed_sizes; i++ )
+ * {
+ * size = preferred_sizes[i].size;
+ *
+ * error = FT_Set_Pixel_Sizes( face, size, size );
+ * <error handling omitted>
+ *
+ * // check whether we have a glyph in a bitmap strike
+ * error = FT_Load_Glyph( face,
+ * glyph_index,
+ * FT_LOAD_SBITS_ONLY |
+ * FT_LOAD_BITMAP_METRICS_ONLY );
+ * if ( error == FT_Err_Invalid_Argument )
+ * continue;
+ * else if ( error )
+ * <other error handling omitted>
+ * else
+ * break;
+ * }
+ *
+ * if ( i != face->num_fixed_sizes )
+ * <load embedded bitmap with `FT_Load_Glyph`,
+ * scale it, display it, etc.>
+ *
+ * if ( i == face->num_fixed_sizes ||
+ * FT_HAS_SBIX_OVERLAY( face ) )
+ * <use `face2` to load outline glyph with `FT_Load_Glyph`,
+ * scale it, display it on top of the bitmap, etc.>
+ * }
+ * ```
+ *
+ * [*] Assuming a target value of 400dpi and available strike sizes 100,
+ * 200, 300, and 400dpi, a possible order might be [400, 200, 300, 100]:
+ * scaling 200dpi to 400dpi usually gives better results than scaling
+ * 300dpi to 400dpi; it is also much faster. However, scaling 100dpi to
+ * 400dpi can yield a too pixelated result, thus the preference might be
+ * 300dpi over 100dpi.
+ *
+ * @since:
+ * 2.12
+ */
+#define FT_HAS_SBIX( face ) \
+ ( !!( (face)->face_flags & FT_FACE_FLAG_SBIX ) )
+
+
+ /**************************************************************************
+ *
+ * @macro:
+ * FT_HAS_SBIX_OVERLAY
+ *
+ * @description:
+ * A macro that returns true whenever a face object contains an 'sbix'
+ * OpenType table with bit~1 in its `flags` field set, instructing the
+ * application to overlay the bitmap strike with the corresponding
+ * outline glyph. See @FT_HAS_SBIX for pseudo code how to use it.
+ *
+ * @since:
+ * 2.12
+ */
+#define FT_HAS_SBIX_OVERLAY( face ) \
+ ( !!( (face)->face_flags & FT_FACE_FLAG_SBIX_OVERLAY ) )
+
+
+ /**************************************************************************
+ *
* @enum:
* FT_STYLE_FLAG_XXX
*
@@ -2702,8 +2845,8 @@ FT_BEGIN_HEADER
* 'https://www.freetype.org/freetype2/docs/glyphs/glyphs-2.html'.
*
* Contrary to @FT_Set_Char_Size, this function doesn't have special code
- * to normalize zero-valued widths, heights, or resolutions (which lead
- * to errors in most cases).
+ * to normalize zero-valued widths, heights, or resolutions, which are
+ * treated as @FT_LOAD_NO_SCALE.
*
* Don't use this function if you are using the FreeType cache API.
*/
@@ -2819,7 +2962,7 @@ FT_BEGIN_HEADER
*
* load_flags ::
* A flag indicating what to load for this glyph. The @FT_LOAD_XXX
- * constants can be used to control the glyph loading process (e.g.,
+ * flags can be used to control the glyph loading process (e.g.,
* whether the outline should be scaled, whether to load bitmaps or
* not, whether to hint the outline, etc).
*
@@ -2827,8 +2970,10 @@ FT_BEGIN_HEADER
* FreeType error code. 0~means success.
*
* @note:
- * The loaded glyph may be transformed. See @FT_Set_Transform for the
- * details.
+ * For proper scaling and hinting, the active @FT_Size object owned by
+ * 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
@@ -2918,6 +3063,8 @@ FT_BEGIN_HEADER
*
* FT_LOAD_NO_SCALE ::
* Don't scale the loaded outline glyph but keep it in font units.
+ * This flag is also assumed if @FT_Size owned by the face was not
+ * properly initialized.
*
* This flag implies @FT_LOAD_NO_HINTING and @FT_LOAD_NO_BITMAP, and
* unsets @FT_LOAD_RENDER.
@@ -2948,6 +3095,15 @@ FT_BEGIN_HEADER
*
* @FT_LOAD_NO_SCALE always sets this flag.
*
+ * FT_LOAD_SBITS_ONLY ::
+ * [Since 2.12] This is the opposite of @FT_LOAD_NO_BITMAP, more or
+ * less: @FT_Load_Glyph returns `FT_Err_Invalid_Argument` if the face
+ * contains a bitmap strike for the given size (or the strike selected
+ * by @FT_Select_Size) but there is no glyph in the strike.
+ *
+ * Note that this load flag was part of FreeType since version 2.0.6
+ * but previously tagged as internal.
+ *
* FT_LOAD_VERTICAL_LAYOUT ::
* Load the glyph for vertical text layout. In particular, the
* `advance` value in the @FT_GlyphSlotRec structure is set to the
@@ -3004,21 +3160,31 @@ FT_BEGIN_HEADER
* Disable the auto-hinter. See also the note below.
*
* FT_LOAD_COLOR ::
- * Load colored glyphs. There are slight differences depending on the
- * font format.
- *
- * [Since 2.5] Load embedded color bitmap images. The resulting color
- * bitmaps, if available, will have the @FT_PIXEL_MODE_BGRA format,
- * with pre-multiplied color channels. If the flag is not set and
- * color bitmaps are found, they are converted to 256-level gray
- * bitmaps, using the @FT_PIXEL_MODE_GRAY format.
- *
- * [Since 2.10, experimental] If the glyph index contains an entry in
+ * Load colored glyphs. FreeType searches in the following order;
+ * there are slight differences depending on the font format.
+ *
+ * [Since 2.5] Load embedded color bitmap images (provided
+ * @FT_LOAD_NO_BITMAP is not set). The resulting color bitmaps, if
+ * available, have the @FT_PIXEL_MODE_BGRA format, with pre-multiplied
+ * color channels. If the flag is not set and color bitmaps are found,
+ * they are converted to 256-level gray bitmaps, using the
+ * @FT_PIXEL_MODE_GRAY format.
+ *
+ * [Since 2.12] If the glyph index maps to an entry in the face's
+ * 'SVG~' table, load the associated SVG document from this table and
+ * set the `format` field of @FT_GlyphSlotRec to @FT_GLYPH_FORMAT_SVG.
+ * Note that FreeType itself can't render SVG documents; however, the
+ * library provides hooks to seamlessly integrate an external renderer.
+ * See sections @ot_svg_driver and @svg_fonts for more.
+ *
+ * [Since 2.10, experimental] If the glyph index maps to an entry in
* the face's 'COLR' table with a 'CPAL' palette table (as defined in
* the OpenType specification), make @FT_Render_Glyph provide a default
* blending of the color glyph layers associated with the glyph index,
* using the same bitmap format as embedded color bitmap images. This
- * is mainly for convenience; for full control of color layers use
+ * is mainly for convenience and works only for glyphs in 'COLR' v0
+ * tables (or glyphs in 'COLR' v1 tables that exclusively use v0
+ * features). For full control of color layers use
* @FT_Get_Color_Glyph_Layer and FreeType's color functions like
* @FT_Palette_Select instead of setting @FT_LOAD_COLOR for rendering
* so that the client application can handle blending by itself.
@@ -3069,19 +3235,20 @@ FT_BEGIN_HEADER
*
*/
#define FT_LOAD_DEFAULT 0x0
-#define FT_LOAD_NO_SCALE ( 1L << 0 )
-#define FT_LOAD_NO_HINTING ( 1L << 1 )
-#define FT_LOAD_RENDER ( 1L << 2 )
-#define FT_LOAD_NO_BITMAP ( 1L << 3 )
-#define FT_LOAD_VERTICAL_LAYOUT ( 1L << 4 )
-#define FT_LOAD_FORCE_AUTOHINT ( 1L << 5 )
-#define FT_LOAD_CROP_BITMAP ( 1L << 6 )
-#define FT_LOAD_PEDANTIC ( 1L << 7 )
-#define FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ( 1L << 9 )
+#define FT_LOAD_NO_SCALE ( 1L << 0 )
+#define FT_LOAD_NO_HINTING ( 1L << 1 )
+#define FT_LOAD_RENDER ( 1L << 2 )
+#define FT_LOAD_NO_BITMAP ( 1L << 3 )
+#define FT_LOAD_VERTICAL_LAYOUT ( 1L << 4 )
+#define FT_LOAD_FORCE_AUTOHINT ( 1L << 5 )
+#define FT_LOAD_CROP_BITMAP ( 1L << 6 )
+#define FT_LOAD_PEDANTIC ( 1L << 7 )
+#define FT_LOAD_IGNORE_GLOBAL_ADVANCE_WIDTH ( 1L << 9 )
#define FT_LOAD_NO_RECURSE ( 1L << 10 )
#define FT_LOAD_IGNORE_TRANSFORM ( 1L << 11 )
#define FT_LOAD_MONOCHROME ( 1L << 12 )
#define FT_LOAD_LINEAR_DESIGN ( 1L << 13 )
+#define FT_LOAD_SBITS_ONLY ( 1L << 14 )
#define FT_LOAD_NO_AUTOHINT ( 1L << 15 )
/* Bits 16-19 are used by `FT_LOAD_TARGET_` */
#define FT_LOAD_COLOR ( 1L << 20 )
@@ -3091,8 +3258,8 @@ FT_BEGIN_HEADER
/* */
/* used internally only by certain font drivers */
-#define FT_LOAD_ADVANCE_ONLY ( 1L << 8 )
-#define FT_LOAD_SBITS_ONLY ( 1L << 14 )
+#define FT_LOAD_ADVANCE_ONLY ( 1L << 8 )
+#define FT_LOAD_SVG_ONLY ( 1L << 23 )
/**************************************************************************
@@ -3370,6 +3537,44 @@ FT_BEGIN_HEADER
* }
*
* ```
+ *
+ * FreeType has two rasterizers for generating SDF, namely:
+ *
+ * 1. `sdf` for generating SDF directly from glyph's outline, and
+ *
+ * 2. `bsdf` for generating SDF from rasterized bitmaps.
+ *
+ * Depending on the glyph type (i.e., outline or bitmap), one of the two
+ * rasterizers is chosen at runtime and used for generating SDFs. To
+ * force the use of `bsdf` you should render the glyph with any of the
+ * FreeType's other rendering modes (e.g., `FT_RENDER_MODE_NORMAL`) and
+ * then re-render with `FT_RENDER_MODE_SDF`.
+ *
+ * There are some issues with stability and possible failures of the SDF
+ * renderers (specifically `sdf`).
+ *
+ * 1. The `sdf` rasterizer is sensitive to really small features (e.g.,
+ * sharp turns that are less than 1~pixel) and imperfections in the
+ * glyph's outline, causing artifacts in the final output.
+ *
+ * 2. The `sdf` rasterizer has limited support for handling intersecting
+ * contours and *cannot* handle self-intersecting contours whatsoever.
+ * Self-intersection happens when a single connected contour intersect
+ * itself at some point; having these in your font definitely pose a
+ * problem to the rasterizer and cause artifacts, too.
+ *
+ * 3. Generating SDF for really small glyphs may result in undesirable
+ * output; the pixel grid (which stores distance information) becomes
+ * too coarse.
+ *
+ * 4. Since the output buffer is normalized, precision at smaller spreads
+ * is greater than precision at larger spread values because the
+ * output range of [0..255] gets mapped to a smaller SDF range. A
+ * spread of~2 should be sufficient in most cases.
+ *
+ * Points (1) and (2) can be avoided by using the `bsdf` rasterizer,
+ * which is more stable than the `sdf` rasterizer in general.
+ *
*/
typedef enum FT_Render_Mode_
{
@@ -3410,7 +3615,7 @@ FT_BEGIN_HEADER
* @FT_Render_Mode for a list of possible values.
*
* If @FT_RENDER_MODE_NORMAL is used, a previous call of @FT_Load_Glyph
- * with flag @FT_LOAD_COLOR makes FT_Render_Glyph provide a default
+ * with flag @FT_LOAD_COLOR makes `FT_Render_Glyph` provide a default
* blending of colored glyph layers associated with the current glyph
* slot (provided the font contains such layers) instead of rendering
* the glyph slot's outline. This is an experimental feature; see
@@ -3420,9 +3625,6 @@ FT_BEGIN_HEADER
* FreeType error code. 0~means success.
*
* @note:
- * To get meaningful results, font scaling values must be set with
- * functions like @FT_Set_Char_Size before calling `FT_Render_Glyph`.
- *
* When FreeType outputs a bitmap of a glyph, it really outputs an alpha
* coverage map. If a pixel is completely covered by a filled-in
* outline, the bitmap contains 0xFF at that pixel, meaning that
@@ -4739,7 +4941,7 @@ FT_BEGIN_HEADER
*
*/
#define FREETYPE_MAJOR 2
-#define FREETYPE_MINOR 11
+#define FREETYPE_MINOR 12
#define FREETYPE_PATCH 1