ofxsImageEffect.h

Go to the documentation of this file.

#ifndef _ofxsImageEffect_H_
#define _ofxsImageEffect_H_
/*
OFX Support Library, a library that skins the OFX plug-in API with C++ classes.
Copyright (C) 2004-2005 The Foundry Visionmongers Ltd
Author Bruno Nicoletti bruno@thefoundry.co.uk

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name The Foundry Visionmongers Ltd, nor the names of its 
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The Foundry Visionmongers Ltd
1 Wardour St
London W1D 6PA
England



*/

#include <map>
#include <string>
#include <sstream>
#include "ofxsParam.h"
#include "ofxsInteract.h"
#include "ofxsMessage.h"
#include "ofxProgress.h"
#include "ofxTimeLine.h"

#define mDeclareProtectedAssignAndCC(CLASS) \
  CLASS &operator=(const CLASS &v1) {assert(false); return *this;}      \
  CLASS(const CLASS &v) {assert(false); } 

namespace OFX
{
  namespace Private
  {
    OfxStatus mainEntryStr(const char    *actionRaw,
      const void    *handleRaw,
      OfxPropertySetHandle   inArgsRaw,
      OfxPropertySetHandle   outArgsRaw,
      const char* plugname);
  }
}


namespace OFX {
  class ClipDescriptor;
  class ImageEffectDescriptor;

  class Image;
  class Clip;
  class ImageEffect;
  class ImageMemory;

  enum ContextEnum {eContextNone,
    eContextGenerator,
    eContextFilter,
    eContextTransition,
    eContextPaint,
    eContextGeneral,
    eContextRetimer};

  enum BitDepthEnum {eBitDepthNone, 
    eBitDepthUByte,
    eBitDepthUShort,
    eBitDepthFloat,
    eBitDepthCustom 
  };

  enum PixelComponentEnum {ePixelComponentNone,
    ePixelComponentRGBA,
    ePixelComponentAlpha,
    ePixelComponentCustom 
  };

  enum FieldExtractionEnum {eFieldExtractBoth,   
    eFieldExtractSingle, 
    eFieldExtractDoubled 
  };

  enum RenderSafetyEnum {eRenderUnsafe,       
    eRenderInstanceSafe, 
    eRenderFullySafe     
  };

  enum FieldEnum {eFieldNone,   
    eFieldBoth,   
    eFieldLower,  
    eFieldUpper   
  };

  enum PreMultiplicationEnum { eImageOpaque,          
    eImagePreMultiplied,   
    eImageUnPreMultiplied, 
  };


  class PluginFactory
  {
  public:
    virtual void load() {}
    virtual void unload() {}
    virtual void describe(OFX::ImageEffectDescriptor &desc) = 0;
    virtual void describeInContext(OFX::ImageEffectDescriptor &desc, ContextEnum context) = 0;
    virtual ImageEffect* createInstance(OfxImageEffectHandle handle, ContextEnum context) = 0;
    virtual const std::string& getID() const = 0;
    virtual const std::string& getUID() const = 0;
    virtual unsigned int getMajorVersion() const = 0;
    virtual unsigned int getMinorVersion() const = 0;
    virtual OfxPluginEntryPoint* getMainEntry() = 0;
  };

  template<class FACTORY>
  class FactoryMainEntryHelper
  {
  protected:
    const std::string& getHelperID() const { return _id; }
    unsigned int getHelperMajorVersion() const  { return  _maj; }
    unsigned int getHelperMinorVersion() const  { return  _min; }
    std::string toString(unsigned int val)
    {
      std::ostringstream ss;
      ss << val;
      return ss.str();
    }
    FactoryMainEntryHelper(const std::string& id, unsigned int maj, unsigned int min): _id(id), _maj(maj), _min(min)
    {
      _uid = id + toString(maj) + toString(min);
    }
    const std::string& getHelperUID() const { return _uid; }
    static OfxStatus mainEntry(const char *action, const void* handle, OfxPropertySetHandle in, OfxPropertySetHandle out)
    { 
      return OFX::Private::mainEntryStr(action, handle, in, out, _uid.c_str());
    }
    static std::string _uid;
    std::string _id;
    unsigned int _maj;
    unsigned int _min;
  };
  template<class T> std::string OFX::FactoryMainEntryHelper<T>::_uid; 

