EffectInterface.h

Go to the documentation of this file.

/*!********************************************************************
 
   Audacity: A Digital Audio Editor
 
   @file EffectInterface.h
 
   Leland Lucius
 
   Copyright (c) 2014, Audacity Team
   All rights reserved.
 
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:
 
   1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 
   2. 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.
 
   3. Neither the name of the copyright holder 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 HOLDER 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.
 
**********************************************************************/
 
#ifndef __AUDACITY_EFFECTINTERFACE_H__
#define __AUDACITY_EFFECTINTERFACE_H__
 
#include "ComponentInterface.h"
#include "ComponentInterfaceSymbol.h"
#include "EffectAutomationParameters.h"
 
#include "TypedAny.h"
#include <cstdint>
#include <memory>
#include <optional>
#include <type_traits>
 
#include "Observer.h"
 
class ShuttleGui;
template<bool Const> class SettingsVisitorBase;
using SettingsVisitor = SettingsVisitorBase<false>;
using ConstSettingsVisitor = SettingsVisitorBase<true>;
 
typedef enum EffectType : int
{
   EffectTypeNone,
   EffectTypeHidden,
   EffectTypeGenerate,
   EffectTypeProcess,
   EffectTypeAnalyze,
   EffectTypeTool,
} EffectType;
 
 
using EffectFamilySymbol = ComponentInterfaceSymbol;
 
class COMPONENTS_API EffectSettingsExtra final {
public:
   static const RegistryPath &DurationKey();
   const NumericFormatID& GetDurationFormat() const
      { return mDurationFormat; }
   void SetDurationFormat(const NumericFormatID &durationFormat)
      { mDurationFormat = durationFormat; }
 
   double GetDuration() const { return mDuration; }
   void SetDuration(double value) { mDuration = std::max(0.0, value); }
 
   bool GetActive() const { return mActive; }
   void SetActive(bool value) { mActive = value; }
private:
   NumericFormatID mDurationFormat{};
   double mDuration{}; 
   bool mActive{ true };
};
 
struct EffectSettings : audacity::TypedAny<EffectSettings> {
   using TypedAny::TypedAny;
   EffectSettingsExtra extra;
 
   void swap(EffectSettings &other)
   {
      TypedAny::swap(other);
      std::swap(extra, other.extra);
   }
 
   template<typename T, typename... Args>
   static EffectSettings Make(Args &&... args)
   {
      return EffectSettings(std::in_place_type<T>, std::forward<Args>(args)...);
   }
 
   template<typename T>
   static bool Copy(const EffectSettings &src, EffectSettings &dst)
   {
      const T *pSrc = src.cast<T>();
      T *pDst = dst.cast<T>();
      if (pSrc && pDst) {
         *pDst = *pSrc;
         return true;
      }
      return false;
   }
};
 
class COMPONENTS_API EffectOutputs {
public:
   virtual ~EffectOutputs();
   virtual std::unique_ptr<EffectOutputs> Clone() const = 0;
 
 
   virtual void Assign(EffectOutputs &&src) = 0;
};
 
 
class COMPONENTS_API EffectSettingsAccess
   : public std::enable_shared_from_this<EffectSettingsAccess> {
public:
   class COMPONENTS_API Message {
   public:
      virtual ~Message();
      virtual std::unique_ptr<Message> Clone() const = 0;
 
 
      virtual void Assign(Message &&src) = 0;
 
 
      virtual void Merge(Message &&src) = 0;
   };
 
   virtual ~EffectSettingsAccess();
   virtual const EffectSettings &Get() = 0;
   virtual void Set(EffectSettings &&settings,
      std::unique_ptr<Message> pMessage = nullptr) = 0;
   virtual void Set(std::unique_ptr<Message> pMessage = nullptr) = 0;
 
 
   virtual void Flush() = 0;
 
   virtual bool IsSameAs(const EffectSettingsAccess &other) const = 0;
 
 
   template<typename Function>
   void ModifySettings(Function &&function) {
      auto settings = this->Get();
      auto result = std::forward<Function>(function)(settings);
      this->Set(std::move(settings), std::move(result));
   }
};
 
