Build a Filter or Application with Visual C++ 5.x

This article describes step-by-step procedures for building your Microsoft® DirectShow™ projects. You can either build your filter or application from the command line, or build it from within the Visual Studio environment that comes with Microsoft Visual C++®. If you choose to build a filter from within Microsoft Visual Studio™, you can use the VC5Kit set of files shipped with the DirectShow SDK, by default, in the dxmedia\tools\VC5Kit directory. This provides an easy way to configure Visual Studio project settings. You can also set the project settings within Visual Studio yourself.

The main difference between building a filter and building an application from within Visual Studio is that for a filter you select Win32 Dynamic-Link Library as the project type, while for an application you select Win32 Application or Win32 Console Application as the project type. (You choose the project type in the New Projects dialog box opened by choosing the New command from the File menu.)

This article includes the following topics.

Building a Filter or Application from the Command Line

Perform the following steps to build a DirectShow project from the command line.

Go to the Visual C++ Bin directory.
Type VCVARS32.
Go to the directory containing the filter you want to build.
If you are building a sample filter and the sample filter isn't in the default directory (the default is \dxmedia\Samples\ds\Samplename; for example, \dxmedia\Samples\ds\Gargle), set the AXSDK MAKEFILE variable to the top-level DirectShow directory. For example, at the command prompt, type:
```
set axsdk=c:\dxmedia
```
At the command prompt, type:
```
NMAKE
```
For nondebug versions, type:
```
NMAKE NODEBUG=1
```

Using VC5Kit to Build a Filter in Visual Studio

This section discusses building filters with Microsoft® Visual C++® version 5.x. The 5.x VC5Kit is installed by default in the dxmedia\tools\VC5Kit directory.

Setting the Visual Studio Include and Lib Directories

This topic describes how to set your Visual Studio Include and Lib directories. If you are building a DirectShow sample application, such as PlayFile, that comes with a makefile or .mak file, the steps in this topic are the only ones you must perform to build the sample. Once you set your directories, you can choose Open Workspace from the File menu and select the existing makefile or .mak file. Visual Studio will wrap the makefile. If you are building a filter, other steps will probably be necessary.

Open Visual Studio.
From the Tools menu, choose Options.
Choose the Directories tab.
In the Show directories for drop-down list, select Include files.
Add the DirectShow include directories (by default: dxmedia\Include and dxmedia\Classes\Base) to the list.
In the Show directories for drop-down list, select Library files.
Add the DirectShow library directory (by default C:\dxmedia\Lib).

Creating a Project Directory and Adding Source Files

Follow these steps to create your project directory and add your source files to it:

Create an empty directory for your project; for example, C:\Filter.
Copy the VC5Kit Filter.def, Filter.dsp, Filter.dsw, and Filter.mak files into the directory.
Copy your source files into the directory. This includes .h, .cpp and any other miscellaneous source files your project requires. If your project has its own .def and .rc files, you can use these rather than the .def and .rc files provided with VC5Kit.

Building the Project in Visual Studio

Follow these steps to build your project in Visual Studio:

From the File menu in Visual Studio, choose Open Workspace.
In the Open Workspace dialog box that appears, browse to the directory you created and select Filter.dsw.
The project opens.
To add your source files to the project, choose Add to Project from the Project menu, and then choose Files from the submenu that appears. Browse to the directory containing your source files, select the ones you want to add, and click the OK button.
From the Project menu, choose Settings.
Choose the Link tab and select General from the Category drop-down list.
In the Output file name box, type the name of your filter; for example, Filter.ax.
Choose OK to confirm the project settings you've selected.
Choose Build Filter.ax from the Build menu. The name Filter.ax is the name you gave the output file in the Link tab.

Creating a GUID

If you are building your filter using source files from an existing filter, including any samples filter that ships with DirectShow, you must create a GUID for the new filter.

To create a GUID in Visual Studio:

From the Tools menu, choose Create GUID. By default, the GUID is in DEFINE_GUID format, which is the format you want.
Click the Copy button.
Delete the old GUID from your source file.
Put the cursor in your source file where the old GUID used to be, and choose Paste from the Edit menu.

