X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=DEVELOPMENT.markdown;h=154b3695e38e98c38e2a460a2017a755b2526b67;hb=52fc2b017b6914afb3799601b6e93f9306af0058;hp=5af6ed697e3962328fa280d68572fdb392141475;hpb=e7cb2b98575d5ff3801bd3527a648e0dbfdebdad;p=apitrace

diff --git a/DEVELOPMENT.markdown b/DEVELOPMENT.markdown
index 5af6ed6..154b369 100644
--- a/DEVELOPMENT.markdown
+++ b/DEVELOPMENT.markdown
@@ -1,8 +1,82 @@
+Overview
+=========
+
+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
+   sub-directory;
+
+   * 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 parameters to
+   a file, 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.
+
+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
+
+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 arrays, blobs, etc.  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
 ============
 
-These are guidelines for new code.  Some of existing hasn't been updated to
-these conventions yet.
+These are guidelines for new code.  Admittedly some of the existing code hasn't
+been updated to follow these conventions yet.
 
 Whitespace (all languages):
 
@@ -52,12 +126,24 @@ Commit policy
 Feature development:
 
 * Existing features in master branch should not degrade at any time, for any
-  platform.  (Unless it is not widely used and there is agreement.)
+  platform.  (Unless they are seldom used or redundant and there is agreement.)
+
+  * In particular, new features / changes must not introduce any sort of
+    instability when tracing.
+
+    While application developers and driver developers may be able to
+    workaround quirks in apitrace, we want to be able to obtain traces from
+    non-technical end-users with minimal intervention.
+
+    This implies that tracing should not make any non-standard assumptions, and
+    care must be taken to ensure the tracing code is robust against invalid
+    parameters, multiple threads, etc.
 
-* It's fine to add new features for only some platforms.
+* It's fine to add new features for only some platforms or APIs.
 
-* Non-trivial changes should be staged in a branch, to enable peer-review and
-  regression testing.  Branch should be deleted once code has been merged.
+* Non-trivial changes should be staged in a branch, to allow review and
+  regression testing.  Feature branches should be deleted once they have been
+  merged.
 
 * Releases are tagged commits from master.  There are no stable branches.
 
@@ -70,7 +156,7 @@ Backwards compatibility:
 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
   images, etc).
 
-* There should be no gratuitous change to command line tool interfaces, but no
+* There should be no gratuitous changes to command line tool interfaces, but no
   guarantees are given.