Author: Adam Hoult

In this tutorial we will cover the basics on how to Initialise and open a DirectDraw screen. For this example we will open a screen which is 640 pixels wide, 480 pixels high, and uses 16 bit colours. We will assume you already know how to create a project in VB, and know a little about using forms. Now onto the tutorial. NOTE: This tutorial is designed for those of you with VB5. If you find any discrepancies with this Tutorial, please mail me and I will correct it.

Step 1 - Creating the Project

   First you need to create a project in the usual way. This project must be a Standard Executable. Once the form has been generated, you will need to ammend the following properties.

Name = frmMain (Must be this otherwise the example wont work)
BorderStyle = 1 - Fixed Single (This is so we cannot resize the form at runtime)
Caption = [BLANK] (This field must be cleared, we need to remove the title bar.)
ClipControl = False (Remove the control boxes)
ControlBox = False (Remove the control boxes)

You may also want to set the BackColor property to Black, this is not essential.

Step 2 - Adding The Type Library

   Add Patrice Scribes' type library to the project. To do this you must go to Project/References menus and hit browse. You should automatically be put in the Windows System directory. Type in "DirectX5.TLB" and hit return. You should then see the Type Library has been added to the list. Hit OK, you are now ready to start creating your project.

Step 3 - General Declarations and What They Mean

   Right now we have got that out of the way we can get down to the code. First we will add the variables we need into the General Declarations section of the main form. Here is a list of what variables you need and an explanation of each underneath the piece of code.

Dim dd As DirectDraw2 'Main DirectDraw Object

This is the main DirectDraw device, which is used to perform ALL of the DirectDraw operations. You will see when you are typing this in, a list of objects will appear. You will see a few DirectDraw objects. Generally DirectDraw2 is the best one to use, and the one we will be using for all of these tutorials.

' Surfaces
Dim ddsFront As DirectDrawSurface2 ' Primary Surface
Dim ddsBack As DirectDrawSurface2 ' Back Buffer

These are surfaces, areas of memory which will store either an Image, or the current frame which is/will be displayed. Again use DirectDrawSurface2 as we have defined our DirectDraw device in this way. In this example these two surface will act as the Primary Surface (The current frame being displayed), and the Back Buffer (The frame which is being rendered). Doing it in this manner will eliminate any flicker or tearing caused if we were rendering directly to the Primary Surface. Later on in the tutorials we will show you how to use surfaces to store images to be rendered onto the backbuffer.

'Descriptions
Dim ddsdFront As DDSURFACEDESC ' Primary surface description
Dim ddsdBack As DDSURFACEDESC ' Back Buffer Description

These variables are know as Surface Descriptions. These will store the description of the surface and are used when you are creating the surface. You will see later on how these are used to set what type of surface this is.

'Caps
Dim ddCaps As DDSCAPS ' Capabilities for search

I am not so sure about the reasoning behond this. As far as I can work out this variable defines the search options when attaching a surface to another. It lets you specify what part of the surface you are attaching it to. I.e to the BackBuffer section of the Primary Surface.

'Misc
Dim Running As Boolean ' We are running ?

This variable is used only to keep the main Rendering Loop going. Having a rendering loop is far more efficient than using a timer to render the display. You will see the use of this in the later sections.

Step 4 - On Form Load

   O.k so we have set up our variables to store various things. Now What? Well read on. If you are a VB proffesional please be patient, I am writing this tutorial for beginners, so you may find it a bit laborious, but I hope it's helping the newbies :).

NOTE: Although this next source is split up by my comments, it is all one piece of code, and is all inside the Form_Load Sub.

Private Sub Form_Load()
   'Create the DirectDraw device.
   DirectDrawCreate ByVal 0&, dd, Nothing

This is where the main DirectDraw device is created. You need to pass it the name of the variable you are using as your DirectDraw device. In this case we defined out device as dd. This device will now be created and can be used throughout the rest of your program, until you delete it.

   ' This app is full screen and will change the display mode
   ' Set the app to EXCLUSIVE (removes taskbar, and makes it TOP MOST)
   dd.SetCooperativeLevel frmMain.hWnd, DDSCL_EXCLUSIVE Or _
      DDSCL_FULLSCREEN
   ' Set the display mode to 640x480 with 16bit colours
   dd.SetDisplayMode 640, 480, 16, 0, 0

Ok we have set the apps CooperativeLevel. Basically this lets you define how the screen will be opened. In this case we are opening a Fullscreen application. We need to pass it the hWnd of the parent form. Also we are giving that window Exclusive rights to the system. It will be made to be TOPMOST, which means no other application will be able to switch on top of it, that includes the Start Menu. This can be difficult for debugging purposes. Then we set the display mode to 640 pixels wide, 480 pixels high and will use 16bit colours.

   'This section sets the description structure
   'which needs to be set so that the CreateSurface
   'function knows what type the surface is.
   With ddsdFront
      ' Structure size
      'This is so the function knows how much
      'memory to read.
      .dwSize = Len(ddsdFront)
      ' Use DDSD_CAPS and BackBufferCount
      .dwFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
      ' Its a Primary, flipable surface
      .DDSCAPS.dwCaps = DDSCAPS_PRIMARYSURFACE Or DDSCAPS_FLIP Or _
         DDSCAPS_COMPLEX Or DDSCAPS_SYSTEMMEMORY
      ' It has One back buffer
      .dwBackBufferCount = 1
   End With

