Tutorial 1: Initialize a Direct3D Application
Microsoft DirectX 9.0 SDK Update (October 2004)

Tutorial 1: Initialize a Direct3D Application


The goal of this tutorial is to initialize a Direct3D application and render an image to the screen. This is the minimum code necessary to start up a Direct3D application. The tutorial is divided into these tasks:

Setup

Preparation

Open CreateDirect3DWindow.cpp inside of your favorite editor.

Description

CreateDirect3DWindow.cpp contains a few functions with the source code demonstrated in this tutorial. You can follow along and compare the tutorial steps with the functions in the source code.

Duration

This tutorial can take as few as 5-10 minutes if you simply follow the steps, but could take longer if you build the tutorial and use the debugger to step through each of the function calls watching the arguments and the return types.

Task 1: Create a Direct3D Object

Preparation

Locate the function InitD3D() in CreateDirect3DWindow.cpp.

Description

Use Direct3DCreate9 to create a pointer to an IDirect3D9 interface. The Microsoft Direct3D object is a Component Object Model (COM) interface. All COM interfaces start with a capital "I", as in "IDirect3D9".

Solution

IDirect3D9* g_pD3D = NULL;
if(NULL == (g_pD3D = Direct3DCreate9(D3D_SDK_VERSION)))
{
  MessageBox(0, L"Direct3DCreate9() failed", L"InitD3D()", MB_OK);
  return E_FAIL;
}

Direct3DCreate9 takes only one parameter, D3D_SDK_VERSION. This version identifier is passed to this function to ensure that an application is built against the correct DirectX header files. If the value passed into Direct3DCreate9 does not match D3D_SDK_VERSION the call will fail, and the function will return NULL. If the function is successful, the return value will be a valid pointer to an IDirect3D9 object.

The MessageBox World Wide Web link function displays a message box if the object creation fails.

Task 2: Choose the Presentation Settings

Preparation

This code is located the function InitD3D() in CreateDirect3DWindow.cpp.

Description

Initialize the presentation settings which control how the rendered output may be sent to the display. We want to set four default conditions:

Solution

D3DPRESENT_PARAMETERS d3dpp = {0};
d3dpp.Windowed = TRUE;
d3dpp.BackBufferCount = 1;
d3dpp.BackBufferFormat = D3DFMT_UNKNOWN;
d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD;

Task 3: Create a Direct3D Device

Preparation

This code is located the function InitD3D() in CreateDirect3DWindow.cpp.

Description

Use IDirect3D9::CreateDevice to create a Direct3D device.

The most commonly used interface in Direct3D is IDirect3DDevice9. It is the main rendering interface and is commonly called the Direct3D device or render device. The Direct3D device represents a single graphics adapter configured to the application's needs. The device represents the video adapter so we need to tell Direct3D how much work the adapter should do and how much work Direct3D should do.

We have two choices to make that determine where our data will be processed. The vertex data is processed either in software or hardware by setting the vertex processing type. This tutorial uses software vertex processing (specified with D3DCREATE_SOFTWARE_VERTEXPROCESSING), which is best to choose when trying to debug something. The rendering can be done in software of hardware by setting the device type. This tutorial uses hardware accelearation by specifying a HAL device using D3DDEVTYPE_HAL. For more information, see Device Types.

Solution

IDirect3DDevice9*   g_pd3dDevice = NULL;
if(FAILED(g_pD3D->CreateDevice( 
  D3DADAPTER_DEFAULT,                  // Primary display adapter ID.
  D3DDEVTYPE_HAL,                      // Use a HAL device.
  hWnd,                                // Window handle.
  D3DCREATE_SOFTWARE_VERTEXPROCESSING, // Vertex processing mode.
  &d3dpp,                              // Presentation parameters.
  &g_pd3dDevice                        // Device to create.
  )))
{
  MessageBox(0, L"Direct3DCreate9() failed", L"InitD3D()", MB_OK);
      return E_FAIL;
}

Task 4: Clear the Back Buffer

Preparation

This code is located the function Render() in CreateDirect3DWindow.cpp.

Description

Call IDirect3DDevice9::Clear to clear the back buffer

By default the back buffer is the current render target. When setting up the presentation parameters for the device, we specified the swap effect to discard the front buffer data. This means after a swap, the back buffer will contain random data, so it needs to be cleared to a known state. The know state could be a single color value, set with the D3DCOLOR_XRGB macro. Color channel data varies from 0 to 255.

Solution

g_pd3dDevice->Clear( 
  0, 
  NULL,                     // Clear the entire viewport.
  D3DCLEAR_TARGET,          // What surface in the view port to clear. 
  D3DCOLOR_XRGB(0, 0, 255), // Color to clear with 
  0,                        // Z-Buffer (Not Used)
  0                         // Stencil data (Not Used)
  );

Task 5: Render to the Back Buffer

Preparation

This code is located the function Render() in CreateDirect3DWindow.cpp.

Description

Add IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene calls.

All custom render code should be added to an application between IDirect3DDevice9::BeginScene and IDirect3DDevice9::EndScene.

Solution

if(SUCCEEDED(g_pd3dDevice->BeginScene()))
{
     // Custom rendering code belongs here...
	
     g_pd3dDevice->EndScene();
} 
Tip  

Use the SUCCEEDED macro to check the return code. If IDirect3DDevice9::BeginScene fails, an application should not call any rendering methods and should not call IDirect3DDevice9::EndScene.

Task 6: Display the Output

Preparation

This code is located the function Render() in CreateDirect3DWindow.cpp.

Description

Call IDirect3DDevice9::Present to send the render calls to Direct3D.

After the scene is rendered to the back buffer, swap the back buffer to the front buffer to display the image. The entire back buffer (or any rectangular portion of it) can be swapped with the front buffer (or any rectangular portion of it).

Solution

g_pd3dDevice->Present( 
  NULL, // Pointer to the source RECT.
  NULL, // Pointer to the destination RECT.
  NULL, // Destination window for present.
  NULL  // Minimal set of pixels to be updated.
  )

Task 7: Releasing COM objects

Preparation

This code is located the function Shutdown() in CreateDirect3DWindow.cpp.

Description

When exiting the application, use the SAFE_RELEASE macro to clean up any COM objects that we have created.

An applications shuts down after a Windows quit message (WM_QUIT) is received by the message processing loop. In response to this message, the application needs to release all COM objects that it created. COM objects should be released in the opposite order from which they were created.

Solution

if(g_pd3dDevice != NULL)
{
    g_pd3dDevice>Release();
    g_pd3dDevice = NULL;
}

if(g_pD3D != NULL)
{
    g_pD3D->Release();
    g_pD3D = NULL;
}

Running the SAFE_RELEASE macro checks the pointer to make sure it is valid before releasing it and setting it to NULL. This code could be replaced with:

    SAFE_RELEASE(g_pd3dDevice);
    SAFE_RELEASE(g_pD3D);


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