The Basic Direct3D Program

We won't be making a "Hello World!" application for Direct3D.  We will assume that Direct3D is not a language on its own (which it isn't).  Instead, we will start by filling our window with blue.  For this we have four steps:

1.  Create global variables and function prototypes
2.  Create a function to initialize Direct3D and create the Direct3D Device
3.  Create a function to render a frame
4.  Create a function to close Direct3D

Let's go over each function and its parts, then look at the whole picture and how to plug it in to your windows program.

我们不会去写一个Direct3D的“Hello World”。因为我们知道Direct3D不是一门新的语言，取而代之的是，我们要去写一个蓝色背景的WINDOWS窗体，具体步骤如下：

1.创建全局变量和函数原型

2．写一个函数来初始化Direct3D以及创建Direct3D设备

3．写一个函数来渲染帧

4．写一个关闭Dierect3D的函数

下面让我们来看看各个函数及其部分细节

，以及如何把它们嵌入到我们的Windows 程序中。

1.  创建全局变量和函数原型

We need to add a few things to the top of our program before we start working with Direct3D in the first place.  Let's take a look at these and see what they are.

在主程序开始之前我们要添加一些Direct3D的引用和全局变量声明，我们看看下面的代码：

 

 

#include <d3d9.h>

This includes the Direct3D 9 header file.  This consists of various declarations to the actual methods contained in the Direct3D library.

这一句包含Direct3D9的头文件，这里是我们用到的Direct3D库里面的类啊函数啊神马的声明。

 

#pragma comment (lib, "d3d9.lib")

This includes the Direct3D 9 library file.  The #pragma comment directive places a certain piece of information in your project's object file.  With our first paramter, lib, we indicate that we want to add a library file to the project.  We then specify which file, "d3d9.lib".

这一句包含了Direct3D的库文件。“#pragma comment”这个命令是用来在你的项目中指定包含一个静态库文件的。他的第一个参数”lib”表明要引入到项目的是一个静态库文件，然后第二个参数是文件名，这里我们用”d3d9.lib”

 

LPDIRECT3D9 d3d;

This variable is a long pointer to Direct3D.  What this means is that we will create a class called iDirect3D9.  When COM makes this class, we will ignore it, and access it only indirectly using this pointer.  We will cover how the class is created in a moment.

这是一个指向Direct3D的长指针变量。这意思就是说我们将创建一个叫iDirect3D9的类。当然我们不需要动手，COM会自己创建它，而我们只要通过这个指针间接访问那个类。稍后我们会讲到这个类具体是怎样被创建的。

 

LPDIRECT3DDEVICE9 d3ddev;

The Direct3D Device interface holds all the information pertaining to the graphics drivers, the video card, and everything else having to do with the hardware side of graphics.  This is a pointer to the class that stores all this information.

Direct3D Device接口里保留着所有与图形驱动，显卡，以及其他什么东西相关的信息。而我们定义的这个指针指向Direct3D Device类存储所有的信息。

 

2. 创建一个函数来初始化Direct3D和创建Direct3D Device

The first step to actually coding Direct3D is to create the interface and initialize the graphics device.  This is done using two functions and a struct containing graphics device information.  Let's take a look at this function here, then go over its parts.  I didn't bother to bold the new parts, because the entire thing is new.

实际上Direct3D编码的第一步是建立界面和初始化图形设备。我们用两个函数加一个包含图形设备信息的结构体来完成这一步。让我们看看这个函数,然后再分析部分代码。我不想去加粗新的部分,因为那一整块都是新的。

 

 

if the comments here are good enough for you, excellent.  Otherwise, I've described each of these commands below.

如果这些注释足够你看懂程序，那TM太好了，恭喜你，你可以跳过下面的详细解释了

 

d3d = Direct3DCreate9(D3D_SDK_VERSION);

This is where the fun begins.  This is the first Direct3D function you will run.  It's primary purpose is to create the Direct3D interface.  The return value is the address of the interface created, and so we will store this address in the pointer we created earlier, d3d.

这是个有趣的开始。这是你将要运行的第一个Direct3D函数。它的主要目的是创建Direct3D接口。它的返回值是创建的借口的地址，于是我们就能把这个地址存储在名为d3d的指针中。

 

