To create a vertex buffer, the CreateVertexBuffer method is used. Here’s its prototype:

HRESULT IDirect3DDevice9::CreateVertexBuffer
(
	// Length of the vertex buffer
	UINT Length,

	// Usage flags
	DWORD Usage,

	// Vertex format
	DWORD FVF,

	// Memory pool
	D3DPOOL Pool,

	// Pointer to a vertex buffer interface object pointer
	IDirect3DVertexBuffer9** ppVertexBuffer,

	// Reserved, must be null
	HANDLE* pSharedHandle
);

The Usage parameter is used to tell DirectX what we’re going to do with the object we want to create. If i had created a software vertex processing device, i would have to add the D3DUSAGE_SOFTWAREPROCESSING flag; since i’ve specified hardware processing instead, this flag is not set, and the default approach (hardware) will be used. The next flag i’ve specified into the source code (D3DUSAGE_WRITEONLY) will be explained later when i speak about the memory pools.

The FVF (Flexible Vertex Format) parameter can be set to a valid FVF identifier in case you want to use a standard vertex format. Here’s the one i used in the source code:

DWORD g_dwVertexFormat = D3DFVF_XYZ | D3DFVF_DIFFUSE;

It tells DirectX that for each vertex stored in the buffer, 3 float data types will be reserved for the XYZ coordinates, and a double-word (4 bytes) will be used to define the color.  I will not explain here what happen when you set it to zero; refer to the documentation or wait for the next tutorials.

Now that we have decided the format we want to use, we must create a vertex structure.

// Structure of a D3DFVF_XYZ | D3DFVF_DIFFUSE vertex
typedef struct __VERTEX
{
	// Position
	FLOAT fX, fY, fZ;

	// Color
	DWORD dwDiffuseColor;
} VERTEX, *LPVERTEX;

Note that DirectX expects to find the structure fields in a specific order; if you swap two variables, the vertex buffer will not be read in the correct way, and the geometry will appear corrupted. This is the order you must use:

1. Position
2. RHW value (only for already transformed vertices)
3. Blending values (up to 5)
4. Vertex normal
5. Vertex point size
6. Diffuse color
7. Specular color
8. Texture coordinates (up to 8 pairs of UV coordinates)

The memory pool field defines where the created object will be stored; valid values are:

• D3DPOOL_DEFAULT: DirectX will automatically store the resource in the best position available according to the specified usage flags (usually, it is placed into video memory). When using this pool for vertex buffer, the D3DUSAGE_WRITEONLY must be specified to improve performances. Default memory pool resources must be released everytime a lost device status is detected; if you do not release them before calling the Reset method, you will deadlock the application (TestCooperativeLevel will return a D3DERR_DEVICENOTRESET status but the Reset method will always fail).

• D3DPOOL_MANAGED: The resources will be stored in system memory and copied into video memory as needed. Managed resources does not need to be released and recreated when the device is reset.

• D3DPOOL_SYSTEMMEM: This memory pool is located into the system memory. The resources will not be copied into video memory and does not need to be created after a lost device. The pourpose of this memory pool is to store data used to update surfaces or textures.

• D3DPOOL_SCRATCH: It’s nearly the same as the previous one; the contents of the resources created here are indipendent from the DirectX device and can only be created, copied and locked. They can’t be set as textures or render targets.

The vertex buffer has been created but it doesn’t contains anything yet; in order to fill it with our vertices, we first need to define them in some way. Here’s where the vertex structure we created before comes in handy:

VERTEX g_a_vxVertices[] =
{
	// First vertex (red) of the first triangle
	-5.0f, 5.0f, 0.0f, 0xFFFF0000,

	// Second vertex (blue) of the first triangle
	5.0f, 5.0f, 0.0f, 0xFF0000FF,

	// Third vertex (green) of the first triangle
	-5.0f, -5.0f, 0.0f, 0xFF00FF00,

	// First vertex (yellow) of the second triangle
	5.0f, 5.0f, 0.0f, 0xFFFFF200,

	// Second vertex (purple) of the second triangle
	5.0f, -5.0f, 0.0f, 0xFF8F00FF,

	// Third vertex (orange) of the second triangle
	-5.0f, -5.0f, 0.0f, 0xFFFF8F00
};

