Visual Basic Explorer - DirectX DDraw Tutorial 1.1

This text is about the DirectDraw system for VB. DirectDraw is comprised of 10 classes. Each of these classes abstracts an important aspect for video / graphics programming. This text does not cover all of the classes, but is limited to the following:

These five classes form the foundation for using DirectDraw as a tool for games and animation. The rest of the classes will be covered in later DirectX-files™.

We will start this file with a small overview of each of the classes that will be covered in this text. An in-depth discussion of each class will be given as the DirectX-file™ series progresses.

This is the main DirectDraw object. This object is used to create a few of the other objects, but also to provide generic system info on the video hardware capabilities and the DirectDraw driver version installed on the system. The DirectDraw7 object is used in the setup phase of a program to set certain system settings and properties and to get information about the available resources and possible configurations.

This object is used to automate clipping functionality. Giving the control of clipping to the DirectDrawClipper can mean the difference between a fast program and a really fast program. A clipper is basically a list of RECTS (rectangular structures) that determine the areas where the bit block transfer (The Blitter) can move pixels to (Blit to).

This object is used to store the possible display mode settings of the system. It is a very simple object and will be introduced in the first sample application.

The object encapsulates the palette used on the DirectDraw surfaces. It functionality and purpose is the same as the normal Win32 palette. Palettes in DirectDraw are still widely used and we will examine some pretty funky palette animation tricks.

This is the most used and most important in the collection of objects that DirectDraw is. It holds function and methods for blitting, accessing, storing and using video memory either with assisted hardware or in pure software. The surface is such an essential object in DirectDraw that you must be careful that you completely understand it and how it is used. Through this object we can get direct access to the memory of the video card, which is something completely unique in the world of Win32 so please read the sections on the surface carefully.

The purpose of this sub case is to demonstrate using the DirectDraw7 object. We will examine how to use this object to get information on the possible settings for the display mode supported by your hardware and also see how we can set these. Likewise will present the 'standard' way of creating the top DirectDraw objects.

The project presented is the DXFile1_1 sample project. As stated above, this project has a twofold purpose – first we will obtain the possible display resolution configurations of the primary display card, and then try out these settings by changing the display mode.

The first step before doing anything else with DirectDraw is to declare and initialize the main DirectDraw and DirectX objects. These main objects are essential for any DirectDraw application. It is these we will use to create and initialize the rest of the DirectDraw objects. Since the DirectX7 object and the DirectDraw7 objects are being used in this context we must keep them active throughout the lifetime of the application, and only release them when we terminate the application. In this example we have declared the objects and given them global scope by placing them in the General Declarations section of the main form. The declarations are shown in Listing 1:

Option Explicit

        

        Dim objDx As DirectX7

        Dim objDraw7 As DirectDraw7

        Dim objEnumModes As DirectDrawEnumModes

The DirectX7 object is the main DirectX object. It is from this object that we will create the DirectDraw object (this object is also used to create the other foundation objects of DirectX, such as DirectSound, Direct3D etc.). The DirectX7 object also contains some useful generic methods, which can be considered global methods for the DirectX libraries. These include, among others, functionality for setting an event callback function, getting the RECT of the main DirectDraw window, getting system color information (usable by both Direct3D and DirectDraw). In this sample we will only be concerned with the method for creating a DirectDraw7 object.

The DirectDraw7 object is in essence a representation of a video card installed
on the system. Since both Windows98 and Windows2000 supports multiple video cards you can have
multiple DirectDraw7 objects. This file will not cover multiple video card support.

Using the DirectDraw7 object you can instantiate the other related object that make up the DirectDraw object. You can also use it to get information on the available features of the video card / driver and the state of the video card and video memory. All objects created from the DirectDraw7 objects are destroyed and unusable if the DirectDraw7 object is destroyed. Therefore it is of utmost importance that you control both the scope and the lifetime of this object. As we progress into the DirectX-file™ series we will study the methods and features of this object in considerably more detail. For now, just remember that it is this object that is used to create other DirectDraw related objects. When it gets released, so will all the other objects we created using it.

As you can see from Listing 1 we have declared a third object with Public scope. This object is a DirectDrawEnumModes object. This object will, when we create and initialize it, contain all the possible display settings of the video card. It is a simple object with only two methods, GetCount and GetItem. We will be covering these in just a short while.

The main object creation and initialization action takes place in the load event of our form. The first thing we have to do is to create a new DirectX object. This is done in much the same way as you create any new object in Visual Basic – using the New operator. If this creation fails you will get a run-time error indicating the failure. There is always the possibility that the user of your application has not installed the version of DirectX that your program requires. It is therefore essential that you trap any errors and warn the user if your program requires a later version than what has been installed. We will trap any errors in the declared ErrHandler label.

After creating a valid DirectX7 object we can use it to create the DirectDraw7 object via the DirectDrawCreate function.

In the sample application we simply create the DirectDraw7 object by passing an empty string. After having created the DirectDraw7 object we use the GetDisplayModesEnum function for getting the available display modes into the DirectDrawEnumModes object. This object will then contain all the possible display modes that we can use in our application. You should always check the display hardware to see if it supports a given resolution. Otherwise, if you try to set a resolution that the hardware does not support you will get a run-time error.