Creating a Definition File

If your filter implements the DllGetClassObject, DllCanUnloadNow, DllRegisterServer, or DllUnregisterServer functions, you must include a definition file (.def file) that exports them. For example (where Filter.ax is the name you gave the output file):


LIBRARY FILTER.AX
DESCRIPTION 'Description of my filter'
PROTMODE
EXPORTS 
    DllGetClassObject  
    DllCanUnloadNow  
    DllRegisterServer  
    DllUnregisterServer

Setting DirectShow Project Settings in Visual Studio

This section describes how to set project settings in Visual Studio to build your own DirectShow applications and filters. If you are building samples supplied by DirectShow, you need only set your Include and Lib directories.

In some cases, you might need to add to these project settings for your particular application. For example, if you use DirectDraw functions, you must add Ddraw.lib to the list of Link libraries.

In all cases, you must set the Visual Studio Include and Lib directories as described in Setting the Visual Studio Include and Lib Directories.

This section contains the following topics.

Creating a Project

To create a project, perform the following steps.

From the File menu, choose New.
Choose the Projects tab.
If you are building an application, select Win32 Application as the type of project. If you are building a filter, select Win32 Dynamic-Link Library.
Type a name for the project and a location for the project files.

Adding Files to the Project

To add files to the project, perform the following steps.

From the Project menu, choose Add to Project. From the submenu that appears, choose Files.
In the Insert Files into Project dialog box that appears, browse for the filter files you want to add to the project, such as the .cpp, .h, .rc, and .def files.
Select the file or files you want to add and choose OK.

Setting Project Settings For Both Release and Debug Builds

To set project settings for both release and debug builds, perform the following steps.

From the Project menu, choose Settings.
In the dialog box that appears, select All Configurations in the Settings For drop-down list.

Follow these steps to set your project general settings:

From the Project menu, choose Settings.
Choose the General tab.
From the Microsoft Foundation Classes drop-down list, select Not Using MFC.

Follow these steps to set your project compiler settings:

From the Project menu, choose Settings.
Choose the C/C++ tab.
In the Category drop-down list, select General.
In the Preprocessor definitions text box, insert the following:
```
INC_OLE2,STRICT,WIN32,_MT,_DLL,_X86_=1,WINVER=0x0400
```
Select the C++ Language category.
Select the Enable exception handling check box.
Choose the Code Generation category.
In the Processor drop-down list, select Blend*.
In the Calling convention drop-down list, select _stdcall.
In the Use Run-time library drop-down list, select Multithreaded DLL.
Select the Precompiled Headers category.
Select the Not using precompiled headers option button.

Follow these steps to set your project link settings:

From the Project menu, choose Settings.
Choose the Link tab.
In the Category drop-down list, select General.
In the Output file name text box, type the filter's output file name; for example, Debug/Filter.ax.
Add the following libraries to the beginning of the Object/Library modules text box.
```
quartz.lib strmbase.lib msvcrt.lib
```
These libraries must be the first libraries in the link list. Depending on the functions your application accesses, you might need to add other libraries to this list.
Select the Ignore all default libraries check box.
Select the Customize category.
Clear the Use program database check box.
Select the Output category.
In the Base address text box, type:
```
0x1c400000
```
In the Entry-point symbol text box, type:
```
DllEntryPoint@12
```

Setting Project Settings for Debug Builds

To set project settings for debug builds, perform the following steps.

From the Project menu, choose Settings.
Select Win32 Debug in the Settings For drop-down list in the Project Settings dialog box that appears.
Choose the C/C++ tab.
In the Category drop-down list, select General.
Select the Generate browse info check box.
In the Debug info drop-down list, select C7 Compatible.
Select the Code Generation category.
In the Use Run-time library drop-down list, select Debug Multithreaded DLL.
Choose the Link tab.
Select the Debug category.
Select the Debug info check box.

Building a Release or Debug Version of Your Project

To build a release or debug version of your project:

Choose Set Active Configuration from the Build menu, and select Win32 Release or Win32 Debug from the list that appears.
Choose Build Filter.ax from the Build menu. The name Filter.ax is the name you gave the output file in the Link tab.