Jump to content

  • Log In with Google      Sign In   
  • Create Account

We're offering banner ads on our site from just $5!

1. Details HERE. 2. GDNet+ Subscriptions HERE. 3. Ad upload HERE.


Like
0Likes
Dislike

Direct3D Immediate-Mode Tutorial

By Colin McCartney | Published Sep 23 1999 03:35 AM in DirectX and XNA

static d3dval hres device return hresult surface function #define
If you find this article contains errors or problems rendering it unreadable (missing images or files, mangled code, improper text formatting, etc) please contact the editor so corrections can be made. Thank you for helping us improve this resource

(Editor's Note - this article requires additional formatting work and is incomplete)

To create a Windows-based Direct3D Immediate-Mode application, you create DirectDraw and Direct3D objects, set render states, fill execute buffers, and execute those buffers.

This section includes a simple Immediate-Mode application that draws a single, rotating, Gouraud-shaded triangle (please note: you will need to have the current version of DirectX installed in order to view the triangle). The triangle is drawn in a window whose size is fixed. For code clarity, we have chosen not to address a number of issues in this sample. For example, full screen operation, resizing the window, and texture mapping are not included. Furthermore, we have not included some optimizations when their inclusion would have made the code more obscure. Code comments highlight the places in which we did not implement a common optimization.
Definitions, Prototypes, and Globals

This section contains the definitions, function prototypes, global variables, constants, and other structural underpinnings for the Imsample.c code sample.
Header and Includes

/***********************************************************************
 *
 * File :   	imsample.c
 *
 * Author : 	Colin D. C. McCartney
 *
 * Date :   	1/7/97
 *
 * Version :	V1.1
 *
 **********************************************************************/

/***********************************************************************
 *
 * Include files
 *
 **********************************************************************/

#define  INITGUID
#include <windows.h>
#include <math.h>
#include <assert.h>
#include <ddraw.h>
#include <d3d.h>

#include "resource.h"

Constants

// Class name for this application's window class.

#define WINDOW_CLASSNAME  	"D3DSample1Class"

// Title for the application's window.

#define WINDOW_TITLE      	"D3D Sample 1"

// String to be displayed when the application is paused.

#define PAUSED_STRING 		"Paused"

// Half height of the view window.

#define HALF_HEIGHT   		D3DVAL(0.5)

// Front and back clipping planes.

#define FRONT_CLIP        	D3DVAL(1.0)
#define BACK_CLIP     		D3DVAL(1000.0)

// Fixed window size.

#define WINDOW_WIDTH      	320
#define WINDOW_HEIGHT 		200

// Maximum length of the chosen device name and description of the
// chosen Direct3D device.

#define MAX_DEVICE_NAME   	256
#define MAX_DEVICE_DESC   	256

// Amount to rotate per frame.

#define M_PI              	3.14159265359
#define M_2PI         		6.28318530718
#define ROTATE_ANGLE_DELTA	(M_2PI / 300.0)

// Execute buffer contents

#define NUM_VERTICES      	3
#define NUM_INSTRUCTIONS  	6
#define NUM_STATES        	7
#define NUM_PROCESSVERTICES   1
#define NUM_TRIANGLES 		1

Macros

// Extract the error code from an HRESULT

#define CODEFROMHRESULT(hRes) ((hRes) & 0x0000FFFF)

#ifdef _DEBUG
#define ASSERT(x)   	assert(x)
#else
#define ASSERT(x)
#endif

// Used to keep the compiler from issuing warnings about any unused 
// parameters.

#define USE_PARAM(x)	(x) = (x)

Global Variables

// Application instance handle (set in WinMain).

static HINSTANCE       		hAppInstance          	= NULL;

// Running in debug mode?

static BOOL                	fDebug                	= FALSE;

// Is the application active?

static BOOL                	fActive           		= TRUE;

// Has the application been suspended?

static BOOL                	fSuspended            	= FALSE;

// DirectDraw interfaces

static LPDIRECTDRAW        	lpdd                  	= NULL;
static LPDIRECTDRAWSURFACE 	lpddPrimary       		= NULL;
static LPDIRECTDRAWSURFACE 	lpddDevice            	= NULL;
static LPDIRECTDRAWSURFACE 	lpddZBuffer       		= NULL;
static LPDIRECTDRAWPALETTE 	lpddPalette       		= NULL;

// Direct3D interfaces

static LPDIRECT3D          	lpd3d             		= NULL;
static LPDIRECT3DDEVICE    	lpd3dDevice       		= NULL;
static LPDIRECT3DMATERIAL  	lpd3dMaterial     		= NULL;
static LPDIRECT3DMATERIAL  	lpd3dBackgroundMaterial   = NULL;
static LPDIRECT3DVIEWPORT  	lpd3dViewport     		= NULL;
static LPDIRECT3DLIGHT 		lpd3dLight            	= NULL;
static LPDIRECT3DEXECUTEBUFFER lpd3dExecuteBuffer    	= NULL;

// Direct3D handles

static D3DMATRIXHANDLE 		hd3dWorldMatrix   		= 0;
static D3DMATRIXHANDLE 		hd3dViewMatrix        	= 0;
static D3DMATRIXHANDLE 		hd3dProjMatrix        	= 0;
static D3DMATERIALHANDLE   	hd3dSurfaceMaterial   	= 0;
static D3DMATERIALHANDLE   	hd3dBackgroundMaterial	= 0;

// Globals used for selecting the Direct3D device. They are
// globals because this makes it easy for the enumeration callback
// function to read and write from them.

static BOOL                	fDeviceFound          	= FALSE;
static DWORD           		dwDeviceBitDepth      	= 0;
static GUID                	guidDevice;
static char                	szDeviceName[MAX_DEVICE_NAME];
static char                	szDeviceDesc[MAX_DEVICE_DESC];
static D3DDEVICEDESC   		d3dHWDeviceDesc;
static D3DDEVICEDESC   		d3dSWDeviceDesc;

// The screen coordinates of the client area of the window. This
// rectangle defines the destination into which we blit to update
// the client area of the window with the results of the 3D rendering.

static RECT                	rDstRect;

// This rectangle defines the portion of the rendering target surface
// into which we render. The top-left coordinates of this rectangle
// are always zero; the right and bottom coordinates give the size of 
// the viewport.

static RECT                	rSrcRect;

// Angle of rotation of the world matrix.

static double              	dAngleOfRotation      	= 0.0;

// Predefined transformations.

static D3DMATRIX d3dWorldMatrix =
{
	D3DVAL( 1.0), D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 1.0), D3DVAL( 0.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 1.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 1.0)
};

static D3DMATRIX d3dViewMatrix =
{
	D3DVAL( 1.0), D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 1.0), D3DVAL( 0.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 1.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 5.0), D3DVAL( 1.0)
};

static D3DMATRIX d3dProjMatrix =
{
	D3DVAL( 2.0), D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 2.0), D3DVAL( 0.0), D3DVAL( 0.0),
	D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL( 1.0), D3DVAL( 1.0),
	D3DVAL( 0.0), D3DVAL( 0.0), D3DVAL(-1.0), D3DVAL( 0.0)
};


Function Prototypes

static void   		ReportError(HWND hwnd, int nMessage, 
                              	HRESULT hRes);
static void   		FatalError(HWND hwnd, int nMessage, HRESULT hRes);

static DWORD      	BitDepthToFlags(DWORD dwBitDepth);
static DWORD      	FlagsToBitDepth(DWORD dwFlags);

static void   		SetPerspectiveProjection(LPD3DMATRIX lpd3dMatrix,
                                     		double  	dHalfHeight,
                                     		double  	dFrontClipping,
                                     		double  	dBackClipping);
static void   		SetRotationAboutY(LPD3DMATRIX lpd3dMatrix,
                                    	double  	dAngleOfRotation);

