D3DSpy
Microsoft DirectX 9.0 SDK Update (October 2004)

D3DSpy


D3DSpy is a utility 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:

The communication between the elements is shown here.

Network

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 box:

Startup screen

The first option, local mode, runs both the target program and the D3DSpy user interface on the same computer.

The second and third options, remote mode, runs the D3DSpy the target program and the user interface on different computers. Remote mode supports monitoring of Direct3D programs running full-screen.

In the Startup box, choose the mode you want.

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

Looking For Host dialog box

To show the Start Target Program dialog box, click Connect.

Start Target dialog box

In the Start Target Program dialog box, enter the target name or, in the Path to target executable box, enter the path, either by typing it or by clicking Browse and selecting it. In addition, you can enter the initial working directory for the target program, or any command-line arguments that you want to pass to the target program.

When the target program starts, it must 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:

  1. Click the Copy DLL from option button, and enter the path to the proxy DLL by typing it in or by clicking Browse and selecting it. Note that the proxy DLL is stored in the software development kit (SDK) as D3dspy9.dll but is renamed to D3d9.dll while it is copied.
  2. Select the Delete copied DLL after target program exits check box. You will generally want to to do this because, if the proxy DLL is not deleted, the next time you run the target program it will connect to the proxy DLL and attempt to use D3DSpy, which might not be what you want.
  3. Press OK. The DLL will be copied and the target program and launched automatically. Alternatively, you can start the target program manually (perhaps under a debugger or development environment). If you start the target program manually, however, 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:

Main User Interface

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


© 2004 Microsoft Corporation. All rights reserved.
Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center.