From 04b70cf9a1c8295dfc357947d3895f19c7f8bac9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Fonseca?= Date: Wed, 27 Mar 2013 11:09:46 +0000 Subject: [PATCH] Add a high-level overview of apitrace source tree. --- DEVELOPMENT.markdown | 73 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/DEVELOPMENT.markdown b/DEVELOPMENT.markdown index 5af6ed6..a777b53 100644 --- a/DEVELOPMENT.markdown +++ b/DEVELOPMENT.markdown @@ -1,3 +1,76 @@ +Overview +========= + +Although focus has and still is on graphical APIs, apitrace has an +infrastructure to trace generic APIs: + + * The APIs types and calls are specified in Python files in spec + + * 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 to disk, 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. + +There are several main layers in apitrace. Too many to show in a single graph, +so below only those relevant for GL are shown: + + specs + ^ + | + dispatch <-------------- glws + ^ ^ + | / + helpers <--- glstate / + ^ ^ ^ / + / \ | / + / \ | / + trace retrace | / + ^ ^ | / + / \ | / + gltrace glretrace + / | \ + / | \ + / | \ + / | \ + / | \ + glxtrace wgltrace cgltrace + +And 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 array/blob/etc, and other. + 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 ============ -- 2.43.0