class COMPONENTS_API SimpleEffectSettingsAccess final
   : public EffectSettingsAccess {
public:
   explicit SimpleEffectSettingsAccess(EffectSettings &settings)
      : mSettings{settings} {}
   ~SimpleEffectSettingsAccess() override;
   const EffectSettings &Get() override;
   void Set(EffectSettings &&settings,
      std::unique_ptr<Message> pMessage) override;
   void Set(std::unique_ptr<Message> pMessage) override;
   void Flush() override;
   bool IsSameAs(const EffectSettingsAccess &other) const override;
private:
   EffectSettings &mSettings;
};
 
/*************************************************************************************/
class COMPONENTS_API EffectDefinitionInterface  /* not final */
   : public ComponentInterface
{
public:
   static Identifier GetSquashedName(const Identifier &ident);
 
   virtual ~EffectDefinitionInterface();
 
   virtual EffectType GetType() const = 0;
 
   virtual EffectType GetClassification() const;
 
   virtual EffectFamilySymbol GetFamily() const = 0;
 
   virtual bool IsInteractive() const = 0;
 
   virtual bool IsDefault() const = 0;
 
   enum class RealtimeSince : unsigned {
      Never,
      // For built-in effects that became realtime in 3.2.x or a later version
      // but were non-realtime in an earlier version; must also increase
      // REGVERCUR in any release with such a change
      After_3_1,
      Always,
   };
 
   virtual RealtimeSince RealtimeSupport() const = 0;
 
   bool SupportsRealtime() const
   { return RealtimeSupport() != RealtimeSince::Never; }
 
   virtual bool SupportsAutomation() const = 0;
 
   virtual bool EnablesDebug() const;
 
   virtual ManualPageID ManualPage() const;
 
   virtual FilePath HelpPage() const;
 
   virtual bool IsHiddenFromMenus() const;
};
 
using OptionalMessage =
   std::optional<std::unique_ptr<EffectSettingsAccess::Message>>;
 
/*************************************************************************************/
class COMPONENTS_API EffectSettingsManager  /* not final */
   : public EffectDefinitionInterface
{
public:
   virtual ~EffectSettingsManager();
 
 
   virtual EffectSettings MakeSettings() const;
 
 
   virtual bool CopySettingsContents(
      const EffectSettings &src, EffectSettings &dst) const;
 
 
   virtual bool SaveSettings(
      const EffectSettings &settings, CommandParameters & parms) const = 0;
 
 
   virtual bool LoadSettings(
      const CommandParameters & parms, EffectSettings &settings) const = 0;
 
   virtual RegistryPaths GetFactoryPresets() const = 0;
 
   [[nodiscard]] virtual OptionalMessage LoadUserPreset(
      const RegistryPath & name, EffectSettings &settings) const = 0;
   virtual bool SaveUserPreset(
      const RegistryPath & name, const EffectSettings &settings) const = 0;
 
   [[nodiscard]] virtual OptionalMessage LoadFactoryPreset(
      int id, EffectSettings &settings) const = 0;
   [[nodiscard]] virtual OptionalMessage LoadFactoryDefaults(
      EffectSettings &settings) const = 0;
 
   virtual bool VisitSettings(
      SettingsVisitor &visitor, EffectSettings &settings); // TODO const
 
   virtual bool VisitSettings(
      ConstSettingsVisitor &visitor, const EffectSettings &settings) const;
 
 
   virtual std::unique_ptr<EffectOutputs> MakeOutputs() const;
};
 
// ----------------------------------------------------------------------------
// Supported channel assignments
// ----------------------------------------------------------------------------
 
