Effect.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  Effect.h
 
  Dominic Mazzoni
  Vaughan Johnson
 
**********************************************************************/
 
#ifndef __AUDACITY_EFFECT__
#define __AUDACITY_EFFECT__
 
#include "EffectBase.h"
 
#include "StatefulEffectBase.h"
 
#define BUILTIN_EFFECT_PREFIX wxT("Built-in Effect: ")
 
class EffectParameterMethods;
class LabelTrack;
class WaveTrack;
 
class sampleCount;
 
/*
 Also pops the even handler stack of a window, if given to the contructor
 
 This is a transitional class; it should be eliminated when all effect classes
 define their own associated subclasses of EffectUIValidator, which can hold
 state only for the lifetime of a dialog, so the effect object need not hold it
*/
class DefaultEffectUIValidator
   : public EffectUIValidator
   // Inherit wxEvtHandler so that Un-Bind()-ing is automatic in the destructor
   , protected wxEvtHandler
{
public:
   DefaultEffectUIValidator(
      EffectUIClientInterface &effect, EffectSettingsAccess &access,
      wxWindow *pParent = nullptr);
   ~DefaultEffectUIValidator() override;
   bool ValidateUI() override;
   bool IsGraphicalUI() override;
   void Disconnect() override;
protected:
   wxWindow *mpParent{};
};
 
