The Get Frames Needed Action

	#include "ofxImageEffect.h"
	#define kOfxImageEffectActionGetFramesNeeded              "OfxImageEffectActionGetFramesNeeded"
Arguments

  • handle handle to the instance, cast to an OfxImageEffectHandle ,
  • inArgs has the following property...
    • kOfxPropTime the effect time for which we need to calculate the frames needed on input
  • outArgs has a set of properties, one for each input clip, named "OfxImageClipPropFrameRange_" with the name of the clip post-pended. For example "OfxImageClipPropFrameRange_Source". All these properties are multi-dimensional doubles, with the dimension is a multiple of two. Each pair of values indicates a continuous range of frames that is needed on the given input. They are all initalised to the default value.

Description

This action lets the host ask the effect what frames are needed from each input clip to process a given frame. For example a temporal based degrainer may need several frames around the frame to render to do its work.

This action need only ever be called if the plugin has set the kOfxImageEffectPropTemporalClipAccess property on the plugin descriptor to be true. Otherwise the host assumes that the only frame needed from the inputs is the current one and this action is not called.

Note that each clip can have it's required frame range specified, and that you can specify discontinuous sets of ranges for each clip, for example...

	  // The effect always needs the initial frame of the source as well as the previous and current frame
	  double rangeSource[4];
	  
	  // required ranges on the source
	  rangeSource[0] = 0; // we always need frame 0 of the source
	  rangeSource[1] = 0;
	  rangeSource[2] = currentFrame - 1; // we also need the previous and current frame on the source
	  rangeSource[3] = currentFrame;
	  
	  gPropHost->propSetDoubleN(outArgs, "OfxImageClipPropFrameRange_Source", 4, rangeSource); 

Which sets two discontinuous range of frames from the 'Source' clip required as input.

Return Values

  • kOfxStatOK, the action was trapped and at least one frame range in the outArgs property set
  • kOfxStatReplyDefault, the action was not trapped and the host should use the default values
  • kOfxStatErrMemory, in which case the action may be called again after a memory purge
  • kOfxStatFailed, something wrong, but no error code appropriate, plugin to post message
  • kOfxStatErrFatal

Default Action

The default frame range is simply the single frame, kOfxPropTime..kOfxPropTime, found on the inArgs property set. All the frame ranges in the outArgs property set must initialised to this value before the action is called.