1Design of the GLES Tracing Library
2
3Code Runtime Behavior:
4
5    Initialization:
6    
7    egl_display_t::initialize() calls initEglTraceLevel() to figure out whether tracing should be
8    enabled. Currently, the shell properties "debug.egl.trace" and "debug.egl.debug_proc" together
9    control whether tracing should be enabled for a certain process. If tracing is enabled, this
10    calls GLTrace_start() to start the trace server.
11    
12    Note that initEglTraceLevel() is also called from early_egl_init(), but that happens in the
13    context of the zygote, so that invocation has no effect.
14    
15    egl_display_t::initialize() then calls setGLHooksThreadSpecific() where we set the thread
16    specific gl_hooks structure to point to the trace implementation. From this point on, every
17    GLES call is redirected to the trace implementation.
18    
19    Application runtime:
20
21    While the application is running, all its GLES calls are directly routed to their corresponding
22    trace implementation.
23
24    For EGL calls, the trace library provides a bunch of functions that must be explicitly called
25    from the EGL library. These functions are declared in glestrace.h
26
27    Application shutdown:
28
29    Currently, the application is killed when the user stops tracing from the frontend GUI. We need
30    to explore if a more graceful method of stopping the application, or detaching tracing from the
31    application is required.
32
33Code Structure:
34
35    glestrace.h declares all the hooks exposed by libglestrace. These are used by EGL/egl.cpp and
36    EGL/eglApi.cpp to initialize the trace library, and to inform the library of EGL calls.
37
38    All GL calls are present in GLES_Trace/src/gltrace_api.cpp. This file is generated by the
39    GLES_Trace/src/genapi.py script. The structure of all the functions looks like this:
40
41            void GLTrace_glFunction(args) {
42                // declare a protobuf
43                // copy arguments into the protobuf
44                // call the original GLES function
45                // if there is a return value, save it into the protobuf
46                // fixup the protobuf if necessary
47                // transport the protobuf to the host
48            }
49
50    The fixupGLMessage() call does any custom processing of the protobuf based on the GLES call.
51    This typically amounts to copying the data corresponding to input or output pointers.
52