Now that we have defined the geometry for our object, we need to store it inside the vertex buffer. The vertices have to be copied to the buffer returned from the Lock method; here’s the prototype:

HRESULT IDirect3DVertexBuffer9::Lock
(
	// Offset into the vertex data
	UINT OffsetToLock,

	// Size of the vertex data to lock
	UINT SizeToLock,

	// Pointer to a memory buffer containing the returned vertex data
	VOID **ppbData,

	// Flags
	DWORD Flags
);

A simple memcpy call will do the job:

memcpy(ReturnedPointer, ArrayOfVertices, sizeof(ArrayOfVertices))

The vertex buffer is ready to be drawn, we just need to call the Unlock() method; this will update the vertex data with the user-supplied buffer and release the lock. Everything i’ve explained now takes place inside the vInitializeDeviceObjects function.

Before we can render the vertices, we need to call BeginScene and tell DirectX the format we used to declare the vertices:

DirectX9Device->SetFVF(g_D3DFVF_XYZ | D3DFVF_DIFFUSE)

The last step is to set the stream source and call the draw method:

DirectX9Device->SetStreamSource
(
	// Stream number
	0,

	// Vertex buffer
	VertexBuffer,

	// Offset into the vertex buffer
	0,

	// Can be used for instancing, we will set this to the vertex size
	sizeof(VERTEX)
)

DirectX9Device->DrawPrimitive
(
	// Type of primitive to render
	D3DPT_TRIANGLELIST,

	// First vertex to draw
	0,

	// Primitive count
	sizeof(g_a_vxVertices) / sizeof(VERTEX)
)

The scene can now be drawn to screen calling EndScene and Present.

Source code: http://insanedevelopers.net/downloads/Sources/DirectX9Tutorials/02 – Vertex Buffers.zip

As you can see from the source code, the first thing i do is to initialize the logger object; a graphical application can grow a lot thus becoming really complex and hard to debug. My suggestion is to always log every error, so that it will be easier to track down bugs when we need to.

Let’s talk about the main window; as you can see, we need to declare and fill a WNDCLASS/WNDCLASSEX structure. It defines the basic informations of the window we are going to create. The class name is just a string that will be used to identify our window class, and it is needed by CreateWindow/CreateWindowEx. Once filled, the window class structure needs to be registered using RegisterClass/RegisterClassEx (note that you need to match the extended version of the structure with the extended version of the RegisterClass function).

Once registered, the window class can be used through a call to either CreateWindow or CreateWindowEx. The parameters the functions needs are very simple; from left to right, it will asks for: extended window style, window class name (the one we specified inside the window class structure), window name, window style, position, size, parent window (since this is a top-level window, we don’t have any parent), menu handle (that can be created or loaded from the resources using LoadMenu), the module instance handle, and a user-defined parameter that will be sent to the window procedure (the callback function that handles the events) through the WM_CREATE event.

Speaking of that callback, its prototype is:

LRESULT CALLBACK lrWindowProcedure(
HWND hwndWindow, UINT uiMessage,
WPARAM wpParam, LPARAM lpParam
);

