What is GfxTrace?
=================

GfxTrace is an open source trace-capture-and-replay tool. It is designed to be 
trivially extendible and is open sourced to allow any developer to quickly 
extend the tool to support their particular application.


Supported Platforms 
===================

Although GfxTrace is designed to easily support any platform where OpenGL (or 
OpenGL ES) is available, it currently only supports Windows. This should change
as time and resources permit.


Building
========

To build GfxTrace, you will need:

- Visual Studio 2010 (or later)
- Python 2.7 (or later)

1) Open the solution file gfxTrace.sln
2) Select debug or release
3) Build


Capturing a Trace
=================

To capture a trace, you will need to inject inception.dll into your process. 
This is most trivially achieved using the provided eztrace.exe (built during
the previous step).

With eztrace.exe you simply run:

	eztrace.exe -p <full path to your executable> -w <working directory for \
	your executable> -o <output trace> <arguments to your executable>

You then press the capture key (by default F11) to capture a single frame 
trace. The application will pause briefly while capturing the trace, then 
should resume. 

To see more arguments to eztrace (for example to specify where to write the 
trace file or to specify a different hotkey to capture a trace), run 
eztrace.exe without additional arguments.


Replaying a Trace
=================

A trace can be replayed with the provided glReplayer.exe tool:

	glReplayer.exe <path to trace file>

Similarly, traces can be explored (this is very early, currently only supports
viewing texture objects) by running:

	glExplorer.exe <path to trace file>


Extending GfxTrace
==================

The bulk of GfxTrace is generated through a pair of python files:
	common/codegen/functionhooks.py    # Contains list of functions to 
	                                   # generate, along with markup
	common/codegen/codegen.py          # Contains code to actually generate our
	                                   # generated C source files

To extend GfxTrace, you simply add an entry point to 
functionhooks.Hooks.GlobalState.ContextState. For example, the C entry point 
for glScissor looks like this:

WINGDIAPI void APIENTRY glScissor (GLint x, GLint y, GLsizei width, GLsizei 
                                   height);

In ContextState, there is a python definition that looks like this:
	def glScissor(GLint_x, GLint_y, GLsizei_width, GLsizei_height): pass

This causes code to be spit out in several places, specifically:
- Function hooking / recording / forwarding
- Command replay
- State accumulation

Please note that this section of GfxTrace is massively in flux right now--the 
current design requires most "interesting" entry points to perform manual_state
recording, and that's annoying. I'm moving to a design that should largely
eliminate manual state recording--and should largely be auto-generated from the
official spec files. Stay tuned for more details.

That's about it!