4 Although focus was and still is on graphical APIs, apitrace has a
5 generic infrastructure to trace any kind of API:
7 * the APIs types and calls are specified in Python files in specs
10 * there is a type hierarchy in specs/stdapi.py, capable of representing
11 most types in C language, and additional semantic metadata
13 * Python scripts generate C++ code to trace and serialize calls parameters to
14 a file, and vice-versa.
16 * Visitor software design pattern is used to navigate over the types.
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.
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:
28 dispatch <-------------- glws
31 helpers <--- glstate /
44 glxtrace wgltrace cgltrace
46 Here is a quick synopsis of what the layers do:
48 * specs -- specification of the API, expressed in a Python class hierarchy
50 * dispatch -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
51 address, and call it passing all arguments as-is)
53 * helpers -- helper functions to determine sizes of arrays, blobs, etc. It
54 often needs to dispatch calls to give the answers.
56 * trace -- generate C++ code for tracing an API based on its spec
58 * gltrace -- specialization of the tracing generation for GL API, with extra
61 * glxtrace, wgltrace, cgltrace -- specialization of the tracing code for the
62 GLX, WGL, and CGL APIs.
64 * retrace -- generate C++ code to interpret calls from trace, based on the
67 * glretrace -- specialization of the retrace code for the GL API
69 * glstate -- code to dump OpenGL state to a JSON file
71 * glws -- abstraction of the window system specific APIs (GXL, WGL, CGL), to
72 enable cross-platform portability of glretrace
78 These are guidelines for new code. Admittedly some of the existing code hasn't
79 been updated to follow these conventions yet.
81 Whitespace (all languages):
83 * indentation is 4 spaces
85 * never use tabs as indents
87 * otherwise tab equals to 8 spaces
89 * separate classes with two empty lines
93 * camelCase for functions/methods
95 * UpperCase for structures/classes
97 * lowercase for namespaces/modules
99 * `UPPER_CASE` for #defines
101 * single underscore prefix for variables/functions in automatically generated
106 * enclose single statement `if` clauses in { }, specially for automatically
111 * use inlines for functions/methods which are called with high-frequency
115 * `lower_case` commands
117 * space between ( and precedent name
120 When in doubt, be consistent with the existing code.
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.)
131 * In particular, new features / changes must not introduce any sort of
132 instability when tracing.
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.
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.
142 * It's fine to add new features for only some platforms or APIs.
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
148 * Releases are tagged commits from master. There are no stable branches.
151 Backwards compatibility:
153 * Backwards binary compatibility with old traces must be always maintained: all
154 tools, including glretrace, must handle old traces without regressions.
156 * No backwards compatibility guarantees for derived data (ASCII dumps, state,
159 * There should be no gratuitous changes to command line tool interfaces, but no
160 guarantees are given.
167 There is a regression test suite under development in
168 https://github.com/apitrace/apitrace-tests .