4 Although focus has and still is on graphical APIs, apitrace has an
5 infrastructure to trace generic APIs:
7 * The APIs types and calls are specified in Python files in spec
9 * there is a type hierarchy in specs\stdapi.py , capable of representing
10 most types in C language, and additional semantic metadata
12 * Python scripts generate C code to trace and serialize calls to disk, and
15 * Visitor software design pattern is used to navigate over the types.
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.
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:
27 dispatch <-------------- glws
30 helpers <--- glstate /
43 glxtrace wgltrace cgltrace
45 And here is a quick synopsis of what the layers do:
47 * specs -- specification of the API, expressed in a Python class hierarchy
49 * dispatch -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
50 address, and call it passing all arguments as-is)
52 * helpers -- helper functions to determine sizes of array/blob/etc, and other.
53 It often needs to dispatch calls to give the answers.
55 * trace -- generate C++ code for tracing an API based on its spec
57 * gltrace -- specialization of the tracing generation for GL API, with extra
60 * glxtrace, wgltrace, cgltrace -- specialization of the tracing code for the
61 GLX, WGL, and CGL APIs.
63 * retrace -- generate C++ code to interpret calls from trace, based on the
66 * glretrace -- specialization of the retrace code for the GL API
68 * glstate -- code to dump OpenGL state to a JSON file
70 * glws -- abstraction of the window system specific APIs (GXL, WGL, CGL), to
71 enable cross-platform portability of glretrace
77 These are guidelines for new code. Some of existing hasn't been updated to
78 these conventions yet.
80 Whitespace (all languages):
82 * indentation is 4 spaces
84 * never use tabs as indents
86 * otherwise tab equals to 8 spaces
88 * separate classes with two empty lines
92 * camelCase for functions/methods
94 * UpperCase for structures/classes
96 * lowercase for namespaces/modules
98 * `UPPER_CASE` for #defines
100 * single underscore prefix for variables/functions in automatically generated
105 * enclose single statement `if` clauses in { }, specially for automatically
110 * use inlines for functions/methods which are called with high-frequency
114 * `lower_case` commands
116 * space between ( and precedent name
119 When in doubt, be consistent with the existing code.
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.)
130 * It's fine to add new features for only some platforms.
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.
135 * Releases are tagged commits from master. There are no stable branches.
138 Backwards compatibility:
140 * Backwards binary compatibility with old traces must be always maintained: all
141 tools, including glretrace, must handle old traces without regressions.
143 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
146 * There should be no gratuitous change to command line tool interfaces, but no
147 guarantees are given.
154 There is a regression test suite under development in
155 https://github.com/apitrace/apitrace-tests .