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

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