  template<class FACTORY>
  class PluginFactoryHelper : public FactoryMainEntryHelper<FACTORY>, public PluginFactory
  {
  public:
    PluginFactoryHelper(const std::string& id, unsigned int maj, unsigned int min): FactoryMainEntryHelper<FACTORY>(id, maj, min)
    {}
    OfxPluginEntryPoint* getMainEntry() { return FactoryMainEntryHelper<FACTORY>::mainEntry; }
    const std::string& getID() const { return FactoryMainEntryHelper<FACTORY>::getHelperID(); }
    const std::string& getUID() const { return FactoryMainEntryHelper<FACTORY>::getHelperUID(); }
    unsigned int getMajorVersion() const { return FactoryMainEntryHelper<FACTORY>::getHelperMajorVersion(); }
    unsigned int getMinorVersion() const { return FactoryMainEntryHelper<FACTORY>::getHelperMinorVersion(); }
  };

#define mDeclarePluginFactory(CLASS, LOADFUNCDEF, UNLOADFUNCDEF) \
  class CLASS : public OFX::PluginFactoryHelper<CLASS> \
  { \
  public: \
  CLASS(const std::string& id, unsigned int verMaj, unsigned int verMin):OFX::PluginFactoryHelper<CLASS>(id, verMaj, verMin){} \
  virtual void load() LOADFUNCDEF ;\
  virtual void unload() UNLOADFUNCDEF ;\
  virtual void describe(OFX::ImageEffectDescriptor &desc); \
  virtual void describeInContext(OFX::ImageEffectDescriptor &desc, OFX::ContextEnum context); \
  virtual OFX::ImageEffect* createInstance(OfxImageEffectHandle handle, OFX::ContextEnum context); \
  };

  typedef std::vector<PluginFactory*> PluginFactoryArray;

  void * fetchSuite(char *suiteName, int suiteVersion, bool optional = false);


  struct ImageEffectHostDescription {
  public :
    std::string hostName;
    bool hostIsBackground;
    bool supportsOverlays;
    bool supportsMultiResolution;
    bool supportsTiles;
    bool temporalClipAccess;
    bool supportsMultipleClipDepths;
    bool supportsMultipleClipPARs;
    bool supportsSetableFrameRate;
    bool supportsSetableFielding;
    bool supportsStringAnimation;
    bool supportsCustomInteract;
    bool supportsChoiceAnimation;
    bool supportsBooleanAnimation;
    bool supportsCustomAnimation;
    int maxParameters;
    int maxPages;
    int pageRowCount;
    int pageColumnCount;
    typedef std::vector<PixelComponentEnum> PixelComponentArray;
    PixelComponentArray _supportedComponents;
    typedef std::vector<ContextEnum> ContextArray;
    ContextArray _supportedContexts;
    typedef std::vector<BitDepthEnum> PixelDepthArray;
    PixelDepthArray _supportedPixelDepths;
    bool supportsProgressSuite;
    bool supportsTimeLineSuite;
  };


  ImageEffectHostDescription* getImageEffectHostDescription();


  class ClipDescriptor {
  protected :
    mDeclareProtectedAssignAndCC(ClipDescriptor);
    ClipDescriptor(void) {assert(false);}

  protected :
    std::string _clipName;

    PropertySet _clipProps;

  protected :
    ClipDescriptor(const std::string &name, OfxPropertySetHandle props);

    friend class ImageEffectDescriptor;

  public :
    const PropertySet &getPropertySet() const {return _clipProps;}

    PropertySet &getPropertySet() {return _clipProps;}


    void setLabels(const std::string &label, const std::string &shortLabel, const std::string &longLabel);

    void setFieldExtraction(FieldExtractionEnum v);

    void addSupportedComponent(PixelComponentEnum v);

    void addSupportedComponent(const std::string &comp);

    void setTemporalClipAccess(bool v);

    void setOptional(bool v);

    void setSupportsTiles(bool v);

    void setIsMask(bool v);    
  };


