ref: d8228a00704d7932bd54a87dc5b69561ac7ba594
parent: 6730854c397130879c64bd766c673b9bccf9c04a
author: Alexei Podtelezhnikov <apodtele@gmail.com>
date: Fri Aug 28 18:28:47 EDT 2020
Improve FT_Outline_Render docs.
--- a/include/freetype/ftimage.h
+++ b/include/freetype/ftimage.h
@@ -1011,20 +1011,26 @@
* User-supplied data that is passed to each drawing callback.
*
* clip_box ::
- * An optional clipping box. It is only used in direct rendering mode.
- * Note that coordinates here should be expressed in _integer_ pixels
- * (and not in 26.6 fixed-point units).
+ * An optional span clipping box expressed in _integer_ pixels
+ * (not in 26.6 fixed-point units).
*
* @note:
- * An anti-aliased glyph bitmap is drawn if the @FT_RASTER_FLAG_AA bit
- * flag is set in the `flags` field, otherwise a monochrome bitmap is
- * generated.
+ * The @FT_RASTER_FLAG_AA bit flag must be set in the `flags` to
+ * generate an anti-aliased glyph bitmap, otherwise a monochrome bitmap
+ * is generated. The `target` should have appropriate pixel mode and its
+ * dimensions define the clipping region.
*
- * If the @FT_RASTER_FLAG_DIRECT bit flag is set in `flags`, the raster
- * will call the `gray_spans` callback to draw gray pixel spans. This
- * allows direct composition over a pre-existing bitmap through
- * user-provided callbacks to perform the span drawing and composition.
- * Not supported by the monochrome rasterizer.
+ * If both `( @FT_RASTER_FLAG_AA | @FT_RASTER_FLAG_DIRECT )` bit flags
+ * are set in `flags`, the raster will call an @FT_SpanFunc callback
+ * `gray_spans` with `user` data as an argument ignoring `target`. This
+ * allows direct composition over a pre-existing user surface to perform
+ * the span drawing and composition. To optionally clip the spans, set
+ * the @FT_RASTER_FLAG_CLIP flag and `clip_box`. The monochrome raster
+ * does not support the direct mode.
+ *
+ * The gray-level rasterizer always uses 256 gray levels. If you want
+ * fewer gray levels, you have to use @FT_RASTER_FLAG_DIRECT and reduce
+ * the levels in the callback function.
*/
typedef struct FT_Raster_Params_
{--- a/include/freetype/ftoutln.h
+++ b/include/freetype/ftoutln.h
@@ -482,19 +482,13 @@
* FreeType error code. 0~means success.
*
* @note:
- * This advanced function uses @FT_Raster_Params as an argument,
- * allowing FreeType rasterizer to be used for direct composition,
- * translucency, etc. You should know how to set up @FT_Raster_Params
- * for this function to work.
- *
+ * This advanced function uses @FT_Raster_Params as an argument.
* The field `params.source` will be set to `outline` before the scan
* converter is called, which means that the value you give to it is
- * actually ignored.
- *
- * The gray-level rasterizer always uses 256 gray levels. If you want
- * less gray levels, you have to provide your own span callback. See the
- * @FT_RASTER_FLAG_DIRECT value of the `flags` field in the
- * @FT_Raster_Params structure for more details.
+ * actually ignored. Either `params.target` must point to preallocated
+ * bitmap, or @FT_RASTER_FLAG_DIRECT must be set in `params.flags`
+ * allowing FreeType rasterizer to be used for direct composition,
+ * translucency, etc. See @FT_Raster_Params for more details.
*/
FT_EXPORT( FT_Error )
FT_Outline_Render( FT_Library library,