Commit d8228a00704d7932bd54a87dc5b69561ac7ba594
2020-08-28T22:28:47
Improve FT_Outline_Render docs.
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
diff --git a/include/freetype/ftimage.h b/include/freetype/ftimage.h
index 105e09d..58b674f 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.
- *
- * 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.
+ * 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 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 5069d18..84e9b14 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,