There is an easy way to learn DirectX.  Unfortunately, that easy way has a lot of limits to its capabilities, and even if it didn't, it is quite a hassle to use in large games.  The easier way to program is, of course, harder to learn, and this lesson will cover that easier-to-program way, hopefully without making the learning part too hard.

In this lesson you will learn to draw a triangle on the screen.  We will build this triangle by creating a series of vertices and having the Direct3D device draw them on the screen.

First we will cover the theory of how this all works, then we will go over the code itself and build the program.

If you went through Lesson 3 in any great detail, you will recall the definition of vertex:  the location and properties of an exact point in 3D space.  The location simply consists of three numerical values which represent the vertex's coordinates.  The properties of the vertex are also defined using numerical values.

Direct3D uses a technology called a Flexible Vertex Format (or FVF).  A vertex format is the layout of the data containing the location and properties of a vertex.  A flexible vertex format would be a format of data that you can modify and set according to your needs.  Let's take a look at how this works exactly.

A vertex is made of a struct, which contains the data pertinent to creating whatever 3D image it is made for.  To display the image, we will copy all the information to the Video RAM and then order Direct3D to copy the data to the back buffer.  However, what if we were forced to send all the data that could possibly be wanted for a vertex?  This would happen.

Image 4.1 - A Vertex Format Containing All Possible Data

Of course, you may not see right away what the problem is here, but let's say we only needed two of these blocks of information.  We could send it to the Video RAM much faster by doing it like this:

Image 4.2 - A Flexible Vertex Format Goes Faster

This is what happens when we use a flexible format.  We select which information we want to use, and send just that, enabling us to send many more vertices between each frame.

FVF Codes

In Direct3D, each vertex is made from a pre-set vertex format.  As the title claims, this format is flexible, and is built using certain elements Direct3D provides.  The elements are set using specific flags which, when logically ORed together, create a vertex definition, or a code that tells Direct3D the vertex format.

Let's take a look at how this is done.  Let's say we want to include the location and the diffuse color of our vertices.  We would build a code that looked like this:

Later, when we are working with the vertices, we will simply use CUSTOMFVF, rather than type out the entire FVF code each time.  We'll see an example of this in a minute.

