diff options
author | Moazin Khatti <moazinkhatri@gmail.com> | 2019-08-24 18:24:28 +0500 |
---|---|---|
committer | Moazin Khatti <moazinkhatri@gmail.com> | 2019-08-26 01:17:15 +0500 |
commit | eb9a614011051580f54c9f1878e2783ac4b93607 (patch) | |
tree | b142201641bfcb47a1fb7176b3af8328c84103c3 | |
parent | 67c108bc9c1e8f00dccda6012866c4c854efd7f0 (diff) | |
download | freetype2-eb9a614011051580f54c9f1878e2783ac4b93607.tar.gz |
Improve ot-svg callback hooks documentation
-rw-r--r-- | include/freetype/otsvg.h | 44 |
1 files changed, 33 insertions, 11 deletions
diff --git a/include/freetype/otsvg.h b/include/freetype/otsvg.h index 8979d06a9..787f421b6 100644 --- a/include/freetype/otsvg.h +++ b/include/freetype/otsvg.h @@ -36,12 +36,15 @@ FT_BEGIN_HEADER * SVG_Lib_Init_Func * * @description: - * A callback used to initiate the SVG Rendering port. + * A callback which is called when the first OT-SVG glyph is rendered in + * the lifetime of an @FT_Library object. The callback should perform all + * sorts of initializations that the SVG rendering library needs such as + * allocating memory for `svg_renderer_state` of @FT_LibraryRec. * * @input: * library :: - * A instance of library. This is required to initialize the - * renderer's state which will be held in the library. + * An instance of @FT_Library. It's passed to give the callbacks access + * to `svg_renderer_state` of @FT_LibraryRec. * * @return: * FreeType error code. 0 means success. @@ -56,13 +59,15 @@ FT_BEGIN_HEADER * SVG_Lib_Free_Func * * @description: - * A callback used to free the SVG Rendering port. Calling this callback - * shall do all cleanups that the SVG Rendering port wants to do. + * A callback which is called when the `ot-svg` module is being freed. + * It is only called only if the init hook was called earlier. So, if no + * OT-SVG glyph is rendered, neither the init hook is called nor the free + * hook. * * @input: * library :: - * A instance of library. This is required to free the renderer's - * state which will be held in the library. + * An instance of @FT_Library. It's passed to give the callbacks access + * to `svg_renderer_state` of @FT_LibraryRec. */ typedef void (*SVG_Lib_Free_Func)( FT_Library library ); @@ -74,11 +79,15 @@ FT_BEGIN_HEADER * SVG_Lib_Render_Func * * @description: - * A callback used to render the glyph loaded in the slot. + * A callback which is called to render an OT-SVG glyph. This callback + * hook is called right after the preset hook has been called with + * `cache` set to `TRUE`. The data necessary to render is available + * through the handle @FT_SVG_Document which is set in `other` field of + * @FT_GlyphSlotRec. * * @input: * slot :: - * The whole glyph slot object. + * The slot to render. * * @return: * FreeType error code. 0 means success. @@ -92,12 +101,26 @@ FT_BEGIN_HEADER * SVG_Lib_Preset_Slot_Func * * @description: - * A callback which is to preset the glyphslot. + * A callback which is called to preset the glyphslot. It is called from + * two places. + * + * 1. When `FT_Load_Glyph` needs to preset the glyphslot. + * 2. Right before the `ot-svg` module calls the render callback hook. + * + * When it is the former, the argument `cache` is set to `FALSE`. When it + * is the latter, the argument `cache` is set to `TRUE`. This distinction + * has been made because while presetting a glyphslot many calculations + * are needed and later the render callback hook needs the same + * calculations, thus, if `cache` is `TRUE`, the hook might _cache_ these + * calculations in `svg_renderer_state` of @FT_LibraryRec. * * @input: * slot :: * The glyph slot which has the SVG document loaded. * + * cache :: + * See description. + * * @return: * FreeType error code. 0 means success. */ @@ -130,7 +153,6 @@ FT_BEGIN_HEADER */ typedef struct SVG_RendererHooks_ { - /* Api Hooks for OT-SVG Rendering */ SVG_Lib_Init_Func init_svg; SVG_Lib_Free_Func free_svg; SVG_Lib_Render_Func render_svg; |