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 contents simple.

Release History

Release notes

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.

Download

To download the latest copy of Shadesmith and a demo application (ZIP file, 256KB) click here.

Usage

The debugger currently works only under Windows. We currently support debugging fragment programs written in either ARB_FRAGMENT_PROGRAM or NV_FRAGMENT_PROGRAM. 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:

#if DEBUG shadesmithFP(display, prog_id); #else display(); #endif

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.

Features

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 immediately.

User interface

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:

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 draw loop.
512x512 debug window only. This is hard coded into the system. Smaller size applications will work fine, larger ones will have problems.
No breakpoints. We currently break at the top of a fragment program and require single stepping.

For an up-to-date list of bugs, please check the current bug list in this distribution.

Send bug reports to tpurcell at graphics dot stanford_edu and psen at graphics dot stanford_edu