An Introduction To Direct3D
By Simon Price
Tutorial Breakdown
This tutorial will consist of the following steps :

 

Explanation of what Direct3D does and how you can use it
from Visual Basic
 

Definitions of all the objects, types and enumerations you
will need to know to get started
 

Example source code with heavy commenting
 

Summary of what you have learnt
 

Exercises to make you remember it all

Direct3D Overview
Direct3D is a part of DirectX. This tutorial is specific to
Direct3D 7, so you will need DirectX 7.0 or higher if you are planning to use
what you learn here. DirectX has a component called DirectDraw, which is used to
perform graphics functions at a lower level that Windows GDI. If you have never
used DirectDraw before, I suggest you look at my tutorial "An Introduction
To DirectDraw", available on this site, or my
website. Direct3D (D3D) has two main parts - Immediate Mode and Retained
Mode. This tutorial deals with Immediate Mode only. Immediate Mode (IM) is built
on top of DirectDraw. That means it uses DirectDraw to place graphics on the
screen, or in memory. D3D Retained Mode (RM) is built on top of D3D IM.
Therefore, D3D RM is not as efficient as D3D IM. This is why I have chosen to
learn D3D IM. However, I do not claim that one is better than the other, just
that IM is faster and RM is easier to learn and create applications very quickly
with. If you learn IM, heavy vector mathematics and slow development is involved
but you will be rewarded with more power and control. The choice is yours. If
you still want to learn IM, then read on.
Direct3D has a job - to give programmers a common interface for
all 3D devices. In English - no matter what computer your application runs on,
whether it has a Voodoo Mega Wicked 10000 3D accelerator or a Omega Budget 256
Color Economy VGA card, you still use the same objects to program with. It means
that you don't have to learn about how every graphics card works for your
application to work on every computer. Direct3D also provides software
emulation. This means that if half your users have hardware acceleration, and
half don't, you can use hardware if available and then fall back to using
Direct3D software emulation if the hardware is not available. Of course software
emulation is alot slower.
It's time to start Visual Basic! Create a new project and called
it something imaginative like "D3Dintro.vbp". Next, click Project -> References
and a dialog box will show a list of references your project uses. If you have
installed the DirectX7 For Visual Basic type library, scroll down to it and
check the check box next to it. Click OK to add the reference. Now Visual Basic
knows every single class, type and enumeration you need to use DirectX7. If you
do not have the DirectX 7 For Visual Basic Type Library, you can download it
from www.microsoft.com .
Get on with the programming!
Here are the declarations you will need for the tutorial
programs, with a short explanation as to what they are all about. First the
objects followed by the types.

 

DirectX7 - this is the great big daddy of them all!
It is from the DirectX7 object that you will create all the other objects,
including DirectDraw and Direct3D. Note the use of the New keyword, meaning
that your application puts aside the memory to create a new instance of this
object.


 
Dim DX As New DirectX7


 

DirectDraw7 - this is the base of all the graphics
functionality that DirectX provides, including Direct3D7. Note the omission
of the New keyword, since you do not create this object, but DirectX does.


 
Dim DDRAW As DirectDraw7


 

DirectDrawSurface7 - this is an object created by
DirectDraw to represent a piece of memory. You will need a primary and
backbuffer surface. The primary surface represents the actual graphics on
the screen, the backbuffer is a surface to draw our whole image onto before
we copy it to the primary surface.


 
Dim Primary As DirectDrawSurface7


 
Dim Backbuffer As DirectDrawSurface7


 

DirectDrawClipper - this is used to clip areas,
meaning that if you try draw outside the clipping boundaries, nothing will
be drawn. This is useful in Windows so that you don't make a mess all over
bits of screen that don't belong to your application.


 
Dim Clipper As DirectDrawClipper


 

Direct3D7 - this is based upon DirectDraw. It
provides all the 3D functionality you will need.


 
Dim D3D As Direct3D7


 

Direct3DDevice7 - this is the rendering device. You
use it to control the states and parameters of Direct3D, and to send drawing
commands to draw (usually) triangles.


 
Dim D3Ddevice As Direct3DDevice7


 

RECT - this describes a rectangle, and DirectDraw
uses it to copy rectangular pieces of pictures around. Here we need two,
they are just cached for regular use in the program.


 
Dim SrcRect As RECT


 
Dim DestRect As RECT


 