Then there is the parameter.  This parameter is always the same: D3D_SDK_VERSION.  Why is this?  Well, it really only matters for compatibility on other machines.  When a later release of DirectX is published, the users will usually have varying levels of DirectX upgrades.  This tells the user's DirectX which version you developed your game for.  The user's DirectX can then look back and properly execute your program without implementing the upgrades that have occurred since then.  Kinda useful, eh?

然后你发现，哎呀，这还有个参数呢。是的是的，我没忘记它，这个参数他永远是这个单词“D3D_SDK_VERSION”，这是为神马呢？原来，他是为了保证在不同机器上的兼容性。当一个更新版本的DirectX推出以后，用户一般会有不同程度的升级。这个常量会告诉用户的DirectX你写的程序是哪个版本的。然后用户的DirectX就不会调用升级后的新特性以便能够正确执行你的程序。

 

In the version of Direct3D 9c, this value returns 32.  Previous versions would return different values, causing DirectX to function in different ways.  Note that you should not change this value, as it will cause confusion and is not really needed anyway.  Just use D3D_SDK_VERSION, and everything will work out all right.

在DirectX 9c中，这个返回值是32。更早的版本会返回其他值。造成DirectX调用不同的函数。注意，你不能改变这个值，这样会引起天下大乱而且你也不需要这么做。老老实实就就用“D3D_SDK_VERSION”吧，代表国家感谢你。

 

D3DPRESENT_PARAMETERS d3dpp;

There are certain factors involved in both beginning and advanced game programming which require certain information to be fed into the graphics device from the start.  There are plenty of these, but we will only go into three of them here.  For now, D3DPRESENT_PARAMETERS is a struct whose members will contain information about the graphics device.  We will go over the ones we use here and cover new members as they come up throughout the tutorial.

在初级和高级游戏编程,有一些因素从一开始就需要馈入图形设备。这样的因素有许多,但是我们只需要三个。在这里,D3DPRESENT_PARAMETERS是一个结构体，它的成员包含了图形设备的信息。下面我们将来了解那些我们现在用到的以及后面将要用到的贯穿这个教程始终的新成员。

 

ZeroMemory(&d3dpp, sizeof(d3dpp));

We use ZeroMemory() to quickly initialize the entire d3dpp struct to NULL.  That way we don't have to go through every member of the struct and set them individually.

我们ZeroMemory

这个函数来快速初始化我们的结构体d3dpp，将其值置为空。

 

d3dpp.Windowed = TRUE;

When we run Direct3D in a window like we are now, this value is set to TRUE.  Otherwise, it is set to false.  Later, when we make our window full-screen, we will change this value to FALSE.

Note:  There are other changes to make when an application goes full-screen.  Changing this one value will not make your application full-screen, unfortunately.  Patience until the next lesson.

当我们像现在这样在窗口中运行Direct3D，把它的值设为TRUE。否则，它会被设置为false。之后，当我们要让我们的窗口全屏化，我们需将改变这个值设置为false。

注意：要想让程序全屏。仅仅改变这一个值可不行，欲知具体如何，请听下节课分解。

 

d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD;

Before, we talked about swap chains as the method Direct3D uses to change images on the screen.  However, we get to pick which type of swap chain is used.  There are three different kinds.

首先，我们讨论了交换链----也就是使用Direct3D改变屏幕上的图像的方法。然而，交换链是有很多种的，我们需要选择其中一种来使用。这里有三种。

 

[Table 1.1 - d3dpp.SwapEffect Flags]

So which one to use?  Throughout this tutorial I will be using D3DSWAPEFFECT_DISCARD.  The only exception to this will be at some later date when I add additional tutorials on various effects that use the other two methods.

那我们应该用哪一个呢？这个教程自始至终我都会选择D3DSWAPEFFECT_DISCARD。唯一的例外将在以后的某天，我用一个额外的教程讲述其他两种交换链的影响的时候。

 

d3dpp.hDeviceWindow = hWnd;

This value sets the handle to the window Direct3D should use.  We'll just use the same hWnd we've always been using.

这个值用于设定Direct3D的窗口句柄。我们会始终使用“hWnd”这个单词。

 

d3d->CreateDevice()

This is a big function, but in actual fact, it is quite simple.  Most of the parameters will probably stay the same in every game you write.

What this function does is create a graphics device interface.  What this means is a new class will be created from which you will handle all the graphics you need.  Notice that this function is part of the d3d class.  Most of the functions you use in Direct3D will come from here, so we give the pointer a rather simple name, d3ddev, as seen before.

Here is this function's prototype:

这是一个很大的函数，但实际上，它还很简单的。大多数参数可能会总是一样，在你写的每个游戏中。

这个函数的作用是创建一个图形设备接口。这意味着一个新的类将被创建，从从您可以进行所有你需要的图形处理。注意，这个函数是D3D的类的一部分。你在Direct3D中使用的大多数函数将来自这里，所以我们给这个指针一个相当简单的名称，d3ddev，正如我们前面见过的那样。

下面是这个函数的原型：

 

现在让我们来看看这个函数的参数。他们都很简单,那么这将会很快。

 UINT Adapter,

This is an unsigned integer that stores a value indicating what graphics adapter, or video card, Direct3D should use.  We could get detailed here, and try to find the better graphics card, but we'll let Direct3D take care of that for us (because in most cases there's only one).  To tell Direct3D that it needs to decide, we put into this parameter the value D3DADAPTER_DEFAULT, indicating the default graphics card.

这是一个无符号整数，用于存储一个值来指明我们要使用哪些图形适配器，或视频卡，Direct3D。在这里我们可以得到详细的，并试图找到更好的图形卡，但我们会让Direct3D尽量小心（因为在大多数情况下只有一个）。要告诉Direct3D它进行决断需要的信息，我们把这个参数的值设为D3DADAPTER_DEFAULT，表示默认的图形卡。

 

D3DDEVTYPE DeviceType,

While there are four possible values for this parameter, we are only going to be concerned with one of them, and stay away from the others until later.  The one we will use is D3DDEVTYPE_HAL.

D3DDEVTYPE_HAL tells Direct3D to use what is called the Hardware Abstraction Layer.  The Hardware Abstraction Layer, or HAL, is used to indicate that Direct3D should be using hardware to process graphics (and we would use...what else?).  If for some reason our graphics device cannot use hardware to handle something, that something will be rendered by software instead.  This is done automatically, but probably won't be done, considering the capabilities of modern cards.

虽然有四个可能的值，但我们只打算用其中的一个方面，并且一直用它。他就是D3DDEVTYPE_HAL。
D3DDEVTYPE_HAL告诉Direct3D使用所谓的硬件抽象层。硬件抽象层，或者简称HAL，是用来指示Direct3D应该用硬件来处理图像（不然我们还能用什么？）。如果由于某种原因，我们的图形设备无法使用硬件来处理的东西，这东西会被软件渲染来代替。这都是自动完成的，但也可能不会这么做，考虑到现代卡的性能。

 

HWND hFocusWindow,

This is the handle to our window.  We can just put 'hWnd' in here as we passed the value from WinMain().

这是我们的窗口句柄。我们可以把'hWnd'放在这里，正如我们从WinMain（）中传递了这个值一样。

 

DWORD BehaviorFlags,

While there are plenty of values we can store in this parameter, there are only three we will cover just now.  They are D3DCREATE_SOFTWARE_VERTEXPROCESSING, D3DCREATE_MIXED_VERTEXPROCESSING and D3DCREATE_HARDWARE_VERTEXPROCESSING.  These three values are fairly self-explanatory.  The software one indicates that all 3D calculations should be done with software, the hardware one with hardware, and the mixed one using a combination of both, depending on which Direct3D sees fit.  We will use the software value for compatibility, but you can experiment with these as you desire.  At first you will notice no difference, but as we move into advanced topics, you may start to see some differences appear.

尽管有很多的值供我们存储在此参数中，但是我们只会用其中三个。他们是D3DCREATE_SOFTWARE_VERTEXPROCESSING，D3DCREATE_MIXED_VERTEXPROCESSING和D3DCREATE_HARDWARE_VERTEXPROCESSING。这三个值是相当顾名思义，不言自明，一目了然。第一个表示，所有的3D计算应用软件实现，第三个完全使用硬件，而第二个两者都用，这取决于Direct3D认为哪个在这个工作上哪者更合适。为了兼容性我们会使用第一个值，但是你个人高兴的话，试试别的我也不介意。起初，你会发现没有什么区别，但是当我们玩到更深层次的时候，你可能会开始看到一些不同之处。

 

D3DPRESENT_PARAMETERS *pPresentationParameters,

This is a pointer to the d3dpp struct that we filled out earlier.  We just fill this with '&d3dpp'.

这是一个指向我们早些时候定义的d3dpp结构体的指针。我们只要在这写上'＆d3dpp'。

 

IDirect3DDevice9 **ppReturnedDeviceInterface

This is a pointer to a pointer to the graphics device interface (if you can understand that).  Earlier in the program we defined this pointer as d3ddev, so we will put '&d3ddev' in this parameter.

And that's it!  You have an entire function using Direct3D.  However, if you run this program (and you should not), you will find that absolutely nothing different occurs.  All we have done at this point is prepare for action.  Now let's have some action!

这是一个指向图形设备接口（如果你能理解）的指针。早些时候，我们在程序中定义的这个d3ddev指针，所以我们会在这使用参数'＆d3ddev'。
就是这样！然后你就可以使用Direct3D的完整功能。但是，如果你运行这个程序（其实你不应该这么做），你会发现，绝对没有什么不同的发生。所有我们在这一点上做的准备动作。现在，让我们有一些行动！

 

3.  Create a function to render a frame

In this function we will render a single frame.  The frame will be rather simple, and will consist of a blue background.  Of course, you can change the color if you want.  Here is the code for this function. 

 

 

 

 There are four functions to rendering a frame, two of them big (but simple) and two of them small.  We'll go over them here.

这儿有个用来渲染帧的函数，两个大的（但简单），两个小的。让我们一起去了解他们。

 

d3ddev->Clear(0, NULL, D3DCLEAR_TARGET, D3DCOLOR_XRGB(0, 40, 100), 1.0f, 0)

This clears a buffer to a specific color.  In this case, we are going to clear our back buffer.  It's pretty simple.

Because most of the parameters are irrelevant at this point, we will leave most of them alone.  The first two have to do with clearing a specific area.  You will rarely need this, but will just leave them at 0 and NULL, indicating the entire back buffer is to be cleared.  The third parameter, set to D3DCLEAR_TARGET, indicates that we should clear the back buffer.  There are other types of buffers, but we want this type.  Next we have color.  The parameter is the struct D3DCOLOR, and we will use the function D3DCOLOR_XRGB() to build the color.  The next two parameters we will get into in later lessons.  For now, just set them to '1.0f' and 0.

这将清空一个特定的颜色缓冲区。在这短代码中我们会清空我们的后缓冲区。这相当简单。
由于大多数参数里无关紧要，所以我们不管他。前两个负责清除特定区域。一般咱用不到，所以就给他们0和NULL，这样整个背部缓冲区都将被清除。第三个参数“D3DCLEAR_TARGET”表明我们应该清除后备缓冲区。还有其他类型的缓冲区，但我们需要清除的就是这种类型。下一步，我们的颜色参数是D3DCOLOR结构体，我们将使用函数D3DCOLOR_XRGB（）来构建颜色。接下来的两个参数，我们将在以后的课程了解。现在，只需将它们设置为'1 .0 f'和0。

 

 

d3ddev->BeginScene()

Next we call the function BeginScene() which tells Direct3D you are ready to start rendering.  This function needs to be called for two reasons.  First, you need to tell Direct3D that you are in control of the memory.  Second, this function does something called locking, where the buffer in the video RAM is 'locked', granting you exclusive access to this memory.  There is no guarantee that your memory will stay put and not be moved around while you are trying to work on it.  Having your memory suddenly appear somewhere else can be quite a hassle for sure.

接下来我们调用函数BeginScene（），它告诉Direct3D休息时间结束，可以开始渲染了。这个函数需要被调用的原因有两个。首先，你需要告诉Direct3D她现在受内存管。其次，这个函数会对在视频RAM的缓冲区进行锁定，授予您独家访问此内存的权限。毫无疑问，你的内存将留在原地，不会随意移动，而你正在试图进行这项工作的保证。如果你的内存突然出现在别的地方可以是一个相当肯定的麻烦。

 

d3ddev->EndScene()

Next we call the function EndScene().  While BeginScene() locked the video memory we wanted, EndScene() unlocks it, making it available by other processes that need access to it.

Note:  Locking video RAM is slow, but required.  You should call BeginScene() and EndScene() only once per frame to save your valuable CPU ticks.

接下来，我们调用函数EndScene（）。BeginScene（）会锁定我们想要的显存，而EndScene（）可以对之解锁，使得它可以被其他进程访问。
注意：锁定视频RAM是很慢的，但又是必要的。你应该每帧只调用BeginScene（）和EndScene（）一次，节约宝贵的CPU资源。

 

d3ddev-> (NULL, NULL, NULL, NULL)

And finally we call the Present() function.  The four parameters, all set to NULL, are not going to be used in this tutorial.  Three of them have to do with the slowest method of handling the swap chain (which we don't use) and the other one has to do with presenting to a different window (which we won't need and won't go into).

最后，我们调用Present()函数。这四个都设置为NULL的参数，不会在本教程中使用。其中3个是与处理交换链的方法中最慢的（本教程坚决不用），而另一个是介绍到不同的窗口（我们不需要，也不会进入）。

 

4.  Create a function to close Direct3D

This is the last (and easiest) step to creating a Direct3D program.  We just have two steps here:

这是最后一个（最简单）的步骤，创建一个Direct3D程序。我们只是在这里有两个步骤:

 

 

 

Here, we call the Release() function from each of the two interfaces we created, d3ddev and d3d.  No parameters, nothing spectacular.  Just cleans everything up.

在这里，我们从我们创建的两个接口调用Release（），d3ddev和D3D的每一个功能。没有参数，没有返回。仅仅是清理一切。

 

Why?  Well, let's say it would be a bad thing to do otherwise.  Basically, if you create Direct3D, but never close it, it will just keep on running in the background of the computer until your next reboot, even after the program itself closes.  Bad.  Especially bad if you have a lot of resources in your game.  Releasing these two interfaces let's everything off the hook and allows Windows to take back it's memory.

为什么呢？我得说如果不这么做请你后果自负。基本上，如果你创建了Direct3D却从来没有关闭它，它就会不停地在计算机后台运行直到你重启电脑，即使在程序本身关闭之后。特别是如果你有一堆坏的资源在你的游戏中，哦，买雷迪嘎嘎。释放这两个接口吧，让一切干干净净，而Windows也可以收回它的内存。

 

The Finished Program

Wow!  That was quite a start, but it will go down from here.

Let's take a look at what we just did.  Following is the code we added to our program.  The new parts are now in bold.

哇！这仅仅还一个开始，但是我们将从这里迈出第一步。
让我们来跑跑看我们刚刚做的程序。以下是我们的代码。没出现的部分会以粗体显示。

[Show Code]

And that's it!  If you run this program you should get something like this:

那么，不出意外的话，你的程序跑起来应该像这样：

Image 1.3 - Our First Direct3D Program

Summary

Well, it isn't much yet.  But you have begun the journey into the near-inifinite depths of 3D game programming.  You've created a window and gotten DirectX to put an image (albeit a somewhat dull image) into it.

嗯，本节课已经没有多少了呢。但是我已经成功地把你带进3D游戏编程的旅程，虽然现在还在入门水平。您已经成功地创建了一个窗口，并通过DirectX成功嵌入一幅图像（虽然这图像实在很无聊）。

As an exercise, see if you can get your program to change colors while running.  Try to make it fade from blue to black, then to blue again, and repeat.

尝试一下这个练习吧，看看你能不能在程序运行时改变它的颜色。尝试做个蓝黑渐变，然后再为蓝色，反复如此。

So we haven't got a game running yet, but we have enough concepts to start.  So with that, let's dive right in and start your next step (which is rather short, btw)!

事实上我们还有没有一个游戏运行，但我们有足够的基础概念。千里之行，始于足下，各位看官切记，切记！

Next Lesson:  Going Fullscreen

下一课：走向全屏

GO!GO!GO!

Finished 20101110,耗时10天