This article will walk you through the steps needed to make your own project template. It uses the EmptyProject sample from the Microsoft DirectX SDK to make a Visual Studio template.
When you open Visual Studio Express Edition and create a new project, you get presented with a list of templates. But what if there is a kind of project that you use all the time that isn't in that list? You could start with the closest one and add your own code every time. Or you can take a project that has everything you want and turn it into a template that you can share with your friends and teammates. This article will walk you through the steps needed to make your own project template.
A project that I use all of the time when writing for http://www.ircomm.net is a managed DirectX template. There is a lot of code which is the same or similar in every project. The Microsoft DirectX SDK contains a project which is a good starting point, but it's not provided as a Visual Studio template. This article will use the EmptyProject sample from the Microsoft DirectX SDK to make a Visual Studio template. This template can then be used as a starting point for managed DirectX applications.
The principles in this article can be used to create any type of application template using Visual Studio 2005 or the Express editions.
Set up the Project Files
Start by creating a new Windows forms application and calling it "DirectXApplication" and then save the base project.
Once saved, remove the "Form1.cs" and "Program.cs" files as these will not be needed in the application.
The next stage is to set up the folder structure that the application will use. In the Solution Explorer right-click the project name "DirectXApplication" and select Add > New Folder. Add two folders and call them "Common" and "Media," respectively. Inside the "Media" folder add another two folders and call them "SharedFx" and "UI".
Add the Project References
With all Managed DirectX applications you have to make sure that the correct references are added to the project. For the base application you will need to make sure that the standard references for DirectX are added. These standard references are as follows.
NOTE: I am basing the DirectX code in this sample on the October 2005 release of the Microsoft DirectX SDK.
To add these references, right-click the References section in the Solution Explorer and select "Add References" from the menu. In the dialog that is presented, scroll down and highlight the references listed above, then click OK.
Your references section should look like the above figure.
When using the sample framework, you have to make sure that you have your project set to "Allow unsafe code." Right-click the "DirectXApplication" project in the Solution Explorer and select Properties. Next, on the Properties page go to the Build tab and make sure that the "Allow unsafe code" option is checked.
Setting up the Common Framework
Now that the folder structure is complete, it is time to add the Common Framework from the Microsoft DirectX SDK. In the Solution Explorer right-click on the "Common" folder and select Add > Existing Item, browse to the location of the sample directory in the SDK (Generally this is going to be "C:\Program Files\Microsoft DirectX 9.0 SDK (October 2005)\Samples\Managed\Common"), and add all of the dxmut*.cs files. You don't need assembly.cs or any of the files that begin with w as those are for use with the .NET Framework 2.0.
The next set of files to add are the media files that will be used by the common framework to display the GUI system. Highlight the "UI" directory in the Solution Explorer and add all of the files in the "C:\Program Files\Microsoft DirectX 9.0 SDK (October 2005)\Samples\Media\UI" directory.
The last set of files required are the main programs files. Browse to the EmptyProject sample in the SDK (C:\Program Files\Microsoft DirectX 9.0 SDK (October 2005)\Samples\Managed\Direct3D\EmptyProject) and add EmptyProject.cs and EmptyProject.fx.
Including the Content Files in the Application.
One of the new features that are included in the new SDK is the ability to have content files copied to the output directory of the application. When this feature is enabled, the compiler will create the directory structure identical to the one inside the solution in the output directory. There are several choices of what you can do with content files.
- "Do Not Copy": the file is not copied to the output directory. This could be used to add reference documents to the application that you would like to use while developing, but not when distributing.
- "Copy Always": the file is copied to the output directory every time you build the application.
- "Copy if newer", the file is copied to the output directory only if the file is newer then the file already in the output directory. If the file is not there, it will create a new file. Using this option for most of the content files will reduce the time taken during a compile, as VS will not have to transfer the files.
In the current project we want the content to be copied each time if the files are newer then the ones in the output directory. To do this, go to the Solution Explorer and highlight the files as shown in the figure below.
Next, in the Properties pane (press F4 if it's not visible) change the "Copy to Output Directory" to "Copy if newer"
Save the application and execute it to test before we create the template.
Converting the Application into a Template file
The next step, and the main point of this article, is to convert the project into a template. Both Visual Studio 2005 and Express systems can do this out of the box using the built-in functions and wizards.
The first step is to make sure that the application has been saved; once this is done select "Export Template" from the file menu.
This will open up the Export Template Wizard.
On the main dialog there is a choice of two different types of templates to create, "Project Template" and "Item Template". Project template creates a template from the entire project. "Item Template" creates a template from a specific item in the project. An item template would be used for a Windows form or a class file that you would use in multiple projects; e.g., a splash form or a configuration class.
Leave the "Project Template" option selected, and then enter a name for the template. I will be leaving it as "DirectXApplication". Press "Next" to continue.
Enter in an easy-to-understand name and description for the application template. This will be the name and description that appears in the project selection dialog when you select the template in a new application. The application icon should represent the application. Select the browse button and browse to the directory where the SDK and Common Framework was first created (C:\Program Files\Microsoft DirectX 9.0 SDK (October 2005)\Samples\Managed\Common), change the selection to display all files, and select the DirectX icon.
Testing the Template
Now that the template application is completed, it should be tested to make sure that the system is working correctly. To test the application template, close the current solution and create a new one. You should see up the following dialog box:
Select the "DirectX Application" Template (or whatever you called it). Change the name of the application to what you would like your new project to be called (I chose to call mine "GameEngine") and then press OK to continue. The Visual Studio IDE will create the project in a temporary space and set up all of the files needed. At the same time it will automatically change all of the references to "DirectXApplication" to "GameEngine," including the root namespace for the application. The last step you need to do is to save the application. This will make sure that the project is saved to the disk and is ready for use.
Resources and Links
- Microsoft DirectX Developer Center
- Microsoft DirectX SDK October 2005 Release
- MSDN Windows Game development Forums,
- Managed DirectX Resource Sites
- MSDN Documentation on Visual Studio Templates