Source video sampling allows a filter to pick a number of frames from its source to determine the characteristics of the incoming video.  This is useful, for instance, to display a histogram of the input so the user can adjust contrast and brightness.

How the sampling interface works

Video sampling requires the use of active preview and is thus attached to the TFilterPreview class, made available through the fa^.ifp member.  There are three sampling functions:

• procedure SetSampleCallback(fp: TFilterPreviewSampleCallback; p: Pointer);
• function SampleCurrentFrame: Boolean;
• function SampleFrames: LongInt;

Use SetSampleCallback to give VirtualDub a callback function to accept frames for sampling.  The callback has this prototype:

TFilterPreviewSampleCallback = procedure(aVFBitmap: PCObj_VFBitmap; lFrame, lCount: LongInt; pData: Pointer); cdecl;

Once the callback is set up, call SampleCurrentFrame to sample the frame currently being previewed by the user, or SampleFrames to sample parts of the entire video.  In the latter case, the user will be presented with a dialog box asking whether to sample the entire video, all keyframes, or one keyframe per second of video.  SampleCurrentFrame returns true if a frame was sampled, and SampleFrames returns the total number of frames sampled, or -1 on error.

The preview window must be up before calling either function.  Otherwise, SampleCurrentFrame returns false, and SampleFrames returns -1.  Usually, you will want to install a button callback to disable sampling buttons when the preview window is not up.

Hints

• During a sampling operation, VirtualDub runs all filters before the one currently being configured.  The video you sample is the same video your runProc sees.
• You cannot automate the sampling operation.  It would be a very, very expensive process if all filters decided they wanted to sample their entire input before beginning operation.  Do not rely on sample data, because the user may not hit the sample button before the dubbing operation begins.
• The TVFBitmap.Histogram function may be of some use here.