docs: Improve hacking graph/text.

1 files changed, 44 insertions, 28 deletions

diff --git a/docs/HACKING.markdown b/docs/HACKING.markdown
index 467eabcb..7891e922 100644
--- a/docs/HACKING.markdown
+++ b/docs/HACKING.markdown
@@ -3,7 +3,7 @@
 Although focus was and still is on graphical APIs, apitrace has a
 generic infrastructure to trace any kind of API:
 
- * the APIs types and calls are specified in Python files in specs
+ * the API's types and calls are specified in Python files in specs
    sub-directory;
 
    * there is a type hierarchy in `specs/stdapi.py`, capable of representing
@@ -18,38 +18,48 @@ generic infrastructure to trace any kind of API:
      generation to be overriden by derived classes, allowing to handle
      cases that need special treatment without sacrifycing code reuse.
 
-apitrace's architecture is composed of several layers.  Too many to show in a
-single graph, so only those relevant for OpenGL API are shown below:
-
-                        specs
-                          ^
-                          |
-                       dispatch  <-------------- glws
-                          ^                       ^
-                          |                      /
-                       helpers  <--- glstate    /
-                         ^  ^          ^       /
-                        /    \         |      /
-                       /      \        |     /
-                   trace      retrace  |    /
-                    ^             ^    |   /
-                   /               \   |  /
-               gltrace            glretrace
-                ^ ^ ^                  ^
-               /  |  \                  \
-              /   |   \                  \
-             /    |    \                  \
-            /     |     \                  \
-           /      |      \                  \
-     glxtrace  wgltrace  cgltrace       qapitrace
+apitrace's architecture is composed of several layers/components.  There are
+too many to show in a single graph, so only those relevant for OpenGL API are
+illustrated below:
+
+                                   specs
+                                     ^
+                                     |
+                                   glproc
+                                   ^ ^ ^
+                                   | | |
+                            /------/ | \--\
+                            |        |    |
+                         helpers     |    |
+                          ^ ^ ^      |    |
+                          | | |      |    |
+                 /--------/ | \----\ |    |
+                 |          |      | |    |
+                 |          |      | |    |
+               trace     retrace glstate glws
+                 ^          ^       ^     ^
+                 |          |       |     |
+                 |          \-----\ | /---/
+                 |                | | |
+                 |                | | |
+              gltrace           glretrace
+               ^ ^ ^                ^
+               | | |                |
+        /------/ | \-----\          |
+        |        |       |          |
+        |        |       |          |
+    glxtrace wgltrace cgltrace  qapitrace
 
 Here is a quick synopsis of what the layers do:
 
- * `specs` -- specification of the API, expressed in a Python class hierarchy
+ * `specs` -- specifies the types, functions, and interfaces of the API,
+   expressed as a hierarchy of Python objects
 
  * `dispatch` -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
    address, and call it passing all arguments as-is)
 
+   * `glproc` -- specialization of the dispatch generation for GL APIs
+
  * `helpers` -- helper functions to determine sizes of arrays, blobs, etc.  It
    often needs to dispatch calls to give the answers.
 
@@ -74,6 +84,9 @@ Here is a quick synopsis of what the layers do:
  * `qapitrace` -- the GUI; it reads traces directly, and gets JSON state by
    invoking `glretrace`
 
+The architecture for Direct3D APIs is similar, with the exception that, because
+it's not cross platform, there are less specialized variations.
+
 
 # Coding Style #
 
@@ -193,8 +206,8 @@ specifications:
 * Fix-up the types of array, blob, and pointer arguments.
 
   * For `glGet*` you can use `"_gl_param_size(pname)"` for automatically determining the number of parameters written, e.g.
-    
-        GlFunction(Void, "glGetIntegerv", [(GLenum, "pname"), Out(Array(GLint, "_gl_param_size(pname)"), "params")], sideeffects=False),
+
+            GlFunction(Void, "glGetIntegerv", [(GLenum, "pname"), Out(Array(GLint, "_gl_param_size(pname)"), "params")], sideeffects=False),
 
 * Add the `sideeffects=False` keyword argument where appropriate, so that those
   calls can be merely ignored by `glretrace`.
@@ -204,3 +217,6 @@ specifications:
   swizzle the objects IDs, when replaying on a different OpenGL implementation.
 
 
+## Dump more OpenGL state ##
+
+