Commit 681c7e238755700bc7001aeec63b486aeab5cac2
2020-10-30T23:03:12
Better scan converter documentation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h
index 4199bb7..82e9f40 100644
--- a/include/freetype/ftimage.h
+++ b/include/freetype/ftimage.h
@@ -772,17 +772,6 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /**************************************************************************
- *
- * A raster is a scan converter, in charge of rendering an outline into a
- * bitmap. This section contains the public API for rasters.
- *
- * Note that in FreeType 2, all rasters are now encapsulated within
- * specific modules called 'renderers'. See `ftrender.h` for more details
- * on renderers.
- *
- */
-
/**************************************************************************
*
@@ -796,16 +785,35 @@ FT_BEGIN_HEADER
* How vectorial outlines are converted into bitmaps and pixmaps.
*
* @description:
- * This section contains technical definitions.
+ * A raster or a raterizer is a scan converter in charge of producing
+ * a pixel coverage bitmap that can be used as an alpha channel when
+ * compositing a glyph with a background. FreeType comes with two
+ * rasterizers: bilevel `raster1` and anti-aliased `smooth` are two
+ * separate modules. They are usually called from high-level
+ * @FT_Load_Glyph or @FT_Render_Glyph and produce the entire coverage
+ * bitmap at once, while staying largely invisible to users.
+ *
+ * Instead of working with complete coverage bitmaps, it is also
+ * possible to intercept consecutive pixel runs on the same scanline
+ * with the same coverage, called spans, and process them individually.
+ * Only `smooth` rasterizer permits this when calling @FT_Outline_Render
+ * with @FT_Raster_Params described below.
+ *
+ * Whether working with complete bitmaps or spans, it is important to
+ * think of them as colorless coverage objects suitable as alpha channels
+ * in blending arbitrary colors with background. For best results, it is
+ * recommended to use gamma correction too.
+ *
+ * This section also describes public API needed to set up alternative
+ * @FT_Renderer modules.
*
* @order:
- * FT_Raster
* FT_Span
* FT_SpanFunc
- *
* FT_Raster_Params
* FT_RASTER_FLAG_XXX
*
+ * FT_Raster
* FT_Raster_NewFunc
* FT_Raster_DoneFunc
* FT_Raster_ResetFunc
@@ -818,24 +826,12 @@ FT_BEGIN_HEADER
/**************************************************************************
*
- * @type:
- * FT_Raster
- *
- * @description:
- * An opaque handle (pointer) to a raster object. Each object can be
- * used independently to convert an outline into a bitmap or pixmap.
- */
- typedef struct FT_RasterRec_* FT_Raster;
-
-
- /**************************************************************************
- *
* @struct:
* FT_Span
*
* @description:
- * A structure used to model a single span of gray pixels when rendering
- * an anti-aliased bitmap.
+ * A structure used to model a single span of consecutive pixels
+ * when rendering an anti-aliased bitmap.
*
* @fields:
* x ::
@@ -852,20 +848,8 @@ FT_BEGIN_HEADER
* This structure is used by the span drawing callback type named
* @FT_SpanFunc that takes the y~coordinate of the span as a parameter.
*
- * The coverage value is always between 0 and 255. If you want less gray
- * values, the callback function has to reduce them by scaling the
- * outline four times and using bilevel monochrome renderer to then
- * average 16~pixels in each 4-by-4 box.
- *
- * The only correct way to blend colors is to convert the colors from
- * sRGB to linear colorspace, then perform the weighted average, then
- * convert to sRGB, but this is out of scope of FreeType. Using an
- * approximation such as gamma 2.2 or 2.3 or interpolation from a lookup
- * table of more than three entries or sampling from a lookup table of
- * more than fifteen entries is acceptable, but any implementation
- * significantly deviating from that (for example a gamma of 1.8 or less,
- * or a gamma of 2.7 or greater, or not implementing gamma properly at
- * all) will most likely yield bad results.
+ * The anti-aliased rasterizer produces coverage values from 0 to 255,
+ * from completely transparent to completely opaque.
*/
typedef struct FT_Span_
{
@@ -883,8 +867,8 @@ FT_BEGIN_HEADER
*
* @description:
* A function used as a call-back by the anti-aliased renderer in order
- * to let client applications draw themselves the gray pixel spans on
- * each scan line.
+ * to let client applications draw themselves the pixel spans on each
+ * scan line.
*
* @input:
* y ::
@@ -900,11 +884,12 @@ FT_BEGIN_HEADER
* User-supplied data that is passed to the callback.
*
* @note:
- * This callback allows client applications to directly render the gray
- * spans of the anti-aliased bitmap to any kind of surfaces.
+ * This callback allows client applications to directly render the spans
+ * of the anti-aliased bitmap to any kind of surfaces.
*
* This can be used to write anti-aliased outlines directly to a given
- * background bitmap, and even perform translucency.
+ * background bitmap using alpha compositing. It can also be used for
+ * oversampling and averaging.
*/
typedef void
(*FT_SpanFunc)( int y,
@@ -1061,6 +1046,23 @@ FT_BEGIN_HEADER
/**************************************************************************
*
+ * @type:
+ * FT_Raster
+ *
+ * @description:
+ * An opaque handle (pointer) to a raster object. Each object can be
+ * used independently to convert an outline into a bitmap or pixmap.
+ *
+ * @note
+ * In FreeType 2, all rasters are now encapsulated within specific
+ * @FT_Renderer modules and only used in their context.
+ *
+ */
+ typedef struct FT_RasterRec_* FT_Raster;
+
+
+ /**************************************************************************
+ *
* @functype:
* FT_Raster_NewFunc
*