ref_vfmethod_prefetchProc

VirtualDub Plugin SDK 1.2

prefetchProc video filter method

prefetchProc

Retrieves the input frame number required to produce a given output frame.

sint64 prefetchProc(const VDXFilterActivation *fa, const VDXFilterFunctions *ff, sint64 frame);

Parameters

fa	Pointer to filter activation structure.
ff	Pointer to callback function structure.

Thread safety

This method is not thread-safe.

Exceptions

This function must not throw exceptions (see Except()).

Return value

The source frame required for the given output frame.

API version requirement

Requires V12 or later.

Default behavior

If omitted, the source frame is automatically chosen based on the output frame timestamp. This makes the frame numbers equal if the filter does not change the video frame rate.

Remarks

The purpose of prefetchProc is to allow the filter to direct the host in how to prefetch source frames for processing by a filter. For each output frame, prefetchProc specifies which source frame is needed to produce that output frame. This is similar to what would be passed to a GetFrame() function except that the actual frame fetching is asynchronous. By default, when prefetchProc is omitted, the host assumes that the source frame with the nearest timestamp to that of the output frame should be used.

prefetchProc is used to implement frame reordering, particularly in the case where the frame rate is modified by the filter. In most cases the default behavior suffices, but for some filters, particularly those that process fields, prefetchProc should be overridden to ensure exact frame timing.

There are some big gotchas with implementing this function:

Unlike most callbacks, prefetchProc must be implemented as thread-safe. Prefetching can occur at any time during execution and in parallel to frame processing, in particular runProc. Any mutable data that is accessed, like a cache, must be properly synchronized with a mutex or other mutual exclusion mechanism.
Prefetching can't depend on frame processing. For instance, a filter can't analyze previous frames in order to determine the next frame to fetch.
The prefetch pattern must be constant. Between startProc and endProc, a particular output frame must always map to the same source frame, no matter how many times prefetchProc is called and in what order.
Unused, extra prefetches can occur. A filter must not rely on a prefetch resulting in a call to runProc on the prefetched frame.

Audio is not reordered along with the frames, so this is not intended to allow for editing.