[freetype2] 1100-sdf-precision-improvement 8ffa954: * include/freetype/freetype.h (FT_RENDER_MODE_SDF): Improve documentation.

[Werner Lemberg]

branch: 1100-sdf-precision-improvement
commit 8ffa954507d21a8706f41fc26ecdc9cba3ed43c2
Author: Anuj Verma <anujv@iitbhilai.ac.in>
Commit: Anuj Verma <anujv@iitbhilai.ac.in>

    * include/freetype/freetype.h (FT_RENDER_MODE_SDF): Improve documentation.
    
    * include/freetype/freetype.h (FT_RENDER_MODE_SDF): Added more
      documentation for the render mode regarding the stability and point
      where artifacts are expected to occur.  Also added more information
      for both `sdf`, `bsdf` and when they are used.
---
 include/freetype/freetype.h | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/include/freetype/freetype.h b/include/freetype/freetype.h
index b457183..d34c48c 100644
--- a/include/freetype/freetype.h
+++ b/include/freetype/freetype.h
@@ -3368,6 +3368,40 @@ FT_BEGIN_HEADER
    *   }
    *
    *   ```
+   *
+   *   FreeType has two rasterizers for generating SDF, namely:
+   *
+   *   1. `sdf`  - For generating SDF directly from glyph's outline.
+   *
+   *   2. `bsdf` - For generating SDF from rasterized bitmaps.
+   *
+   *   Depending on the glyph type (i.e. outline or bitmap), one of the two
+   *   rasterizer is chosen at runtime and used for generating SDF.  To
+   *   force use `bsdf` you can simply render the glyph using any of the
+   *   FreeType's other rendering modes (e.g. `FT_RENDER_MODE_NORMAL`) and
+   *   then re-render using `FT_RENDER_MODE_SDF`.
+   *
+   *   Now, a few notes on the stability and point of failures for the SDF
+   *   renderers (specifically `sdf`):
+   *
+   *   1. The `sdf` rasterizer is sensitive to really small features (e.g.
+   *      sharp turns which are less than 1 pixel) and imperfections in the
+   *      glyph's outline.  Having these in the outline can cause artifats
+   *      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 and having these in your font will definately
+   *      pose a problem to the rasterizer and cause artifacts.
+   *
+   *   3. Generating SDF for really small glyphs may result in undesirable
+   *      output due to limited availability of pixel grid to store distance
+   *      information.
+   *
+   *   Point (1) and (2) can be avoided by using `bsdf` and overall it is
+   *   more stable than the `sdf` rasterizer.
+   *
    */
   typedef enum  FT_Render_Mode_
   {