class AUDACITY_DLL_API Effect /* not final */
   : public wxEvtHandler
   , public EffectBase
{
 //
 // public methods
 //
 // Used by the outside program to determine properties of an effect and
 // apply the effect to one or more tracks.
 //
 public:
   static inline Effect *FetchParameters(Effect &e, EffectSettings &)
   { return &e; }
 
   // The constructor is called once by each subclass at the beginning of the program.
   // Avoid allocating memory or doing time-consuming processing here.
   Effect();
   virtual ~Effect();
 
   // ComponentInterface implementation
 
   PluginPath GetPath() const override;
   bool VisitSettings(
      SettingsVisitor &visitor, EffectSettings &settings) override;
   bool VisitSettings(
      ConstSettingsVisitor &visitor, const EffectSettings &settings)
      const override;
 
   ComponentInterfaceSymbol GetSymbol() const override;
 
   VendorSymbol GetVendor() const override;
   wxString GetVersion() const override;
   TranslatableString GetDescription() const override;
 
   // EffectDefinitionInterface implementation
 
   EffectType GetType() const override;
   EffectFamilySymbol GetFamily() const override;
   bool IsInteractive() const override;
   bool IsDefault() const override;
   RealtimeSince RealtimeSupport() const override;
   bool SupportsAutomation() const override;
 
   bool SaveSettings(
      const EffectSettings &settings, CommandParameters & parms) const override;
   bool LoadSettings(
      const CommandParameters & parms, EffectSettings &settings) const override;
 
   OptionalMessage LoadUserPreset(
      const RegistryPath & name, EffectSettings &settings) const override;
   bool SaveUserPreset(
      const RegistryPath & name, const EffectSettings &settings) const override;
 
   RegistryPaths GetFactoryPresets() const override;
   OptionalMessage LoadFactoryPreset(int id, EffectSettings &settings)
      const override;
   OptionalMessage LoadFactoryDefaults(EffectSettings &settings)
      const override;
 
   // VisitSettings(), SaveSettings(), and LoadSettings()
   // use the functions of EffectParameterMethods.  By default, this function
   // defines an empty list of parameters.
   virtual const EffectParameterMethods &Parameters() const;
 
   int ShowClientInterface(wxWindow &parent, wxDialog &dialog,
      EffectUIValidator *pValidator, bool forceModal) override;
 
   EffectUIClientInterface* GetEffectUIClientInterface() override;
 
   // EffectUIClientInterface implementation
 
   std::unique_ptr<EffectUIValidator> PopulateUI(
      ShuttleGui &S, EffectInstance &instance, EffectSettingsAccess &access,
      const EffectOutputs *pOutputs) override;
   bool IsGraphicalUI() override;
   bool ValidateUI(EffectSettings &) override;
   bool CloseUI() override;
 
   bool CanExportPresets() override;
   void ExportPresets(const EffectSettings &settings) const override;
   OptionalMessage ImportPresets(EffectSettings &settings) override;
 
   bool HasOptions() override;
   void ShowOptions() override;
 
   // EffectPlugin implementation
 
   const EffectSettingsManager& GetDefinition() const override;
   virtual NumericFormatSymbol GetSelectionFormat() /* not override? */; // time format in Selection toolbar
 
   // EffectPlugin implementation
 
   int ShowHostInterface( wxWindow &parent,
      const EffectDialogFactory &factory,
      std::shared_ptr<EffectInstance> &pInstance, EffectSettingsAccess &access,
      bool forceModal = false) override;
   bool SaveSettingsAsString(
      const EffectSettings &settings, wxString & parms) const override;
   [[nodiscard]] OptionalMessage LoadSettingsFromString(
      const wxString & parms, EffectSettings &settings) const override;
   bool IsBatchProcessing() const override;
   void SetBatchProcessing() override;
   void UnsetBatchProcessing() override;
   bool TransferDataToWindow(const EffectSettings &settings) override;
   bool TransferDataFromWindow(EffectSettings &settings) override;
 
   // Effect implementation
 
   unsigned TestUIFlags(unsigned mask);
 
   bool Delegate(Effect &delegate, EffectSettings &settings);
 
   // Display a message box, using effect's (translated) name as the prefix
   // for the title.
   enum : long { DefaultMessageBoxStyle = wxOK | wxCENTRE };
   int MessageBox(const TranslatableString& message,
                  long style = DefaultMessageBoxStyle,
                  const TranslatableString& titleStr = {}) const;
 
   static void IncEffectCounter(){ nEffectsDone++;}
 
   bool EnableApply(bool enable = true);
 
 protected:
 
   bool EnablePreview(bool enable = true);
 
   bool CheckWhetherSkipEffect(const EffectSettings &settings) const override;
 
   double CalcPreviewInputLength(
      const EffectSettings &settings, double previewLength) const override;
 
 
   virtual std::unique_ptr<EffectUIValidator> PopulateOrExchange(
      ShuttleGui & S, EffectInstance &instance, EffectSettingsAccess &access,
      const EffectOutputs *pOutputs);
 
   // No more virtuals!
 
   // The Progress methods all return true if the user has cancelled;
   // you should exit immediately if this happens (cleaning up memory
   // is okay, but don't try to undo).
 
   // Pass a fraction between 0.0 and 1.0
   bool TotalProgress(double frac, const TranslatableString & = {}) const;
 
   // Pass a fraction between 0.0 and 1.0, for the current track
   // (when doing one track at a time)
   bool TrackProgress(
      int whichTrack, double frac, const TranslatableString & = {}) const;
 
   // Pass a fraction between 0.0 and 1.0, for the current track group
   // (when doing stereo groups at a time)
   bool TrackGroupProgress(
      int whichGroup, double frac, const TranslatableString & = {}) const;
 
   int GetNumWaveTracks() const { return mNumTracks; }
   int GetNumWaveGroups() const { return mNumGroups; }
 
   // Calculates the start time and length in samples for one or two channels
   void GetBounds(
      const WaveTrack &track, const WaveTrack *pRight,
      sampleCount *start, sampleCount *len);
 
   // Use this method to copy the input tracks to mOutputTracks, if
   // doing the processing on them, and replacing the originals only on success (and not cancel).
   // If not all sync-locked selected, then only selected wave tracks.
   void CopyInputTracks(bool allSyncLockSelected = false);
 
   // For the use of analyzers, which don't need to make output wave tracks,
   // but may need to add label tracks.
   class AUDACITY_DLL_API AddedAnalysisTrack {
      friend Effect;
      AddedAnalysisTrack(Effect *pEffect, const wxString &name);
      AddedAnalysisTrack(const AddedAnalysisTrack&) PROHIBITED;
 
   public:
 
      AddedAnalysisTrack() {}
 
      // So you can have a vector of them
      AddedAnalysisTrack(AddedAnalysisTrack &&that);
 
      LabelTrack *get() const { return mpTrack; }
 
      // Call this to indicate successful completion of the analyzer.
      void Commit();
 
      // Destructor undoes the addition of the analysis track if not committed.
      ~AddedAnalysisTrack();
 
   private:
      Effect *mpEffect{};
      LabelTrack *mpTrack{};
   };
 
   // Set name to given value if that is not empty, else use default name
   std::shared_ptr<AddedAnalysisTrack> AddAnalysisTrack(const wxString &name = wxString());
 
   // For the use of analyzers, which don't need to make output wave tracks,
   // but may need to modify label tracks.
   class AUDACITY_DLL_API ModifiedAnalysisTrack {
      friend Effect;
      ModifiedAnalysisTrack
         (Effect *pEffect, const LabelTrack *pOrigTrack, const wxString &name);
      ModifiedAnalysisTrack(const ModifiedAnalysisTrack&) PROHIBITED;
 
   public:
 
      ModifiedAnalysisTrack();
 
      // So you can have a vector of them
      ModifiedAnalysisTrack(ModifiedAnalysisTrack &&that);
 
      LabelTrack *get() const { return mpTrack; }
 
      // Call this to indicate successful completion of the analyzer.
      void Commit();
 
      // Destructor undoes the modification of the analysis track if not committed.
      ~ModifiedAnalysisTrack();
 
   private:
      Effect *mpEffect{};
      LabelTrack *mpTrack{};
      std::shared_ptr<Track> mpOrigTrack{};
   };
 
   // Set name to given value if that is not empty, else use default name
   ModifiedAnalysisTrack ModifyAnalysisTrack
      (const LabelTrack *pOrigTrack, const wxString &name = wxString());
 
   // Use this to append a NEW output track.
   Track *AddToOutputTracks(const std::shared_ptr<Track> &t);
 
protected:
   // UI
   wxWeakRef<wxDialog> mHostUIDialog;
   wxWindow       *mUIParent{};
 
public:
   wxWindow* GetUIParent() { return mUIParent; }
 
private:
   wxString GetSavedStateGroup();
 
   bool mIsBatch{ false };
};
 