static HRESULT    	CreateDirect3D(HWND hwnd);
static HRESULT    	ReleaseDirect3D(void);

static HRESULT    	CreatePrimary(HWND hwnd);
static HRESULT    	RestorePrimary(void);
static HRESULT    	ReleasePrimary(void);

static HRESULT WINAPI EnumDeviceCallback(LPGUID   	lpGUID, 
                                  	LPSTR   		lpszDeviceDesc,
                                  	LPSTR   		lpszDeviceName,
                                  	LPD3DDEVICEDESC lpd3dHWDeviceDesc,
                                  	LPD3DDEVICEDESC lpd3dSWDeviceDesc,
                                  	LPVOID      	lpUserArg);
static HRESULT    	ChooseDevice(void);

static HRESULT    	CreateDevice(DWORD dwWidth, DWORD dwHeight);
static HRESULT    	RestoreDevice(void);
static HRESULT    	ReleaseDevice(void);

static LRESULT    	RestoreSurfaces(void);

static HRESULT    	FillExecuteBuffer(void);
static HRESULT    	CreateScene(void);
static HRESULT    	ReleaseScene(void);
static HRESULT    	AnimateScene(void);

static HRESULT    	UpdateViewport(void);

static HRESULT    	RenderScene(void);
static HRESULT    	DoFrame(void);
static void   		PaintSuspended(HWND hwnd, HDC hdc);

static LRESULT    	OnMove(HWND hwnd, int x, int y);
static LRESULT    	OnSize(HWND hwnd, int w, int h);
static LRESULT    	OnPaint(HWND hwnd, HDC hdc, LPPAINTSTRUCT lpps);
static LRESULT    	OnIdle(HWND hwnd);

LRESULT CALLBACK  	WndProc(HWND hwnd, UINT msg,
                          	WPARAM wParam, LPARAM lParam);
int PASCAL        	WinMain(HINSTANCE hInstance, 
                          	HINSTANCE hPrevInstance,
                          	LPSTR lpszCommandLine, int cmdShow);

Enumerating Direct3D Devices

The first thing a Direct3D application should do is enumerate the available Direct3D device drivers. The most important API element in this job is IDirect3D::EnumDevices.

This section contains the ChooseDevice function that selects among the available Direct3D devices and the EnumDeviceCallback function that implements the selection mechanism.
This sample application does not demonstrate the enumeration of display modes, which you will need to do if your application supports full-screen rendering modes. To enumerate the display modes, call the IDirectDraw3::EnumDisplayModes method.

Enumeration Callback Function

The EnumDeviceCallback function is invoked for each Direct3D device installed on the system. For each device we retrieve its identifying GUID, a name and description, a description of its hardware and software capabilities, and an unused user argument.

The EnumDeviceCallback function uses the following algorithm to choose an appropriate Direct3D device:
  • Discard any devices which don't match the current display depth.
  • Discard any devices which can't do Gouraud-shaded triangles.
  • If a hardware device is found which matches 1) and 2) use it. However, if we are running in debug mode we will skip hardware.
  • Otherwise favor Mono/Ramp mode software renderers over RGB ones as, at least until MMX is widespread, Mono will be faster.
This callback function is invoked by the ChooseDevice enumeration function, which is described in Enumeration Function.

Note that the first parameter passed to this callback function, lpGUID, is NULL for the primary device. All other devices should have a non-NULL pointer. You should consider saving the actual GUID for the device you choose, not the pointer to the GUID, in case the pointer is accidentally corrupted.

static HRESULT WINAPI
EnumDeviceCallback(LPGUID      	lpGUID, 
           		LPSTR   		lpszDeviceDesc,
           		LPSTR   		lpszDeviceName,
           		LPD3DDEVICEDESC lpd3dHWDeviceDesc,
           		LPD3DDEVICEDESC lpd3dSWDeviceDesc,
           		LPVOID      	lpUserArg)
{
	BOOL        	fIsHardware;
	LPD3DDEVICEDESC lpd3dDeviceDesc;

    	// Call the USE_PARAM macro on the unused parameter to
    	// avoid compiler warnings.

	USE_PARAM(lpUserArg);

    	// If there is no hardware support the color model is zero.
    
	fIsHardware 	= (0 != lpd3dHWDeviceDesc->dcmColorModel);
	lpd3dDeviceDesc = (fIsHardware ? lpd3dHWDeviceDesc :
                             		lpd3dSWDeviceDesc);

    	// If we are in debug mode and this is a hardware device,
    	// skip it.
    
	if (fDebug && fIsHardware)
    	return D3DENUMRET_OK;

    	// Does the device render at the depth we want?
    
	if (0 == (lpd3dDeviceDesc->dwDeviceRenderBitDepth & 
          	dwDeviceBitDepth))
	{
            	// If not, skip this device.
        
    	return D3DENUMRET_OK;
	}

    	// The device must support Gouraud-shaded triangles.
    
	if (D3DCOLOR_MONO == lpd3dDeviceDesc->dcmColorModel)
	{
    	if (!(lpd3dDeviceDesc->dpcTriCaps.dwShadeCaps & 
          	D3DPSHADECAPS_COLORGOURAUDMONO))
    	{
                    	// No Gouraud shading. Skip this device.
   	     
        	return D3DENUMRET_OK;
    	}
	}
	else
	{
    	if (!(lpd3dDeviceDesc->dpcTriCaps.dwShadeCaps & 
          	D3DPSHADECAPS_COLORGOURAUDRGB))
    	{
                    	// No Gouraud shading. Skip this device.
   	     
        	return D3DENUMRET_OK;
    	}
	}

	if (!fIsHardware && fDeviceFound && 
   		(D3DCOLOR_RGB == lpd3dDeviceDesc->dcmColorModel))
	{
            	// If this is software RGB and we already have found 
            	// a software monochromatic renderer, we are not 
            	// interested. Skip this device.
        
    	return D3DENUMRET_OK;
	}

    	// This is a device we are interested in. Save the details.
    
	fDeviceFound = TRUE;
	CopyMemory(&guidDevice, lpGUID, sizeof(GUID));
	strcpy(szDeviceDesc, lpszDeviceDesc);
	strcpy(szDeviceName, lpszDeviceName);
	CopyMemory(&d3dHWDeviceDesc, lpd3dHWDeviceDesc, 
       		sizeof(D3DDEVICEDESC));
	CopyMemory(&d3dSWDeviceDesc, lpd3dSWDeviceDesc, 
       		sizeof(D3DDEVICEDESC));

    	// If this is a hardware device, we have found 
    	// what we are looking for.
    
	if (fIsHardware)
    	return D3DENUMRET_CANCEL;

    	// Otherwise, keep looking.
    
	return D3DENUMRET_OK;
}

Enumeration Function

The ChooseDevice function invokes the EnumDeviceCallback function , which is described in Enumeration Callback Function.

static HRESULT
ChooseDevice(void)
{
	DDSURFACEDESC ddsd;
	HRESULT   	hRes;

	ASSERT(NULL != lpd3d);
	ASSERT(NULL != lpddPrimary);

    	// Since we are running in a window, we will not be changing the 
    	// screen depth; therefore, the pixel format of the rendering 
    	// target must match the pixel format of the current primary 
    	// surface. This means that we need to determine the pixel 
    	// format of the primary surface.
    
	ZeroMemory(&ddsd, sizeof(ddsd));
	ddsd.dwSize = sizeof(ddsd);
	hRes = lpddPrimary->lpVtbl->GetSurfaceDesc(lpddPrimary, &ddsd);
	if (FAILED(hRes))
    	return hRes;

	dwDeviceBitDepth = 
    	BitDepthToFlags(ddsd.ddpfPixelFormat.dwRGBBitCount);

    	// Enumerate the devices and pick one.

	fDeviceFound = FALSE;
	hRes = lpd3d->lpVtbl->EnumDevices(lpd3d, EnumDeviceCallback, 
                                  	&fDeviceFound);
	if (FAILED(hRes))
    	return hRes;

	if (!fDeviceFound)
	{
            	// No suitable device was found. We cannot allow 
            	// device-creation to continue.

    	return DDERR_NOTFOUND;
	}

	return DD_OK;
}

