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

   1 Overview
   2 =========
   3
   4 Although focus was and still is on graphical APIs, apitrace has a
   5 generic infrastructure to trace any kind of API:
   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 parameters to
  14    a file, and 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 apitrace's architecture is composed of several layers.  Too many to show in a
  23 single graph, so only those relevant for OpenGL API are shown below:
  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 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 arrays, blobs, etc.  It
  54    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.  Admittedly some of the existing code hasn't
  79 been updated to follow 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 they are seldom used or redundant and there is agreement.)
 130
 131   * In particular, new features / changes must not introduce any sort of
 132     instability when tracing.
 133
 134     While application developers and driver developers may be able to
 135     workaround quirks in apitrace, we want to be able to obtain traces from
 136     non-technical end-users with minimal intervention.
 137
 138     This implies that tracing should not make any non-standard assumptions, and
 139     care must be taken to ensure the tracing code is robust against invalid
 140     parameters, multiple threads, etc.
 141
 142 * It's fine to add new features for only some platforms or APIs.
 143
 144 * Non-trivial changes should be staged in a branch, to allow review and
 145   regression testing.  Feature branches should be deleted once they have been
 146   merged.
 147
 148 * Releases are tagged commits from master.  There are no stable branches.
 149
 150
 151 Backwards compatibility:
 152
 153 * Backwards binary compatibility with old traces must be always maintained: all
 154   tools, including glretrace, must handle old traces without regressions.
 155
 156 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
 157   images, etc).
 158
 159 * There should be no gratuitous changes to command line tool interfaces, but no
 160   guarantees are given.
 161
 162
 163
 164 Regression testing
 165 ==================
 166
 167 There is a regression test suite under development in
 168 https://github.com/apitrace/apitrace-tests .
 169