  class ImageEffectDescriptor : public ParamSetDescriptor
  {
  protected :
    mDeclareProtectedAssignAndCC(ImageEffectDescriptor);
    ImageEffectDescriptor(void) {assert(false);}

  protected :
    OfxImageEffectHandle _effectHandle;

    PropertySet _effectProps;

    std::map<std::string, ClipDescriptor *> _definedClips;

    std::map<std::string, std::string> _clipComponentsPropNames;
    std::map<std::string, std::string> _clipDepthPropNames;
    std::map<std::string, std::string> _clipPARPropNames;
    std::map<std::string, std::string> _clipROIPropNames;
    std::map<std::string, std::string> _clipFrameRangePropNames;

    std::auto_ptr<EffectOverlayDescriptor> _overlayDescriptor;
  public :
    ImageEffectDescriptor(OfxImageEffectHandle handle);

    ~ImageEffectDescriptor();

    const PropertySet &getPropertySet() const {return _effectProps;}

    PropertySet &getPropertySet() {return _effectProps;}

    void setLabels(const std::string &label, const std::string &shortLabel, const std::string &longLabel);

    void setPluginGrouping(const std::string &group);

    void addSupportedContext(ContextEnum v);

    void addSupportedBitDepth(BitDepthEnum v);

    void setSingleInstance(bool v);

    void setHostFrameThreading(bool v);

    void setSupportsMultiResolution(bool v);

    void setSupportsTiles(bool v);

    void setTemporalClipAccess(bool v);

    void setRenderTwiceAlways(bool v);

    void setSupportsMultipleClipDepths(bool v);

    void setSupportsMultipleClipPARs(bool v);

    void setRenderThreadSafety(RenderSafetyEnum v);

    void addClipPreferencesSlaveParam(ParamDescriptor &p);

    ClipDescriptor *defineClip(const std::string &name);

    const std::map<std::string, std::string>& getClipComponentPropNames() const { return _clipComponentsPropNames; }
    const std::map<std::string, std::string>& getClipDepthPropNames() const { return _clipDepthPropNames; }
    const std::map<std::string, std::string>& getClipPARPropNames() const { return _clipPARPropNames; }
    const std::map<std::string, std::string>& getClipROIPropNames() const { return _clipROIPropNames; }
    const std::map<std::string, std::string>& getClipFrameRangePropNames() const { return _clipFrameRangePropNames; }

    virtual void setOverlayInteractDescriptor(EffectOverlayDescriptor* desc);
  };  


  class Image {
  protected :
    PropertySet _imageProps;

    friend class Clip;

    void     *_pixelData;                    
    PixelComponentEnum _pixelComponents;     
    int       _rowBytes;                     
    int       _pixelBytes;                   
    BitDepthEnum _pixelDepth;                 
    PreMultiplicationEnum _preMultiplication; 
    OfxRectI  _regionOfDefinition;           
    OfxRectI  _bounds;                       
    double    _pixelAspectRatio;             
    FieldEnum _field;                        
    std::string _uniqueID;                   
    OfxPointD _renderScale;                  
  public :
    Image(OfxPropertySetHandle props);

    virtual ~Image();

    const PropertySet &getPropertySet() const {return _imageProps;}

    PropertySet &getPropertySet() {return _imageProps;}

    BitDepthEnum getPixelDepth(void) const {return _pixelDepth;}

    PixelComponentEnum getPixelComponents(void) const { return _pixelComponents;}

    std::string getPixelComponentsProperty(void) const { return _imageProps.propGetString(kOfxImageEffectPropComponents);}

    PreMultiplicationEnum getPreMultiplication(void) const { return _preMultiplication;}

    OfxPointD getRenderScale(void) const { return _renderScale;}

    double getPixelAspectRatio(void) const { return _pixelAspectRatio;}

    void *getPixelData(void) const { return _pixelData;}

    OfxRectI getRegionOfDefinition(void) const { return _regionOfDefinition;}

    OfxRectI getBounds(void) const { return _bounds;}

    int getRowBytes(void) const { return _rowBytes;}

    FieldEnum getField(void) const { return _field;}

    std::string getUniqueIdentifier(void) const { return _uniqueID;}