Creating Objects and Interfaces

This section contains functions that create the primary DirectDraw surface, a DirectDrawClipper object, a Direct3D object, and a Direct3DDevice.
Creating the Primary Surface and Clipper Object

The CreatePrimary function creates the primary surface (representing the desktop) and creates and attaches a clipper object. If necessary, this function also creates a palette.

static HRESULT
CreatePrimary(HWND hwnd)
{
	HRESULT     		hRes;
	DDSURFACEDESC   	ddsd;
	LPDIRECTDRAWCLIPPER lpddClipper;
	HDC         		hdc;
	int         		i;
	PALETTEENTRY    	peColorTable[256];

	ASSERT(NULL != hwnd);
	ASSERT(NULL != lpdd);
	ASSERT(NULL == lpddPrimary);
	ASSERT(NULL == lpddPalette);

	// Create the primary surface.
    
	ZeroMemory(&ddsd, sizeof(ddsd));
	ddsd.dwSize 		= sizeof(ddsd);
	ddsd.dwFlags    	= DDSD_CAPS;
	ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
	hRes = lpdd->lpVtbl->CreateSurface(lpdd, &ddsd, &lpddPrimary, NULL);
	if (FAILED(hRes))
    	return hRes;

	// Create the clipper. We bind the application's window to the
	// clipper and attach it to the primary. This ensures that when we
	// blit from the rendering surface to the primary we don't write
	// outside the visible region of the window.
    
	hRes = DirectDrawCreateClipper(0, &lpddClipper, NULL);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpddClipper->lpVtbl->SetHWnd(lpddClipper, 0, hwnd);
	if (FAILED(hRes))
	{
    	lpddClipper->lpVtbl->Release(lpddClipper);
    	return hRes;
	}
	hRes = lpddPrimary->lpVtbl->SetClipper(lpddPrimary, lpddClipper);
	if (FAILED(hRes))
	{
    	lpddClipper->lpVtbl->Release(lpddClipper);
    	return hRes;
	}

	// We release the clipper interface after attaching it to the 
	// surface because we don't need to use it again. The surface 
	// holds a reference to the clipper when it has been attached. 
	// The clipper will therefore be released automatically when the 
	// surface is released.
    
	lpddClipper->lpVtbl->Release(lpddClipper);

	// If the primary surface is palettized, the device will be, too. 
	// (The device surface must have the same pixel format as the 
	// current primary surface if we want to double buffer with 
	// DirectDraw.) Therefore, if the primary surface is palettized we 
	// need to create a palette and attach it to the primary surface 
	// (and to the device surface when we create it).
    
	ZeroMemory(&ddsd, sizeof(ddsd));
	ddsd.dwSize = sizeof(ddsd);
	hRes = lpddPrimary->lpVtbl->GetSurfaceDesc(lpddPrimary, &ddsd);
	if (FAILED(hRes))
    	return hRes;
	if (ddsd.ddpfPixelFormat.dwFlags & DDPF_PALETTEINDEXED8)
	{
	// Initializing the palette correctly is essential. Since we are
	// running in a window, we must not change the top ten and bottom 
	// ten static colors. Therefore, we copy them from the system 
	// palette and mark them as read only (D3DPAL_READONLY). The middle 
	// 236 entries are free for use by Direct3D so we mark them free 
	// (D3DPAL_FREE).

	// NOTE: In order that the palette entries are correctly
	// allocated it is essential that the free entries are
	// also marked reserved to GDI (PC_RESERVED).

	// NOTE: We don't need to specify the palette caps flag
	// DDPCAPS_INITIALIZE. This flag is obsolete. CreatePalette
	// must be given a valid palette-entry array and always
	// initializes from it.
        
    	hdc = GetDC(NULL);
    	GetSystemPaletteEntries(hdc, 0, 256, peColorTable);
    	ReleaseDC(NULL, hdc);

    	for (i = 0; i < 10; i++)
        	peColorTable[i].peFlags = D3DPAL_READONLY;
    	for (i = 10; i < 246; i++)
        	peColorTable[i].peFlags = D3DPAL_FREE | PC_RESERVED;
    	for (i = 246; i < 256; i++)
        	peColorTable[i].peFlags = D3DPAL_READONLY;
    	hRes = lpdd->lpVtbl->CreatePalette(lpdd,
        	DDPCAPS_8BIT, peColorTable, &lpddPalette, NULL);

    	if (FAILED(hRes))
        	return hRes;

    	hRes = lpddPrimary->lpVtbl->SetPalette(lpddPrimary, 
            	lpddPalette);
        	return hRes;
	}

	return DD_OK;
}

Creating the Direct3D Object

The CreateDirect3D function creates the DirectDraw (Direct3D) driver objects and retrieves the COM interfaces for communicating with these objects. This function calls three crucial methods: DirectDrawCreate, to create the DirectDraw object, IDirectDraw3::SetCooperativeLevel, to determine whether the application will run in full-screen or windowed mode, and IDirectDraw::QueryInterface to retrieve a pointer to the Direct3D interface.

static HRESULT
CreateDirect3D(HWND hwnd)
{
	HRESULT hRes;

	ASSERT(NULL == lpdd);
	ASSERT(NULL == lpd3d);

	// Create the DirectDraw/3D driver object and get the DirectDraw
	// interface to that object.
    
	hRes = DirectDrawCreate(NULL, &lpdd, NULL);
	if (FAILED(hRes))
    	return hRes;

	// Since we are running in a window, set the cooperative level to 
	// normal. Also, to ensure that the palette is realized correctly,
	// we need to pass the window handle of the main window.
    
	hRes = lpdd->lpVtbl->SetCooperativeLevel(lpdd, hwnd, DDSCL_NORMAL);
	if (FAILED(hRes))
    	return hRes;

    	// Retrieve the Direct3D interface to the DirectDraw/3D driver 
    	// object.
    
	hRes = lpdd->lpVtbl->QueryInterface(lpdd, &IID_IDirect3D, &lpd3d);
	if (FAILED(hRes))
    	return hRes;

	return DD_OK;
}

Creating the Direct3D Device

The CreateDevice function creates an instance of the Direct3D device we chose earlier, using the specified width and height.

This function handles all aspects of the device creation, including choosing the surface-memory type, creating the device surface, creating the z-buffer (if necessary), and attaching the palette (if required). If you create a z-buffer, you must do so before creating an IDirect3DDevice interface.

