|
4 | 4 | * |
5 | 5 | * FreeType high-level API and common types (specification only). |
6 | 6 | * |
7 | | - * Copyright (C) 1996-2023 by |
| 7 | + * Copyright (C) 1996-2024 by |
8 | 8 | * David Turner, Robert Wilhelm, and Werner Lemberg. |
9 | 9 | * |
10 | 10 | * This file is part of the FreeType project, and may only be used, |
@@ -1322,9 +1322,13 @@ FT_BEGIN_HEADER |
1322 | 1322 | * FT_FACE_FLAG_KERNING :: |
1323 | 1323 | * The face contains kerning information. If set, the kerning distance |
1324 | 1324 | * can be retrieved using the function @FT_Get_Kerning. Otherwise the |
1325 | | - * function always returns the vector (0,0). Note that FreeType |
1326 | | - * doesn't handle kerning data from the SFNT 'GPOS' table (as present |
1327 | | - * in many OpenType fonts). |
| 1325 | + * function always returns the vector (0,0). |
| 1326 | + * |
| 1327 | + * Note that for TrueType fonts only, FreeType supports both the 'kern' |
| 1328 | + * table and the basic, pair-wise kerning feature from the 'GPOS' table |
| 1329 | + * (with `TT_CONFIG_OPTION_GPOS_KERNING` enabled), though FreeType does |
| 1330 | + * not support the more advanced GPOS layout features; use a library |
| 1331 | + * like HarfBuzz for those instead. |
1328 | 1332 | * |
1329 | 1333 | * FT_FACE_FLAG_FAST_GLYPHS :: |
1330 | 1334 | * THIS FLAG IS DEPRECATED. DO NOT USE OR TEST IT. |
@@ -3767,87 +3771,18 @@ FT_BEGIN_HEADER |
3767 | 3771 | * pixels and use the @FT_PIXEL_MODE_LCD_V mode. |
3768 | 3772 | * |
3769 | 3773 | * FT_RENDER_MODE_SDF :: |
3770 | | - * This mode corresponds to 8-bit, single-channel signed distance field |
3771 | | - * (SDF) bitmaps. Each pixel in the SDF grid is the value from the |
3772 | | - * pixel's position to the nearest glyph's outline. The distances are |
3773 | | - * calculated from the center of the pixel and are positive if they are |
3774 | | - * filled by the outline (i.e., inside the outline) and negative |
3775 | | - * otherwise. Check the note below on how to convert the output values |
3776 | | - * to usable data. |
| 3774 | + * The positive (unsigned) 8-bit bitmap values can be converted to the |
| 3775 | + * single-channel signed distance field (SDF) by subtracting 128, with |
| 3776 | + * the positive and negative results corresponding to the inside and |
| 3777 | + * the outside of a glyph contour, respectively. The distance units are |
| 3778 | + * arbitrarily determined by an adjustable @spread property. |
3777 | 3779 | * |
3778 | 3780 | * @note: |
3779 | | - * The selected render mode only affects vector glyphs of a font. |
| 3781 | + * The selected render mode only affects scalable vector glyphs of a font. |
3780 | 3782 | * Embedded bitmaps often have a different pixel mode like |
3781 | 3783 | * @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them |
3782 | 3784 | * into 8-bit pixmaps. |
3783 | 3785 | * |
3784 | | - * For @FT_RENDER_MODE_SDF the output bitmap buffer contains normalized |
3785 | | - * distances that are packed into unsigned 8-bit values. To get pixel |
3786 | | - * values in floating point representation use the following pseudo-C |
3787 | | - * code for the conversion. |
3788 | | - * |
3789 | | - * ``` |
3790 | | - * // Load glyph and render using FT_RENDER_MODE_SDF, |
3791 | | - * // then use the output buffer as follows. |
3792 | | - * |
3793 | | - * ... |
3794 | | - * FT_Byte buffer = glyph->bitmap->buffer; |
3795 | | - * |
3796 | | - * |
3797 | | - * for pixel in buffer |
3798 | | - * { |
3799 | | - * // `sd` is the signed distance and `spread` is the current spread; |
3800 | | - * // the default spread is 2 and can be changed. |
3801 | | - * |
3802 | | - * float sd = (float)pixel - 128.0f; |
3803 | | - * |
3804 | | - * |
3805 | | - * // Convert to pixel values. |
3806 | | - * sd = ( sd / 128.0f ) * spread; |
3807 | | - * |
3808 | | - * // Store `sd` in a buffer or use as required. |
3809 | | - * } |
3810 | | - * |
3811 | | - * ``` |
3812 | | - * |
3813 | | - * FreeType has two rasterizers for generating SDF, namely: |
3814 | | - * |
3815 | | - * 1. `sdf` for generating SDF directly from glyph's outline, and |
3816 | | - * |
3817 | | - * 2. `bsdf` for generating SDF from rasterized bitmaps. |
3818 | | - * |
3819 | | - * Depending on the glyph type (i.e., outline or bitmap), one of the two |
3820 | | - * rasterizers is chosen at runtime and used for generating SDFs. To |
3821 | | - * force the use of `bsdf` you should render the glyph with any of the |
3822 | | - * FreeType's other rendering modes (e.g., `FT_RENDER_MODE_NORMAL`) and |
3823 | | - * then re-render with `FT_RENDER_MODE_SDF`. |
3824 | | - * |
3825 | | - * There are some issues with stability and possible failures of the SDF |
3826 | | - * renderers (specifically `sdf`). |
3827 | | - * |
3828 | | - * 1. The `sdf` rasterizer is sensitive to really small features (e.g., |
3829 | | - * sharp turns that are less than 1~pixel) and imperfections in the |
3830 | | - * glyph's outline, causing artifacts in the final output. |
3831 | | - * |
3832 | | - * 2. The `sdf` rasterizer has limited support for handling intersecting |
3833 | | - * contours and *cannot* handle self-intersecting contours whatsoever. |
3834 | | - * Self-intersection happens when a single connected contour |
3835 | | - * intersects itself at some point; having these in your font |
3836 | | - * definitely poses a problem to the rasterizer and cause artifacts, |
3837 | | - * too. |
3838 | | - * |
3839 | | - * 3. Generating SDF for really small glyphs may result in undesirable |
3840 | | - * output; the pixel grid (which stores distance information) becomes |
3841 | | - * too coarse. |
3842 | | - * |
3843 | | - * 4. Since the output buffer is normalized, precision at smaller spreads |
3844 | | - * is greater than precision at larger spread values because the |
3845 | | - * output range of [0..255] gets mapped to a smaller SDF range. A |
3846 | | - * spread of~2 should be sufficient in most cases. |
3847 | | - * |
3848 | | - * Points (1) and (2) can be avoided by using the `bsdf` rasterizer, |
3849 | | - * which is more stable than the `sdf` rasterizer in general. |
3850 | | - * |
3851 | 3786 | */ |
3852 | 3787 | typedef enum FT_Render_Mode_ |
3853 | 3788 | { |
@@ -4058,9 +3993,26 @@ FT_BEGIN_HEADER |
4058 | 3993 | * out of the scope of this API function -- they can be implemented |
4059 | 3994 | * through format-specific interfaces. |
4060 | 3995 | * |
4061 | | - * Kerning for OpenType fonts implemented in a 'GPOS' table is not |
4062 | | - * supported; use @FT_HAS_KERNING to find out whether a font has data |
4063 | | - * that can be extracted with `FT_Get_Kerning`. |
| 3996 | + * Note that, for TrueType fonts only, this can extract data from both |
| 3997 | + * the 'kern' table and the basic, pair-wise kerning feature from the |
| 3998 | + * GPOS table (with `TT_CONFIG_OPTION_GPOS_KERNING` enabled), though |
| 3999 | + * FreeType does not support the more advanced GPOS layout features; use |
| 4000 | + * a library like HarfBuzz for those instead. If a font has both a |
| 4001 | + * 'kern' table and kern features of a GPOS table, the 'kern' table will |
| 4002 | + * be used. |
| 4003 | + * |
| 4004 | + * Also note for right-to-left scripts, the functionality may differ for |
| 4005 | + * fonts with GPOS tables vs. 'kern' tables. For GPOS, right-to-left |
| 4006 | + * fonts typically use both a placement offset and an advance for pair |
| 4007 | + * positioning, which this API does not support, so it would output |
| 4008 | + * kerning values of zero; though if the right-to-left font used only |
| 4009 | + * advances in GPOS pair positioning, then this API could output kerning |
| 4010 | + * values for it, but it would use `left_glyph` to mean the first glyph |
| 4011 | + * for that case. Whereas 'kern' tables are always advance-only and |
| 4012 | + * always store the left glyph first. |
| 4013 | + * |
| 4014 | + * Use @FT_HAS_KERNING to find out whether a font has data that can be |
| 4015 | + * extracted with `FT_Get_Kerning`. |
4064 | 4016 | */ |
4065 | 4017 | FT_EXPORT( FT_Error ) |
4066 | 4018 | FT_Get_Kerning( FT_Face face, |
@@ -5222,7 +5174,7 @@ FT_BEGIN_HEADER |
5222 | 5174 | */ |
5223 | 5175 | #define FREETYPE_MAJOR 2 |
5224 | 5176 | #define FREETYPE_MINOR 13 |
5225 | | -#define FREETYPE_PATCH 2 |
| 5177 | +#define FREETYPE_PATCH 3 |
5226 | 5178 |
|
5227 | 5179 |
|
5228 | 5180 | /************************************************************************** |
|
0 commit comments