+### Windows ###
+
+When tracing third-party applications, you can identify the target
+application's main executable, either by:
+
+* right clicking on the application's icon in the _Start Menu_, choose
+ _Properties_, and see the _Target_ field;
+
+* or by starting the application, run Windows Task Manager (taskmgr.exe), right
+ click on the application name in the _Applications_ tab, choose _Go To Process_,
+ note the highlighted _Image Name_, and search it on `C:\Program Files` or
+ `C:\Program Files (x86)`.
+
+On 64 bits Windows, you'll need to determine ether the application is a 64 bits
+or 32 bits. 32 bits applications will have a `*32` suffix in the _Image Name_
+column of the _Processes_ tab of _Windows Task Manager_ window.
+
+Copy the appropriate `opengl32.dll`, `d3d8.dll`, or `d3d9.dll` from the
+wrappers directory to the directory with the application you want to trace.
+Then run the application as usual.
+
+You can specify the written trace filename by setting the `TRACE_FILE`
+environment variable before running.
+
+For D3D10 and higher you really must use `apitrace trace -a DXGI ...`. This is
+because D3D10-11 API span many DLLs which depend on each other, and once a DLL
+with a given name is loaded Windows will reuse it for LoadLibrary calls of the
+same name, causing internal calls to be traced erroneously. `apitrace trace`
+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
+---------------------------------
+
+From whitin OpenGL applications you can embed annotations in the trace file
+through the following extensions:
+
+* [`GL_KHR_debug`](http://www.opengl.org/registry/specs/KHR/debug.txt)
+
+* [`GL_ARB_debug_output`](http://www.opengl.org/registry/specs/ARB/debug_output.txt)
+
+* [`GL_AMD_debug_output`](http://www.opengl.org/registry/specs/AMD/debug_output.txt)
+
+* [`GL_GREMEDY_string_marker`](http://www.opengl.org/registry/specs/GREMEDY/string_marker.txt)
+
+* [`GL_GREMEDY_frame_terminator`](http://www.opengl.org/registry/specs/GREMEDY/frame_terminator.txt)
+
+**apitrace** will advertise and intercept these OpenGL extensions regardless
+of whether the OpenGL implementation supports them or not. So all you have
+to do is to use these extensions when available, and you can be sure they
+will be available when tracing inside **apitrace**.
+
+For example, if you use [GLEW](http://glew.sourceforge.net/) to dynamically
+detect and use OpenGL extensions, you could easily accomplish this by doing:
+
+ void foo() {
+
+ if (GLEW_KHR_debug) {
+ glPushDebugGroup(GL_DEBUG_SOURCE_APPLICATION, 0, -1, __FUNCTION__);
+ }
+
+ ...
+
+ if (GLEW_KHR_debug) {
+ glDebugMessageInsert(GL_DEBUG_SOURCE_APPLICATION, GL_DEBUG_TYPE_OTHER,
+ 0, GL_DEBUG_SEVERITY_MEDIUM, -1, "bla bla");
+ }
+
+ ...
+
+ if (GLEW_KHR_debug) {
+ glPopDebugGroup();
+ }
+
+ }
+
+This has the added advantage of working equally well with other OpenGL debugging tools.
+
+Also, provided that the OpenGL implementation supports `GL_KHR_debug`, labels
+defined via glObjectLabel() , and the labels of several objects (textures,
+framebuffers, samplers, etc. ) will appear in the GUI state dumps, in the
+parameters tab.
+
+
+For OpenGL ES applications you can embed annotations in the trace file through the
+[`GL_KHR_debug`](http://www.khronos.org/registry/gles/extensions/KHR/debug.txt) or
+[`GL_EXT_debug_marker`](http://www.khronos.org/registry/gles/extensions/EXT/EXT_debug_marker.txt)
+extensions.
+
+
+For Direct3D applications you can follow the standard procedure for
+[adding user defined events to Visual Studio Graphics Debugger / PIX](http://msdn.microsoft.com/en-us/library/vstudio/hh873200.aspx):
+
+- `D3DPERF_BeginEvent`, `D3DPERF_EndEvent`, and `D3DPERF_SetMarker` for D3D9 applications.
+
+- `ID3DUserDefinedAnnotation::BeginEvent`,
+ `ID3DUserDefinedAnnotation::EndEvent`, and
+ `ID3DUserDefinedAnnotation::SetMarker` for D3D11.1 applications.
+
+
+Dump OpenGL state at a particular call
+----------------------------------
+
+You can get a dump of the bound OpenGL state at call 12345 by doing:
+
+ apitrace replay -D 12345 application.trace > 12345.json