static HRESULT
CreateDevice(DWORD dwWidth, DWORD dwHeight)
{
	LPD3DDEVICEDESC lpd3dDeviceDesc;
	DWORD   		dwDeviceMemType;
	DWORD   		dwZBufferMemType;
	DDSURFACEDESC   ddsd;
	HRESULT 		hRes;
	DWORD   		dwZBufferBitDepth;

	ASSERT(NULL != lpdd);
	ASSERT(NULL != lpd3d);
	ASSERT(NULL != lpddPrimary);
	ASSERT(NULL == lpddDevice);
	ASSERT(NULL == lpd3dDevice);

	// Determine the kind of memory (system or video) from which the 
	// device surface should be allocated.
    
	if (0 != d3dHWDeviceDesc.dcmColorModel)
	{
    	lpd3dDeviceDesc = &d3dHWDeviceDesc;

    	// Device has a hardware rasterizer. Currently this means that
    	// the device surface must be in video memory.
        
    	dwDeviceMemType  = DDSCAPS_VIDEOMEMORY;
    	dwZBufferMemType = DDSCAPS_VIDEOMEMORY;
	}
	else
	{
    	lpd3dDeviceDesc = &d3dSWDeviceDesc;

    	// Device has a software rasterizer. We will let DirectDraw
    	// decide where the device surface resides unless we are
    	// running in debug mode, in which case we will force it into
    	// system memory. For a software rasterizer the z-buffer should
    	// always go into system memory. A z-buffer in video memory will
    	// seriously degrade the application's performance.
        
    	dwDeviceMemType  = (fDebug ? DDSCAPS_SYSTEMMEMORY : 0);
    	dwZBufferMemType = DDSCAPS_SYSTEMMEMORY;
	}

	// Create the device surface. The pixel format will be identical
	// to that of the primary surface, so we don't have to explicitly 
	// specify it. We do need to explicitly specify the size, memory 
	// type and capabilities  of the surface.
    
	ZeroMemory(&ddsd, sizeof(ddsd));
	ddsd.dwSize 		= sizeof(ddsd);
	ddsd.dwFlags    	= DDSD_CAPS | DDSD_WIDTH | DDSD_HEIGHT;
	ddsd.dwWidth    	= dwWidth;
	ddsd.dwHeight   	= dwHeight;
	ddsd.ddsCaps.dwCaps = DDSCAPS_3DDEVICE | DDSCAPS_OFFSCREENPLAIN | 
                      	dwDeviceMemType;
	hRes = lpdd->lpVtbl->CreateSurface(lpdd, &ddsd, &lpddDevice, NULL);
	if (FAILED(hRes))
    	return hRes;

	// If we have created a palette, we have already determined that
	// the primary surface (and hence the device surface) is palettized. 
	// Therefore, we should attach the palette to the device surface. 
	// (The palette is already attached to the primary surface.)
    
	if (NULL != lpddPalette)
	{
    	hRes = lpddDevice->lpVtbl->SetPalette(lpddDevice, lpddPalette);
    	if (FAILED(hRes))
        	return hRes;
	}

	// We now determine whether or not we need a z-buffer and, if 
	// so, its bit depth. 
    
	if (0 != lpd3dDeviceDesc->dwDeviceZBufferBitDepth)
	{
    	// The device supports z-buffering. Determine the depth. We
    	// select the lowest supported z-buffer depth to save memory.
    	// (Accuracy is not too important for this sample.)
        
    	dwZBufferBitDepth = 
        	FlagsToBitDepth(lpd3dDeviceDesc->dwDeviceZBufferBitDepth);

    	// Create the z-buffer.
        
    	ZeroMemory(&ddsd, sizeof(ddsd));
    	ddsd.dwSize        	= sizeof(ddsd);
    	ddsd.dwFlags   		= DDSD_CAPS   |
                         		DDSD_WIDTH  |
                         		DDSD_HEIGHT |
                         		DDSD_ZBUFFERBITDEPTH;
    	ddsd.ddsCaps.dwCaps	= DDSCAPS_ZBUFFER | dwZBufferMemType;
    	ddsd.dwWidth   		= dwWidth;
    	ddsd.dwHeight      	= dwHeight;
    	ddsd.dwZBufferBitDepth = dwZBufferBitDepth;
    	hRes = lpdd->lpVtbl->CreateSurface(lpdd, &ddsd, &lpddZBuffer,
                                   		NULL);
    	if (FAILED(hRes))
        	return hRes;

            	// Attach it to the rendering target.
        
    	hRes = lpddDevice->lpVtbl->AddAttachedSurface(lpddDevice, 
                                                  	lpddZBuffer);
    	if (FAILED(hRes))
        	return hRes;
	}

	// Now all the elements are in place: the device surface is in the 
	// correct memory type; a z-buffer has been attached with the 
	// correct depth and memory type; and a palette has been attached, 
	// if necessary. Now we can query for the Direct3D device we chose 
	// earlier.
    
	hRes = lpddDevice->lpVtbl->QueryInterface(lpddDevice,
                           		&guidDevice, &lpd3dDevice);
	if (FAILED(hRes))
    	return hRes;

	return DD_OK;
}


Creating the Scene

The CreateScene function creates the elements making up the 3D scene. In this sample, the scene consists of a single light, the viewport, the background and surface materials, the three transformation matrices, and the execute buffer holding the state changes and drawing primitives.

