The Grabbit plug-in gives the ability to use captured video inside Viz Engine. Grabbit uses the Microsoft DirectShow Filter graph framework to capture the video.

Devices which are supported by DirectShow and are self-contained such as capture cards or web cameras, can be used. Self-contained means the capture device does not need any further input.

This page contains the following topics and procedures:

Grabbit Properties

Following is a list of all parameters of the plug-in. Depending on the state of the plug-in, they may be hidden. Some of them are not visible at all.

• Available Devices: Decides which video capture device to use. This list is created when the plug-in loads. That means if you have a capture device which is not known at startup of the renderer, it does not show up. On the other hand, it does not know if a capture device is already in use by some other plug-in. Since the list is static, it just shows all capture devices which were available at startup. If the parameter is changed and the plug-in is already started, it stops capturing before loading the new capture device. Changes are effective immediately.

  • Parameter name: CaptureDevices (list).

• Selected Capture Device: Contains the simple name for the chosen capture device from the list. This parameter decides which DirectShow Device is taken for capturing. If the parameter is changed and the plug-in is already started, it stops the capturing before loading the new capture device.

  • Parameter name: CaptureDevice (string).

• Capture Format: Represents the current capturing format as a human readable string. It shows the width by height, frame rate, video subtype, and bit depth. It is a read only resource and is changed with the configuration dialogs below. This should really be an opaque data type.

  • Parameter name: CaptureFormat (string). Parameters are shown if the filter supports the ProcAmp interface.

• Brightness: Changes the brightness. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Brightness.

  • Type: float. Range: [0-100]. Default: 50.

• Contrast: Changes the contrast. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Contrast.

  • Type: float. Range: [0-100]. Default: 50.

• Hue: Changes the hue. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Hue.

  • Type: float. Range: [0-100]. Default: 50.

• Saturation: Changes the saturation. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Saturation.

  • Type: float. Range: [0-100]. Default: 50.

• Sharpness: Changes the sharpness. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Sharpness.

  • Type: float. Range: [0-100]. Default: 50.

• Gamma: Changes the gamma. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Gamma.

  • Type: float. Range: [0-100]. Default: 50.

• Colorenable: Enables or disables color. Changes are effective immediately but not for already captured video.

  • Parameter Name: Colorenable.

  • Type: toggle button. Default: on.

• Whitebalance: Changes the white balance. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Whitebalance.

  • Type: float. Range: [0-100]. Default: 50.

• Backlight Compensation: Enables or disables the back light compensation. Changes are effective immediately but not for already captured video.

  • Parameter Name: BacklightComp.

  • Type: toggle button. Default: on.

• Gain: Changes the gain. The range is relative and the value is re-calculated internally according to the possibilities (min/max/stepping) of the device. Changes are effective immediately but not for already captured video.

  • Parameter Name: Gain.

  • Type: float. Range: [0-100]. Default: 50.
    Parameters are shown if the filter supports the DirectShow dialog interface. Since the dialogs are handled by Windows and not the Viz Artist GUI they may open in the background. If so please bring the dialog to the front and make your settings. Make sure that the dialog is closed before you change anything in the Viz Artist GUI.

The buttons are disabled if there is no such dialog. Some implementations hint that a dialog is available even if it is not. In that case the button is not disabled but no dialog window shows.

• Video Filter: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up. Changes are effective immediately.

  • Parameter Name: ButtonVideoFilter.

  • Type: push button.

• Video Capture Pin: If available choose RGB24 or UYV as format. Other settings may not work. The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up. Changes are effective immediately.

  • Parameter Name: ButtonVideoCapPin.

  • Type: push button.

• Audio Filter: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up. Changes are effective immediately.

  • Parameter Name: ButtonAudioFilter.

  • Type: push button.

• Audio Capture Pin: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up. Changes are effective immediately.

  • Parameter Name: ButtonAudioCapPin.

  • Type: push button.

• Crossbar 1: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up.

  • Parameter Name: ButtonCrossbar1.

  • Type: push button.

• Crossbar 2: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up.

  • Parameter Name: ButtonCrossbar2.

  • Type: push button.

• TV-Tuner Video: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up.

  • Parameter Name: ButtonTvVideo.

  • Type: push button.

• TV-Tuner Audio: The dialog window may be behind the renderer GUI after activation. Please be careful to close the dialog window. Otherwise the renderer and the GUI may lock up.

  • Parameter Name: ButtonTvAudio.

  • Type: push button.
    Video for Windows Dialogs:

Parameters are shown if the filter supports the Video for Windows (VfW) dialog interface. Since the dialogs are handled by Windows and not the Viz Artist GUI they may open in the background. If so please bring the dialog to the front and make your settings. Make sure that the dialog is closed before you change anything in the Viz Artist GUI.

Buttons are disabled if there is no such dialog. Some implementations hint that a dialog is available even if it is not. In that case the button is not disabled but no dialog window shows.

• Cap Source: If the filter supports the VfW Source dialog this button is present. It can be activated if the capturing is stopped otherwise the button is grayed out. The dialog window may be behind the renderer GUI after activation. please be careful to close the dialog window. otherwise the renderer and the GUI may act in a strange way. Changes are effective immediately.

  • Parameter Name: ButtonCaptureSource.

  • Type: push button.