template<typename Settings, typename Base>
class EffectWithSettings : public Base {
public:
   EffectSettings MakeSettings() const override
   {
      return EffectSettings::Make<Settings>();
   }
   bool CopySettingsContents(
      const EffectSettings &src, EffectSettings &dst) const override
   {
      return EffectSettings::Copy<Settings>(src, dst);
   }
   static inline Settings &GetSettings(EffectSettings &settings)
   {
      auto pSettings = settings.cast<Settings>();
      assert(pSettings);
      return *pSettings;
   }
   static inline const Settings &GetSettings(const EffectSettings &settings)
   {
      return GetSettings(const_cast<EffectSettings &>(settings));
   }
   static inline Settings *
   FetchParameters(Base &, EffectSettings &s) {
      return &GetSettings(s);
   }
};
 
class StatefulEffect
   : public StatefulEffectBase
   , public Effect
{
public:
   class AUDACITY_DLL_API Instance : public StatefulEffectBase::Instance {
   public:
      using StatefulEffectBase::Instance::Instance;
      bool Process(EffectSettings &settings) override;
      SampleCount GetLatency(
         const EffectSettings &settings, double sampleRate) const override;
   };
   std::shared_ptr<EffectInstance> MakeInstance() const override;
};
 
// FIXME:
// FIXME:  Remove this once all effects are using the NEW dialog
// FIXME:
 
#define ID_EFFECT_PREVIEW ePreviewID
 
#endif