The Virtual Video DirectShow Filter is a Windows component that allows you to configure virtual cameras and PTZ controllers and stream live video into any DirectShow based application (including Windows Media Player). No knowledge of DirectShow programming is required to use the filter to generate canned video, as described in Generating Canned Video below. However, DirectShow programming may be required to use the filter to stream live video directly into your custom DirectShow-based application. Further information on DirectShow programming can be found in the MSDN DirectShow documentation.

Note that the Virtual Video C Library and network protocol offer alternative methods to configure cameras and retrieve rendered frames. However, even if you use these alternative interfaces in your application, the DirectShow filter provides a useful and simple method to debug your virtual camera configuration using Windows Media Player.

In DirectShow, a video stream is specified by a URI. The Virtual Video DirectShow filter uses the URI to locate the host machine running the game engine and determine settings such as resolution, location and motion of the camera in the virtual world. The URI takes the following form:

simvideo://host:3166?option=value&option=value&...

where host is the name of the machine running the game engine, and option=value indicates one of the options in the table below. For example, to connect to a host machine called hl2box and create a new camera with the identifier camID = 5, placed at a height of 500 inches above initial player view, panning between angles of -30 and +30 degrees, the URI would be:

simvideo://hl2box:3166?camID=5&z=500&ptzcontrol=true&scanning=true&panmin=-30&panmax=30

All option values are ‘sticky’, so if a new DirectShow filter is created with the same camID, omitted options will retain their previously assigned value (or the default settings if a value was not previously assigned). Available options and default values are described in the tables below. Note that all options are CaSe InSeNsItIvE.

To view a camera in Windows Media Player, select File->Open URL... and type the appropriate URI into the Open URL dialog box. To retrieve frames from this camera in your DirectShow-based application, pass the same URI as a parameter to the RenderFile() or AddSourceFilter() member function of the IGraphBuilder interface (see the MSDN DirectShow documentation for more details). The following examples describe common camera configurations and the appropriate URI (in all cases Half-Life 2 is running on the local machine):

• A static camera located at (30.6, 70.0, -40.0), tilted down by 20 degrees, with a roll of -1.7 degrees and a frame rate of 25 frames/sec:
  
  simvideo://localhost:3166?x=30.6&y=70&z=-40&ry=20&rx=-1.7&framerate=25


• A pair of static stereo cameras separated by a baseline of 10 inches, both tilted by 10 degrees and with a FOV of 50 degrees:
  
  simvideo://localhost:3166?camID=1&y=-5&ry=10&fov=50
  simvideo://localhost:3166?camID=2&y=5&ry=10&fov=50


• To view the right camera from the above stereo pair without changing any camera settings (since camera options are 'sticky', all above settings for camera 2 are retained), with ground truth bounding boxes overlaid:
  
  simvideo://localhost:3166?camID=2&showbboxes


• A PTZ camera connected to the controller with a ptzID of 5, the pan axis tilted forwards by 5.8 degrees, an initial pan and tilt of 30 and 10 degrees, and an initial zoom of 2.6:
  
  simvideo://localhost:3166?ptzcontrol=true&ptzID=5&ry=5.8&pan=30&tilt=10&zoom=2.6


• A ceiling-mounted scanning PTZ camera that automatically scans between pan angles of +/-20 degrees (note that the retrieved images will be upside down):
  
  simvideo://localhost:3166?ptzcontrol=true&scanning=true&panmin=-20&panmax=20&rx=180

When using the savedir option to save frames to disk, care must be taken to ensure that the URI can be correctly parsed, which may require replacing some characters with URI escape codes. The following table lists the most common characters that may need to be replaced:

For example, to use the savedir option with the directory C:\Temp Files, the URI should be encoded as savedir=C%3A%5CTemp%20Files.

Generating canned video is the simplest way to use the Virtual Video Tool with minimal programming effort, and may be the best choice in large multi-camera installations (each camera can be simulated in a separate run) and when computational resources are at a premium (running Half-Life 2 consumes considerable computational power). The following sections show how to generate canned video using two methods:

1. Using Windows Media Player and VirtualDub: This method requires more processing steps but is the best way to ensure that all rendered frames are captured to AVI.
2. Using GraphEdit: This method captures video directly to AVI but may drop frames if CPU usage is high.

Canned Video Method 1: Windows Media Player and VirtualDub

To use this method you will need both Windows Media Player (or other DirectShow-based media player) and VirtualDub, a free video manipulation tool. Further information on VirtualDub can be found at www.virtualdub.org. The process is described below:

• Launch the mod as described on the Launching Mod page.
• Open Windows Media Player (Start->All Programs->Windows Media Player)
• Select File->Open URL... and type the URI of the virtual camera with the desired configuration as described above. Be sure to include a savedir=path option as shown in the example below.
  Note: You may want to omit the savedir option until you confirm that the camera configuration is correct as viewed in Media Player. You can select File->Open URL... and modify the URI as many times as needed.

• When you have finished capturing frames, open the URI again with savedir set to an empty string (ie. "savedir=") to stop video capture.
• The JPEG files saved to disk can now be assembled into an AVI using VirtualDub. Launch VirtualDub and select File->Open video file....
• In the Open video file dialog box, select Image sequence under Files of type:. Browse to the directory specified by path in the savedir option used above. Saved frames are named clientCCC-frameFFFF.jpg where CCC is a three digit camera identifier, and FFFF is a four digit frame number. Select the first frame of the appropriate camera as shown below and click Open.

• If you want to output compressed video, select the appropriate options under Video->Compression...
• Select File->Save as AVI... to render the AVI output.

Canned Video Method 2: GraphEdit

GraphEdit is a graphical utility for manually creating and running DirectShow filter graphs, and can be downloaded here. Using this tool, it is straightforward to create a three-filter graph that channels frames from the Virtual Video DirectShow filter directly into an AVI file. Note that the resulting AVI is uncompressed (= large) and you will need to add additional codec filters for compressed video. This is left as an exercise for the reader! The graph is created and run using the following steps:

• Open GraphEdit and select File->Render URL... from the menu.
• Type the URL of the virtual camera with the desired configuration as described above and click OK. The graph will appear as shown below. Note that you do not need to include a savedir=path option in the URL since GraphEdit will be saving the frames directly to AVI. However, you may want to use Media Player to refine the configuration before launching GraphEdit, and also to view the camera while saving the AVI since you will not be able to view the rendered frames in GraphEdit.
• Select Graph->Insert Filters... to bring up the dialog box shown below.

• Expand the DirectShow Filters list item. Scroll down the list until you find the AVI Mux filter. Select this filter and click the Insert Filter button.
• Repeat for the File Writer filter. Choose a file name and location for the output AVI file in the dialog box that appears when you click Insert Filter.
• Delete the Color Space Converter and Video Renderer filters by selecting these filters in the main GraphEdit window and pressing the Delete key.
• Connect the source filter to the AVI Mux by dragging you mouse pointer from the "Out" pin of the source filter to the "Input 01" pin of the AVI Mux.
• Connect the output of the AVI Mux to the input of the file writer as above. The final filter graph will appear as shown below.

• Select Graph->Play from the menu to start video capture.
• To stop video capture, select Graph->Stop.
• You can save your graph for future use by selecting File->Save Graph.