DESIGN.txt 3.9 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980
  1. Design of the GLES Tracing Library
  2. Code Runtime Behavior:
  3. Initialization:
  4. egl_display_t::initialize() calls initEglTraceLevel() to figure out whether tracing should be
  5. enabled. Currently, the shell properties "debug.egl.trace" and "debug.egl.debug_proc" together
  6. control whether tracing should be enabled for a certain process. If tracing is enabled, this
  7. calls GLTrace_start() to start the trace server.
  8. egl_display_t::initialize() then calls setGLHooksThreadSpecific() where we set the thread
  9. specific gl_hooks structure to point to the trace implementation. From this point on, every
  10. GLES call is redirected to the trace implementation.
  11. Application runtime:
  12. While the application is running, all its GLES calls are directly routed to their corresponding
  13. trace implementation.
  14. For EGL calls, the trace library provides a bunch of functions that must be explicitly called
  15. from the EGL library. These functions are declared in glestrace.h
  16. Application shutdown:
  17. Currently, the application is killed when the user stops tracing from the frontend GUI. We need
  18. to explore if a more graceful method of stopping the application, or detaching tracing from the
  19. application is required.
  20. Enabling tracing while the application is running:
  21. In order to allow tracing of an already running application, we allow DdmServer to enable
  22. OpenGL tracing. In such a case, the application already has its GL hooks set up to point to the
  23. real GL implementation, and we need to switch them to point to the trace implementation.
  24. This is achieved by checking whether tracing should be enabled at every eglSwap call.
  25. (Note: We were already checking for tracing at every eglSwap, the only change now is that
  26. the tracing could actually be ON/OFF at runtime - earlier it was set once and never changed).
  27. If eglSwap detects that tracing should be enabled now, then it performs the following steps:
  28. - switch the gl hooks to point to the trace implementation.
  29. - call trace eglMakeCurrent to indicate that there is now a new context that is current.
  30. - continue on with tracing the eglSwap call.
  31. This switches the hooks to point to the trace implementation only for the current context.
  32. But the other contexts have their gl hooks updated when they perform eglMakeCurrent.
  33. The GLTrace version of eglMakeCurrent now has to be updated to allow switching to a context
  34. it may not know of. In such a case, it creates a context matching the version that it is now
  35. switching to.
  36. Disabling tracing:
  37. We disable tracing under two conditions:
  38. - stop tracing request from DdmServer
  39. - gltrace transport gets disconnected from the host.
  40. In either case, both actions simply disable the tracing flag. The current context gets its
  41. gl hooks restored in the next eglSwap, and the other traced contexts get their gl hooks
  42. restored when they perform a eglMakeCurrent.
  43. Code Structure:
  44. glestrace.h declares all the hooks exposed by libglestrace. These are used by EGL/egl.cpp and
  45. EGL/eglApi.cpp to initialize the trace library, and to inform the library of EGL calls.
  46. All GL calls are present in GLES_Trace/src/gltrace_api.cpp. This file is generated by the
  47. GLES_Trace/src/genapi.py script. The structure of all the functions looks like this:
  48. void GLTrace_glFunction(args) {
  49. // declare a protobuf
  50. // copy arguments into the protobuf
  51. // call the original GLES function
  52. // if there is a return value, save it into the protobuf
  53. // fixup the protobuf if necessary
  54. // transport the protobuf to the host
  55. }
  56. The fixupGLMessage() call does any custom processing of the protobuf based on the GLES call.
  57. This typically amounts to copying the data corresponding to input or output pointers.