+Overview
+=========
+
+Although focus was and still is on graphical APIs, apitrace has a
+generic infrastructure to trace any kind of API:
+
+ * the APIs types and calls are specified in Python files in specs
+ sub-directory;
+
+ * there is a type hierarchy in specs/stdapi.py, capable of representing
+ most types in C language, and additional semantic metadata
+
+ * Python scripts generate C++ code to trace and serialize calls parameters to
+ a file, and vice-versa.
+
+ * Visitor software design pattern is used to navigate over the types.
+
+ * Template design pattern is use so that any step of code generation can be
+ overriden by derived classes, allowing to easily handle cases that need
+ special treatment without sacrifycing code reuse.
+
+apitrace's architecture is composed of several layers. Too many to show in a
+single graph, so only those relevant for OpenGL API are shown below:
+
+ specs
+ ^
+ |
+ dispatch <-------------- glws
+ ^ ^
+ | /
+ helpers <--- glstate /
+ ^ ^ ^ /
+ / \ | /
+ / \ | /
+ trace retrace | /
+ ^ ^ | /
+ / \ | /
+ gltrace glretrace
+ / | \
+ / | \
+ / | \
+ / | \
+ / | \
+ glxtrace wgltrace cgltrace
+
+Here is a quick synopsis of what the layers do:
+
+ * specs -- specification of the API, expressed in a Python class hierarchy
+
+ * dispatch -- runtime dispatch of calls to DLLs (open the DLL, get the symbol
+ address, and call it passing all arguments as-is)
+
+ * helpers -- helper functions to determine sizes of arrays, blobs, etc. It
+ often needs to dispatch calls to give the answers.
+
+ * trace -- generate C++ code for tracing an API based on its spec
+
+ * gltrace -- specialization of the tracing generation for GL API, with extra
+ code to generate
+
+ * glxtrace, wgltrace, cgltrace -- specialization of the tracing code for the
+ GLX, WGL, and CGL APIs.
+
+ * retrace -- generate C++ code to interpret calls from trace, based on the
+ API's spec
+
+ * glretrace -- specialization of the retrace code for the GL API
+
+ * glstate -- code to dump OpenGL state to a JSON file
+
+ * glws -- abstraction of the window system specific APIs (GXL, WGL, CGL), to
+ enable cross-platform portability of glretrace
+
+
Coding Style
============
-These are guidelines for new code. Some of existing hasn't been updated to
-these conventions yet.
+These are guidelines for new code. Admittedly some of the existing code hasn't
+been updated to follow these conventions yet.
Whitespace (all languages):
Feature development:
* Existing features in master branch should not degrade at any time, for any
- platform. (Unless it is not widely used and there is agreement.)
+ platform. (Unless they are seldom used or redundant and there is agreement.)
+
+ * In particular, new features / changes must not introduce any sort of
+ instability when tracing.
+
+ While application developers and driver developers may be able to
+ workaround quirks in apitrace, we want to be able to obtain traces from
+ non-technical end-users with minimal intervention.
+
+ This implies that tracing should not make any non-standard assumptions, and
+ care must be taken to ensure the tracing code is robust against invalid
+ parameters, multiple threads, etc.
-* It's fine to add new features for only some platforms.
+* It's fine to add new features for only some platforms or APIs.
-* Non-trivial changes should be staged in a branch, to enable peer-review and
- regression testing. Branch should be deleted once code has been merged.
+* Non-trivial changes should be staged in a branch, to allow review and
+ regression testing. Feature branches should be deleted once they have been
+ merged.
* Releases are tagged commits from master. There are no stable branches.
* No backwards compatibility guarantees for derived data (ASCII dumps, state,
images, etc).
-* There should be no gratuitous change to command line tool interfaces, but no
+* There should be no gratuitous changes to command line tool interfaces, but no
guarantees are given.
projects / apitrace / blobdiff