Add a high-level overview of apitrace source tree.

1 files changed, 73 insertions, 0 deletions

diff --git a/DEVELOPMENT.markdown b/DEVELOPMENT.markdown
index 5af6ed69..a777b539 100644
--- a/DEVELOPMENT.markdown
+++ b/DEVELOPMENT.markdown
@@ -1,3 +1,76 @@
+Overview
+=========
+
+Although focus has and still is on graphical APIs, apitrace has an
+infrastructure to trace generic APIs:
+
+ * The APIs types and calls are specified in Python files in spec
+
+   * there is a type hierarchy in specs\stdapi.py , capable of representing
+     most types in C language, and additional semantic metadata
+
+ * Python scripts generate C code to trace and serialize calls to disk, and
+   vice-versa.
+
+   * Visitor software design pattern is used to navigate over the types.
+
+   * Template design pattern is use so that any step of code generation can be
+     overriden by derived classes, allowing to easily handle cases that need
+     special treatment without sacrifycing code reuse.
+
+There are several main layers in apitrace.  Too many to show in a single graph,
+so below only those relevant for GL are shown:
+
+                        specs
+                          ^
+                          |
+                       dispatch  <-------------- glws
+                          ^                       ^
+                          |                      /
+                       helpers  <--- glstate    /
+                         ^  ^          ^       /
+                        /    \         |      /
+                       /      \        |     /
+                   trace      retrace  |    /
+                    ^             ^    |   /
+                   /               \   |  /
+               gltrace            glretrace
+               /  |  \
+              /   |   \
+             /    |    \
+            /     |     \
+           /      |      \
+     glxtrace  wgltrace  cgltrace
+
+And here is a quick synopsis of what the layers do:
+
+ * specs -- specification of the API, expressed in a Python class hierarchy
+
+ * dispatch -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
+   address, and call it passing all arguments as-is)
+
+ * helpers -- helper functions to determine sizes of array/blob/etc, and other.
+   It often needs to dispatch calls to give the answers.
+
+ * trace -- generate C++ code for tracing an API based on its spec
+
+   * gltrace -- specialization of the tracing generation for GL API, with extra
+     code to generate
+
+   * glxtrace, wgltrace, cgltrace -- specialization of the tracing code for the
+     GLX, WGL, and CGL APIs.
+
+ * retrace -- generate C++ code to interpret calls from trace, based on the
+   API's spec
+
+   * glretrace -- specialization of the retrace code for the GL API
+
+ * glstate -- code to dump OpenGL state to a JSON file
+
+ * glws -- abstraction of the window system specific APIs (GXL, WGL, CGL), to
+   enable cross-platform portability of glretrace
+
+
 Coding Style
 ============