JMU
DXUT Basics
with Examples in C++


Prof. David Bernstein
James Madison University

Computer Science Department
bernstdh@jmu.edu


Introduction
The Process (in WinMain)
  1. Register the display callback function
  2. Initialize DXUT
  3. Create the window
  4. Create the device (i.e., the rendering engine)
  5. Start event processing
  6. Clean-up before exiting
Initialization
directx9examples/dxut/window/window.cpp (Fragment: init)
            // Initialize DXUT and create the desired Win32 window
        // and Direct3D device for the application
        //
    DXUTInit(true,  // Parse the command line
             true,  // Handle default hotkeys
                         true); // Show msgboxes

        // Setup the cursor
    DXUTSetCursorSettings(true,   // Show the cursor
                                  true ); // Clip the cursor in full screen mode

        // Create the window
    DXUTCreateWindow(L"Window"); // Title

        // Create the device/renderer
    DXUTCreateDevice(D3DADAPTER_DEFAULT,    // Adapter
                     true,                  // Windowed
                     640, 480,              // Width, Height
                     isDeviceAcceptable,    // Acceptable Callback
                     modifyDeviceSettings); // Settings Callback
        
Keyboard Callback

The Callback

directx9examples/dxut/window/window.cpp (Fragment: keyboardcallback)
        /**
 * The function that is called when a key is pressed/released
 */
void CALLBACK keyPressed(UINT nChar, bool keyDown, bool altDown, 
                                                 void* userContext )
{
}
        

Registration

directx9examples/dxut/window/window.cpp (Fragment: register-keyboard)
        
        // Register the keyboard callback
        DXUTSetCallbackKeyboard(keyPressed);
        
Mouse Callback

The Callback

directx9examples/dxut/window/window.cpp (Fragment: mousecallback)
        /**
 * The function that is called when the mouse is
 * moved or clicked
 */
void CALLBACK mouseEvent(bool leftDown, bool rightDown, bool middleDown,
                                                 bool side1Down, bool side2Down,
                                                 int wheelDelta, int x, int y, void* userContext)
{
}
        

Registration

directx9examples/dxut/window/window.cpp (Fragment: register-mouse)
        
        // Register the mouse callback
        bool includeMouseMoveEvents = true;
        DXUTSetCallbackMouse(mouseEvent, includeMouseMoveEvents);
        
Device-Related Callbacks
directx9examples/dxut/window/window.cpp (Fragment: register-device)
        
    // Register the device-reated callbacks
    DXUTSetCallbackDeviceCreated(onCreateDevice);
    DXUTSetCallbackDeviceReset(onResetDevice);
    DXUTSetCallbackDeviceLost(onLostDevice);
    DXUTSetCallbackDeviceDestroyed(onDestroyDevice);
        
Starting the Event-Loop
directx9examples/dxut/window/window.cpp (Fragment: event-loop)
        
    // Start the render loop
    DXUTMainLoop();
        
A Complete Example

That Does Nothing

directx9examples/dxut/window/window.cpp
        #include "dxstdafx.h"
#include "resource.h"

/**
 * An application that uses DXUT to create and display a window
 *
 * This application also illustrates how to use mouse and
 * keyboard callbacks
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */


/**
 * Checks to see if a device is acceptable
 *
 * @return false if the device isn't acceptable
 */
bool CALLBACK isDeviceAcceptable(D3DCAPS9* caps, D3DFORMAT adapterFormat, 
                                 D3DFORMAT backBufferFormat, bool windowed, 
                                                                 void* userContext )
{
    // Skip backbuffer formats that don't support alpha blending
    IDirect3D9* d3d = DXUTGetD3DObject(); 
    if( FAILED(d3d->CheckDeviceFormat(caps->AdapterOrdinal, caps->DeviceType,
                    adapterFormat, D3DUSAGE_QUERY_POSTPIXELSHADER_BLENDING, 
                    D3DRTYPE_TEXTURE, backBufferFormat)))
        return false;

    return true;
}



/**
 * The function that is called when a key is pressed/released
 */
void CALLBACK keyPressed(UINT nChar, bool keyDown, bool altDown, 
                                                 void* userContext )
{
}



/**
 * Modify device settings (as needed)
 *
 * Note: This function is called before a device is created
 */
bool CALLBACK modifyDeviceSettings(DXUTDeviceSettings* deviceSettings, 
                                                                   const D3DCAPS9* caps, void* userContext )
{
        // Nothing to change in this case
    return true;
}



