[freetype2] master d8228a0: Improve FT_Outline_Render docs.

[Alexei Podtelezhnikov]

branch: master
commit d8228a00704d7932bd54a87dc5b69561ac7ba594
Author: Alexei Podtelezhnikov <apodtele@gmail.com>
Commit: Alexei Podtelezhnikov <apodtele@gmail.com>

    Improve FT_Outline_Render docs.
---
 include/freetype/ftimage.h | 30 ++++++++++++++++++------------
 include/freetype/ftoutln.h | 16 +++++-----------
 2 files changed, 23 insertions(+), 23 deletions(-)

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,