    void *getPixelAddress(int x, int y);
  };


  class Clip {
  protected :
    mDeclareProtectedAssignAndCC(Clip);

    std::string _clipName;

    PropertySet _clipProps;

    OfxImageClipHandle _clipHandle;

    ImageEffect *_effect;

    Clip(ImageEffect *effect, const std::string &name, OfxImageClipHandle handle, OfxPropertySetHandle props);

    friend class ImageEffect;

  public :
    const PropertySet &getPropertySet() const {return _clipProps;}

    PropertySet &getPropertySet() {return _clipProps;}

    OfxImageClipHandle getHandle() {return _clipHandle;}

    const std::string &name(void) const {return _clipName;}

    void getLabels(std::string &label, std::string &shortLabel, std::string &longLabel) const;

    BitDepthEnum getPixelDepth(void) const;

    PixelComponentEnum getPixelComponents(void) const;

    std::string getPixelComponentsProperty(void) const { return _clipProps.propGetString(kOfxImageEffectPropComponents);}

    BitDepthEnum getUnmappedPixelDepth(void) const;

    PixelComponentEnum getUnmappedPixelComponents(void) const;

    std::string getUnmappedPixelComponentsProperty(void) const { return _clipProps.propGetString(kOfxImageClipPropUnmappedComponents);}

    PreMultiplicationEnum getPreMultiplication(void) const;

    FieldEnum getFieldOrder(void) const;

    bool isConnected(void) const;

    bool hasContinuousSamples(void) const;

    double getPixelAspectRatio(void) const;

    double getFrameRate(void) const;

    OfxRangeD getFrameRange(void) const;

    double getUnmappedFrameRate(void) const;

    OfxRangeD getUnmappedFrameRange(void) const;

    OfxRectD getRegionOfDefinition(double t);

    Image *fetchImage(double t);

    Image *fetchImage(double t, OfxRectD bounds);

    Image *fetchImage(double t, OfxRectD *bounds)
    {
      if(bounds) 
        return fetchImage(t, *bounds);
      else
        return fetchImage(t);
    }
  };


  class ImageMemory {
  protected :
    OfxImageMemoryHandle _handle;

  public :
    ImageMemory(size_t nBytes, ImageEffect *associatedEffect = 0);

    ~ImageMemory();

    void *lock(void);

    void unlock(void);
  };


  struct RenderArguments {
    double    time;
    OfxPointD renderScale;
    OfxRectI  renderWindow;
    FieldEnum fieldToRender;
  };

  struct BeginSequenceRenderArguments {
    OfxRangeD frameRange;
    double    frameStep;
    bool      isInteractive;
    OfxPointD renderScale;
  };

  struct EndSequenceRenderArguments {
    bool      isInteractive;
    OfxPointD renderScale;
  };

  struct RegionOfDefinitionArguments {
    double    time;
    OfxPointD renderScale;
  };

  struct RegionsOfInterestArguments {
    double    time;
    OfxPointD renderScale;
    OfxRectD  regionOfInterest;
  };

  class RegionOfInterestSetter {
  public :
    virtual void setRegionOfInterest(const Clip &clip, const OfxRectD &RoI) = 0;
  };

  struct FramesNeededArguments {
    double    time;
  };

  class FramesNeededSetter {
  public :
    virtual void setFramesNeeded(const Clip &clip, const OfxRangeD &range) = 0;
  };

  class ClipPreferencesSetter {
    OFX::PropertySet outArgs_;
    bool doneSomething_;
    typedef std::map<std::string, std::string> StringStringMap;
    const StringStringMap& clipDepthPropNames_;
    const StringStringMap& clipComponentPropNames_;
    const StringStringMap& clipPARPropNames_;
    const std::string& extractValueForName(const StringStringMap& m, const std::string& name);
  public :
    ClipPreferencesSetter( OFX::PropertySet props, 
      const StringStringMap& depthPropNames,
      const StringStringMap& componentPropNames,
      const StringStringMap& PARPropNames) 
      : outArgs_(props)
      , doneSomething_(false)
      , clipDepthPropNames_(depthPropNames)
      , clipComponentPropNames_(componentPropNames)
      , clipPARPropNames_(PARPropNames)
    {}

