videofilt_programmingmodel - shekh/VirtualDub2 GitHub Wiki
VirtualDub Plugin SDK 1.2
Programming model
A video filter plugin exposes one or more video filters, which appear in VirtualDub's filter list. Each time the filter is added to the list, a filter instance is created, which corresponds to a stage in the pipeline where the filter processes frames. Multiple instances of the same filter may be active within the same chain.
Filter code is called with pointers to VDXFilterActivation and
VDXFilterFunctions structures. The VDXFilterActivation structure
contains information about the incoming video stream, input and output
bitmap structures, and data assocated with the filter instance.
VDXFilterFunctions points to a series of callbacks the filter can use
to issue requests to the host.
Each instance also has a memory block associated with it, pointed to by
the filter_data field in the VDXFilterActivation structure, which
holds per-instance data. VirtualDub allocates this memory according to
the inst_data_size field in the filter definition, but otherwise, the
contents are completely up to the filter.
When a filter instance is created, the initProc routine is called, if present, to initialize the instance data associated with the filter instance. A corresponding deinitProc routine may be included to clean up instance data before the instance is destroyed, and copyProc can be specified to handle cloning of it. These can be implemented to call the C++ constructor, destructor, and copy constructor of a class in order to treat the instance data as a C++ object with methods.
The paramProc function of a filter is
called to determine the basic processing parameters of a filter, most
notably the output it produces for a given input. This is done
repeatedly as the filter chain is built; VirtualDub's video filter chain
dialog, for instance, uses paramProc to determine frame sizes to
display in the dialog. It's worth nothing that paramProc cannot fail —
even if the configuration parameters are invalid or the input frame size
cannot be supported, paramProc must return a reasonable default.
Once the basic operating parameters of all instances in the filter chain
have been determined, the host can then prepare all filter instances for
processing video frames by calling the
startProc function of each instance in
turn. This is where filters perform heavy initialization that isn't
otherwise necessary, such as allocating working buffers and reading
auxiliary data files. Unlike paramProc, startProc can and should
fail with an exception if configuration parameters are invalid or the
filter instance otherwise cannot start.
During main filter chain operation, runProc
is called repeatedly on each filter instance to process each video frame
in turn. Once all video frames have been processed,
endProc is called to notify filter
instances of the end of the operation and allow each to clean up
resources that were allocated in startProc.
An instance of a video filter is generally active on only one thread at a time. However, different instances of the same video filter may run in parallel. The code for a video filter must therefore be re-entrant, and if any data is shared between instances, access to the shared data must be done in a thread-safe manner.
Copyright (C) 2007-2012 Avery Lee.