enum ChannelName : int {
   // Use to mark end of list
   ChannelNameEOL = -1,
   // The default channel assignment
   ChannelNameMono,
   // From this point, the channels follow the 22.2 surround sound format
   ChannelNameFrontLeft,
   ChannelNameFrontRight,
   ChannelNameFrontCenter,
   ChannelNameLowFrequency1,
   ChannelNameBackLeft,
   ChannelNameBackRight,
   ChannelNameFrontLeftCenter,
   ChannelNameFrontRightCenter,
   ChannelNameBackCenter,
   ChannelNameLowFrequency2,
   ChannelNameSideLeft,
   ChannelNameSideRight,
   ChannelNameTopFrontLeft,
   ChannelNameTopFrontRight,
   ChannelNameTopFrontCenter,
   ChannelNameTopCenter,
   ChannelNameTopBackLeft,
   ChannelNameTopBackRight,
   ChannelNameTopSideLeft,
   ChannelNameTopSideRight,
   ChannelNameTopBackCenter,
   ChannelNameBottomFrontCenter,
   ChannelNameBottomFrontLeft,
   ChannelNameBottomFrontRight,
};
using ChannelNames = const ChannelName *;
 
/***************************************************************************/
class COMPONENTS_API EffectInstance
   : public std::enable_shared_from_this<EffectInstance>
{
public:
   virtual ~EffectInstance();
 
   virtual size_t GetBlockSize() const = 0;
 
   // Suggest a block size, but the return is the size that was really set:
   virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
 
 
   virtual unsigned GetAudioInCount() const = 0;
 
 
   virtual unsigned GetAudioOutCount() const = 0;
 
   virtual bool RealtimeInitialize(EffectSettings &settings, double sampleRate);
 
   virtual bool RealtimeAddProcessor(
      EffectSettings &settings, EffectOutputs *pOutputs,
      unsigned numChannels, float sampleRate);
 
   virtual bool RealtimeSuspend();
 
   virtual bool RealtimeResume();
 
   using Message = EffectSettingsAccess::Message;
 
 
   virtual std::unique_ptr<Message> MakeMessage() const;
 
   // TODO make it just an alias for Message *
   struct MessagePackage { EffectSettings &settings; Message *pMessage{}; };
 
 
   virtual bool UsesMessages() const noexcept;
 
 
   virtual bool RealtimeProcessStart(MessagePackage &package);
 
   virtual size_t RealtimeProcess(size_t group, EffectSettings &settings,
      const float *const *inBuf, float *const *outBuf, size_t numSamples);
 
   virtual void RealtimePassThrough(
      size_t group, EffectSettings& settings, const float* const* inBuf,
      size_t numSamples);
 
 
   virtual bool RealtimeProcessEnd(EffectSettings &settings) noexcept;
 
   virtual bool RealtimeFinalize(EffectSettings &settings) noexcept;
 
   virtual size_t GetTailSize() const;
 
   using SampleCount = uint64_t;
 
   virtual SampleCount GetLatency(
      const EffectSettings &settings, double sampleRate) const;
 
   virtual bool NeedsDither() const;
 
 
   virtual bool ProcessInitialize(EffectSettings &settings,
      double sampleRate, ChannelNames chanMap) = 0;
 
   virtual bool ProcessFinalize() noexcept = 0;
 
   virtual size_t ProcessBlock(EffectSettings &settings,
      const float *const *inBlock, float *const *outBlock, size_t blockLen)
   = 0;
};
 
class COMPONENTS_API EffectInstanceWithBlockSize
   : public virtual EffectInstance
{
public:
   ~EffectInstanceWithBlockSize() override;
   size_t GetBlockSize() const override;
   size_t SetBlockSize(size_t maxBlockSize) override;
protected:
   size_t mBlockSize{ 0 };
};
 
/***************************************************************************/
class COMPONENTS_API EffectInstanceFactory
   : public EffectSettingsManager
{
public:
   virtual ~EffectInstanceFactory();
 
 
   virtual std::shared_ptr<EffectInstance> MakeInstance() const = 0;
 
};
 
COMPONENTS_API const RegistryPath &CurrentSettingsGroup();
 
COMPONENTS_API const RegistryPath &FactoryDefaultsGroup();
 
COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath & name);
 
#endif // __AUDACITY_EFFECTINTERFACE_H__