Commit e8bbef85c0027cb5ade84dbcc0bb12c1eb080e06
2018-12-12T14:05:03
Fix documentation of TrueType bytecode interpreter debug hook.
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 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
diff --git a/include/freetype/ftmodapi.h b/include/freetype/ftmodapi.h
index c64db75..bee93f3 100644
--- a/include/freetype/ftmodapi.h
+++ b/include/freetype/ftmodapi.h
@@ -592,14 +592,56 @@ FT_BEGIN_HEADER
FT_EXPORT( FT_Error )
FT_Done_Library( FT_Library library );
- /* */
+ /**************************************************************************
+ *
+ * @functype:
+ * FT_DebugHook_Func
+ *
+ * @description:
+ * A drop-in replacement (or rather a wrapper) for the bytecode or
+ * charstring interpreter's main loop function.
+ *
+ * Its job is essentially
+ *
+ * - to activate debug mode to enforce single-stepping,
+ * - to call the main loop function to interpret the next opcode, and
+ * - to show the changed context to the user.
+ *
+ * An example for such a main loop function is `TT_RunIns` (declared in
+ * FreeType's internal header file `src/truetype/ttinterp.h`).
+ *
+ * Have a look at the source code of the `ttdebug` FreeType demo program
+ * for an example of a drop-in replacement.
+ *
+ * @inout:
+ * arg ::
+ * A typeless pointer, to be cast to the main loop function's data
+ * structure (which depends on the font module). For TrueType fonts
+ * it is bytecode interpreter's execution context, `TT_ExecContext`,
+ * which is declared in FreeType's internal header file `tttypes.h`.
+ */
typedef void
(*FT_DebugHook_Func)( void* arg );
/**************************************************************************
*
+ * @enum:
+ * FT_DEBUG_HOOK_XXX
+ *
+ * @description:
+ * A list of named debug hook indices.
+ *
+ * @values:
+ * FT_DEBUG_HOOK_TRUETYPE::
+ * This hook index identifies the TrueType bytecode debugger.
+ */
+#define FT_DEBUG_HOOK_TRUETYPE 0
+
+
+ /**************************************************************************
+ *
* @function:
* FT_Set_Debug_Hook
*
@@ -607,25 +649,27 @@ FT_BEGIN_HEADER
* Set a debug hook function for debugging the interpreter of a font
* format.
*
+ * While this is a public API function, an application needs access to
+ * FreeType's internal header files to do something useful.
+ *
+ * Have a look at the source code of the `ttdebug` FreeType demo program
+ * for an example of its usage.
+ *
* @inout:
* library ::
* A handle to the library object.
*
* @input:
* hook_index ::
- * The index of the debug hook. You should use the values defined in
- * `ftobjs.h`, e.g., `FT_DEBUG_HOOK_TRUETYPE`.
+ * The index of the debug hook. You should use defined enumeration
+ * macros like @FT_DEBUG_HOOK_TRUETYPE.
*
* debug_hook ::
* The function used to debug the interpreter.
*
* @note:
- * Currently, four debug hook slots are available, but only two (for the
- * TrueType and the Type~1 interpreter) are defined.
- *
- * Since the internal headers of FreeType are no longer installed, the
- * symbol `FT_DEBUG_HOOK_TRUETYPE` isn't available publicly. This is a
- * bug and will be fixed in a forthcoming release.
+ * Currently, four debug hook slots are available, but only one (for the
+ * TrueType interpreter) is defined.
*/
FT_EXPORT( void )
FT_Set_Debug_Hook( FT_Library library,
diff --git a/include/freetype/internal/ftobjs.h b/include/freetype/internal/ftobjs.h
index 9124105..7a70a72 100644
--- a/include/freetype/internal/ftobjs.h
+++ b/include/freetype/internal/ftobjs.h
@@ -821,11 +821,6 @@ FT_BEGIN_HEADER
/*************************************************************************/
- /* This hook is used by the TrueType debugger. It must be set to an */
- /* alternate truetype bytecode interpreter function. */
-#define FT_DEBUG_HOOK_TRUETYPE 0
-
-
/**************************************************************************
*
* @struct: