DXETool for Transform Writers

You can use the DXETool application to test new transforms you have written. This application performs the following three key tasks.

It searches your system registry for all properly registered transforms each time it executes.
It enables you to use and debug your transform without requiring you to write a separate application to do so.
It can access your transform's property page, so you can check that it is working properly.

DXETool also enables you to check that your transform is correctly implementing dithering, alpha blending, and surface picking.

Before using DXETool, it might be helpful to familiarize yourself with DXETool by running it and using several transforms. It is located in the Dxmedia/Bin/X86 folder of the Microsoft® DirectX® Media Software Development Kit (SDK). For information about the features of this application, see DXETool for Transform Users.

You can configure Microsoft Visual Studio® to register your transform dynamic-link library (DLL) after it has successfully linked. In the Workspace of your project, go to the Project menu and click Settings. Click the Custom Build tab, and type the following in the Build Command(s) list.

regsvr32 /s /c "$(TargetPath)"

Click OK and relink your DLL. Visual Studio should register your transform before finishing the build. If the build is successful but the transform still does not show up on DXETool's list of transforms, you can register the transform from an MS-DOS prompt. Use Regsvr32.exe in the C:/Windows/System directory, with the path to the DLL file as a parameter. The system will respond with a dialog box that indicates whether the registration was successful.

The first few times you use your DLL code, you may want to be using a debugging application. Using DXETool as your debugger requires some special setup in Visual Studio. On the Visual Studio Project menu, click Settings. On the dialog box that appears, select the Debug tab. On the line "Executable for debug session:", type the path to your copy of Dxetool.exe. You also can click the arrow button on that line which will enable you to browse for the path. Click OK to save the changes. Set breakpoints in your code and start a debug session by clicking Build from the Visual Studio menu, then Start Debug and Go. DXETool should start executing, and Visual Studio should enter its debugger mode. To check that all is working correctly, select a transform that has a breakpoint in its OnExecute method. Selecting the transform should cause control to jump from DXETool to the Visual Studio debugger.

This article takes you through the following steps.

Step 1: Testing the Transform
Step 2: Viewing the Property Page
Step 3: Surface Picking
Step 4: Measuring Performance

Step 1: Testing the Transform

After selecting your transform from the list and loading the required surfaces or meshes, you should see your transform effect in DXETool's image region.

When the transform is selected, DXETool checks to see which interfaces and custom properties your transform supports. Within your code, this is determined by whether the transform derives from the IDXEffect interface and which of the DXTMISCFLAGS you have set. Any options that are not supported are unavailable in DXETool. Because all options are set within a given transform, you can check that they are properly supported by checking that all the correct controls are enabled.

If you have a one-step transform, you should see the resulting effect immediately. If your transform supports the Progress property, you can move the Progress slider and watch the effect. Clicking one of the Progress slider's arrows plays the transform either forward or backward in the Duration number of seconds. Only transforms that inherit from IDXEffect will have these capabilities.

Step 2: Viewing the Property Page

If your transform supports some custom properties, you have probably built a property page for it. You can access this property page with the Settings button on the left side of the DXETool dialog box. If you didn't build a property page, this button is unavailable.

Make some changes to these properties to check that they produce the expected results on your output.

Step 3: Surface Picking

If your image transform implements surface picking through the IDXSurfacePick interface, you can test this with DXETool. Just click on the image window and watch the status bar at the bottom of your screen.

For a surface pick event, one of the following messages are printed in the DXETool status bar.

Hit Input A at (x,y)
Hit Input B at (x,y)
No Surface Hit
Hit the output, but maps to no input

For a surface that was successfully hit, the values these messages return are the x-coordinate and y-coordinate of the pixel that you clicked on the input surface. Even if the image is rotated or flipped, it should map properly to the source. A "No Surface Hit" message indicates that you clicked outside the bounds of any image, which can happen if the DXETool image region is bigger than the image. The last message in the previous list is often returned by procedural surfaces because they don't have input surfaces.

For three-dimensional (3-D) meshes, there are two possible messages. If you miss the object when you click in the image window, you will get a "No pickable object found" message. If your click hits the object, DXETool indicates which face of which mesh builder object you hit.

Step 4: Measuring Performance

After you get your transform working correctly, you may need to optimize it for speed. DXETool helps you optimize by calculating the frame rate of any animation. This is calculated by clicking the arrow buttons on the Progress slider.

When the Perf Test check box on the left side of the dialog box is selected for an animation, the transform calculates its output but does not render the output to the screen. This can help you to isolate the performance of your transform and to determine how different options, such as alpha blending, contribute to the frame rate.

To get constant frame rate updates, you can use the Repeat and Bounce check boxes.