static HRESULT
CreateScene(void)
{
	HRESULT          	hRes;
	D3DMATERIAL      	d3dMaterial;
	D3DLIGHT     		d3dLight;
	DWORD            	dwVertexSize;
	DWORD            	dwInstructionSize;
	DWORD            	dwExecuteBufferSize;
	D3DEXECUTEBUFFERDESC d3dExecuteBufferDesc;
	D3DEXECUTEDATA   	d3dExecuteData;

	ASSERT(NULL != lpd3d);
	ASSERT(NULL != lpd3dDevice);
	ASSERT(NULL == lpd3dViewport);
	ASSERT(NULL == lpd3dMaterial);
	ASSERT(NULL == lpd3dBackgroundMaterial);
	ASSERT(NULL == lpd3dExecuteBuffer);
	ASSERT(NULL == lpd3dLight);
	ASSERT(0  == hd3dWorldMatrix);
	ASSERT(0  == hd3dViewMatrix);
	ASSERT(0  == hd3dProjMatrix);

	// Create the light.
    
	hRes = lpd3d->lpVtbl->CreateLight(lpd3d, &lpd3dLight, NULL);
	if (FAILED(hRes))
    	return hRes;

	ZeroMemory(&d3dLight, sizeof(d3dLight));
	d3dLight.dwSize = sizeof(d3dLight);
	d3dLight.dltType = D3DLIGHT_POINT;
	d3dLight.dcvColor.dvR	= D3DVAL( 1.0);
	d3dLight.dcvColor.dvG	= D3DVAL( 1.0);
	d3dLight.dcvColor.dvB	= D3DVAL( 1.0);
	d3dLight.dcvColor.dvA	= D3DVAL( 1.0);
	d3dLight.dvPosition.dvX  = D3DVAL( 1.0);
	d3dLight.dvPosition.dvY  = D3DVAL(-1.0);
	d3dLight.dvPosition.dvZ  = D3DVAL(-1.0);
	d3dLight.dvAttenuation0  = D3DVAL( 1.0);
	d3dLight.dvAttenuation1  = D3DVAL( 0.1);
	d3dLight.dvAttenuation2  = D3DVAL( 0.0);
	hRes = lpd3dLight->lpVtbl->SetLight(lpd3dLight, &d3dLight);
	if (FAILED(hRes))
    	return hRes;

	// Create the background material.
    
	hRes = lpd3d->lpVtbl->CreateMaterial(lpd3d, 
    	&lpd3dBackgroundMaterial, NULL);
	if (FAILED(hRes))
    	return hRes;

	ZeroMemory(&d3dMaterial, sizeof(d3dMaterial));
	d3dMaterial.dwSize = sizeof(d3dMaterial);
	d3dMaterial.dcvDiffuse.r  = D3DVAL(0.0);
	d3dMaterial.dcvDiffuse.g  = D3DVAL(0.0);
	d3dMaterial.dcvDiffuse.b  = D3DVAL(0.0);
	d3dMaterial.dcvAmbient.r  = D3DVAL(0.0);
	d3dMaterial.dcvAmbient.g  = D3DVAL(0.0);
	d3dMaterial.dcvAmbient.b  = D3DVAL(0.0);
	d3dMaterial.dcvSpecular.r = D3DVAL(0.0);
	d3dMaterial.dcvSpecular.g = D3DVAL(0.0);
	d3dMaterial.dcvSpecular.b = D3DVAL(0.0);
	d3dMaterial.dvPower   	= D3DVAL(0.0);

	// Since this is the background material, we don't want a ramp to be 
	// allocated. (We will not be smooth-shading the background.)
    
	d3dMaterial.dwRampSize	= 1;
    
	hRes = lpd3dBackgroundMaterial->lpVtbl->SetMaterial
    	(lpd3dBackgroundMaterial, &d3dMaterial);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dBackgroundMaterial->lpVtbl->GetHandle
    	(lpd3dBackgroundMaterial, lpd3dDevice, &hd3dBackgroundMaterial);
	if (FAILED(hRes))
    	return hRes;

	// Create the viewport.
	// The viewport parameters are set in the UpdateViewport function, 
	// which is called in response to WM_SIZE.
    
	hRes = lpd3d->lpVtbl->CreateViewport(lpd3d, &lpd3dViewport, NULL);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dDevice->lpVtbl->AddViewport(lpd3dDevice, lpd3dViewport);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dViewport->lpVtbl->SetBackground(lpd3dViewport, 
    	hd3dBackgroundMaterial);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dViewport->lpVtbl->AddLight(lpd3dViewport, lpd3dLight);
	if (FAILED(hRes))
    	return hRes;

	// Create the matrices.
    
	hRes = lpd3dDevice->lpVtbl->CreateMatrix(lpd3dDevice, 
    	&hd3dWorldMatrix);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dDevice->lpVtbl->SetMatrix(lpd3dDevice, hd3dWorldMatrix, 
    	&d3dWorldMatrix);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dDevice->lpVtbl->CreateMatrix(lpd3dDevice, 
    	&hd3dViewMatrix);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dDevice->lpVtbl->SetMatrix(lpd3dDevice, hd3dViewMatrix, 
    	&d3dViewMatrix);
	if (FAILED(hRes))
    	return hRes;
	hRes = lpd3dDevice->lpVtbl->CreateMatrix(lpd3dDevice, 
    	&hd3dProjMatrix);
	if (FAILED(hRes))
    	return hRes;
	SetPerspectiveProjection(&d3dProjMatrix, HALF_HEIGHT, FRONT_CLIP, 
    	BACK_CLIP);
	hRes = lpd3dDevice->lpVtbl->SetMatrix(lpd3dDevice, hd3dProjMatrix,
    	&d3dProjMatrix);
	if (FAILED(hRes))
    	return hRes;

	// Create the surface material.
    
	hRes = lpd3d->lpVtbl->CreateMaterial(lpd3d, &lpd3dMaterial, NULL);
	if (FAILED(hRes))
    	return hRes;
	ZeroMemory(&d3dMaterial, sizeof(d3dMaterial));
	d3dMaterial.dwSize = sizeof(d3dMaterial);

	// Base green with white specular.
    
	d3dMaterial.dcvDiffuse.r  = D3DVAL(0.0);
	d3dMaterial.dcvDiffuse.g  = D3DVAL(1.0);
	d3dMaterial.dcvDiffuse.b  = D3DVAL(0.0);
	d3dMaterial.dcvAmbient.r  = D3DVAL(0.0);
	d3dMaterial.dcvAmbient.g  = D3DVAL(0.4);
	d3dMaterial.dcvAmbient.b  = D3DVAL(0.0);
	d3dMaterial.dcvSpecular.r = D3DVAL(1.0);
	d3dMaterial.dcvSpecular.g = D3DVAL(1.0);
	d3dMaterial.dcvSpecular.b = D3DVAL(1.0);
	d3dMaterial.dvPower   	= D3DVAL(20.0);
	d3dMaterial.dwRampSize	= 16;
    
	hRes = lpd3dMaterial->lpVtbl->SetMaterial(lpd3dMaterial, 
    	&d3dMaterial);
	if (FAILED(hRes))
    	return hRes;

	hRes = lpd3dMaterial->lpVtbl->GetHandle(lpd3dMaterial, lpd3dDevice, 
    	&hd3dSurfaceMaterial);
	if (FAILED(hRes))
    	return hRes;

	// Build the execute buffer.
    
	dwVertexSize  	= (NUM_VERTICES    	* sizeof(D3DVERTEX));
	dwInstructionSize = (NUM_INSTRUCTIONS	* sizeof(D3DINSTRUCTION)) +
                    	(NUM_STATES      	* sizeof(D3DSTATE))   	+
                    	(NUM_PROCESSVERTICES * 
                                    	sizeof(D3DPROCESSVERTICES))	+
                    	(NUM_TRIANGLES  	* sizeof(D3DTRIANGLE));
	dwExecuteBufferSize = dwVertexSize + dwInstructionSize;
	ZeroMemory(&d3dExecuteBufferDesc, sizeof(d3dExecuteBufferDesc));
	d3dExecuteBufferDesc.dwSize   	= sizeof(d3dExecuteBufferDesc);
	d3dExecuteBufferDesc.dwFlags  	= D3DDEB_BUFSIZE;
	d3dExecuteBufferDesc.dwBufferSize = dwExecuteBufferSize;
	hRes = lpd3dDevice->lpVtbl->CreateExecuteBuffer(lpd3dDevice,
    	&d3dExecuteBufferDesc, &lpd3dExecuteBuffer, NULL);
	if (FAILED(hRes))
    	return hRes;

	// Fill the execute buffer with the required vertices, state
	// instructions and drawing primitives.
    
	hRes = FillExecuteBuffer();
	if (FAILED(hRes))
    	return hRes;

	// Set the execute data so Direct3D knows how many vertices are in 
	// the buffer and where the instructions start.
    
	ZeroMemory(&d3dExecuteData, sizeof(d3dExecuteData));
	d3dExecuteData.dwSize = sizeof(d3dExecuteData);
	d3dExecuteData.dwVertexCount   	= NUM_VERTICES;
	d3dExecuteData.dwInstructionOffset = dwVertexSize;
	d3dExecuteData.dwInstructionLength = dwInstructionSize;
	hRes = lpd3dExecuteBuffer->lpVtbl->SetExecuteData
    	(lpd3dExecuteBuffer, &d3dExecuteData);
	if (FAILED(hRes))
    	return hRes;

	return DD_OK;
}


Filling the Execute Buffer

The FillExecuteBuffer function fills the single execute buffer used in this sample with all the vertices, transformations, light and render states, and drawing primitives necessary to draw our triangle.

NOTE: This is not the most efficient way of organizing the execute buffer. For best performance you should minimize state changes. In this sample we submit the execute buffer for each frame in the animation loop and no state in the buffer is modified. The only thing we modify is the world matrix (its contents--not its handle). Therefore, it would be more efficient to extract all the static state instructions into a separate execute buffer which we would issue once only at startup and, from then on, simply execute a second execute buffer with vertices and triangles.

However, because this sample is more concerned with clarity than performance, it uses only one execute buffer and resubmits it in its entirety for each frame.

