git.cworth.org Git - apitrace/blob - DEVELOPMENT.markdown

   1 Overview
   2 =========
   3
   4 Although focus has and still is on graphical APIs, apitrace has an
   5 infrastructure to trace generic APIs:
   6
   7  * The APIs types and calls are specified in Python files in spec
   8
   9    * there is a type hierarchy in specs\stdapi.py , capable of representing
  10      most types in C language, and additional semantic metadata
  11
  12  * Python scripts generate C code to trace and serialize calls to disk, and
  13    vice-versa.
  14
  15    * Visitor software design pattern is used to navigate over the types.
  16
  17    * Template design pattern is use so that any step of code generation can be
  18      overriden by derived classes, allowing to easily handle cases that need
  19      special treatment without sacrifycing code reuse.
  20
  21 There are several main layers in apitrace.  Too many to show in a single graph,
  22 so below only those relevant for GL are shown:
  23
  24                         specs
  25                           ^
  26                           |
  27                        dispatch  <-------------- glws
  28                           ^                       ^
  29                           |                      /
  30                        helpers  <--- glstate    /
  31                          ^  ^          ^       /
  32                         /    \         |      /
  33                        /      \        |     /
  34                    trace      retrace  |    /
  35                     ^             ^    |   /
  36                    /               \   |  /
  37                gltrace            glretrace
  38                /  |  \
  39               /   |   \
  40              /    |    \
  41             /     |     \
  42            /      |      \
  43      glxtrace  wgltrace  cgltrace
  44
  45 And here is a quick synopsis of what the layers do:
  46
  47  * specs -- specification of the API, expressed in a Python class hierarchy
  48
  49  * dispatch -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
  50    address, and call it passing all arguments as-is)
  51
  52  * helpers -- helper functions to determine sizes of array/blob/etc, and other.
  53    It often needs to dispatch calls to give the answers.
  54
  55  * trace -- generate C++ code for tracing an API based on its spec
  56
  57    * gltrace -- specialization of the tracing generation for GL API, with extra
  58      code to generate
  59
  60    * glxtrace, wgltrace, cgltrace -- specialization of the tracing code for the
  61      GLX, WGL, and CGL APIs.
  62
  63  * retrace -- generate C++ code to interpret calls from trace, based on the
  64    API's spec
  65
  66    * glretrace -- specialization of the retrace code for the GL API
  67
  68  * glstate -- code to dump OpenGL state to a JSON file
  69
  70  * glws -- abstraction of the window system specific APIs (GXL, WGL, CGL), to
  71    enable cross-platform portability of glretrace
  72
  73
  74 Coding Style
  75 ============
  76
  77 These are guidelines for new code.  Some of existing hasn't been updated to
  78 these conventions yet.
  79
  80 Whitespace (all languages):
  81
  82  * indentation is 4 spaces
  83
  84  * never use tabs as indents
  85
  86  * otherwise tab equals to 8 spaces
  87
  88  * separate classes with two empty lines
  89
  90 Naming convention:
  91
  92  * camelCase for functions/methods
  93
  94  * UpperCase for structures/classes
  95
  96  * lowercase for namespaces/modules
  97
  98  * `UPPER_CASE` for #defines
  99
 100  * single underscore prefix for variables/functions in automatically generated
 101    code
 102
 103 C++:
 104
 105  * enclose single statement `if` clauses in { }, specially for automatically
 106    generated code
 107
 108  * } else {
 109
 110  * use inlines for functions/methods which are called with high-frequency
 111
 112 CMake:
 113
 114  * `lower_case` commands
 115
 116  * space between ( and precedent name
 117
 118
 119 When in doubt, be consistent with the existing code.
 120
 121
 122 Commit policy
 123 =============
 124
 125 Feature development:
 126
 127 * Existing features in master branch should not degrade at any time, for any
 128   platform.  (Unless it is not widely used and there is agreement.)
 129
 130 * It's fine to add new features for only some platforms.
 131
 132 * Non-trivial changes should be staged in a branch, to enable peer-review and
 133   regression testing.  Branch should be deleted once code has been merged.
 134
 135 * Releases are tagged commits from master.  There are no stable branches.
 136
 137
 138 Backwards compatibility:
 139
 140 * Backwards binary compatibility with old traces must be always maintained: all
 141   tools, including glretrace, must handle old traces without regressions.
 142
 143 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
 144   images, etc).
 145
 146 * There should be no gratuitous change to command line tool interfaces, but no
 147   guarantees are given.
 148
 149
 150
 151 Regression testing
 152 ==================
 153
 154 There is a regression test suite under development in
 155 https://github.com/apitrace/apitrace-tests .
 156