/**
 * The function that is called when the mouse is
 * moved or clicked
 */
void CALLBACK mouseEvent(bool leftDown, bool rightDown, bool middleDown,
                                                 bool side1Down, bool side2Down,
                                                 int wheelDelta, int x, int y, void* userContext)
{
}





/**
 *  The function that is called to handle MS-Windows messages
 */
LRESULT CALLBACK MsgProc( HWND hWnd, UINT uMsg, WPARAM wParam, LPARAM lParam, 
                          bool* pbNoFurtherProcessing, void* pUserContext )
{
    return 0;
}




/**
 * The function that is called when a device is created
 *
 * Note: This is where D3DPOOL_MANAGED resources should be created
 */
HRESULT CALLBACK onCreateDevice(IDirect3DDevice9* d3dDevice, 
                                                                const D3DSURFACE_DESC* backBufferSurfaceDesc, 
                                                                void* userContext )
{
    return S_OK;
}





/**
 * The function that is called when the device is destroyed
 *
 * Note: This function should release resources created in the 
 * OnCreateDevice callback
 */
void CALLBACK onDestroyDevice(void* userContext )
{
}



/**
 * The function that is called before the call to the 
 * rendering callback
 */
void CALLBACK onFrameMove(IDirect3DDevice9* d3dDevice, 
                                                  double time, float elapsedTime, 
                                                  void* userContext )
{
}

/**
 * The function that is called when the device is lost
 *
 * Note: This function should release resources created in the 
 * OnResetDevice callback
 */
void CALLBACK onLostDevice(void* userContext)
{
}


/**
 * The function that is called when a device is created
 *
 * Note: This is where D3DPOOL_DEFAULT resources should be created
 */
HRESULT CALLBACK onResetDevice(IDirect3DDevice9* d3dDevice, 
                                const D3DSURFACE_DESC* backBufferSurfaceDesc, 
                                                                void* userContext )
{
    return S_OK;
}




/**
 * The function that is called when the scene needs to be rendered
 */
void CALLBACK paint(IDirect3DDevice9* d3dDevice, 
                                        double time, float elapsedTime, 
                                        void* userContext )
{
    HRESULT hr;

    // Clear the render target and the zbuffer 
    V(d3dDevice->Clear(0, NULL, D3DCLEAR_TARGET | D3DCLEAR_ZBUFFER, 
                           D3DCOLOR_ARGB(0, 0, 0, 0), 1.0f, 0) );

    // Render the scene
    if( SUCCEEDED(d3dDevice->BeginScene()))
    {
                //
            // Insert Rendering Code Here
            //

        V(d3dDevice->EndScene());
    }
}




/**
 * The entry-point of the application
 */
INT WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
{

    // Register the device-reated callbacks
    DXUTSetCallbackDeviceCreated(onCreateDevice);
    DXUTSetCallbackDeviceReset(onResetDevice);
    DXUTSetCallbackDeviceLost(onLostDevice);
    DXUTSetCallbackDeviceDestroyed(onDestroyDevice);

        // Register message callbacks
    DXUTSetCallbackMsgProc(MsgProc);

        // Register the pre-rendering callback
    DXUTSetCallbackFrameMove(onFrameMove);


        // Register the render/display callback
    DXUTSetCallbackFrameRender(paint);


        // Register the keyboard callback
        DXUTSetCallbackKeyboard(keyPressed);
   

        // Register the mouse callback
        bool includeMouseMoveEvents = true;
        DXUTSetCallbackMouse(mouseEvent, includeMouseMoveEvents);
   


        //
    // Insert application initialization here
        //


    // Initialize DXUT and create the desired Win32 window
        // and Direct3D device for the application
        //
    DXUTInit(true,  // Parse the command line
             true,  // Handle default hotkeys
                         true); // Show msgboxes

        // Setup the cursor
    DXUTSetCursorSettings(true,   // Show the cursor
                                  true ); // Clip the cursor in full screen mode

        // Create the window
    DXUTCreateWindow(L"Window"); // Title

        // Create the device/renderer
    DXUTCreateDevice(D3DADAPTER_DEFAULT,    // Adapter
                     true,                  // Windowed
                     640, 480,              // Width, Height
                     isDeviceAcceptable,    // Acceptable Callback
                     modifyDeviceSettings); // Settings Callback


    // Start the render loop
    DXUTMainLoop();

        //
    // Insert application clean-up here
        //

    return DXUTGetExitCode();
}