static HRESULT
FillExecuteBuffer(void)
{
	HRESULT          	hRes;
	D3DEXECUTEBUFFERDESC d3dExeBufDesc;
	LPD3DVERTEX      	lpVertex;
	LPD3DINSTRUCTION 	lpInstruction;
	LPD3DPROCESSVERTICES lpProcessVertices;
	LPD3DTRIANGLE    	lpTriangle;
	LPD3DSTATE   		lpState;

	ASSERT(NULL != lpd3dExecuteBuffer);
	ASSERT(0  != hd3dSurfaceMaterial);
	ASSERT(0  != hd3dWorldMatrix);
	ASSERT(0  != hd3dViewMatrix);
	ASSERT(0  != hd3dProjMatrix);

	// Lock the execute buffer.
    
	ZeroMemory(&d3dExeBufDesc, sizeof(d3dExeBufDesc));
	d3dExeBufDesc.dwSize = sizeof(d3dExeBufDesc);
	hRes = lpd3dExecuteBuffer->lpVtbl->Lock(lpd3dExecuteBuffer, 
    	&d3dExeBufDesc);
	if (FAILED(hRes))
    	return hRes;

	// For purposes of illustration, we fill the execute buffer by 
	// casting a pointer to the execute buffer to the appropriate data 
	// structures.
    
	lpVertex = (LPD3DVERTEX)d3dExeBufDesc.lpData;

	// First vertex.
    
	lpVertex->dvX  = D3DVAL( 0.0); // Position in model coordinates      
	lpVertex->dvY  = D3DVAL( 1.0);
	lpVertex->dvZ  = D3DVAL( 0.0);
	lpVertex->dvNX = D3DVAL( 0.0); // Normalized illumination normal     
	lpVertex->dvNY = D3DVAL( 0.0);
	lpVertex->dvNZ = D3DVAL(-1.0);
	lpVertex->dvTU = D3DVAL( 0.0); // Texture coordinates (not used) 
	lpVertex->dvTV = D3DVAL( 1.0);
	lpVertex++;

	// Second vertex.
    
	lpVertex->dvX  = D3DVAL( 1.0); // Position in model coordinates      
	lpVertex->dvY  = D3DVAL(-1.0);
	lpVertex->dvZ  = D3DVAL( 0.0);
	lpVertex->dvNX = D3DVAL( 0.0); // Normalized illumination normal     
	lpVertex->dvNY = D3DVAL( 0.0);
	lpVertex->dvNZ = D3DVAL(-1.0);
	lpVertex->dvTU = D3DVAL( 1.0); // Texture coordinates (not used)
	lpVertex->dvTV = D3DVAL( 1.0);
	lpVertex++;

	// Third vertex.
    
	lpVertex->dvX  = D3DVAL(-1.0); // Position in model coordinates      
	lpVertex->dvY  = D3DVAL(-1.0);
	lpVertex->dvZ  = D3DVAL( 0.0);
	lpVertex->dvNX = D3DVAL( 0.0); // Normalized illumination normal     
	lpVertex->dvNY = D3DVAL( 0.0);
	lpVertex->dvNZ = D3DVAL(-1.0);
	lpVertex->dvTU = D3DVAL( 1.0); // Texture coordinates (not used)
	lpVertex->dvTV = D3DVAL( 0.0);
	lpVertex++;

	// Transform state - world, view and projection.
    
	lpInstruction = (LPD3DINSTRUCTION)lpVertex;
	lpInstruction->bOpcode = D3DOP_STATETRANSFORM;
	lpInstruction->bSize   = sizeof(D3DSTATE);
	lpInstruction->wCount  = 3U;
	lpInstruction++;
	lpState = (LPD3DSTATE)lpInstruction;
	lpState->dtstTransformStateType = D3DTRANSFORMSTATE_WORLD;
	lpState->dwArg[0] = hd3dWorldMatrix;
	lpState++;
	lpState->dtstTransformStateType = D3DTRANSFORMSTATE_VIEW;
	lpState->dwArg[0] = hd3dViewMatrix;
	lpState++;
	lpState->dtstTransformStateType = D3DTRANSFORMSTATE_PROJECTION;
	lpState->dwArg[0] = hd3dProjMatrix;
	lpState++;

	// Lighting state.
    
	lpInstruction = (LPD3DINSTRUCTION)lpState;
	lpInstruction->bOpcode = D3DOP_STATELIGHT;
	lpInstruction->bSize   = sizeof(D3DSTATE);
	lpInstruction->wCount  = 2U;
	lpInstruction++;
	lpState = (LPD3DSTATE)lpInstruction;
	lpState->dlstLightStateType = D3DLIGHTSTATE_MATERIAL;
	lpState->dwArg[0] = hd3dSurfaceMaterial;
	lpState++;
	lpState->dlstLightStateType = D3DLIGHTSTATE_AMBIENT;
	lpState->dwArg[0] = RGBA_MAKE(128, 128, 128, 128);
	lpState++;

	// Render state.
    
	lpInstruction = (LPD3DINSTRUCTION)lpState;
	lpInstruction->bOpcode = D3DOP_STATERENDER;
	lpInstruction->bSize = sizeof(D3DSTATE);
	lpInstruction->wCount = 3U;
	lpInstruction++;
	lpState = (LPD3DSTATE)lpInstruction;
	lpState->drstRenderStateType = D3DRENDERSTATE_FILLMODE;
	lpState->dwArg[0] = D3DFILL_SOLID;
	lpState++;
	lpState->drstRenderStateType = D3DRENDERSTATE_SHADEMODE;
	lpState->dwArg[0] = D3DSHADE_GOURAUD;
	lpState++;
	lpState->drstRenderStateType = D3DRENDERSTATE_DITHERENABLE;
	lpState->dwArg[0] = TRUE;
	lpState++;

	// The D3DOP_PROCESSVERTICES instruction tells the driver what to
	// do with the vertices in the buffer. In this sample we want
	// Direct3D to perform the entire pipeline on our behalf, so
	// the instruction is D3DPROCESSVERTICES_TRANSFORMLIGHT.
    
	lpInstruction = (LPD3DINSTRUCTION)lpState;
	lpInstruction->bOpcode = D3DOP_PROCESSVERTICES;
	lpInstruction->bSize   = sizeof(D3DPROCESSVERTICES);
	lpInstruction->wCount  = 1U;
	lpInstruction++;
	lpProcessVertices = (LPD3DPROCESSVERTICES)lpInstruction;
	lpProcessVertices->dwFlags	= D3DPROCESSVERTICES_TRANSFORMLIGHT;
	lpProcessVertices->wStart 	= 0U;   		// First source vertex
	lpProcessVertices->wDest  	= 0U;
	lpProcessVertices->dwCount	= NUM_VERTICES; // Number of vertices 
	lpProcessVertices->dwReserved = 0;
	lpProcessVertices++;

	// Draw the triangle.
    
	lpInstruction = (LPD3DINSTRUCTION)lpProcessVertices;
	lpInstruction->bOpcode = D3DOP_TRIANGLE;
	lpInstruction->bSize   = sizeof(D3DTRIANGLE);
	lpInstruction->wCount  = 1U;
	lpInstruction++;
	lpTriangle = (LPD3DTRIANGLE)lpInstruction;
	lpTriangle->wV1	= 0U; 
	lpTriangle->wV2	= 1U;
	lpTriangle->wV3	= 2U;
	lpTriangle->wFlags = D3DTRIFLAG_EDGEENABLETRIANGLE;
	lpTriangle++;

	// Stop execution of the buffer.
    
	lpInstruction = (LPD3DINSTRUCTION)lpTriangle;
	lpInstruction->bOpcode = D3DOP_EXIT;
	lpInstruction->bSize   = 0;
	lpInstruction->wCount  = 0U;

	// Unlock the execute buffer.
    
	lpd3dExecuteBuffer->lpVtbl->Unlock(lpd3dExecuteBuffer);

	return DD_OK;
}


Animating the Scene

The animation in this sample is simply a rotation about the Y axis. All we need to do is build a rotation matrix and set the world matrix to that new rotation matrix.

We don't need to modify the execute buffer in any way to peform this rotation. We simply set the matrix and resubmit the execute buffer.

static HRESULT
AnimateScene(void)
{
	HRESULT hRes;

	ASSERT(NULL != lpd3dDevice);
	ASSERT(0  != hd3dWorldMatrix);

	// We rotate the triangle by setting the world transform to a
	// rotation matrix.
    
	SetRotationAboutY(&d3dWorldMatrix, dAngleOfRotation);
	dAngleOfRotation += ROTATE_ANGLE_DELTA;
	hRes = lpd3dDevice->lpVtbl->SetMatrix(lpd3dDevice,
    	hd3dWorldMatrix, &d3dWorldMatrix);
	if (FAILED(hRes))
    	return hRes;

	return DD_OK;
}


