Active preview is a new feature of VirtualDub 1.2 that allows the user to dynamically view the results of a filter's configuration settings in real-time.  The feature is handled through the class TFilterPreview, that does most of the work for you.

How the active preview interface works

The TFilterPreview class is available through the fa^.ifp member. To make use of this class, your filter must do the following:

• Add a 'show preview' button to its configure dialog.
• Call fa^.ifp^.InitButton(HWND) with the 'show preview' button handle on initialization to associate the button with the preview feature and disable it if there is no video to preview.
• Call fa^.ifp^.Toggle(HWND) with the dialog handle whenever the button is clicked.
• Use fa^.ifp^.UndoSystem, fa^.ifp^.RedoSystem, and fa^.ifp^.RedoFrame whenever appropriate as filter parameters change.

VirtualDub stores the button handle when InitButton(HWND) is called, and will automatically change the label on a Toggle(HWND) or when the preview window is closed, so your filter need not worry about maintaining the label.  In addition, VirtualDub also automatically handles updating the preview display whenever the user uses the position buttons or slider.

When the preview is activated, VirtualDub initializes the current filter chain, thus calling your startProc, paramProc, and runProc routines, same as during a dub operation.  Similarly, the endProc method is invoked when the window closes.  Thus your filter must be reentrant enough to allow the processing portion to execute while the configuration dialog is displayed.  You can force VirtualDub to deinitialize and reinitialize the filter chain by using the UndoSystem and RedoSystem methods.  When a parameter is changed, you can redo any lookup tables and buffers the startProc routine may have created by calling UndoSystem, changing the parameter in your private data structure, and then reinitializing the chain with RedoSystem.  VirtualDub will resize the preview window automatically if the size of the output frame changes due to new filter parameters.

If the user makes a trivial change that doesn't require redoing any tables or buffers and doesn't change any intermediate frames between the filters, you can simply call RedoFrame to reprocess and redisplay the current frame.

The button callback

By installing a button callback, you can modify other parts of your dialog as the user opens and closes the active preview window:

When you install the button callback, VirtualDub calls your callback function every time the active preview opens or closes.  For instance, you can replace the TFilterPreview.InitButton functionality using this callback.  The button callback is most useful for dimming sampling buttons used for sampling incoming video.

Subtleties of active preview

The old method of filling in your data structure on the OnClick event handler of the OK buttom won't work anymore, because filter parameters in the data structure have to be changed on the fly.  One way around this problem is to make a temporary copy of your data structure, and then use that to restore the original data if the user selects Cancel.

Another problem is illegal values, such as resizing to -1x-1.  You can trap these in the dialog, by beeping and not accepting bad values, or by substituting valid values when needed.  Alternatively, you can trap them in startProc.  Edit fields are a special problem because partial values arrive as the user types in the numbers; in this case, it is recommended that you examine and act only when the user leaves the edit field, i.e. the OnExit event handler.  In addition to avoiding partial number problems, this also avoids annoying lags when working with complex filter chains that take a third of a second or more per frame.