sdk

legacy SDK

All documented features of original SDK are compatible with VirtualDub2.
see VDPluginSDK-1.1.zip, VDPluginSDK-1.2.zip
Documentation online copy

Updated headers and wrappers can be extracted from example filter: crossfade (recommended way)
or from source tree.

Amendments to text:

API versioning

Initial set of features was added side-by-side without touching base API.
These features are indicated by letters FM or FilterMod in the names of classes etc.
More recent changes extend base API.
FM features are versioned separately (FILTERMOD_VERSION) and are all optional: the host may either implement them or not.
Therefore, for example check all interface pointers for null when accessing fma->fmtimeline:

int64 LogoFilter::currentFrame(int64 r)
{
  int64 frame = fa->pfsi->lCurrentSourceFrame;
  if(r!=-1) frame = r;
  if(fma && fma->fmtimeline){
    frame = fma->fmtimeline->FilterSourceToTimeline(frame);
  }
  return frame;
}

Plugin initialization

To access new features in video filter, additional export is required (example):

extern "C" int __cdecl FilterModModuleInit(VDXFilterModule *fm, const FilterModInitFunctions *ff, int& vdfd_ver, int& vdfd_compat, int& mod_ver, int& mod_min) {
  if(VDXVideoFilterModuleInitFilterMod(fm,ff,vdfd_ver,mod_ver)) return 1;

  vdfd_ver = VIRTUALDUB_FILTERDEF_VERSION;
  vdfd_compat = 9;      // copy constructor support required

  mod_ver = FILTERMOD_VERSION;
  mod_min = FILTERMOD_VERSION;
  return 0;
}

Writing video filters, Programming model

Additional structure, FilterModActivation, is exposed to provide access for new features.

Handling bitmaps

New structure is associated with input and output buffer: FilterModPixmapInfo

    uint32 ref_r;
    uint32 ref_g;
    uint32 ref_b;
    uint32 ref_a;

With new 16-bit formats these fields indicate maximum value (per channels for rgba, and only ref_r for all yuv channels).
When bitmap is normalized, ref values are 0xFFFF.
For example when bitmap contains un-normalized 10-bit from ffmpeg, ref values are 0x3F.
Can change with each frame (for example when appending different clips or using image sequence of different formats).
No matter what ref values are, all pixel values that fit in uint16 are legal (clamp during processing if necessary).

    uint32 alpha_type;

Indicates whether alpha is present and wheter it is premultiplied.
Valid only with rgba32, rgba64 modes.
When alpha is not present a filter can perform optimized processing.
How to use alpha is up to filter. Do anything of:

• preserve it (default)
• apply the same transform as other channels
• something else
• clear alpha_type on output (so it becomes not present down the pipeline)

    int64 frame_num;

Do not use. May be helpful with debugging.

    nsVDXPixmap::ColorSpaceMode colorSpaceMode;
    nsVDXPixmap::ColorRangeMode colorRangeMode;

Indicate colorspace parameters with new 16-bit YUV modes.
Initialized once, do not change per-frame.

Gotchas

Alpha channel

See alpha_type above.

Extensions overview

Documentation for extensions is a work in progress.
Extensions API and ABI are improved in (mostly) backwards compatible way.

Video filter extensions

Example code: rgb levels plugin
This filter can process un-normalized RGBA64 format.

Example code: crossfade
This filter can process 8-bit or 16-bit RGB/RGBA/YUV (most useful modes).

Example code: owdenoise
This filter can process 8-bit or 16-bit YUV.

Summary of features:

• new formats
• per frame metadata (alpha, colorspace, scale/bitdepth)
• alternate preview modes
• interact with preview: watch picker data, handle click on pixel
• interact with preview: select rectangular region
• request sampling over arbitrary frames
• get current timeline position, perform some timeline math
• set timeline position
• respond to timeline position change
• forward hotkeys
• find and create video filters (to host sub filters inside a filter)
• save and restore extended state
• request source filename and project directory
• new behavior flag: terminal (stop further processing)
• new behavior flag: normalize16 (for easy support of 16-bit formats)
• request image rows alignment on 16/32/64 bytes

Input driver extensions

Example code can be found in avlib-1
This lib contains input driver based on FFMPEG.

Summary of features:

• new formats
• flag presence of alpha
• switch operation mode (direct/full/etc)
• implement export commands
• switch audio decoding format
• improve driver priority with kFlagForceByName

Output driver, video encoder, audio encoder

These extensions are in early state.
Example code can be found in avlib-1
This lib contains all these plugin types based on FFMPEG.

Example code: x264 encoder
This plugin is x264vfw (vfw codec) ported to FilterMod (encoding only).

Tool

Tool scope is not well defined.
Script editor implements a menu command, a gui window, can access and control some internal state.
Example code scripted