We can add all kinds of flags into this expression here.  Following is a table of flags we will use throughout this tutorial, and a description of what they do (although don't go plugging them in randomly just yet).

[Table 4.1 - FVF Code Flags]

There are, of course, more things to put in, and they are all covered in the DirectX documentation.  However, we will only be needing these flags for this tutorial.

Creating Vertices

Now we need to create the vertices using our new format.  We don't use any new function or anything like that; we do it by building a simple struct containing the variables we included in the FVF code.

For instance, we used both the D3DFVF_XYZRHW and D3DFVF_DIFFUSE flags in the example above, and to go with it, we should build the following struct:

As you can see, the first four FLOATs are values represented by the D3DFVF_XYZRHW flag, while the DWORD is represented by the D3DFVF_DIFFUSE flag.  If you look at the above table, you will find which variable types go with which FVF code flags.

Now let's build an actual vertex using our new CUSTOMVERTEX struct.  We could do it like this:

Of course, we could also make an array of vertices like this:

This results in a triangle, which we will see drawn on the screen shortly.

This is just one example of a Flexible Vertex Format.  We will go over how to build more complex vertex formats later, but this one will do for now.

Now we have acomplished two things.  First, we have built an FVF code.  Second, we have constructed a triangle.  Now we need to get that triangle ready for Direct3D to use.  To do this, we create what is called a vertex buffer.

A vertex buffer is simply an interface that stores a section in memory (either Video RAM or system memory) to holds information about the vertices/models in your game.  We create this interface by using the function CreateVertexBuffer().  The name is self-explanatory.  It's parameters, however, are less merciful.  Here is the prototype:

Let's take these parameters up one at a time.

UINT Length,

This parameter contains the size of the buffer that will be created.  We get this number by multiplying the size of one vertex by the number of vertices that will be stored in the buffer.  For example, a triangle contains three vertices, so the size of the triangle's buffer is:  3 * sizeof(CUSTOMVERTEX).

DWORD Usage,

Sometimes there are special ways to use vertices which alter the DirectX handles the vertices.  We will not get into these in any great detail in this tutorial.  This parameter can contain flags indicating these special ways.  As we won't be using any yet, we'll just set it to 0 for now.

DWORD FVF,

This is the FVF code we constructed earlier.  We just fill it in with CUSTOMFVF.  If we went up to change the FVF code, this part would also change (hence the #define).  This is what tells DirectX what format the vertices are in, so it is important that what you put here is accurate.

D3DPOOL Pool,

This parameter tells Direct3D where to create the vertex buffer and how.  Following is a table that describes the possible entries for this parameter.  For this tutorial, we will be using the flag D3DPOOL_MANAGED.

LPDIRECT3DVERTEXBUFFER9 ppVertexBuffer,

If you can't decode that, it's the pointer to the vertex buffer interface we're making.  We put the blank pointer in this parameter and the function simply fills it in for us.

HANDLE* pSharedHandle

The documentation says this parameter is, and I quote, "Reserved.  Set this parameter to NULL".  What this means I can't say for certain, but apparently Microsoft want us to set it to NULL.  So be it.  We'll set it to NULL.

And with all that in mind, let's take a look at how this function appears in our program:

Now that you have created your vertex buffer, you need to load the vertices into it.  You do this using a simple call memcpy().  However, before you can get access to the buffer, you need to lock it.

There are two reasons you need to lock the buffer.  First, you need to tell Direct3D that you need complete control of the memory.  In other words, it shouldn't be handled by any other process that might be going on.  Second, you need to tell the video hardware not to move it around.  There is no guarantee that the Video RAM will stay put.  Locking tells the video hardware not to mess around with the memory while you are working with it.

To lock a buffer, you use the Lock() function, which has four parameters, but is actually quite simple:

Let's go over these parameters.

UINT OffsetToLock, UINT SizeToLock,

If we only wanted to lock part of our vertex buffer, we would indicate that in these two parameters.  The first one indicates how far into the buffer, in bytes, the lock should start.  The second indicates how much should be locked, again in bytes.  We want to lock the entire buffer, so we'll set both of these to 0.

VOID** ppbData,

Unless you are at least intermediate with C++ this will probably make no sense to you.  Basically a void* is a pointer that points to no particular type of variable.  For example, a double* points a double, whereas an int* points to an int.  Each type of pointer has it's own format, and so it can't convert to another type without loss of data.  A void* points to any of these, and can be converted without trouble.

Here we have a pointer to a void*.  This pointer gets filled with the location of the memory to contain our vertices.  The vertex buffer interface will take care of the details of this, but we need the pointer in the next step, so the Lock() function will fill this pointer with the proper address.  Have a look at the example below to see how we fill this parameter.

DWORD Flags

This is an advanced parameter, and we won't get into it anywhere in this tutorial.  They basically provide special ways to handle the locked memory.  If you are truly interested, they can be researched in the DirectX documentation.  For now, we will just set it to 0.

Let's fill this function out and see how it looks:

Next, we use a call to memcpy() to copy the vertices to the vertex buffer.

Lastly, we have a very complicated function: Unlock().  This function has no parameters.  What it does is tell Direct3D that we're all done with the memory, and it doesn't have to be locked anymore.  It looks like this:

Because of the number of commands we've just learned, we're going to stick them all away into a single function of our own creation: init_graphics().

At this point I would suggest going over this section a couple times to make sure you thoroughly got it all.  This is a rather key part of 3D programming, and we'll be using it and modifying it throughout the rest of the tutorial.

Now we actually get to have something on the screen!  We have three very simple functions to talk about before this happens though.  Each are called from the Direct3D Device interface.  Let's take a look at each one.

SetFVF()

The first of these functions is SetFVF().  SetFVF() is a function that tells Direct3D what FVF code we are using currently.  We could, of course, have multiple FVF codes and use them in two different parts of the 3D scene.  Before we draw anything, we need to tell Direct3D which one we are using.  This function is written out like this:

SetStreamSource()

Next we have the function SetStreamSource(), which tells Direct3D which vertex buffer we are drawing from.  This one has a couple parameters, so let's take a look at the prototype:

The first parameter is the number of the stream source.  We'll get into how this works later, but for now set it to 0, as we only have one vertex buffer.

The second parameter is the pointer to the vertex buffer we created earlier.

The third parameter is the number of bytes into the vertex buffer we should start from.  This will usually be 0.

The last parameter is the size of each vertex.  We fill this with:  sizeof(CUSTOMVERTEX).

Let's take a look at the function as it is used:

DrawPrimitive()

Now that we have told Direct3D what kind of vertices we are using and where to get them from, we tell it to draw the vertices we have built.  This function draws the primitives in the selected vertex buffer to the screen.  Here is the prototype:

The first parameter is the type of primitive that is used.  These were covered in Lesson 3, but the codes used are here:

The second parameter is the number of the first vertex we will put on the screen.  We could, if we wanted, start in the middle of the vertex buffer.  However, we want the whole buffer drawn, so we will put 0 here.

The third and last parameter is the number of primitives we want to draw.  If we draw a triangle, we put one here (there's only one triangle).  If we were using points, we would put 3, as there are three points.  Lines would also be 3.

Now let's take a look at the entire render_frame() function now that we have modified it.

Before looking at the whole program, let's look at one last step that is required.

Just like the Direct3D Device and Direct3D itself, a vertex buffer must be released before our program closes.

Now let's take a look at the whole program to see what we have.

Ok, let's see what a triangle looks like.  If you've never seen one, this will be an educational experience.  If you have (please) you can see how one is made in Direct3D.

Anyway, let's examine the final DirectX code.  The new parts covered in this lesson are in bold as usual.

Go ahead and update your program and let's see what we get.  If you run this, you should see the following on your screen:

Image 4.3 - The Drawn Triangle

Well done!  You have made DirectX actually draw something.  Of course, there is a lot more we can do, but let's start with what we have.  I'd recommend doing the following short exercises before moving on, just so you get familiarity with the program.

1.  Change the colors of the triangle.
2.  Get the triangle to change shape during runtime.
3.  Get the colors to fade from one point to the next.

Of course, you may be disappointed to find that this triangle is not 3D yet, but let's go on to the next lesson and make it 3D by rotating it, resizing it and moving it in a 3D world.