    bool didSomething(void) const {return doneSomething_;}

    void setClipComponents(Clip &clip, PixelComponentEnum comps);

    void setClipBitDepth(Clip &clip, BitDepthEnum bitDepth);

    void setPixelAspectRatio(Clip &clip, double PAR);

    void setOutputFrameRate(double v);

    void setOutputPremultiplication(PreMultiplicationEnum v);

    void setOutputHasContinousSamples(bool v);

    void setOutputFrameVarying(bool v);

    void setOutputFielding(FieldEnum v);
  };

  struct InstanceChangedArgs {
    InstanceChangeReason reason;      
    double               time;        
    OfxPointD            renderScale; 
  };


  class ImageEffect : public ParamSet
  {
  protected :
    mDeclareProtectedAssignAndCC(ImageEffect);

  private :
    friend class ImageMemory;

    OfxImageEffectHandle _effectHandle;

    PropertySet _effectProps;

    ContextEnum _context;

    std::map<std::string, Clip *> _fetchedClips;

    std::list<OverlayInteract *> _overlayInteracts;

    bool _progressStartSuccess;
  public :
    ImageEffect(OfxImageEffectHandle handle);

    virtual ~ImageEffect();

    const PropertySet &getPropertySet() const {return _effectProps;}

    PropertySet &getPropertySet() {return _effectProps;}


    OfxImageEffectHandle getHandle(void) const {return _effectHandle;}

    ContextEnum getContext(void) const;

    OfxPointD getProjectSize(void) const;

    OfxPointD getProjectOffset(void) const;

    OfxPointD getProjectExtent(void) const;

    double getProjectPixelAspectRatio(void) const;

    double getEffectDuration(void) const;

    double getFrameRate(void) const;

    bool isInteractive(void) const;

    void setSequentialRender(bool v);

    bool getSequentialRender(void) const;

    OFX::Message::MessageReplyEnum sendMessage(OFX::Message::MessageTypeEnum type, const std::string& id, const std::string& msg);

    Clip *fetchClip(const std::string &name);

    bool abort(void) const;

    void addOverlayInteract(OverlayInteract *interact);

    void removeOverlayInteract(OverlayInteract *interact);

    void redrawOverlays(void);

    // these are actions that need to be overridden by a plugin that implements an effect host

    virtual void purgeCaches(void);

    virtual void syncPrivateData(void);

    virtual void render(const RenderArguments &args) = 0;

    virtual void beginSequenceRender(const BeginSequenceRenderArguments &args); 

    virtual void endSequenceRender(const EndSequenceRenderArguments &args); 

    virtual bool isIdentity(const RenderArguments &args, Clip * &identityClip, double &identityTime);

    virtual bool getRegionOfDefinition(const RegionOfDefinitionArguments &args, OfxRectD &rod);

    virtual void getRegionsOfInterest(const RegionsOfInterestArguments &args, RegionOfInterestSetter &rois);

    virtual void getFramesNeeded(const FramesNeededArguments &args, FramesNeededSetter &frames);

    virtual void getClipPreferences(ClipPreferencesSetter &clipPreferences);

    virtual void beginEdit(void);

    virtual void endEdit(void);

    virtual void beginChanged(InstanceChangeReason reason);

    virtual void changedParam(const InstanceChangedArgs &args, const std::string &paramName);

    virtual void changedClip(const InstanceChangedArgs &args, const std::string &clipName);

    virtual void endChanged(InstanceChangeReason reason);

    virtual bool getTimeDomain(OfxRangeD &range);

    void progressStart(const std::string &message);

    void progressEnd();

    bool progressUpdate(double t);   

    double timeLineGetTime();

    void timeLineGotoTime(double t);

    void timeLineGetBounds(double &t1, double &t2);  
  };  



  namespace Plugin {
    void getPluginID(OFX::PluginFactoryArray &id);

#ifdef OFX_CLIENT_EXCEPTION_TYPE
    OfxStatus catchException(OFX_CLIENT_EXCEPTION_TYPE &ex);
#endif
  };

};

// undeclare the protected assign and CC macro
#undef mDeclareProtectedAssignAndCC

#endif

---