From d8228a00704d7932bd54a87dc5b69561ac7ba594 Mon Sep 17 00:00:00 2001 From: Alexei Podtelezhnikov Date: Fri, 28 Aug 2020 22:28:47 -0400 Subject: [PATCH] Improve FT_Outline_Render docs. --- include/freetype/ftimage.h | 28 +++++++++++++++++----------- include/freetype/ftoutln.h | 16 +++++----------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h index 105e09d12..58b674f97 100644 --- a/include/freetype/ftimage.h +++ b/include/freetype/ftimage.h @@ -1011,20 +1011,26 @@ FT_BEGIN_HEADER * 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_ { diff --git a/include/freetype/ftoutln.h b/include/freetype/ftoutln.h index 5069d187b..84e9b144c 100644 --- a/include/freetype/ftoutln.h +++ b/include/freetype/ftoutln.h @@ -482,19 +482,13 @@ FT_BEGIN_HEADER * 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,