A video filter is passed a handle to a VideoRecord with almost every selector.

typedef struct {
  PrMemoryHandle          specsHandle;
  PPixHand                source;
  PPixHand                destination;
  csSDK_int32             part;
  csSDK_int32             total;
  char                    previewing;
  void*                   privateData;
  VFilterCallBackProcPtr  callBack;
  BottleRec*              bottleNecks;
  short                   version;
  short                   sizeFlags;
  csSDK_int32             flags;
  TDB_TimeRecord*         tdb;
  PrMemoryHandle          instanceData;
  piSuitesPtr             piSuites;
  PrTimelineID            timelineData;
  char                    altName[MAX_FXALIAS];
  PrPixelFormat           pixelFormatSupported;
  csSDK_int32             pixelFormatIndex;
  csSDK_uint32            instanceID;
  TDB_TimeRecord          tdbTimelineLocation;
  csSDK_int32             sessionPluginID;
} VideoRecord, **VideoHandle;

Instance settings, persistent across Premiere sessions.

Create this handle during fsInitSpec or fsSetup.

Populated by Premiere if the filter’s parameters can be manipulated in the Effect Controls Panel.

Use Premiere’s memory allocation callbacks to allocate memory for the specsHandle.

source PPixHand for the source video frame.

PPixHand for the destination video frame, always the same size as source.

Store the output frame here during fsExecute.


How far into the effect you are.

part varies from 0 to total, inclusive.


Total length of the video filter.

Divide part by total to calculate the percentage of the time-variant filter for a given fsExecute.

This value doesn’t necessarily correspond to frames or fields.

previewing Unsupported

Data private to Premiere.

Pass to the frame-retrieval callback when requesting a frame.

callBack Pointer to VFilterCallbackProcPtr, used for retrieving frames (or fields, for interlaced video) from source clips.
bottleNecks Pointer to Premiere’s bottleRec functions.

Version of this structure (kVideoFilterVersion).

  • Premiere Pro CS5 = VIDEO_FILTER_VERSION_11
  • Premiere Pro CS3 = VIDEO_FILTER_VERSION_10
sizeFlags Field-rendering information.

If doing a lower-quality render, Premiere will pass in kEffectFlags_DraftQuality during fsExecute.

The filter can then optionally render a faster, lower-quality image for previewing.

tdb Pointer to a time database record describing the sequence timebase.

Handle to private instance data that persists across invocations.

Allocate the memory for this during fsExecute and deallocate during fsDisposeData.

Do not use this field during fsSetup.

piSuites Pointer to callback piSuites.

Only available during fsInitSpec and fsSetup.

This opaque handle to the timeline database is required by timelineFuncs callbacks available in piSuites.

This handle is useful in order to have a preview in a modal setup dialog during fsSetup.

altName Unused.

Only valid during fsGetPixelFormatsSupported.

Return pixel type supported.


Only valid during fsGetPixelFormatsSupported.

Index of fourCC of pixel type supported.


The runtime instance ID uniquely identifies filters during a session.

This is the same ID that is passed to players in prtFilterRec.


A time database record describing the location of the filter in sequence.

Only valid during fsInitSpec and fsSetup.


This ID should be used in the File Registration Suite for registering external files (such as textures, logos, etc) that are used by a plugin instance but do not appear as footage in the Project Panel.

Registered files will be taken into account when trimming or copying a project using the Project Manager.


Pointer to a callback for retrieving frames (or fields, for interlaced video) from the source clip.

Do not expect real-time performance from this callback.

typedef short (CALLBACK *VFilterCallBackProcPtr)(
  csSDK_int32  frame;
  PPixHand     thePort;
  RECT*        theBox;
  Handle       privateData);
Parameter Description

Frame requested. The frame value passed in should be frame * samplesize.

The callback will always return the current field (upper or lower) during field rendering.

thePort PPixHand where Premiere will store the frame
theBox Bounds of the frame you want Premiere to retrieve.
privateData Handle provided by Premiere in VideoRecord.privateData


For sizeFlags, the following bit flags are of interest:

Flag Description
gvFieldsEven The video filter should render upper-field dominance
gvFieldsOdd The video filter should render lower-field dominance
gvFieldsFirst The video filter is currently rendering the dominant field