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