D3DRECT - this is similar to the RECT type used with
DirectDraw. We will use it in clearing operations. You will always need to
declare it as an array, even if you only need one of them.


 
Dim Viewport(0) As D3DRECT


 


 
DDSURFACEDESC2 - this describes a DirectDrawSurface,
 so we can ask DirectDraw to create a surface with the properties we need.
 
 

Dim SurfDesc as DDSURFACEDESC2
 


 

D3DVIEWPORT7 - this describes the way in which
Direct3D transforms a 3D scene to represent it on a 2D surface.


 
Dim VPdesc As D3DVIEWPORT7


 

D3DVERTEX - this type holds all the information we need to
 create a vertex. We are going to create a triangle so we need an array
 of 3.
 


 
Dim Vertex(0 to 2) as D3DVERTEX


 

D3DMATRIX - this holds 16 values which are used for
any and every translation in 3D. With a matrix, you can translate, rotate
and scale. We will need four in this tutorial, the world, view, projection
and spin matrices.


 
Dim matWorld As D3DMATRIX
Dim matView As D3DMATRIX
Dim matProj As D3DMATRIX
Dim matSpin As D3DMATRIX

 
You will also need to declare two other variables:

 
' this tells the program when to end
Dim EndNow As Boolean
' this is used to rotate the triangle
Dim Counter As Long


Initiation of DirectDraw and Direct3D
Now we have declared all the objects we need, we need to call
some of their methods to make them do something. We will also use the variables
to send information to DirectX. Since Direct3D is built upon DirectDraw, we will
need to initialize the DirectDraw objects before Direct3D.
The DirectDrawInit Function
We will create a function that creates the DirectDraw object,
sets the cooperative level, sets up the primary and backbuffer surfaces for
our graphics functions to work on, and finally creates a clipper to restrict
drawing to just the application window. Note then when we create the backbuffer
surface, we pass the DDSCAPS_3DDEVICE flag to tell DirectDraw that we are going
to use it as a 3D rendering target.

 
Function DirectDrawInit() As Long
' create the directdraw object
Set DDRAW = DX.DirectDrawCreate("")
' set the cooperative level, we only need normal
DDRAW.SetCooperativeLevel hWnd, DDSCL_NORMAL
' set the properties of the primary surface
SurfDesc.lFlags = DDSD_CAPS
SurfDesc.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE
' create the primary surface
Set Primary = DDRAW.CreateSurface(SurfDesc)
' set up the backbuffer surface (which will be where we render the 3D view)
SurfDesc.lFlags = DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_CAPS
SurfDesc.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_3DDEVICE
' use the size of the form to determine the size of the render target
' and viewport rectangle
DX.GetWindowRect hWnd, DestRect
' set the dimensions of the surface description
SurfDesc.lWidth = DestRect.Right - DestRect.Left
SurfDesc.lHeight = DestRect.Bottom - DestRect.Top
' create the backbuffer surface
Set Backbuffer = DDRAW.CreateSurface(SurfDesc)
' cache the size of the render target for later use
With SrcRect
.Left = 0: .Top = 0
.Bottom = SurfDesc.lHeight
.Right = SurfDesc.lWidth
End With
' create a DirectDrawClipper and attach it to the primary surface.
Set Clipper = DDRAW.CreateClipper(0)
Clipper.SetHWnd hWnd
Primary.SetClipper Clipper
' report any errors
DirectDrawInit = Err.Number
End Function


 
The Direct3DInit Function
 
Now we need to initialize all our Direct3D objects. In this
 function, we need to create Direct3D, a rendering device (something that does
 the drawing for us), a material (defines the appearance of polygons), and
 several matrices. The rendering device can be some hardware device like a 3D
 accelerator card, or software emulation. For this tutorial, we will use
 software emulation for simplicity. The matrices are :

 

The world matrix - all objects in world space are
transformed by this matrix
 

The view matrix - sets the position of the camera
 

The projection matrix - defines how Direct3D projects the 3D
scene onto the 2D surface


 
Function Direct3DInit() As Long
' create the direct3d object
Set D3D = DDRAW.GetDirect3D
' create the rendering device - we are using software emulation only
Set D3Ddevice = D3D.CreateDevice("IID_IDirect3DRGBDevice", Backbuffer)
' set the viewport rectangle.
VPdesc.lWidth = DestRect.Right - DestRect.Left
VPdesc.lHeight = DestRect.Bottom - DestRect.Top
VPdesc.minz = 0
VPdesc.maxz = 1
D3Ddevice.SetViewport VPdesc
' cache the viewport rectangle for later use
With Viewport(0)
.X1 = 0: .Y1 = 0
.X2 = VPdesc.lWidth
.Y2 = VPdesc.lHeight
End With
' enable ambient lighting
D3Ddevice.SetRenderState D3DRENDERSTATE_AMBIENT, DX.CreateColorRGBA(1, 1, 1, 1)
' disable culling
D3Ddevice.SetRenderState D3DRENDERSTATE_CULLMODE, D3DCULL_NONE
' set the material to a red color
Material.Ambient.r = 1
Material.Ambient.g = 0
Material.Ambient.b = 0
D3Ddevice.SetMaterial Material
' the world matrix - all polygons in world space are transformed by this matrix
DX.IdentityMatrix matWorld
D3Ddevice.SetTransform D3DTRANSFORMSTATE_WORLD, matWorld
' the view matrix - basically the camera position is at -3
' (although it's really just making the whole world at +3)
DX.IdentityMatrix matView
DX.ViewMatrix matView, MakeVector(0, 0, -3), MakeVector(0, 0, 0), MakeVector(0, 1, 0), 0
D3Ddevice.SetTransform D3DTRANSFORMSTATE_VIEW, matView
' the projection matrix - decides how the 3D scene is projected onto the 2D surface
DX.IdentityMatrix matProj
DX.ProjectionMatrix matProj, 1, 1000, 3.14 / 2
D3Ddevice.SetTransform D3DTRANSFORMSTATE_PROJECTION, matProj
' report errors
Direct3DInit = Err.Number
End Function


The MakeVector Function
If you're still alert and haven't become totally confused yet,
you will be saying "hey Simon, you called a MakeVector function - what's
that all about? The MakeVector function is very similar to the
DX.CreateD3DVertex (see later) function - it just saves us alot of typing by
copying values into the D3DVECTOR type. So we need to create the MakeVector
function for the Direct3DInit function to work.

 
Function MakeVector(x As Single, y As Single, z As Single) As D3DVECTOR
' copy x, y and z into the return value
With MakeVector
.x = x
.y = y
.z = z
End With
End Function

Creating The Scene
We need to supply triangles for Direct3D to render. Therefore we
should declare some vertices to make the triangle from. For simplicity, we will
render just one triangle which means we need only 3 vertices (one for each
corner). We could fill in the data separately for each field of the type
D3DVERTEX, but it's much shorter to use a function of the DirectX object that
does this for you in one line of code.
The CreateTriangle Sub
This procedure takes the already declare vertices and forms them
into a triangle shape. In a D3DVERTEX, there are three pieces of data - the
position (x,y,z), the normal (nx,ny,nz) and the texture coordinates (tu,tv). We
only need to use the position in this tutorial. The normal of a triangle is
concerned with lighting, which we aren't using. The texture coordinates are for,
well, textures - which we aren't using either.

 
Sub CreateTriangle()
' fill in the vertex positions - we don't need to worry about the normals
' or texture coordinates for this tutorial
DX.CreateD3DVertex -1, 0, 0, 0, 0, 0, 0, 0, Vertex(0)
DX.CreateD3DVertex 0, 2, 0, 0, 0, 0, 0, 0, Vertex(1)
DX.CreateD3DVertex 1, 0, 0, 0, 0, 0, 0, 0, Vertex(2)
End Sub


