About Shadesmith The Shadesmith fragment program debugger was written by Tim
Purcell and Pradeep Sen. It provides an automatic way to debug
fragment programs. The debugger runs on the hardware -- no software
emulation! The values for the watches you set are what the hardware
is using. In addition to setting watch variables, you can edit your
fragment program and see the changes happen without quitting and
restarting your program. Finally, the debugger displays the values of
a given watch register at every pixel. We allow the user to write
custom visualization code... making scale and bias of register
Currently we are on our first release - a limited alpha release. Once
we get feedback from people using the system, we plan to open a full
open source project.
To download the latest copy of Shadesmith and a demo application (ZIP file, 256KB)
The debugger currently works only under Windows. We currently support
debugging fragment programs written in either ARB_FRAGMENT_PROGRAM or
The debugger is simple to use. It works by replacing a user-specified
draw routine and corresponding fragment program with its own. This
means it requires a function pointer to your draw routine, and the
program ID of the fragment program to be debugged.
First, put shadesmith.h, shadesmith.lib, and shadesmith.dll in your main
project directory (alternately, put the .dll in your system/win32 directory).
You'll need to include shadesmith.h in the C file
that calls your draw routine. Second, wrap the debug statement around
the draw function you would like to debug, like the following:
Note 1: The debugger currently creates its own context to run
your program in. That means any GL state that is set up outside the
main draw loop will not be passed along when the debugger is turned
on. We currently require all relevant GL state to be set within the
draw loop being debugged (ie glClearColor, vertex arrays, etc.) This
will be fixed in the next version of the code.
Note 2: The debugger performs glReadPixels at the end of the
draw routine being debugged. The debugger will fail if you change
contexts within the draw routine being debugged, or perform multiple
rendering passes within the same draw routine.
That's it! When you begin rendering with the debugger enabled, your
ap. will run as usual, but a debug window will pop up as well. We have
provided demo.exe as a simple program that uses the debugger. It has
both an ARB path (for ATI cards) and an NVidia specific path.
The fragment program debugger allows you to see the fragment program being
executed by the GPU, step through it and watch the intermediate values produced.
Every register used in the fragment program for every pixel is tracked. These
values can be seen via mouseover in a watch window. The watch window displays
the contents of the register as an image, with a user defined visualization
applied to it. The watch window shows the values in full precision, as returned
by the hardware. Custom visualization allows you to scale and bias the display
of the data since often a picture is more useful than register values (ie a register
holding the results of a surface that has been diffusely lit before specularity is applied).
We provide the ability to single step through the fragment program, both forwards and
backwards. This makes it easy to see exactly what changes the given line of code is causing.
Finally, we allow for modifications to the fragment program to occur during debugging.
It is as simple as switching to edit mode, typing the new lines of code, and sending it
back down to the hardware. No more recompiling and rerunning your code... see the results
The Shadesmith fragment program debugger has a graphical user interface that allows you
to visualize the values stored in registers in the hardware. First, let's look at the main debugger window
which contains the editor:
As you can see, the editor displays the fragment program that is being debugged. The margin on
the left shows the instruction line number and the position of the current step of
execution in the debugger. Remember that the line the arrow indicates is the one which
is about to be executed, so the result register has not been written to yet. Now let's look
at the tools on the toolbar.
Button 1 is the revert button, which when clicked will bring back the fragment program
as it was originally loaded. Buttons 2-8 should all be familiar to windows users, although
some of them are disabled or not fully working for this alpha release. Buttons 9 and 10 step
the fragment program backward or forward respectively (which can also be done with the F9 and F11
keys). Button 11 enables writing to allow editting of the fragment program. When the code
has been updated, button 12 downloads the new code to the hardware for execution. If there
is an error in this code, the program will try to highlight the portion of the code that
is causing problems.
Now let's take a look at the visualization window, shown below.
The dropdown combo box labeled 1 allows
you to select the register or variable you want to watch. Buttons 2,3, and 4 work in the same
manner as that of the main debug window and allow you to edit the fragment program used
to visualize the variable (3),
bind it to the hardware (4), or revert to the standard fragment program (2). This fragment program
can be used to scale and bias the values of the variable to make debugging easier and is editted
in textbox 5. When we shrink the combo box, the watch window looks like:
You can see the checkboxes labeled 2 which allow you to control the components that are being
viewed. Finally, the values in 3 are the values of the pixel probe which return the value
stored at the register for a specific pixel as you move the mouse over the image.
Known Issues and Bugs
Shadesmith is in an alpha version, so there is currently a list of oustanding bugs
and issues. Some of these include:
For an up-to-date list of bugs, please check the current bug list
in this distribution.
- Context initialization. As mentioned above, we create our own
context for the debugger and we do not currently initialize it with
all the necessary draw state. This is forth coming. Instead, we
currently require all relevant draw state to be included within the
- 512x512 debug window only. This is hard coded into the system.
Smaller size applications will work fine, larger ones will have
- No breakpoints. We currently break at the top of a fragment
program and require single stepping.
Send bug reports to tpurcell at graphics dot stanford_edu and
psen at graphics dot stanford_edu