ref_struct_VDXInputDriverDefinition - shekh/VirtualDub2 GitHub Wiki

VirtualDub Plugin SDK 1.2

VDXInputDriverDefinition structure

Defines an input driver plugin.

struct VDInputDriverDefinition {
    enum {
        kFlagNone               = 0x00000000,
        kFlagSupportsVideo      = 0x00000001,
        kFlagSupportsAudio      = 0x00000002,
        kFlagCustomSignature    = 0x00010000,
        kFlagAll                = 0xFFFFFFFF
    };
    uint32      mSize;              // size of this structure in bytes
    uint32      mFlags;
    sint32      mPriority;
    uint32      mSignatureLength;
    const void *mpSignature;
    const wchar_t *mpFilenameDetectPattern;
    const wchar_t *mpFilenamePattern;
    const wchar_t *mpDriverTagName;

    VDInputDriverCreateProc         mpCreate;
};

mSize
Set this field to sizeof(VDInputDriverDefinition). This is used for future extensibility.

mFlags
A bitfield indicating some miscellaneous properties of the input plugin:

kFlagSupportsVideo
Indicates that the file format supported by this plugin may support video, although not necessarily always. This indicates to the host that this plugin should be included in features that load files for video. If the file turns out not to have video, the host will display an error for the user or script.

In VirtualDub, this causes a plugin to be included in the Open video file... dialog, and in the associated script function.

kFlagSupportsAudio
Indicates that the file format supported by this plugin may support audio, although not necessarily always. This indicates to the host that this plugin should be included in features that load files for video. If the file turns out not to have audio, the host will display an error for the user or script.

As of VirtualDub 1.7.5 (API V2), this is not yet supported, but in a future version it will cause the plugin to become available in the WAV audio... feature.

kFlagCustomSignature
The input plugin supports the DetectBySignature() function. If set, the plugin is loaded and DetectBySignature() is called after the initial signature match via mpSignature (if non-null) to return a definitive result. Not setting this flag prevents DetectBySignature() from being called, which speeds up autodetection because the plugin does not need to be loaded into memory.

kFlagNoOptions
Specifies that the input plugin does not support extended options and should not be asked to display options UI (PromptForOptions).

mPriority
A value indicating the relative priority of this plugin relative to other plugins during file autodetection, including ones internal to the host. Zero is the default; a plugin with a higher priority value wins over one with a lower priority value if the match result is the same. Note that a plugin that returns a better match result always wins regardless of priority. Plugins should exercise restraint here in using high priority values — in particular, plugins should never use the maximum value of 7FFFFFFF to "always win." Plugins that "handle" a format by returning a descriptive error message should always use a negative priority.

VirtualDub internally uses zero for most of its internal input drivers. Notable exceptions are the fake ASF loader, which uses -1; the AVIFile-based AVI loader, which uses -4 to avoid conflicting with the normal AVI loader at 0; and the image loader, which uses -1 because TARGA signatures can conflict with other file types. If you want to override a format that VirtualDub itself supports, you should use at least 1 for priority.

mSignatureLength
The number of bytes in the signature; must be even. Generally this is set to sizeof(signature). Must be zero if mpSignature is NULL.

mpSignature
Pointer to the signature, if present. This is an array of pairs of bytes signifying a match pattern against the bytes starting at the beginning of the file, where the first byte in each pair is the match byte and the second byte is the mask byte. A byte pair in the signature matches the corresponding byte in the file only if the bits that are significant according to the mask are the same between the match byte and the file byte, i.e. (match & mask) == (data & mask). If the mask bytes are all FF, then the signature simply looks for a specific, contiguous string at the beginning of the file. Pairs of (0,0) allow bytes to be entirely skipped.

If a custom signature match routine is also present, then both this signature and the custom signature must pass for the plugin to be eligible for the file. This allows the signature in this structure to be used for a quick cull pass, and the plugin loaded for its custom signature match routine only if the first signature passes.

In versions of VirtualDub up to 1.7.5 (API V2), there is a bug where a plugin that only uses a signature string only returns a sketchy match (0) instead of a definitive match (1). The workaround is to use a custom signature match routine.

mpFilenameDetectPattern
The filename pattern used for autodetection; may be NULL if none is supported. This is applied to the incoming filename, including the extension if present, but not the drive letter or directory path. If this string matches, a poor match is automatically registered for this plugin during autodetection. The pattern string may include ? and * wildcards, and may include multiple patterns may be supplied separated by vertical bars.

The filename matching algorithm applied is not guaranteed to exactly match the underlying OS mechanism. In particular, Windows has a number of odd special cases involving short (8.3) filenames and leading periods that VirtualDub's internal matching algorithm does not support. The implemented algorithm is instead equivalent to transforming the pattern string to a regular expression by replacing ? with . and * with .*. The filename detection pattern is mainly intended for patterns of the form *.ext that look for particular extensions, although it can be legitimately used to look for base filename patterns as well.

mpFilenamePattern
The filename pattern displayed and used in file selection UI. It should be of the form "readable-form|pattern|...," where the readable form is displayed to the user, and the pattern is a filename wildcard expression with semicolon separators. Multiple patterns may be supplied, separated by vertical bars. For instance, if your plugin supported text files and bitmaps, you could use: "Text files|*.txt;*.ini|Bitmaps|*.bmp". This expression is essentially the same as a Windows common file dialog's filter, except with vertical bars instead of nulls. Note that if multiple filters are included, the plugin has no way of knowing which was used, and that the plugin should not include an "All files (*.*)" escape as that is generally done by the host.

mpDriverTagName
A name that is used to identify this plugin in scripts and batch jobs. This name is not the primary name shown to users but should be human-readable. It should be stable to avoid breaking existing scripts, so version and build strings should not be embedded, but it is a good idea to make it fairly unique. Example: "Foobar's BLAH reader."

mpCreate
Pointer to function that creates an input driver object for this plugin.

Copyright (C) 2007-2012 Avery Lee.