This topic gives a high-level introduction to the Microsoft Direct3D Sample Framework.
Overview
The framework is designed to help the programmer spend less time worrying about how to create a window, how to create a device, or when to handle device events.
Here is an example main function of an application using the framework:
INT WINAPI WinMain( HINSTANCE, HINSTANCE, LPSTR, INT )
{
// Set the callback functions. These functions allow the sample framework
// to notify the application about device changes, user input, and window
// messages. The callback functions are optional, so you need only set
// them for events you are interested in.
DXUTSetCallbackDeviceCreated( OnCreateDevice );
DXUTSetCallbackDeviceReset( OnResetDevice );
DXUTSetCallbackDeviceLost( OnLostDevice );
DXUTSetCallbackDeviceDestroyed( OnDestroyDevice );
DXUTSetCallbackFrameRender( OnFrameRender );
DXUTSetCallbackFrameMove( OnFrameMove );
// Initialize the sample framework and create the desired Win32 window and
// Direct3D device for the application. Calling each of these functions is
// optional, but they allow you to set several options which control the
// behavior of the framework.
DXUTInit( TRUE, TRUE, TRUE );
DXUTCreateWindow( L"BasicHLSL" );
DXUTCreateDevice( D3DADAPTER_DEFAULT, TRUE, 640, 480 );
// Pass control to the sample framework for handling the message pump and
// dispatching render calls. The framework will call your OnFrameMove and
// OnFrameRender callback functions when there is idle time between
// handling window messages.
DXUTMainLoop();
return DXUTGetExitCode();
}
In the example code above, the framework does most of the work. It creates a window, creates a device, handles the main loop, and uses the application-supplied callback functions when events occur, such as device reset or frame render. The framework is modular, and the application can use all of the framework features or just the parts desired.
The remainder of this programming guide covers each of these steps in detail and looks at the choices the application has available to control or replace each step.
Further details on syntax and usage of functions, callback functions, structures, enumerations, and constants can be found in Sample Framework Reference.
Features
The framework provides the following services to help you create an application:
- Simplified window and device creation.
- Notification of device events (created, reset, lost, destroyed) and window events (messages, keyboard, mouse).
- Toggling between windowed and full-screen modes, and between hardware abstraction layer (HAL) and reference devices.
- High-resolution timer.
- Command-line support for automated testing.
- Device selection via dialog or application programming interface (API).
- Suite of textured graphical user interface (GUI) controls, including an Input Method Editor (IME)-enabled edit box.
- Extra miscellaneous classes, such as simple camera types.
Limitations
For ease of use, the framework supports only a single window attached to a single device. Advanced applications that need to use multiple devices simultaneously or that need to display multiple Direct3D windows are not supported by the framework. However, most typical applications should be able to use the framework.
Starting a New Project
The easiest way to start a new Microsoft Visual Studio .NET development project using the sample framework is to do the following:
- Launch the sample browser, located in the Microsoft DirectX software development kit (SDK) in the following location:
(SDK root)\Samples\SampleBrowser\
- In the browser, select an existing Direct3D sample project that will be a starting point.
- Click on the "Install Project" link next to that project to copy the Visual Studio .NET project files to a new directory location.
- You can also optionally rename the project, in which case the sample browser will change the appropriate files and source code to give the project the new name.
Changes from the Previous Sample Framework
The new framework is significantly redesigned from the sample framework that shipped in the DirectX 9.0 Summer 2003 SDK Update. The following is a list of major differences and improvements.
- Flat API design. The new framework is a set of global functions that more clearly define how the application interacts with the framework.
- Clearer naming. The device, frame, and message events have been renamed to be more easily understood.
- Modular. An application can use only parts of the framework if desired. An application can use the framework to create its own window or its own device, or it can use its own main loop.
- Better device selection. The application can fully customize the presentation parameters or behavior flags before creating the device. The new framework also has a more advanced algorithm for finding valid device settings.
- Toggling between HAL and reference devices (see Device Types). Built-in toggling support is available, and toggling can be bound to a keystroke for simplified debugging.
- Better error handling. Error handling and macros can be used by the application to display error message boxes immediately if an API is called incorrectly.
- Better multiple-monitor support. If this feature is enabled, the new framework will automatically change devices if the window is moved to a different monitor.
- GUI controls. A set of textured GUI controls features an IME-enabled edit box for use in samples, prototypes, and professional games.
- No dialog dependency on Microsoft Windows Graphics Device Interface (GDI). Unlike the previous framework, the new framework does not require any GDI dialog resources in the application.
- Late binding with DirectX. Late binding verifies that the required DirectX version is installed on the system.
- Unicode support. The new framework supports Unicode. Microsoft Windows NT-based operating systems natively support Unicode, which means that ANSI calls need to be converted to Unicode. With this and better international support, Unicode is the better choice because it will result in better performance on these operating systems. For Windows 98 and Windows Millennium Edition (Windows Me) systems, consider using the Microsoft Layer for Unicode (MSLU)
. - Documentation. The framework library functions in the Dxut.h header are documented; see Sample Framework Reference.