Rendering
This section contains functions that render the entire scene and render a single frame.
Rendering the Scene

The RenderScene function renders the 3D scene, just as you might suspect. The fundamental task performed by this function is submitting the single execute buffer used by this sample. However, the function also clears the back and z-buffers and demarcates the start and end of the scene (which in this case is a single execute).

When you clear the back and z-buffers, it's safe to specify the z-buffer clear flag even if we don't have an attached z-buffer. Direct3D will simply discard the flag if no z-buffer is being used.

For maximum efficiency we only want to clear those regions of the device surface and z-buffer which we actually rendered to in the last frame. This is the purpose of the array of rectangles and count passed to this function. It is possible to query Direct3D for the regions of the device surface that were rendered to by that execute. The application can then accumulate those rectangles and clear only those regions. However this is a very simple sample and so, for simplicity, we will just clear the entire device surface and z-buffer. You should probably implement a more efficient clearing mechanism in your application.

The RenderScene function must be called once and once only for every frame of animation. If you have multiple execute buffers comprising a single frame you must have one call to the IDirect3DDevice::BeginScene method before submitting those execute buffers. If you have more than one device being rendered in a single frame, (for example, a rear-view mirror in a racing game), call the IDirect3DDevice::BeginScene and IDirect3DDevice::EndScene methods once for each device.

When the RenderScene function returns DD_OK, the scene will have been rendered and the device surface will hold the contents of the rendering.

static HRESULT
RenderScene(void)
{
	HRESULT hRes;
	D3DRECT d3dRect;

	ASSERT(NULL != lpd3dViewport);
	ASSERT(NULL != lpd3dDevice);
	ASSERT(NULL != lpd3dExecuteBuffer);

	// Clear both back and z-buffer.
    
	d3dRect.lX1 = rSrcRect.left;
	d3dRect.lX2 = rSrcRect.right;
	d3dRect.lY1 = rSrcRect.top;
	d3dRect.lY2 = rSrcRect.bottom;
	hRes = lpd3dViewport->lpVtbl->Clear(lpd3dViewport, 1, &d3dRect,
    	D3DCLEAR_TARGET | D3DCLEAR_ZBUFFER);
	if (FAILED(hRes))
    	return hRes;

	// Start the scene.
    
	hRes = lpd3dDevice->lpVtbl->BeginScene(lpd3dDevice);
	if (FAILED(hRes))
    	return hRes;

	// Submit the execute buffer.
     
	// We want Direct3D to clip the data on our behalf so we specify
	// D3DEXECUTE_CLIPPED.
    
	hRes = lpd3dDevice->lpVtbl->Execute(lpd3dDevice, lpd3dExecuteBuffer,
    	lpd3dViewport, D3DEXECUTE_CLIPPED);
	if (FAILED(hRes))
	{
    	lpd3dDevice->lpVtbl->EndScene(lpd3dDevice);
    	return hRes;
	}

    	// End the scene.
    
	hRes = lpd3dDevice->lpVtbl->EndScene(lpd3dDevice);
	if (FAILED(hRes))
    	return hRes;

	return DD_OK;
}

Rendering a Single Frame

The DoFrame function renders and shows a single frame. This involves rendering the scene and blitting the result to the client area of the application window on the primary surface.

This function handles lost surfaces by attempting to restore the application's surfaces and then retrying the rendering. It is called by the OnMove function (discussed in Redrawing on Window Movement), the OnSize function (discussed in Redrawing on Window Resizing), and the OnPaint function (discussed in Repainting the Client Area).

static HRESULT
DoFrame(void)
{
	HRESULT hRes;

	// We keeping trying until we succeed or we fail for a reason
	// other than DDERR_SURFACELOST.
    
	while (TRUE)
	{
    	hRes = RenderScene();
    	if (SUCCEEDED(hRes))
    	{
        	hRes = lpddPrimary->lpVtbl->Blt(lpddPrimary, &rDstRect,
            	lpddDevice, &rSrcRect, DDBLT_WAIT, NULL);
        	if (SUCCEEDED(hRes))  // If it worked. 
            	return hRes;
    	}
    	while (DDERR_SURFACELOST == hRes)  // Restore lost surfaces
        	hRes = RestoreSurfaces();
    	if (FAILED(hRes))  // handle other failure cases
        	return hRes;
	}
}


Working with Matrices

This section contains two functions that work with matrices: the SetPerspectiveProjection function, which sets a given matrix to the appropriate values for the front and back clipping planes, and the SetRotationAboutY function, which sets a matrix to a rotation about the y axis.
Setting the Perspective Transformation

The SetPerspectiveProjection function sets the given matrix to a perspective transform for the given half-height and front- and back-clipping planes. This function is called as part of the CreateScene function, documented in Creating the Scene.

static void
SetPerspectiveProjection(LPD3DMATRIX lpd3dMatrix,
                 		double  	dHalfHeight,
                 		double  	dFrontClipping,
                 		double  	dBackClipping)
{
	double dTmp1;
	double dTmp2;

	ASSERT(NULL != lpd3dMatrix);

	dTmp1 = dHalfHeight / dFrontClipping;
	dTmp2 = dBackClipping / (dBackClipping - dFrontClipping);

	lpd3dMatrix->_11 =  D3DVAL(2.0);
	lpd3dMatrix->_12 =  D3DVAL(0.0);
	lpd3dMatrix->_13 =  D3DVAL(0.0);
	lpd3dMatrix->_14 =  D3DVAL(0.0);
	lpd3dMatrix->_21 =  D3DVAL(0.0);
	lpd3dMatrix->_22 =  D3DVAL(2.0);
	lpd3dMatrix->_23 =  D3DVAL(0.0);
	lpd3dMatrix->_24 =  D3DVAL(0.0);
	lpd3dMatrix->_31 =  D3DVAL(0.0);
	lpd3dMatrix->_32 =  D3DVAL(0.0);
	lpd3dMatrix->_33 =  D3DVAL(dTmp1 * dTmp2);
	lpd3dMatrix->_34 =  D3DVAL(dTmp1);
	lpd3dMatrix->_41 =  D3DVAL(0.0);
	lpd3dMatrix->_42 =  D3DVAL(0.0);
	lpd3dMatrix->_43 =  D3DVAL(-dHalfHeight * dTmp2);
	lpd3dMatrix->_44 =  D3DVAL(0.0);
}

Setting a Rotation Transformation

The SetRotationAboutY function sets the given matrix to a rotation about the y axis, using the specified number of radians. This function is called as part of the AnimateScene function, documented in Animating the Scene.

static void
SetRotationAboutY(LPD3DMATRIX lpd3dMatrix, double dAngleOfRotation)
{
	D3DVALUE dvCos;
	D3DVALUE dvSin;

	ASSERT(NULL != lpd3dMatrix);

	dvCos = D3DVAL(cos(dAngleOfRotation));
	dvSin = D3DVAL(sin(dAngleOfRotation));

	lpd3dMatrix->_11 =  dvCos;
	lpd3dMatrix->_12 =  D3DVAL(0.0);
	lpd3dMatrix->_13 = -dvSin;
	lpd3dMatrix->_14 =  D3DVAL(0.0);
	lpd3dMatrix->_21 =  D3DVAL(0.0);
	lpd3dMatrix->_22 =  D3DVAL(1.0);
	lpd3dMatrix->_23 =  D3DVAL(0.0);
	lpd3dMatrix->_24 =  D3DVAL(0.0);
	lpd3dMatrix->_31 =  dvSin;
	lpd3dMatrix->_32 =  D3DVAL(0.0);
	lpd3dMatrix->_33 =  dvCos;
	lpd3dMatrix->_34 =  D3DVAL(0.0);
	lpd3dMatrix->_41 =  D3DVAL(0.0);
	lpd3dMatrix->_42 =  D3DVAL(0.0);
	lpd3dMatrix->_43 =  D3DVAL(0.0);
	lpd3dMatrix->_44 =  D3DVAL(1.0);
}