The DirectDrawEnumModes has two methods – GetCount and GetItem. The GetCount method returns the number of available display settings as a simple long. We'll use this function to get the upper bounds of the iterative that fills the list box. As you might have guessed we use the GetItem method to retrieve the settings available. This method takes two parameters, the first being the index to the item that should be received. This index must be in the range of 1 – GetCount(), if it is not a run-time error is generated. The second parameter is a DDSURFACEDESC2 structure. This structure is a descriptor for a given surface and is used it many contexts. In this application we use the lWidth, lHeight and the ddpfPixelFormat.lRGBBitCount members to retrieve the Height, Width and Color depth of the primary surface. In the initialization phase of the sample application we put these members in a list box for display.

Private Sub Form_Load()

        

        On Error GoTo ErrHandler:

        

        Dim ddsd As DDSURFACEDESC2

        Dim I As Long, lgCount As Long

        

        Set objDx = New DirectX7

        ''Create DirectDraw object

        Set objDraw7 = objDx.DirectDrawCreate("")

        

        ''Get the modes in the enum modes object

        Set objEnumModes = objDraw7.GetDisplayModesEnum(DDEDM_DEFAULT, ddsd)

        

        ''Put the data in the listbox

        lgCount = objEnumModes.GetCount()

        

        For I = 1 To lgCount

        

    objEnumModes.GetItem I, ddsd

        

    lstDisplayModes.AddItem CStr(ddsd.lWidth) & "x" & CStr(ddsd.lHeight) & "x" _ 

        & CStr(ddsd.ddpfPixelFormat.lRGBBitCount)

        Next I

        

        ErrHandler:

        

    Select Case Err.Number

        

        Case 0 ''No Errors

        

        Case Else

        Err.Raise Err.Number, Err.Source, Err.Description, Err.HelpContext,  Err.HelpContext

        

            Call CleanUp

        

    End Select

        

        End Sub

One more thing that is worth mentioning is the Error handling in the initialization phase of the application. It cannot be stressed enough how important this is. You must catch any run-time errors that are thrown. If you do not, you run the risk of your application bombing. First and foremost, your application will stop executing before it really starts – and you are not likely to sell many games that way. It may also be possible that the error can be 'fixed'. By trapping and addressing the error, we can keep our program running. A future DirectX-file™ will deal exclusively with error handling techniques that you can employ. Just remember you must do it, even though it seems like redundant and boring code, otherwise you will surely pay the price.

After initialization, the application is ready to run. You should be seeing a small window with a list box and two command buttons, something like Figure 1:

Try to select an item in the list box and click the ‘Set Selected Display mode’ button. Suddenly your display mode will change and the small window will be resized to fill the entire desktop. You have just done two things. First, you have changed the Display setting, and second, you have acquired the entire display under your control. If you move the window around a bit you can see other windows behind it (if you have any open), but you still have control of everything on the primary display. Don’t mistake your form for the primary display – they are two very distinct entities (as we will see later).

The code that changes and acquires the control over the display is in the SetNewDisplayMode function shown in Listing 3:

Private Function SetNewDisplayMode()

        On Error GoTo ErrHandler

        

        Dim ddsd As DDSURFACEDESC2

        Dim I As Long

        

    ''Get the selected item

    I = lstDisplayModes.ListIndex

    If I = -1 Then

        MsgBox "Please select item in Listbox", vbOKOnly, "Error"

        Exit Function

    End If

        

    objEnumModes.GetItem (I + 1), ddsd

        

    ''Set cooperative level

    objDraw7.SetCooperativeLevel Me.hWnd, DDSCL_FULLSCREEN Or DDSCL_ALLOWMODEX Or  _ DDSCL_EXCLUSIVE

        

    ''Set the display mode

    objDraw7.SetDisplayMode ddsd.lWidth, ddsd.lHeight, ddsd.ddpfPixelFormat.lRGBBitCount, 0,  _ DDSDM_DEFAULT

        

    ''Draw the form

    Me.Refresh

        

        ErrHandler:

        

    Select Case Err.Number

        

        Case 0 ''No Errors

        

        Case Else

        

            Err.Raise Err.Number, Err.Source, Err.Description, Err.HelpContext, Err.HelpContext

            Call CleanUp

        

    End Select

        

        End Function

Listing 3 shows the SetNewDisplayMode function in the DXFile1_1 sample project

The function first tries to identify the selected item from the List box. If no item has been selected, the user will be notified and the function will terminate; otherwise, the information for the selected item is stored in a DDSURFACEDESC2 structure. Before we can change the display setting of the primary display to match the selected information, we must announce how we want to cooperate with the DirectDraw system. This is done via the SetDisplayMode method of the DirectDraw7 object. The SetDisplayMode method is one of DirectDraw's initializing functions. This method tells the DirectDraw system how the application wants to interact with the rest of the system. At the basic level you have two choices on how your application can interact with the rest of the windows system: it can either take full and exclusive control of the display, or it can work as a normal window with no special rights. In this sample, we have taken full control of the display system and video card. This is the easiest approach since we do not have to worry about other running applications and their interaction with the system. Later, in this DirectX-file™ series, we will examine how to make DirectDraw applications that interact normally with Windows.

Lastly, we call a refresh on the form to make it display properly. Play around with the system for a while and enjoy the ‘fun’.

Afterthoughts

This sample is very simple and does not involve any special techniques or methods for accomplishing what we need. But it does serve as an example on how much of the interaction with the DirectDraw system is accomplished.

In the next sub case, we will examine some of DirectDraw's basic graphical abilities.