This function (specified inside the window class structure) is automatically called by Windows whenever a user (or another program) interacts with our interface. Each event has a well-known code that is defined as constant inside the platform SDK with the “WM_” prefix, and it’s passed using the second parameter of the function (UINT uiMessage). The hwndWindow parameter is the handle of the window that received the event (we can handle different windows with the same window procedure). The WPARAM and LPARAM values are event-specific, and their contents changes according to what the documentation says (http://www.msdn.com/). For example, the forementioned WM_CREATE message will receive the user-define parameter specified in the last argument of CreateWindow/CreateWindowEx through the LPARAM value of the event.

The AdjustWindowRect function is used to get the window size needed to obtain a particular client area. The client area is the part of the window that is inside the borders. Since DirectX will use only that area, we need to adjust the size of the window according to the DEFAULT_WINDOW_WIDTH/DEFAULT_WINDOW_HEIGHT parameters.

Now that the window is up and running, we just need to add the so-called message loop, that will receive and dispatch the messages to our window procedure; it can be done with the following functions: GetMessage, PeekMessage. The differences between the two functions are that the first is blocking, while the second is not. Since we also need to render, we either have to use PeekMessage in the same thread of the render code, or use GetMessage from another thread. In the samples, i decided to create the window from another thread, so that the entry point will be more simple to read.

In order to initialize DirectX, we first need to obtain its interface object. We do this calling Direct3DCreate9; it requests for the SDK version (just use the D3D_SDK_VERSION value). This is the way a COM interface works; it is very handy, because it lets the developers update the libraries without the risks of breaking old applications by changing/adding functions and features to newer versions.

The first examples will not go full screen, so we need to get the default adapter’s active display mode. Basically, a display mode is just the current configuration (that we assume to be fully-compatible with your hardware) for the specified adapter: resolution, refresh rate, pixel format (that defines how a pixel is built). If we were to go full screen, we would have to enumerate the supported display modes, and the sample source codes would became more complicated; to keep things simple, this will be explained in another tutorial.

The next step is to fill the D3D_PRESENTATION_PARAMETERS structure; it asks for a backbuffer format (we will use the one that the current display mode structure holds), a backbuffer size (the size of the client area of the window), the number of back buffers to use (we will use 3 buffers), and the window handle. For the first examples, i’ll not use neither multisampling nor a stencil buffer; concerning the depth buffer (also known as Z-Buffer), we will ask DirectX to manage it automatically, with a simple 16 bit format. More about the Z-Buffer in the next tutorials, when i’ll introduce you the third dimension.

The Direct3D device can now be created calling CreateDevice:

CreateDevice(
D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL,
NULL, D3DCREATE_HARDWARE_VERTEXPROCESSING,
&g_dppPresentParameters, &g_p_dv9DirectX9Device
);

Here, the default adapter is used to create an HAL device. Basically, we’re asking DirectX to rely on the hardware for rendering and vertex processing, with the configuration we specified inside the D3DPRESENT_PARAMETERS structure.

The program is ready to render! Well, in fact, the only thing it can render is the clear color, because we don’t have any geometry to draw yet. Here’s the typical game loop:

while(running)
{
	handle window events
	handle the user input
	update the objects (sound, movement, networking and so on)
	clear the scene
	begin the scene
	draw the scene
	end the scene
	present the scene
}

Our one is a lot simpler, since we don’t have any sound, input, geometry to draw, or connections to take care of. Everything it does is clear the scene with the predefined color, and begin/end the scene. For simplicity, i’ve defined some functions that gets called from the window procedure: vOnSize, vOnClose, vOnActivate. Those functions will take care of cleanup, resize and activation/deactivation of the window. In the first case, there’s not much to do; we just need to release the DirectX interface object and the Direct3D device. The vOnActive function sets a global flag that tells us if our window is active (we don’t need to render the scene if the user is working on another window). The last function, vOnSize, updates the D3DPRESENT_PARAMETERS structure with the new client area size, and then resets the device. It also sets the global g_blMainWindowIsMinimized flag that tells us if the window is minimized or not.

The last thing to take care of is the lost device status. This is what the DirectX documentation says about lost devices:

…
The lost state is characterized by the silent failure of all rendering operations, which means that the rendering methods can return success codes even though the rendering operations fail. In this situation, the error code D3DERR_DEVICELOST is returned by IDirect3DDevice9::Present.

By design, the full set of scenarios that can cause a device to become lost is not specified. Some typical examples include loss of focus, such as when the user presses ALT+TAB or when a system dialog is initialized. Devices can also be lost due to a power management event, or when another application assumes full-screen operation. In addition, any failure from IDirect3DDevice9::Reset puts the device into a lost state
….
A lost device must re-create resources (including video memory resources) after it has been reset. If a device is lost, the application queries the device to see if it can be restored to the operational state. If not, the application waits until the device can be restored.
…

Handling this event is rather simple; according to the documentation, when the Present() method returns a lost device status, we need to periodically call TestCooperativeLevel to see if the device can be restored (D3DERR_DEVICENOTRESET status). If it can be reset, we just need to release the device objects and call the Reset() method and check for the returned value. Once reset, if everything went good, we need to reload the resources the program was using (in fact, this behavior depends on the memoy pool used to create the resource; more on that in the next tutorial); then, we can restore the normal program flow, as nothing happened.
Before you take a look at the source code for this tutorial, i want to show you how it is organized:

commonheaders.hpp

• Common include files

libraries.hpp

• Libraries to be linked to the project

icons.hpp, icons.rc

• Defines the default icon as well as its resource id.

Logger.cpp, Logger.hpp

• The logger class that is used to log errors, warnings and information strings to file.

main.cpp

• Entry point

Speaking of main.cpp, these are the main blocks:

_tWinMain

• DirectX 9 initialization
• Game loop
• GUI thread creation.

dwCreateWindow

• This is the thread that creates the main window and implements the message loop.

lrWindowProcedure

• The callback that gets called by Windows when someone/something interacts with our window.

vOnClose, vOnActivate

• Cleanup
• Window states update

vOnSize

• Resets the device with the new client area size whenever the dimensions of the window changes

Source code: http://www.insanedevelopers.net/downloads/Sources/DirectX9Tutorials/01 – Initialization.zip

]]> http://insanedevelopers.net/2009/03/14/directx-9-tutorials-01-initialization/feed/ 0 http://insanedevelopers.net/2009/03/13/directx-9-tutorials-00-introduction/ http://insanedevelopers.net/2009/03/13/directx-9-tutorials-00-introduction/#comments Fri, 13 Mar 2009 18:50:51 +0000 Alessandro http://insanedevelopers.net/?p=21 Continue reading →]]> For this tutorials, we’ll need to download the DirectX SDK and a compiler. Since most of the header files are full of Microsoft-specific stuff, the only compiler that will work out-of-the-box is Visual C++. Starting from the 2005 version, Microsoft began to release freeware editions of their development products. In this tutorial, we’ll download and install Visual C++ 2008 Express Edition, but you can use any version you like.