The Main Program Loop
OK that's enough loading and initializing to last me a lifetime!
But once you've learnt it, it will get easier and you can always reuse your
code. Now we move onto the main program loop. This is a loop where we clear the
backbuffer, draw the polygon, copy the backbuffer to the screen and then move
the polygon before we draw the next frame. Don't be surprised if this loop runs
at over 100 frames per second - after all, it's just one polygon. In a real
world application, you may want to render thousands per frame. On with the show:

 
Sub MainLoop()
Do While EndNow = False
' increase the counter
Counter = Counter + 1
' clear the viewport with a green color
D3Ddevice.Clear 1, Viewport(), D3DCLEAR_TARGET, vbGreen, 0, 0
' begin the scene, render the triangle, then end the scene
D3Ddevice.BeginScene
D3Ddevice.DrawPrimitive D3DPT_TRIANGLELIST, D3DFVF_VERTEX, Vertex(0), 3, D3DDP_DEFAULT
D3Ddevice.EndScene
' rotate the matrix
DX.RotateYMatrix matSpin, Counter / 360
' set the new world transform matrix
D3Ddevice.SetTransform D3DTRANSFORMSTATE_WORLD, matSpin
' copy the backbuffer to the screen
DX.GetWindowRect hWnd, DestRect
Primary.Blt DestRect, Backbuffer, SrcRect, DDBLT_WAIT
' look for window messages - we need to know when the escape key is pressed
DoEvents
Loop
End Sub


Getting It Together
If you run your program now, nowt will happen at all. This is
because you have created a load of procedures but you haven't called them from
anywhere. This is when you will need to put some code into the Form_Load event,
to do initiation and then the main loop. We will check the return values of the
initiation functions, and if they report errors we will end the program.
The Form_Load Event

 
Private Sub Form_Load()
' show the form
Show
' call the DirectDrawInit function and exit if it fails
If DirectDrawInit() <> DD_OK Then Unload Me
' call the Direct3DInit function and exit if it fails
If Direct3DInit() <> DD_OK Then Unload Me
' create the triangle
CreateTriangle
' call the main rendering loop
MainLoop
' end the program
Unload Me
End Sub

The Form_Unload and Form_KeyDown Events
There is one more thing to do - end the program! The main loop
is exited if the EndNow variable is set to true - so that's all we need to do.
We can also end the program if the escape key is pressed, by putting the same
code in the Form_KeyDown event.

 
Private Sub Form_Unload(Cancel As Integer)
EndNow = True
End Sub



 
Private Sub Form_KeyDown(KeyCode As Integer, Shift As Integer)
' end program if escape is pressed
If KeyCode = vbKeyEscape Then EndNow = True
End Sub


Run The Program
Run the program. If you've typed it correctly (or just used my
example code), you will see the form has a spinning triangle painted on it. You
can even resize the form and the picture will resize to the form size. When you
close the form or press escape, the program ends.
Summary
In this tutorial, we have :

 
Learnt how to set up DirectDraw surfaces for Direct3D.
 
Set up Direct3D, telling it to render on a DirectDraw surface
 
Create a very basic geometric shape
 
Render a triangle and change the world matrix to move spin the world

There are many bad points to the program you have created, although I have
made the program in this way to make it as simple as possible.

 
All the variables were global - in my opinion you should restrict access
to each variable as much as possible. I made them all global for this
tutorial so I could explain each one at the beginning
 
Very little error handling was done. In a real application, we would find
the cause of the error, attempt to fix it, and if that's not possible we
would tell the user why, rather than ending immediately.
 
We used software rendering only. What we should do is find out what sort
of hardware the user has, and make our program adapt to either make maximum
use of the hardware, or fall back onto just software if no hardware is
available.
 
And I'm sure the critics amongst you will think of more.

Exercises
You can only learn something if you actually practice doing it. So here I
have some features which you can add to the program yourself. Come on, be a
little creative and start making your own 3D graphics!

 
That triangle is boring! It's even looks 2D! Use more vertices to make
another shape - a cube, a pyramid, a sphere if you're smart enough -
whatever you like!
 
Make a frame counter, so that you know how fast the program is running. I
bet it goes at over 100 FPS!
 
Change the colors to something you like.
 
Explore more Direct3D functions, meddle with the code, make it your
program. I don't want here any complaints that this tutorial was boring -
it's up to you to make it interesting!

I hope I've set you along the exciting journey towards creating Direct3D
graphics from Visual Basic. This tutorial has taken me ALOT of time and
effort - I had to write code, make comments, write a tutorial, get it as
accurate as possible. I would appreciate in return:

 
Please vote for me - Whether you think this tutorial was
good or bad, I want to know about it.
 
Please give me some feedback - Tell me why you voted the
score that you did.
 
Please visit my website - If you liked this then you'll want
to visit my website to see more of my programs and tutorials. The URL is www.VBgames.co.uk
 
 
Please give me $30000 to write a book - OK only joking.

Tutorial by Simon Price, you can email me at Si@VBgames.co.uk

Back To Top