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

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