Sample Framework Overview
Microsoft DirectX 9.0 SDK Update (October 2004)

Sample Framework Overview


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:

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:

  1. Launch the sample browser, located in the Microsoft DirectX software development kit (SDK) in the following location:

    (SDK root)\Samples\SampleBrowser\

  2. In the browser, select an existing Direct3D sample project that will be a starting point.
  3. Click on the "Install Project" link next to that project to copy the Visual Studio .NET project files to a new directory location.
  4. 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.



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