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

Improve SDF documentation.

This commit is contained in:
Alexei Podtelezhnikov 2024-04-22 21:21:12 -04:00
parent 982bc83849
commit ec46a50dac
2 changed files with 79 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
include/freetype/freetype.h
View File

@ -3771,87 +3771,18 @@ FT_BEGIN_HEADER
* pixels and use the @FT_PIXEL_MODE_LCD_V mode.
*
* FT_RENDER_MODE_SDF ::
* This mode corresponds to 8-bit, single-channel signed distance field
* (SDF) bitmaps. Each pixel in the SDF grid is the value from the
* pixel's position to the nearest glyph's outline. The distances are
* calculated from the center of the pixel and are positive if they are
* filled by the outline (i.e., inside the outline) and negative
* otherwise. Check the note below on how to convert the output values
* to usable data.
* The positive (unsigned) 8-bit bitmap values can be converted to the
* single-channel signed distance field (SDF) by subtracting 128, with
* the positive and negative results corresponding to the inside and
* the outside of a glyph contour, respectively. The distance units are
* arbitrarily determined by an adjustable @spread property.
*
* @note:
* The selected render mode only affects vector glyphs of a font.
* The selected render mode only affects scalable vector glyphs of a font.
* Embedded bitmaps often have a different pixel mode like
* @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them
* into 8-bit pixmaps.
*
* For @FT_RENDER_MODE_SDF the output bitmap buffer contains normalized
* distances that are packed into unsigned 8-bit values. To get pixel
* values in floating point representation use the following pseudo-C
* code for the conversion.
*
* ```
* // Load glyph and render using FT_RENDER_MODE_SDF,
* // then use the output buffer as follows.
*
* ...
* FT_Byte buffer = glyph->bitmap->buffer;
*
*
* for pixel in buffer
* {
* // `sd` is the signed distance and `spread` is the current spread;
* // the default spread is 2 and can be changed.
*
* float sd = (float)pixel - 128.0f;
*
*
* // Convert to pixel values.
* sd = ( sd / 128.0f ) * spread;
*
* // Store `sd` in a buffer or use as required.
* }
*
* ```
*
* 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
* intersects itself at some point; having these in your font
* definitely poses 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_
{

73
include/freetype/ftdriver.h
View File

@ -817,6 +817,79 @@ FT_BEGIN_HEADER
* 2.5
*/
/**************************************************************************
*
* @property:
* spread
*
* @description:
* This property of the 'sdf' and 'bsdf' renderers defines how the signed
* distance field (SDF) is represented in the output bitmap. The output
* values are calculated as follows, '128 * ( SDF / spread + 1 )', with
* the result truncated to the 8-bit range [0..255]. Therefore, 'spread'
* is also the maximum euclidean distance from the edge after which the
* values are truncated. The spread is specified in pixels with the
* default value of 8.
*
* @example:
* The following example code demonstrates how to set the SDF spread
* (omitting the error handling).
*
* ```
* FT_Library library;
* FT_UInt spread = 2;
*
*
* FT_Init_FreeType( &library );
*
* FT_Property_Set( library, "sdf", "spread", &spread );
* ```
*
* @note
* 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
* intersects itself at some point; having these in your font
* definitely poses 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.
*
* @since:
* 2.11
*/
/**************************************************************************
*
* @property: