diff options
| -rw-r--r-- | docs/BUGS.markdown | 41 | ||||
| -rw-r--r-- | docs/Dalvik.markdown | 9 | ||||
| -rw-r--r-- | docs/USAGE.markdown | 56 |
3 files changed, 37 insertions, 69 deletions
diff --git a/docs/BUGS.markdown b/docs/BUGS.markdown index 1f7ac128..2c35bac7 100644 --- a/docs/BUGS.markdown +++ b/docs/BUGS.markdown @@ -1,5 +1,4 @@ -Reporting bugs -============== +# Reporting bugs # Before reporting, please skim through the known issues below. @@ -11,8 +10,7 @@ always including the following information: * OpenGL/D3D driver name and version -Known issues -============ +# Known issues # These are issues that the developers are already aware of, but for which there is no immediate plan to address them, because either: @@ -34,8 +32,7 @@ if: sooner rather than later. -Tracing -------- +## Tracing ## * Fake calls may be emitted in the trace, in order to provide complete information for retracing. The typical case is OpenGL vertex arrays in user @@ -63,8 +60,7 @@ Tracing * On MacOSX, the internal OpenGL calls done by GLU are not traced yet. -Retracing ---------- +## Retracing ## * Replaying can take substantially more CPU due to the overhead of reading the trace file from disk. @@ -95,15 +91,13 @@ Retracing share state. This is by far the most common case though. -GUI ---- +## GUI ## * Not all types of arguments can be edited. -Proprietary/confidential applications -===================================== +# Proprietary/confidential applications # Issues should be preferably filed on github to facilitate collaborative development and for future reference. @@ -129,8 +123,7 @@ Failure to do so will render the apitrace authors powerless to address the issue. -Attachments -=========== +# Attachments # github issue tracker doesn't support attachments. @@ -147,8 +140,7 @@ further reduce their size when attaching/uploading by compressing with [XZ](http://tukaani.org/xz/) or [7-Zip](http://www.7-zip.org/). -Bugs on tracing -=============== +# Bugs on tracing # For bugs that happen while tracing (e.g., crashes while tracing the application, or incorrect traces) please: @@ -158,8 +150,7 @@ application, or incorrect traces) please: * describe how you were using it when the issue happened. -Bugs on retracing/GUI -===================== +# Bugs on retracing/GUI # For bugs on retracing (e.g. crashes when retracing the application, incorrect inconsistent rendering, or viewing with the GUI) please: @@ -169,15 +160,13 @@ incorrect inconsistent rendering, or viewing with the GUI) please: * describe the results you got, and what results you were expecting. -Obtaining stack back-traces -=========================== +# Obtaining stack back-traces # Please rebuild apitrace with debugging information, by passing `-DCMAKE_BUILD_TYPE=Debug` to cmake, or editing its value in `CMakeCache.txt` and rebuilding. -Linux ------ +## Linux ## To obtain a stack back-trace, run the application with gdb from a terminal: @@ -203,8 +192,7 @@ See also more detailed and Distro specific instructions: * http://live.gnome.org/GettingTraces -Mac OS X --------- +## Mac OS X ## Before you can debug you must first enable developer mode on the machine if you haven't done so before: @@ -220,9 +208,8 @@ To trace an application inside LLDB and obtain a stack backtrace invoke apitrace (lldb) quit -Windows -------- +## Windows ## See: -* https://developer.mozilla.org/en/how_to_get_a_stacktrace_with_windbg +* <https://developer.mozilla.org/en/how_to_get_a_stacktrace_with_windbg> diff --git a/docs/Dalvik.markdown b/docs/Dalvik.markdown index 4564e3b8..559c6d10 100644 --- a/docs/Dalvik.markdown +++ b/docs/Dalvik.markdown @@ -1,5 +1,4 @@ -Tracing Dalvik VM (Java) applications on Android -================================================ +# Tracing Dalvik VM (Java) applications on Android # Android's Java virtual machine, Dalvik, runs as a system service (started at bootup by `init`) and Java applications are run by forks of the initial @@ -11,8 +10,7 @@ The following discussion assumes that tracing library is copied to '/data': adb push /path/to/apitrace/build/wrappers/egltrace.so /data -Tracing on Android 4.0 and newer --------------------------------- +## Tracing on Android 4.0 and newer ## Starting from Android 4.0 (Ice Cream Sandwich) release, Dalvik supports running designated processes with wrappers, in which case a new Java VM is @@ -43,8 +41,7 @@ are saved into '/data/data/$PROCNAME' directory by default: adb shell rm /data/data/$PROCNAME/$PROCNAME.trace -Tracing on Android pre-4.0 --------------------------- +## Tracing on Android pre-4.0 ## `LD_PRELOAD` is supported since Android 2.3 "Gingerbread" and newer, but injecting tracing library globally is no longer supported, as the diff --git a/docs/USAGE.markdown b/docs/USAGE.markdown index 28d481cc..3e819568 100644 --- a/docs/USAGE.markdown +++ b/docs/USAGE.markdown @@ -1,5 +1,4 @@ -Basic usage -=========== +# Basic usage # Run the application you want to trace as @@ -34,8 +33,7 @@ If you run into problems [check if it is a known issue and file an issue if not](BUGS.markdown). -Basic GUI usage -=============== +# Basic GUI usage # Start the GUI as @@ -49,8 +47,7 @@ Press `Ctrl-T` to see per-frame thumbnails. And while inspecting frame calls, press again `Ctrl-T` to see per-draw call thumbnails. -Backtrace Capturing -=================== +# Backtrace Capturing # apitrace now has the ability to capture the call stack to an OpenGL call on certain OSes (only Android and Linux at the moment). This can be helpful in @@ -64,12 +61,10 @@ call prefixes you wish to capture stack traces to. The backtrace data will show up in qapitrace in the bottom section as a new tab. -Advanced command line usage -=========================== +# Advanced command line usage # -Call sets ---------- +## Call sets ## Several tools take `CALLSET` arguments, e.g: @@ -97,8 +92,7 @@ The call syntax is very flexible. Here are a few examples: -Tracing manually ----------------- +## Tracing manually ## ### Linux ### @@ -204,8 +198,7 @@ solves this issue by injecting a DLL `dxgitrace.dll` and patching all modules to hook only the APIs of interest. -Emitting annotations to the trace ---------------------------------- +## Emitting annotations to the trace ## From within OpenGL applications you can embed annotations in the trace file through the following extensions: @@ -277,8 +270,7 @@ For Direct3D applications you can follow the standard procedure for `ID3DUserDefinedAnnotation::SetMarker` for D3D11.1 applications. -Dump OpenGL state at a particular call ----------------------------------- +## Dump OpenGL state at a particular call ## You can get a dump of the bound OpenGL state at call 12345 by doing: @@ -291,8 +283,7 @@ You can compare two state dumps by doing: apitrace diff-state 12345.json 67890.json -Comparing two traces side by side ---------------------------------- +## Comparing two traces side by side ## apitrace diff trace1.trace trace2.trace @@ -300,8 +291,7 @@ This works only on Unices, and it will truncate the traces due to performance limitations. -Recording a video with FFmpeg/Libav ------------------------------------ +## Recording a video with FFmpeg/Libav ## You can make a video of the output with FFmpeg by doing @@ -313,8 +303,8 @@ or Libav (which replaces FFmpeg on recent Debian/Ubuntu distros) doing apitrace dump-images -o - application.trace \ | avconv -r 30 -f image2pipe -vcodec ppm -i - -vcodec mpeg4 -y output.mp4 -Recording a video with gstreamer --------------------------------------- + +## Recording a video with gstreamer ## You can make a video of the output with gstreamer by doing @@ -322,8 +312,8 @@ You can make a video of the output with gstreamer by doing ! videoparse format=rgb width=1920 height=1080 ! queue ! ffmpegcolorspace ! queue \ ! vaapiupload direct-rendering=0 ! queue ! vaapiencodeh264 ! filesink location=xxx.264 -Trimming a trace ----------------- + +## Trimming a trace ## You can truncate a trace by doing: @@ -340,8 +330,7 @@ necessary for a given frame or call: apitrace trim --auto --frames=12345 -o trimed.trace application.trace -Profiling a trace ------------------ +## Profiling a trace ## You can perform gpu and cpu profiling with the command line options: @@ -361,14 +350,12 @@ For example, to record all profiling data and utilise the per shader script: apitrace replay --pgpu --pcpu --ppd foo.trace | ./scripts/profileshader.py -Advanced usage for OpenGL implementors -====================================== +# Advanced usage for OpenGL implementers # There are several advanced usage examples meant for OpenGL implementors. -Regression testing ------------------- +## Regression testing ## These are the steps to create a regression test-suite around **apitrace**: @@ -387,8 +374,7 @@ These are the steps to create a regression test-suite around **apitrace**: apitrace diff-images --output summary.html /path/to/reference/snapshots/ /path/to/test/snapshots/ -Automated git-bisection ------------------------ +## Automated git-bisection ## With tracecheck.py it is possible to automate git bisect and pinpoint the commit responsible for a regression. @@ -439,8 +425,7 @@ driver is unintentionally loaded due to a missing symbol in the DRI driver, or another runtime fault). -Side by side retracing ----------------------- +## Side by side retracing ## In order to determine which draw call a regression first manifests one could generate snapshots for every draw call, using the `-S` option. That is, however, @@ -468,8 +453,7 @@ Or on Windows: python scripts\retracediff.py --retrace \path\to\glretrace.exe --ref-env TRACE_LIBGL=\path\to\reference\opengl32.dll application.trace -Advanced GUI usage -================== +# Advanced GUI usage # qapitrace has rudimentary support for replaying traces on a remote target device. This can be useful, for example, when developing for an |