[Git][freetype/freetype][master] Improve SDF documentation.

Alexei Podtelezhnikov pushed to branch master at FreeType / FreeType

Commits:

ec46a50d
by Alexei Podtelezhnikov (Алексей Подтележников) at 2024-04-22T21:21:12-04:00
```
Improve SDF documentation.
```

2 changed files:

include/freetype/freetype.h
include/freetype/ftdriver.h

Changes:

@@ -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_
+   {

include/freetype/ftdriver.h

@@ -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:

From:	Alexei Podtelezhnikov (@apodtele)
Subject:	[Git][freetype/freetype][master] Improve SDF documentation.
Date:	Tue, 23 Apr 2024 01:22:20 +0000