Right an explanation. First of all the With statement is used to specify the object we are working with. This just saves typeing ddsdFront in front of everything. The dwSize is explained in the comment above it so I will move onto the dwFlags property. This property lets you specify which options are valid in this description. We have specified, DDSD_CAPS Or DDSD_BACKBUFFERCOUNT, which basically means that the DDSCAPS and dwBackBufferCount properties will be read when the surface is created. In the DDSCAPS property we have set a lot of values. Heres an explanation of them all. DDSCAPS_PRIMARYSURFACE means that this surface is the Primary Surface. DDSCAPS_FLIP means that we can flip this surface (basically flips whats on the back buffer to the Primary Surface). DDSCAPS_COMPLEX any ideas ??? . DDSCAPS_SYSTEMMEMORY means that this surface will be created in the System Memory as opposed to Video Memory. We also specify that we will have one Back Buffer attatched to this Primary Surface.

   ' Create front buffer using the Description
   ' structure defined above.
   dd.CreateSurface ddsdFront, ddsFront, Nothing
   ' Set the Search Options to the Back Buffer
   ' Object.
   ddCaps.dwCaps = DDSCAPS_BACKBUFFER
   ' Attach the surface ddsBack to the
   ' Primary surface as the back buffer.
   ddsFront.GetAttachedSurface ddCaps, ddsBack

OK, creating the surfaces. First of all the Primary Surface. We pass the CreateSurface The description variable (which we spent ages defining above), and the actual surface. This will create the Primary Surface, and set all of the options which again we specified in ddsdFront. Then we create the Back Buffer and attatch it to Primary Surface, so that when we flip it (show in later tutorials). First we assign the search options, in the ddCaps variable, so that the GetAttachedSurface function, knows we are attatching it as a Back Buffer. Then we pass this and the Back Buffer surface to it and whala (could be ouala), you have a flippable surface.

   ' Show the form
   frmMain.Show
   ' Set us running.
   Running = True
   Do Until Running = False
      ' Get any key presses
      DoEvents
   Loop
End Sub

Finally we have to show the form and start the Rendering Loop. The Rendering loop only consits of a DoEvents at the minute, because we are not actually rendering anything yet in this tutorial. This will continue to loop until we press escape (which will set Running to False) hense ending the loop.

Step 5 - Did We Press Escape ??

Private Sub Form_KeyDown(KeyCode As Integer, Shift As Integer)
   'When we press escape, Stop the rendering loop
   '(rendering loop is in Form_Load) and quit
   'out. Check Form_Unload for Important info
   'On quitting out.
   If KeyCode = vbKeyEscape Then
      Running = False
      Unload Me
   End If
End Sub

Basically, every time a key is pressed, this Sub is called by the program. We do a quick check to see if the Key which was pressed was escape. vbKeyEscape is a Constant defined within VB5, a list of all the keycodes are shown in the Visual Basic Help. If we did press escape, we set the Running to False. This will end the Rendering Loop started in the Form_Load event. Then we trigger the Unload_Form event to exit the program.

Step 6 - I Want to Exit, What Now?

Ok now we've established that the user pressed escape, we have to exit the program. Earlier we called the Unload event of the form. You must now close down the program. NOTE: This is specific to this program, in application programming you do not normally have to set variables to nothing, unless a type uses obscene amounts of memory. (You can only use a total of 64k per Module when specifying types so it isn't that big a problem).

Private Sub Form_Unload(Cancel As Integer)
   'IMPORTANT: You must set your objects to nothing before you
   'Leave or you will lose memory and stack space

   'Flip The Current Surface to windows
   dd.FlipToGDISurface
   'Restore our old display mode
   dd.RestoreDisplayMode
   'Reset back to normal mode.
   dd.SetCooperativeLevel frmMain.hWnd, DDSCL_NORMAL
   'Free memory.
   'NOTE: You must set the backbuffer to nothing
   'before the primary surface, otherwise your program
   'will crash and you will lose all the memory
   'currently allocated.
   Set ddsBack = Nothing
   Set ddsFront = Nothing
   'Finally reclaim the memory allocated to the
   'DirectDraw device. This must be done last.
   Set dd = Nothing
End Sub

Finally we need to free all the memory we allocated earlier. If you dont you will lose memory and stack space. We do this by setting the variables to nothing. Generally we only have to do this with Surfaces and DirectDraw devices (in this example), because you cant set the descriptions to nothing. The rest of the functions called in this Unload Function are pretty well explained by the comments.

Step 7 - Closing Comments

Thats it, it was a long haul but were through it. You should have some idea on how to Open a DirectDraw Device now. Now your ready to carry on to the other tutorials and Learn EVEN MORE !! WOW. Thanks for reading. Oh and by the way. I hope you appreciate the nice colours and fonts on the bits of code, took me ages to do that. :)

Page 1 2 [NEXT >>]
Back to Tutorials - Main