D3DSpy

D3DSpy is a tool that monitors function calls to the Microsoft?Direct3D® application programming interface (API), and shows a representation of Direct3D's internal state. This is valuable when writing a Direct3D program, or when trying to understand why a program is behaving as it is. D3DSpy can also be used to improve the performance of a Direct3D program by identifying redundant or inefficient use of the Direct3D API.

D3DSpy can monitor a program running on the same computer as the D3DSpy user interface or on a different computer, communicating by way of Microsoft DirectPlay? D3DSpy works by providing a proxy dynamic-link library (DLL), which the application connects to and treats like the real D3d9.dll. It intercepts all the Direct3D calls and gathers various information before making the real Direct3D call.

Elements of D3DSpy

The elements of D3DSpy are defined as follows:

• Target program. This is the program that you want to monitor with D3DSpy. The program must use Direct3D version 9.0 to work with D3DSpy.
• Proxy DLL (D3dspy9.dll). This is a DLL that the target program connects to as though it were the real D3d9.dll. The proxy DLL gathers call information and communicates with the main D3DSpy user interface.
• Main D3DSpy user interface (D3dspy.exe). This program provides the user interface that lets the user monitor the state of Direct3D, step through calls to Direct3D, and set breakpoints. It also acts as the network host when running D3DSpy across the network.
• D3DSpy remote helper (D3dspy.exe). When running D3DSpy across the network, D3DSpy can optionally be run on the target computer in the role of a remote helper program. This enables the user to send requests from the main D3DSpy user interface to the remote helper to launch the target program on the remote computer.

The communication between the elements is shown here.

Running D3DSpy on a Direct3D Program

To start using D3DSpy, choose Start, All Programs, Microsoft DirectX 9.0 SDK, DirectX Utilities, D3DSpy. You will see the startup dialog:

Choose the mode you want. Local mode runs both the D3DSpy user interface and the target program on the same computer. Remote mode runs the D3DSpy user interface and the target program on two different computers. Remote mode is designed to support monitoring Direct3D programs running in full-screen mode.

1. To run in local mode, click the first option button (radio button).
2. To run in remote mode:
   • Click the second option button (to run the target program on a remote computer).

     - or -

   • Click the third option button (to run the D3DSpy user interface on a remote computer).

Press Continue. If you are running in remote mode, the D3DSpy Remote Helper will show the Looking For Host dialog box.

Click the Start button to show the Start Target Program dialog box:

Enter the path to the target program, either by typing or by clicking the Browse button. In addition, you can enter the target name, the initial working directory for the target program, and any command-line arguments that you want to pass to the target program.

When the target program starts, it needs to connect to the D3DSpy proxy DLL rather than to the real D3d9.dll. The easiest way to do this is to have D3DSpy copy the proxy DLL to the same directory as the target program. To do this, click the Copy DLL from option button, and fill in the text box with the path to the proxy DLL by typing or by clicking the Browse button. Note that the proxy DLL is stored in the software development kit (SDK) as D3dspy9.dll, but it will be renamed to D3d9.dll while it is copied. You will generally want to select the Delete copied DLL after target program exits check box. If the proxy DLL is not deleted, then the next time you run the target program it will connect to the proxy DLL and attempt to use D3DSpy, which may not be what you want.

Once you hit OK from the Start Target Program dialog box, the DLL will be copied and target program should be launched automatically. If you want, you can start the target program manually (perhaps under a debugger or development environment). If you start the target program manually, you are responsible for having the proxy DLL copied and named properly.

When the target program starts, it should connect to the proxy DLL, which will then connect to the main D3DSpy user interface (and the helper program, if it is present). At this point, the main D3DSpy dialog box will appear:

The main dialog box has tabs allowing navigation between several pages, each of which shows a different function of D3DSpy or a different section of the current state of Direct3D as the program runs.

Interacting with D3DSpy from a program

D3DSpy works on any program that uses Direct3D version 9.0, without special modification. However, you can add D3DSpy-specific code to your program to achieve several useful results, as follows:

To find out if D3DSpy is currently running on a program, add the following code to the program.

    typedef VOID (*D3DSPYBREAK)();
    HMODULE hModule;
    D3DSPYBREAK D3DSpyBreak;
    hModule = LoadLibrary( TEXT("d3d9.dll") );
    if( hModule != NULL )
    {
        D3DSpyBreak = (D3DSPYBREAK)GetProcAddress( hModule, "D3DSpyBreak" );
        if( D3DSpyBreak != NULL )
        {
            // D3DSpy is monitoring this program.
        }
        else
        {
            // D3DSpy is not monitoring this program.
        }
    }

To block D3DSpy from monitoring a program, add the following code to the program.

    typedef VOID (*DISABLED3DSPY)();
    HMODULE hModule;
    DISABLED3DSPY DisableD3DSpy;
    hModule = LoadLibrary( TEXT("d3d9.dll") );
    if( hModule != NULL )
    {
        DisableD3DSpy = (DISABLED3DSPY)GetProcAddress( hModule, "DisableD3DSpy" );
        if( DisableD3DSpy != NULL )
        {
            // D3DSpy is monitoring this program.
            DisableD3DSpy();
        }
        else
        {
            // D3DSpy is not monitoring this program.
        }
    }

To generate a breakpoint in D3DSpy at a certain point in your program, add the following code to the program.

    typedef VOID (*D3DSPYBREAK)();
    HMODULE hModule;
    D3DSPYBREAK D3DSpyBreak;
    hModule = LoadLibrary( TEXT("d3d9.dll") );
    if( hModule != NULL )
    {
        D3DSpyBreak = (D3DSPYBREAK)GetProcAddress( hModule, "D3DSpyBreak" );
        if( D3DSpyBreak != NULL )
        {
            // D3DSpy is monitoring this program.
            D3DSpyBreak();
        }
        else
        {
            // D3DSpy is not monitoring this program.
        }
    }