The Express Editions can be obtained from http://www.microsoft.com/express/. Downloading the installer should take little time, but you will have to stay online while it is running, because it needs to download the components from the website. During the wizard, you can select what you want to install; the optional products (Microsoft SQL Server Express Edition and Silverlight) are not required to follow the samples, so you can skip them to save disk space and bandwidth.

Go take a coffee, it will take some time to download and install everything; eventually, it will ask you to restart the computer.

Visual C++ 2008 Express Edition - Setup

The setup will also install a basic platform SDK (now called Windows SDK); it should be enough for us, but if you want you can download the latest version from the Microsoft website. Here is a sample “hello world” application you may copy and paste inside Visual C++ to see if everything is working as expected.

#include <windows.h>
#include <tchar.h>

INT WINAPI _tWinMain(HINSTANCE hiProgram, HINSTANCE, LPTSTR tstrCmdLine, INT iCmdShow)
{
	MessageBox(NULL, _T("Hello world!"), _T("Greetings!"), MB_OK);
	return 0;
}

Now we just need the DirectX SDK; it can be downloaded from http://msdn.microsoft.com/en-us/directx/default.aspx. This time the setup application is pretty heavy (should be around 500 MB), but it can be installed without an internet connection. I suggest you to at least install the runtime libraries, the debug symbols, the headers/libraries (of course) and the samples (they may come in handy). The documentation can also be accessed online from the Microsoft website.

The setup program should automatically set the additional library and header directories of the compiler. To be sure the configuration is right, we must open the Tools/Options menu from Visual C++ and check for the VC++ Directories page under the Project and Solutions voice. The following is the configuration the installer set for me on my copy of Visual Studio 2008 Standard Edition.

Visual Studio 2008 Standard Edition - Include directories

Visual Studio 2008 Standard Edition - Library files (x86)

Visual Studio 2008 Standard Edition - Library files (x64)

I noticed that if you’re using Visual C++ 2008 Express Edition the setup will also add an executable directory to the configuration; this didn’t happen for the normal edition of Visual Studio.

Visual C++ 2008 Express Edition - Additional executable directories

Your computer should now be ready to compile the samples, you can then skip to the next tutorials.