Name

OfxImageEffectSuiteV1::clipGetImage — Get a handle for an image in a clip at the indicated time and indicated region

Synopsis

#include "ofxImageEffect.h" 
OfxStatus(*clipGetImage)(OfxImageClipHandleclip,
 OfxTime time,
 const OfxRectD *region,
 OfxPropertySetHandle *imageHandle);
 

Arguments

  • clip - the clip to extract the image from
  • time - time to fetch the image at
  • region - region to fetch the image from (optional, set to NULL to get a 'default' region) this is in the CanonicalCoordinates.
  • imageHandle - property set containing the image's data

Description

An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.

If the region parameter is not set to NULL, then it will be clipped to the clip's Region of Definition for the given time. The returned image will be m at m least as big as this region. If the region parameter is not set, then the region fetched will be at least the Region of Interest the effect has previously specified, clipped the clip's Region of Definition.

If clipGetImage is called twice with the same parameters, then two separate image handles will be returned, each of which must be release. The underlying implementation could share image data pointers and use reference counting to maintain them.

\pre

  • clip was returned by clipGetHandle

\post

  • image handle is only valid for the duration of the action clipGetImage is called in
  • image handle to be disposed of by clipReleaseImage before the action returns

Returns

  • kOfxStatOK - the image was successfully fetched and returned in the handle,
  • kOfxStatFailed - the image could not be fetched because it does not exist in the clip at the indicated time and/or region, the plugin

should continue operation, but assume the image was black and transparent.