videofilt_creatingavideofilter - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

Creating a video filter

The video filter API is designed to allow filters to be partially implemented, reducing the amount of boilerplate code that must accompany a filter.

A filter DLL must export two entry points: VirtualdubFilterModuleInit2 and VirtualdubFilterModuleDeinit. These methods register and deregister the filters within a DLL, respectively. Here is an example of how these filters can be implemented:

extern FilterDefinition g_myFilterDef;
FilterDefinition *g_registeredFilterDef;

extern "C" __declspec(dllexport) int __cdecl VirtualdubFilterModuleInit2(struct VDXFilterModule *fm, const VDXFilterFunctions *ff, int& vdfd_ver, int& vdfd_compat) {
    g_registeredFilterDef = ff->addFilter(fm, &g_myFilterDef, sizeof(FilterDefinition));

    vdfd_ver        = VIRTUALDUB_FILTERDEF_VERSION;
    vdfd_compat     = 8;    // we need this version for copy constructor support

    return 0;
}

extern "C" __declspec(dllexport) void __cdecl VirtualdubFilterModuleDeinit(struct VDXFilterModule *fm, const VDXFilterFunctions *ff) {
    // Note: This must be the pointer returned from addFilter(), NOT your original
    // declaration.
    ff->removeFilter(g_registeredFilterDef);
}

Note that these functions must be exported from the DLL with no name mangling or decoration on the names. This is the reason that the functions are exported as extern "C". If you are using the Microsoft Visual C++ compiler, you can use the DUMPBIN tool with the /LINK flag to check the names. There should be no underscores or at-signs (@) present.

The vdfd_ver and vdfd_compat parameters are particularly important. On entry, these correspond to the highest and lowest plugin API versions supported by the host. These are set by the filter module init routine to the highest and lowest plugin API version supported by the filters in the module. The host can then choose to reject the filter module if it is not compatible, or adjust its interface logic as necessary to suit the API versions the filter expects. Similarly, as necessary, the filter should check the incoming vdfd_ver value and adjust its use of the API accordingly. On exit, vdfd_ver should always be set to the VIRTUALDUB_FILTERDEF_VERSION constant used to compile the filter; vdfd_compat should be set to the lowest API version that the filters can deal with.

Next, a FilterDefinition structure must then be created for every filter in the DLL. This structure consists of a few strings describing the filter and a series of callbacks indicating which routines the filter supports. Most of the callbacks can be set to NULL in order to invoke default behavior; in fact, the only callback that is required is runProc. Therefore, this is a valid definition:

static struct FilterDefinition myfilter_definition={
    0,0,NULL,                       // next, prev, and module (set to zero)
    "my filter",                    // name
    "Description of my filter.",    // description
    "Author of my filter.",         // author / maker
    NULL,                           // no private data
    0,                              // no instance data size
    NULL,                           // no initProc
    NULL,                           // no deinitProc
    myfilter_run,                   // runProc
    // allow the compiler to zero-initialize the rest of the fields
};

(Important note: The structure must not be declared const, as older versions of VirtualDub will write to the structure.)

Copyright (C) 2007-2012 Avery Lee.