• Cap Format: If the filter supports the VfW Format dialog this button is present. It can be activated if the capturing is stopped otherwise the button is greyed out. The dialog window may be behind the renderer GUI after activation. please be careful to close the dialog window. otherwise the renderer and the GUI may act in a strange way. Changes are effective immediately.

  • Parameter Name: ButtonCaptureFormat.

  • Type: push button.

• Cap Display: If the filter supports the VfW Display dialog this button is present. It can be activated if the capturing is stopped otherwise the button is grayed out. The dialog window may be behind the renderer GUI after activation. please be careful to close the dialog window. otherwise the renderer and the GUI may act in a strange way. Changes are effective immediately.

  • Parameter Name: ButtonCaptureDisplay.

  • Type: push button.

• Auto Scale Texture: If enabled the captured video is scaled according to the underlying geometry. Changes are effective immediately but not for already captured video.

  • Parameter Name: AutoScale.

  • Type: toggle button. Default: on.

• Border Crop Width: Crop pixels on the horizontal sides of the video. This parameter is shown only if Auto Scale Texture is enabled. Changes are effective immediately but not for already captured video.

  • Parameter Name: BorderCrop_x.

  • Type: integer. Range: [0-0x7fff]. Default: 0.

• Border Crop Height: Crop pixels on the vertical sides of the video. This parameter is shown only if Auto Scale Texture is enabled. Changes are effective immediately but not for already captured video.

  • Parameter Name: BorderCrop_y.

  • Type: integer. Range: [0-0x7fff]. Default: 0.

• Status Opened: Shows if the capture graph has been built successfully.

  • Parameter Name: StatusOpened.

  • Type: toggle button (show only).

• Status Started: Shows if the capture graph has been started.

  • Parameter Name: StatusStarted.

  • Type: toggle button (show only).

• Status Stream Width: Shows the captured video width.

  • Parameter Name: StatusStream_x.

  • Type: integer (show only).

• Status Stream Height: Shows the captured video height.

  • Parameter Name: StatusStream_y.

  • Type: integer (show only).

• Start: Starts capturing. Feedback is given through Status Started and Status Stream Width/Height. If capturing does not start check the Status Opened and Connected. Capturing cannot commence if the filter graph is not connected. Changes are effective immediately.

  • Parameter Name: ButtonStart.

  • Type: push button.

• Stop: Stops capturing. You need to do this to select the Vfw Dialog buttons. Changes are effective immediately.

  • Parameter Name: ButtonStop.

  • Type: push button.

• Clear: Clears the texture to opaque white. You may need to hit the button twice for the change to show. Changes are effective immediately.

  • Parameter Name: ButtonClear.

  • Type: push button.

Required Software

• DirectShow version 9.0c. It is strongly recommended to have a clean DirectShow installation to start with. Additional source filters may be added later. Find more Information at the

• DirectShow of VfW compatible capture card.

Best Practices

GraphEdit is a tool from the Microsoft DirectShow SDK that allows you to visualize the default Filtergraph that DirectShow builds to render the Media. If you can render the Media inside GraphEdit it should play in Viz Engine, too. If it does not play in GraphEdit, it does not play in Viz Engine.

Known Limitations

• Dynamic listbox for capture devices.

• Handle the capture device list dynamically.

• ProcAmp settings should be updated from dialog settings as well.

• Query for availability in the various ProcAmps.

• The Capture Device must be known to the system at application start. When using USB devices this means they must be connected before Viz Engine is started.

To Capture a Video Stream with Grabbit

1. Add the Rectangle geometry to the Scene Tree.

2. Add the Grabbit plug-in to it.

3. Select the capture device to work with from the Available Capture Devices list.

   • You should get a positive Status Opened feedback.

4. If you have a device that supports the capture format enumeration and the ProcAmp interface you get a screen similar to the following.

5. Set the Capture Format by using the dialogs behind the configuration buttons Video Filter, and so on.

6. Select Auto Scale Texture if you want the texture position and scaling set by this plug-in so that the video fills out the entire geometry. If you have selected this feature you may want to crop something on the horizontal or vertical sides of the video. Use the Border Crop Width and Border Crop Height for this effect.

7. Click the Start button to start capturing. You should get a positive Status Started feedback. In addition, the Status Stream Width and Status Stream Height should reflect the dimensions of the captured video.

8. Adjust the effect settings. You might want to experiment with them. Some parameters have discreet values as for example the Gamma parameter.

To Capture a Video Stream with Grabbit and a VfW Supported Device

Once you have selected the capture device it needs to be configured. You do this by clicking the buttons that leads to the VfW dialog windows.

1. Click Cap Source and Cap Format and set the parameters according to your needs.

   • The values you set here cannot be changed via the usual control mechanism. You need to pay close attention that the dialog window may open in the behind the Viz Artist GUI.

   • Make sure that each dialog window is closed before any other changes are made in the Viz Artist GUI.

   • You should get a positive Status Connected feedback. If you want to go back to change something here the graph must be in Stopped mode.

2. Select Auto Scale Texture if you want the texture position and scaling set by this plug-in so that the video fills out the entire geometry.

   • If you have selected this feature you can use the Border Crop Width and Border Crop Height to crop something on the horizontal or vertical sides of the video.

3. Click the Start button to start capturing.

   • You should get a positive Status Started feedback. In addition the Status Stream Width and Status Stream Height should reflect the dimensions of the captured video.

4. Click the Stop button to stop the capturing.

   • This sets it back to Stopped mode.

   • You should see the feedback in the Status Started toggle.

   • Once the capturing is stopped you can use the Clear button to set the underlying texture to opaque white.