Restoring and Redrawing

This section contains functions that restore objects and surfaces that may have been lost while the application is running.
Restoring the Direct3D Device

The RestoreDevice function restores lost video memory for the device surface and z-buffer.

static HRESULT
RestoreDevice(void)
{
	HRESULT hRes;

	if (NULL != lpddZBuffer)
	{
    	hRes = lpddZBuffer->lpVtbl->Restore(lpddZBuffer);
    	if (FAILED(hRes))
        	return hRes;
	}

	if (NULL != lpddDevice)
	{
    	hRes = lpddDevice->lpVtbl->Restore(lpddDevice);
    	if (FAILED(hRes))
        	return hRes;
	}

	return DD_OK;
}

Restoring the Primary Surface

The RestorePrimary function attempts to restore the video memory allocated for the primary surface. This function will be invoked by a DirectX function returning DDERR_SURFACELOST due to a mode switch or fullscreen DOS box invalidating video memory.

static HRESULT
RestorePrimary(void)
{
	ASSERT(NULL != lpddPrimary);

	return lpddPrimary->lpVtbl->Restore(lpddPrimary);
}

Restoring All Surfaces

The RestoreSurfaces function attempts to restore all the surfaces used by the application.

static LRESULT
RestoreSurfaces(void)
{
	HRESULT hRes;

	hRes = RestorePrimary();
	if (FAILED(hRes))
    	return hRes;

	hRes = RestoreDevice();
	if (FAILED(hRes))
    	return hRes;

	return DD_OK;
}

Redrawing on Window Movement

static LRESULT
OnMove(HWND hwnd, int x, int y)
{
	int 	xDelta;
	int 	yDelta;
	HRESULT hRes;

	// No action if the device has not yet been created or if we are
	// suspended.
    
	if ((NULL != lpd3dDevice) && !fSuspended)
	{
    	// Update the destination rectangle for the new client position.
        
    	xDelta = x - rDstRect.left;
    	yDelta = y - rDstRect.top;

    	rDstRect.left   += xDelta;
    	rDstRect.top	+= yDelta;
    	rDstRect.right  += xDelta;
    	rDstRect.bottom += yDelta;

    	// Repaint the client area.
        
    	hRes = DoFrame();
    	if (FAILED(hRes))
    	{
        	FatalError(hwnd, IDS_ERRMSG_RENDERSCENE, hRes);
        	return 0L;
    	}
	}

	return 0L;
}

Redrawing on Window Resizing

static LRESULT
OnSize(HWND hwnd, int w, int h)
{
	HRESULT   	hRes;
	DDSURFACEDESC ddsd;

    	// Nothing to do if we are suspended.
    
	if (!fSuspended)
	{
    	// Update the source and destination rectangles (used by the
    	// blit that shows the rendering in the client area).
        
    	rDstRect.right  = rDstRect.left + w;
    	rDstRect.bottom = rDstRect.top  + h;
    	rSrcRect.right  = w;
    	rSrcRect.bottom = h;

    	if (NULL != lpd3dDevice)
    	{
        	// Although we already have a device, we need to be sure it 
        	// is big enough for the new window client size.
             
        	// Because the window in this sample has a fixed size, it 
        	// should never be necessary to handle this case. This code 
        	// will be useful when we make the application resizable.
   	     
        	ZeroMemory(&ddsd, sizeof(ddsd));
        	ddsd.dwSize = sizeof(ddsd);
        	hRes = lpddDevice->lpVtbl->GetSurfaceDesc(lpddDevice, 
            	&ddsd);
        	if (FAILED(hRes))
        	{
            	FatalError(hwnd, IDS_ERRMSG_DEVICESIZE, hRes);
            	return 0L;
        	}
    
        	if ((w > (int)ddsd.dwWidth) || (h > (int)ddsd.dwHeight))
        	{
            	// The device is too small. We need to shut it down
            	// and rebuild it.

            	// Execute buffers are bound to devices, so when 
            	// we release the device we must release the execute
            	// buffer.
       	     
            	ReleaseScene();
            	ReleaseDevice();
        	}
    	}

    	if (NULL == lpd3dDevice)
    	{
        	// No Direct3D device yet. This is either because this is 
        	// the first time through the loop or because we discarded 
        	// the existing device because it was not big enough for the 
        	// new window client size.
   	     
        	hRes = CreateDevice((DWORD)w, (DWORD)h);
        	if (FAILED(hRes))
        	{
            	FatalError(hwnd, IDS_ERRMSG_CREATEDEVICE, hRes);
            	return 0L;
        	}
        	hRes = CreateScene();
        	if (FAILED(hRes))
        	{
            	FatalError(hwnd, IDS_ERRMSG_BUILDSCENE, hRes);
            	return 0L;
        	}
    	}

    	hRes = UpdateViewport();
    	if (FAILED(hRes))
    	{
        	FatalError(hwnd, IDS_ERRMSG_UPDATEVIEWPORT, hRes);
        	return 0L;
    	}

    	// Render at the new size and show the results in the window's
    	// client area.
        
    	hRes = DoFrame();
    	if (FAILED(hRes))
    	{
        	FatalError(hwnd, IDS_ERRMSG_RENDERSCENE, hRes);
        	return 0L;
    	}
	}

	return 0L;
}

Repainting the Client Area

The OnPaint function repaints the client area, when required. Notice that it calls the DoFrame function to do much of the work, even though DoFrame rerenders the scene as well as blitting the result to the primary surface. Although the rerendering is not necessary, for this simple sample this inefficiency does not matter. In your application, you should rerender only when the scene changes.

For more information about the DoFrame function, see Rendering a Single Frame. The DoFrame function renders and shows a single frame. This involves rendering the scene and blitting the result to the client area of the application window on the primary surface..

static LRESULT
OnPaint(HWND hwnd, HDC hdc, LPPAINTSTRUCT lpps)
{
	HRESULT hRes;

	USE_PARAM(lpps);

	if (fActive && !fSuspended && (NULL != lpd3dDevice))
	{
    	hRes = DoFrame();
    	if (FAILED(hRes))
    	{
        	FatalError(hwnd, IDS_ERRMSG_RENDERSCENE, hRes);
        	return 0L;
    	}
	}
	else
	{
    	// Show the suspended image if we are not active or suspended or
    	// if we have not yet created the device.
        
    	PaintSuspended(hwnd, hdc);
	}

	return 0L;
}

Updating the Viewport

The UpdateViewport function updates the viewport in response to a change in window size. This ensures that we render at a resolution that matches the client area of the target window.

static HRESULT
UpdateViewport(void)
{
	D3DVIEWPORT d3dViewport;

	ASSERT(NULL != lpd3dViewport);

	ZeroMemory(&d3dViewport, sizeof(d3dViewport));
	d3dViewport.dwSize   = sizeof(d3dViewport);
	d3dViewport.dwX  	= 0;
	d3dViewport.dwY  	= 0;
	d3dViewport.dwWidth  = (DWORD)rSrcRect.right;
	d3dViewport.dwHeight = (DWORD)rSrcRect.bottom;
	d3dViewport.dvScaleX = D3DVAL((float)d3dViewport.dwWidth / 2.0);
	d3dViewport.dvScaleY = D3DVAL((float)d3dViewport.dwHeight / 2.0);
	d3dViewport.dvMaxX   = D3DVAL(1.0);
	d3dViewport.dvMaxY   = D3DVAL(1.0);
	return lpd3dViewport->lpVtbl->SetViewport(lpd3dViewport, 
    	&d3dViewport);
}






Comments

Note: Please offer only positive, constructive comments - we are looking to promote a positive atmosphere where collaboration is valued above all else.




PARTNERS