cli: Don't use the DLL injection method for OpenGL on Windows 8.

[apitrace] / DEVELOPMENT.markdown

diff --git a/DEVELOPMENT.markdown b/DEVELOPMENT.markdown
index a777b539b5bec24b7e521c013ccef45182783c4b..154b3695e38e98c38e2a460a2017a755b2526b67 100644 (file)
--- a/DEVELOPMENT.markdown
+++ b/DEVELOPMENT.markdown
@@ -1,16 +1,17 @@
 Overview
 =========
 
 Overview
 =========
 

-Although focus has and still is on graphical APIs, apitrace has an
-infrastructure to trace generic APIs:
+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 spec
+ * 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
+   * there is a type hierarchy in specs/stdapi.py, capable of representing

      most types in C language, and additional semantic metadata
 
      most types in C language, and additional semantic metadata
 

- * Python scripts generate C code to trace and serialize calls to disk, and
-   vice-versa.
+ * 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.
 
 
    * Visitor software design pattern is used to navigate over the types.
 


@@ -18,8 +19,8 @@ infrastructure to trace generic APIs:
      overriden by derived classes, allowing to easily handle cases that need
      special treatment without sacrifycing code reuse.
 
      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:
+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
                           ^
 
                         specs
                           ^


@@ -42,15 +43,15 @@ so below only those relevant for GL are shown:
            /      |      \
      glxtrace  wgltrace  cgltrace
 
            /      |      \
      glxtrace  wgltrace  cgltrace
 

-And here is a quick synopsis of what the layers do:
+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)
 
 
  * 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.
+ * 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
 
 
  * trace -- generate C++ code for tracing an API based on its spec
 


@@ -74,8 +75,8 @@ And here is a quick synopsis of what the layers do:
 Coding Style
 ============
 
 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):
 
 
 Whitespace (all languages):
 


@@ -125,12 +126,24 @@ Commit policy
 Feature development:
 
 * Existing features in master branch should not degrade at any time, for any
 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.)

 
 

-* It's fine to add new features for only some platforms.
+  * In particular, new features / changes must not introduce any sort of
+    instability when tracing.

 
 

-* 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.
+    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 or APIs.
+
+* 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.
 
 
 * Releases are tagged commits from master.  There are no stable branches.
 


@@ -143,7 +156,7 @@ Backwards compatibility:
 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
   images, etc).
 
 * 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.
 
 
   guarantees are given.