The DirectX SDK

If you did not change the installation options from the defaults (we recommend not changing the default settings), you will see that the DXSDK directory has been added to your C drive.

After installation, opening up the DXSDK directory up will give you the Bin, Doc, Include, Lib, Redist, Samples, and SDKDev sub-directories. For the moment, we will concentrate on the Samples directory; open up this directory and look at its contents. Notice that there are a range of samples for C++ and C#. Open up the C++ directory.

The DirectX SDK consists of several components , which are summarized in the following table.

Component	Purpose
DirectSound	Handles the playback of sound, including mono, stereo, 3-D sound, and multichannel sound.
DirectShow	Controls many different video-rendering and capture options.
Direct3D	Renders 3-D objects in a 3-D world.
DirectInput	Controls input from the mouse, keyboard, joysticks, and force-feedback devices.
DirectMusic	Composes and plays all sounds, including music. Based on DirectSound.
DirectPlay	Controls communications in a multiplayer game.

Now that you have installed the DirectX SDK, this is a good time to run some of the DirectSound, DirectShow, and D3D samples in order to test out your audio and video hardware. If you have any problems, it is better to sort them out now before proceeding any further.

It is important to point out that there are few dependencies between the DirectX components; there is no common kernel. Both DirectMusic and the audio components of DirectShow are based on DirectSound, and DirectShow is tightly coupled with D3D, but other than that, the components can be treated as separate SDKs in their own right.

Although DirectMusic is certainly an audio API, experience has shown that it is both too technical for musicians yet too musical for software engineers , not to mention its proprietary file formats and awkward accompanying tool, DirectMusic Producer. We do not cover DirectMusic any further in this book.

The DirectX SDK documentation goes into great detail about the API calls, but goes into much less detail about the utility code that is provided along with the SDK. The utility code is installed along with the SDK, and has names such as dsutil (for DirectSound), dxutil (for basic DX information), and so on.

One of the most important lessons of this chapter is to point out that this utility code should be considered to be part of the SDK; it should not be considered peripheral or unimportant. It contains more than just utility code, and in some cases the functions provided include work-arounds for some of the known problems of the SDK itself.

If you are planning a game based on D3D, we strongly suggest looking through all the source code that is provided when you install DirectX before you begin any coding. By doing so, you could save a lot of time, not to mention a lot of grief .

There are overly confident programmers who feel that all coding should be done to the SDK API calls without considering any layers that are above them. This is just not realistic. Save your problem-solving skills for the unique problems that will develop within your own application. When developing code using DirectX components, such as DirectSound or DirectPlay, it is usual to write a complete layer that wraps up all the DirectX calls, with your application calling only the functions in this upper layer.

This has the advantage of insulating most of your application from handling DirectX pointers and other goop, and also means that this layer can clearly be tailored to exactly the kind of application that you are writing. There are, of course, performance issues to be addressed, although none with a method that is only called once, nor is there any performance improvement to be gained by rewriting code that is already well-written .

The following tables describe all of the utility code that comes with DirectX. Although this book will explain only the audio and video elements, it is good to know all the tools that you have at your disposal “ and you should familiarize yourself with them before starting development. The utility code is in the C++/Common directory, with the .cpp files in the Src directory and the .h files in the Include directory.

There is almost a one-to-one correspondence between the .cpp files in the Src directory and the header files in the Include directory. Almost all the utilities have at least one associated header file, and some have two.

DirectX utility	Purpose
Dxutil.cpp	Provides some general functions for handling GUIDs and similar laborious duties . This utility is mostly used by the other utility code and you should not have to change it.

D3D utility	Purpose
D3dapp	Provides the basic initialization and termination for most D3D applications. Reports possible installation errors.
D3denumeration	Provides utilities to enumerate the hardware that is available on the computer that the application is running on.
D3dfile	Supports the .X file format, a complex 3-D file format that can handle a hierarchy of objects, textures and animations. It is compatible, either directly or with conversion tools, with third-party graphics tools such as Discreet s 3ds max.
D3dfont	Provides a range of graphic-text handling functions. Very useful, as there is no explicit text handling in the D3D SDK.
D3dsaver	Provides a framework for screen savers.
D3dsettings	Supports the saving and restoring of window settings “ such as whether check boxes have been selected or not, slider positions , and so on. Useful when creating samples.
D3dutil	Initiates essentials for most D3D programs such as lighting, texture, and camera information.
ddutil	Named after the legacy DirectDraw SDK “ now subsumed into D3D “ this set of utilities is mostly used by the other utility code. You may find some of the low-level functions useful, but many developers will not need to touch the code in this file.

DirectInput utility	Purpose
Didevimg	Provides a framework for the drawing of input device images “ and states “ on the screen.
diutil	Provides essential, low-level input functions that map devices to input.

DirectMusic utility	Purpose
Dmutil	Supports the playing of DirectMusic segments and scripts. Most DirectMusic functionality is provided within the SDK.

DirectPlay utility	Purpose
Netclient	Provides base classes for enumerating hosts , and for allowing a user to join a session, which is what DirectPlay calls a multiplayer Internet game.
Netconnect	Provides base classes for enumerating hosts and service providers, and enables a user to either join or host a session.
Netvoice	Provides classes to enable the players of an Internet game to talk to each other through sound capture and replay.
SessionInfo	Handles the storage of information required to run a session, such as the players, addresses, messaging, and so on.

DirectSound utility	Purpose
Dsutil	Provides many useful classes for managing the sound system, reading in wave files, handling streaming sound, and hardware and software buffering.

The DirectShow utilities are not in the same folder as all the other DirectX components, but are in their own Common directory within the DShow directory. The sources and headers are all together, and not in separate directories. The following table summarizes the DirectShow utility code.

DirectShow utility	Purpose
Dshowutil	Assists with DShow graph building and debugging.
Mfcdmoutil	Assists in using DirectX Media Objects (DMOs) in Microsoft Foundation Classes (MFC) applications.
Mfcutil	Assists in developing DirectShow applications using MFC.
Namedguid	Converts various DirectShow GUID values to strings, which is useful when debugging.
seekutil	Adds a user interface for file seeking in a DirectShow application.

The DirectShow utilities do not provide as complete a framework as does the utility code for the rest of DirectX. The chapters in this book on special video effects provide a much better framework from which to start.

Another word of warning. There have been some changes to the parameters of methods in the utility code since DirectX 8.1. These changes should not confuse you, and should be obvious when you look at the sources, however, they could cause programs that you wrote for DX 8.1 to not compile.

In addition to the utility code, the samples provided with the DirectX SDK are another great resource. You will find it instructive to check out all the samples and to work through them. However, particularly for audio and video, we found the samples included with the SDK to be somewhat simplistic, and do not show off the capabilities of the product. Partly for this reason, we have included a set of samples for this book that show a fuller range of the capabilities of the DirectX SDK.

The High5 sample is the only DirectSound sample in this book that does not require any changes or additions to the dsutil.cpp utility code provided in the DirectX SDK package. Generally, the utility code is very useful, however, since it does not give you individual buffer-level access to each sound, it is somewhat restrictive . This restriction does not matter when the sounds that you require do not need any manipulation, which is the case for the High5 sample, and for all the samples included with the SDK. However, you will find that you will need individual buffer manipulation for more complex applications.

We will begin our programming tutorial by going through the High5 sample, layer by layer. Now might be a good time to run the High5 sample a few times, to see how it works and to remind yourself just how much life sound can add to graphics.