general_init - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

Plugin initialization

All plugin DLLs must export the following single function:

const VDXPluginInfo *const *VDXAPIENTRY VDGetPluginInfo();

This must be exported without any decoration (name mangling) and must use the VDXAPIENTRY calling convention, which maps to __stdcall. As the Microsoft Visual C++ compiler is not generally disposed to naming the function appropriately, a module definition (.def) file should be used to export the function correctly. The Microsoft DUMPBIN utility can be used with the /exports flag to verify the exported names.

VDGetPluginInfo() returns a pointer array where each entry points to a VDXPluginInfo structure for each driver or filter in the module. Multiple drivers or filters can thus be included in a single DLL. The array is terminated with a NULL pointer.

Note: Plugin DLLs that only contain video filters do not have to use this mechanism, because the API for video filters predates this mechanism. See Creating a video filter for details.

API versioning

Each plugin API has a version number associated with it, which is increased as new features are added or breaking changes are made. This version is exposed to the plugin and allows newer API features to be used without breaking compatibility with older hosts.

Plugins implementing or using those APIs also expose a pair of version numbers, the compatible version and the latest version. These are used by the host to check for plugin compatibility. The compatible version is the lowest version supported by the plugin, and causes the plugin to be rejected if it is newer than the host's highest supported version. The latest version indicates the largest feature set used by the plugin and can be used by the host to enable compatibility code or reject plugins that are too old. Generally, the compatibility version is hardcoded, whereas the latest version is set to the API version constant in the SDK headers and reflects the headers the plugin was built against.

The plugin does not have to check for host API versions that are too old or too new; this is the responsibility of the host. It only has to check API versions if it can use features that are only supported in some API versions within its [compatible, latest] version bracket. Plugins should always use a >= test instead of an == test when checking versions, as the reported API version may be newer than the one the plugin was built against.

Auto-loading on startup

The 32-bit version of VirtualDub searches the plugins32 directory under its program location for files matching the pattern *.vdplugin; the 64-bit version searches plugins64 instead. Any plugin DLLs found are automatically loaded on startup.

Platform compatibility

Due to limitations in Windows, the 32-bit version of VirtualDub can only load 32-bit plugins, and the 64-bit X64 version of VirtualDub can only load 64-bit X64 plugins. However, it is possible to build both from shared source code if a plugin is written portably.

Video filter API compatibility

Current versions of VirtualDub will still search the plugins directory and load DLLs using the old .vdf extension. It is recommended that plugin vendors migrate to the plugins32 and plugins64 directories for new plugins in order to avoid errors between the 32-bit and 64-bit versions of VirtualDub, which both try to load from the shared plugins directory.

A plugin DLL can expose both old filters and new filters/drivers by exporting both VDGetPluginInfo() and VirtualdubFilterModuleInit2 functions.