Improve SDF documentation.
This commit is contained in:
parent
982bc83849
commit
ec46a50dac
|
@ -3771,87 +3771,18 @@ FT_BEGIN_HEADER
|
||||||
* pixels and use the @FT_PIXEL_MODE_LCD_V mode.
|
* pixels and use the @FT_PIXEL_MODE_LCD_V mode.
|
||||||
*
|
*
|
||||||
* FT_RENDER_MODE_SDF ::
|
* FT_RENDER_MODE_SDF ::
|
||||||
* This mode corresponds to 8-bit, single-channel signed distance field
|
* The positive (unsigned) 8-bit bitmap values can be converted to the
|
||||||
* (SDF) bitmaps. Each pixel in the SDF grid is the value from the
|
* single-channel signed distance field (SDF) by subtracting 128, with
|
||||||
* pixel's position to the nearest glyph's outline. The distances are
|
* the positive and negative results corresponding to the inside and
|
||||||
* calculated from the center of the pixel and are positive if they are
|
* the outside of a glyph contour, respectively. The distance units are
|
||||||
* filled by the outline (i.e., inside the outline) and negative
|
* arbitrarily determined by an adjustable @spread property.
|
||||||
* otherwise. Check the note below on how to convert the output values
|
|
||||||
* to usable data.
|
|
||||||
*
|
*
|
||||||
* @note:
|
* @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
|
* Embedded bitmaps often have a different pixel mode like
|
||||||
* @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them
|
* @FT_PIXEL_MODE_MONO. You can use @FT_Bitmap_Convert to transform them
|
||||||
* into 8-bit pixmaps.
|
* 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_
|
typedef enum FT_Render_Mode_
|
||||||
{
|
{
|
||||||
|
|
|
@ -817,6 +817,79 @@ FT_BEGIN_HEADER
|
||||||
* 2.5
|
* 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:
|
* @property:
|
||||||
|
|
Loading…
Reference in New Issue