DXUT Game Architecture Part One

Understanding *.VSPROJ

I’m of course referring to a standard Visual Studio Project. In order to understand DXUT and for that any API integration, it is quite vital to understand project dependencies and settings. So this first tutorial will focus on just that with emphasis on DXUT project settings.

On quick thing to make a note of is that a visual studio project are the multiple project builds. Most books on this topic already assume you understand this, but for those with less experience in this area due to one reason or another I’ll quickly explain this concept.

A project build are unique project settings often to do with the compiler, and the linker. The most common three types of builds are the Debug, Release, and the Profile build.

The Debug build is usually the configuration you use while trying to test, solve problems, or quite simply debug. This includes enabling things like symbolic debug information, and disabling any form of code optimization such as inline functions for example.

The release build is by far the easiest one to understand because it is what you’ll be providing the end user with. With that being said you want to omit any unnecessary debug information, and include any form of code optimization.

The debug and release builds are what is defaulted during development using Visual Studio. You will then be expected to make any additional builds on your own (doing so is easy, just do some research). The question would than arise, as to what the purpose of these extra builds might be, and this is what I believe a Profile build that is often regarded as in programming books. The profile build or whatever you choose to call it, may be a build specifically designed to run a specific piece of hardware; such as a cell phone, a PlayStation, a different operating system, or it may quite simply act as a midpoint between a Debug and a Release build for testers etc. As long as you understand this, than choosing the appropriate settings for a Profile build or choosing to omit it entirely becomes a simple mater.

Now that’s out of the way, in Visual Studio switching configurations is as simple as choosing one from the drop down list above. Make sure to note the “All Configurations” option which will allow you to make consistent changes to all current builds.

Next you must decide on how you wish for your project to be organized. There is nothing wrong with using the default directory structure that Visual Studio sets up for you, but after reading Mike McShaffry’s Game Coding Complete, I feel in love with his design which you can find on page 93 of his publication. This is roughly what it looks like:

• Project Code Name
  • Docs
    • Documentation, game concepts, etc.
  • Media
  • Folder belongs to the artists, raw .psd, and high res textures
  • Source
  • The source code, .sln and .vproj belong here
  • Obj
  • The junk, SCC, OBJ, SBR, ILK, and PCH files.
  • Deleting the contents of this folder will cause a complete rebuild
  • Bin
  • Game files only.
  • Executables
  • Zipping up this folder should contain everything necessary to play your game.
  • Test
    • Debug and Profile targets of the game, and any utilities useful for the test team.

[Configuration Properties]

[General]

• Output Directory, your output directory is where you can expect to find your .exe
• Intermediate Directory, compiler specific files, this should probably be configured to point inside your Obj folder if you choose to follow the advised dir structure.
• Extensions to Delete on Clean, during the rebuild step the following are the file extensions you would like to be deleted. If you’re confident in what you’re doing this is a great opportunity to delete unwanted logs etc…
• Build Log File, I have never utilized the following log file, but it should be clear as to what to expect here.
• Inherited Project Property Sheets, this is important if you are setting up your project from an empty project with absolutely no defaulted settings. Feel free to read more on this topic if you wish, but for a DXUT project set it to
• $(VCInstallDir)VCProjectDefaults\UpgradeFromVC71.vsprops
• Configuration Type, the following drop down list determines exactly what your project is built to do. If your building an application (*.exe), a static library(*.lib), a dynamic library (*.dll).
• Use of MFC, set the following to Use Standard Windows Libraries
• Use of ATL, set the following to Not Using ATL
• Minimize CRT Use in ATL, think about this for a sec. Are we using ATL? Then set this to No.
• Character Set, DXUT is infamous to using Unicode and not Multibyte which is more common to hand written DirectX. Remember a character set is not something that can’t be changed if you wish by using prefixes such as L, or T.
• Common Language Runtime support, No Common Language Runtime support.
• Whole Program Optimization, No Whole Program Optimization. Remember what we discussed earlier with various build types.

I’ve went into a lot of detail when it comes to General Configuration, from here on out I will not spend the time to explain settings that are build specific, or that have nothing to do with enabling DXUT. Remember that it is important to learn how to do your research here, and I believe I’ve provided you with the stepping stones to do so.

After creating your project and going through the steps of configuring your $(IntDir), $(OutDir), and various build options you should install the latest DirectX Distribution. Each distribution should come with the latest DXUT files usually located in (C:\Program Files\Microsoft DirectX SDK (November 2007)\Samples\C++\DXUT). A good way to find it is to perform a search for dxut.h on your entire computer. Eventually you will two folders, [Core] and [Optional]. What is this you might be wondering? The core folder is where you’ll find dxut.h and other essential header files involved with successfully compiling DXUT code. In other words you’ll defiantly need these files. On the other hand Optional contains the majority of the DirectX wrappers for game development. Please be aware that DXUT does not document the optional wrappers and is not truly part of the API but are provided as sample code for producing your own wrappers to do the same. With that being said, I don’t copy both folders directly, but instead make a new folder in my project source directory called DXUT and paste the appropriate header and cpp files.

Now you’re going to want to right click on your project and add existing files that you just copied into your project. Second, you want to go back into Project Properties and navigate to Configuration Properties -> C/C++ -> Additional Include Directories. Than point once again to the DXUT folder w/ respect to your *.vsproj file. Assuming it is inside your Source folder, simply typing in DXUT; is sufficient.

* If you don’t see the C/C++ tab inside your Configuration File it is most likely due to the fact that Visual Studio has not yet identified your project as a C++ project. To do this simply create a .cpp file such as WinMain.cpp. And open up properties again.

This concludes Part 1 of the tutorial. If you would like to continue without waiting for my next update, feel free to purchase Game Coding Complete or you could simply navigate to Mike McShaffry’s forums at http://www.mcshaffry.com/GameCode/board.php. Something to note about the way Mike sets up his DXUT is by building a separate project with its own precompiled header, and outputting a *.lib. He then sets up his next project that being the Game Architecture project and set’s it to be dependent on the DXUT build. He also does his #include for DXUT files inside his Game Architecture project and not the DXUT project. Hopefully you’ll figure it out. Or feel free to wait for my next update where I’ll try to take this tutorial all the way to rendering a blue screen via the DXUT function calls.