Audacity  3.0.3
EffectInterface.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  EffectInterface.h
6 
7  Leland Lucius
8 
9  Copyright (c) 2014, Audacity Team
10  All rights reserved.
11 
12  Redistribution and use in source and binary forms, with or without
13  modification, are permitted provided that the following conditions
14  are met:
15 
16  1. Redistributions of source code must retain the above copyright
17  notice, this list of conditions and the following disclaimer.
18 
19  2. Redistributions in binary form must reproduce the above copyright
20  notice, this list of conditions and the following disclaimer in the
21  documentation and/or other materials provided with the distribution.
22 
23  3. Neither the name of the copyright holder nor the names of its
24  contributors may be used to endorse or promote products derived from
25  this software without specific prior written permission.
26 
27  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
30  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
31  COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
32  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
33  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
34  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
35  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
36  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38  POSSIBILITY OF SUCH DAMAGE.
39 
40 **********************************************************************/
41 
42 #ifndef __AUDACITY_EFFECTINTERFACE_H__
43 #define __AUDACITY_EFFECTINTERFACE_H__
44 
45 #include <functional>
46 
47 #include "audacity/Types.h"
50 #include "audacity/EffectAutomationParameters.h" // for command automation
51 
52 class ShuttleGui;
53 
54 typedef enum EffectType : int
55 {
63 
64 
65 /*************************************************************************************/
73 class AUDACITY_DLL_API EffectDefinitionInterface /* not final */ : public ComponentInterface
74 {
75 public:
77 
78  // Type determines how it behaves.
79  virtual EffectType GetType() = 0;
80  // Classification determines which menu it appears in.
81  virtual EffectType GetClassification() { return GetType();};
82 
84 
85  // These should move to the "EffectClientInterface" class once all
86  // effects have been converted.
87  virtual bool IsInteractive() = 0;
88 
89  // I don't really like this, but couldn't think of a better way to force the
90  // effect to appear "above the line" in the menus.
91  virtual bool IsDefault() = 0;
92 
93  // This will go away when all Effects have been updated to the new
94  // interface.
95  virtual bool IsLegacy() = 0;
96 
97  // Whether the effect supports realtime previewing (while audio is playing).
98  virtual bool SupportsRealtime() = 0;
99 
100  // Can the effect be used without the UI.
101  virtual bool SupportsAutomation() = 0;
102 };
103 
104 class wxDialog;
105 class wxWindow;
108 
109 /*************************************************************************************/
118 class AUDACITY_DLL_API EffectHostInterface /* not final */ : public ConfigClientInterface
119 {
120 public:
121  virtual ~EffectHostInterface() {};
122 
123  virtual double GetDefaultDuration() = 0;
124  virtual double GetDuration() = 0;
126  virtual void SetDuration(double seconds) = 0;
127 
128  // Preset handling
132 };
133 
134 /*************************************************************************************/
143 class AUDACITY_DLL_API EffectClientInterface /* not final */ : public EffectDefinitionInterface
144 {
145 public:
146  using EffectDialogFactory = std::function<
147  wxDialog* ( wxWindow &parent,
149  >;
150 
152 
153  virtual bool SetHost(EffectHostInterface *host) = 0;
154 
155  virtual unsigned GetAudioInCount() = 0;
156  virtual unsigned GetAudioOutCount() = 0;
157 
158  virtual int GetMidiInCount() = 0;
159  virtual int GetMidiOutCount() = 0;
160 
161  virtual void SetSampleRate(double rate) = 0;
162  // Suggest a block size, but the return is the size that was really set:
163  virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
164  virtual size_t GetBlockSize() const = 0;
165 
166  virtual sampleCount GetLatency() = 0;
167  virtual size_t GetTailSize() = 0;
168 
169  virtual bool IsReady() = 0;
170  virtual bool ProcessInitialize(sampleCount totalLen, ChannelNames chanMap = NULL) = 0;
171  // This may be called during stack unwinding:
172  virtual bool ProcessFinalize() /* noexcept */ = 0;
173  virtual size_t ProcessBlock(float **inBlock, float **outBlock, size_t blockLen) = 0;
174 
175  virtual bool RealtimeInitialize() = 0;
176  virtual bool RealtimeAddProcessor(unsigned numChannels, float sampleRate) = 0;
177  virtual bool RealtimeFinalize() = 0;
178  virtual bool RealtimeSuspend() = 0;
179  virtual bool RealtimeResume() = 0;
180  virtual bool RealtimeProcessStart() = 0;
181  virtual size_t RealtimeProcess(int group, float **inBuf, float **outBuf, size_t numSamples) = 0;
182  virtual bool RealtimeProcessEnd() = 0;
183 
184  virtual bool ShowInterface(
185  wxWindow &parent, const EffectDialogFactory &factory,
186  bool forceModal = false
187  ) = 0;
188  // Some effects will use define params to define what parameters they take.
189  // If they do, they won't need to implement Get or SetAutomation parameters.
190  // since the Effect class can do it. Or at least that is how things happen
191  // in AudacityCommand. IF we do the same in class Effect, then Effect maybe
192  // should derive by some route from AudacityCommand to pick up that
193  // functionality.
194  //virtual bool DefineParams( ShuttleParams & S){ return false;};
195  virtual bool GetAutomationParameters(CommandParameters & parms) = 0;
196  virtual bool SetAutomationParameters(CommandParameters & parms) = 0;
197 
198  virtual bool LoadUserPreset(const RegistryPath & name) = 0;
199  virtual bool SaveUserPreset(const RegistryPath & name) = 0;
200 
202  virtual bool LoadFactoryPreset(int id) = 0;
203  virtual bool LoadFactoryDefaults() = 0;
204 };
205 
206 /*************************************************************************************/
215 class AUDACITY_DLL_API EffectUIHostInterface
216 {
217 public:
219 };
220 
221 /*************************************************************************************/
229 class AUDACITY_DLL_API EffectUIClientInterface /* not final */
230 {
231 public:
233 
234  virtual void SetHostUI(EffectUIHostInterface *host) = 0;
235  virtual bool IsGraphicalUI() = 0;
236  virtual bool PopulateUI(ShuttleGui &S) = 0;
237  virtual bool ValidateUI() = 0;
238  virtual bool HideUI() = 0;
239  virtual bool CloseUI() = 0;
240 
241  virtual bool CanExportPresets() = 0;
242  virtual void ExportPresets() = 0;
243  virtual void ImportPresets() = 0;
244 
245  virtual bool HasOptions() = 0;
246  virtual void ShowOptions() = 0;
247 };
248 
249 
250 /*************************************************************************************/
258 class AUDACITY_DLL_API EffectManagerInterface
259 {
260 public:
262 
263  virtual void FindFilesInPathList(const wxString & pattern,
264  const FilePaths & pathList,
265  FilePaths & files,
266  int searchFlags) = 0;
267 };
268 
269 #endif // __AUDACITY_EFFECTINTERFACE_H__
EffectUIClientInterface
EffectUIClientInterface is an abstract base class to populate a UI and validate UI values....
Definition: EffectInterface.h:230
RegistryPaths
std::vector< RegistryPath > RegistryPaths
Definition: Types.h:262
EffectUIClientInterface::HideUI
virtual bool HideUI()=0
EffectClientInterface::~EffectClientInterface
virtual ~EffectClientInterface()
Definition: EffectInterface.h:151
CommandParameters
CommandParameters, derived from wxFileConfig, is essentially doing the same things as the Shuttle cla...
Definition: EffectAutomationParameters.h:67
EffectClientInterface::SetBlockSize
virtual size_t SetBlockSize(size_t maxBlockSize)=0
EffectTypeProcess
@ EffectTypeProcess
Definition: EffectInterface.h:59
EffectClientInterface::RealtimeAddProcessor
virtual bool RealtimeAddProcessor(unsigned numChannels, float sampleRate)=0
EffectClientInterface::RealtimeInitialize
virtual bool RealtimeInitialize()=0
EffectHostInterface
EffectHostInterface is a decorator of a EffectUIClientInterface. It adds virtual (abstract) functions...
Definition: EffectInterface.h:119
EffectClientInterface::SetSampleRate
virtual void SetSampleRate(double rate)=0
EffectTypeGenerate
@ EffectTypeGenerate
Definition: EffectInterface.h:58
EffectClientInterface::RealtimeFinalize
virtual bool RealtimeFinalize()=0
EffectUIClientInterface::ImportPresets
virtual void ImportPresets()=0
EffectClientInterface::ProcessFinalize
virtual bool ProcessFinalize()=0
EffectClientInterface::RealtimeProcessEnd
virtual bool RealtimeProcessEnd()=0
EffectTypeNone
@ EffectTypeNone
Definition: EffectInterface.h:56
EffectDefinitionInterface::IsInteractive
virtual bool IsInteractive()=0
EffectManagerInterface::~EffectManagerInterface
virtual ~EffectManagerInterface()
Definition: EffectInterface.h:261
EffectHostInterface::~EffectHostInterface
virtual ~EffectHostInterface()
Definition: EffectInterface.h:121
EffectHostInterface::GetCurrentSettingsGroup
virtual RegistryPath GetCurrentSettingsGroup()=0
EffectClientInterface::ProcessBlock
virtual size_t ProcessBlock(float **inBlock, float **outBlock, size_t blockLen)=0
EffectDefinitionInterface::SupportsRealtime
virtual bool SupportsRealtime()=0
EffectClientInterface::ShowInterface
virtual bool ShowInterface(wxWindow &parent, const EffectDialogFactory &factory, bool forceModal=false)=0
EffectClientInterface::GetFactoryPresets
virtual RegistryPaths GetFactoryPresets()=0
EffectDefinitionInterface::SupportsAutomation
virtual bool SupportsAutomation()=0
wxArrayStringEx
Definition: MemoryX.h:663
EffectManagerInterface::FindFilesInPathList
virtual void FindFilesInPathList(const wxString &pattern, const FilePaths &pathList, FilePaths &files, int searchFlags)=0
ComponentInterfaceSymbol
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
Definition: ComponentInterface.h:60
ConfigClientInterface
ConfigClientInterface is an unholy get/set configuration class, which differentiates between private ...
Definition: ConfigInterface.h:57
EffectManagerInterface
UNUSED. EffectManagerInterface provides a single function to find files matching a pattern in a list.
Definition: EffectInterface.h:259
EffectHostInterface::GetDefaultDuration
virtual double GetDefaultDuration()=0
EffectClientInterface::RealtimeSuspend
virtual bool RealtimeSuspend()=0
EffectClientInterface::GetAudioOutCount
virtual unsigned GetAudioOutCount()=0
EffectClientInterface::GetMidiOutCount
virtual int GetMidiOutCount()=0
EffectUIClientInterface::ShowOptions
virtual void ShowOptions()=0
ComponentInterface.h
EffectHostInterface::GetDuration
virtual double GetDuration()=0
EffectClientInterface::SetAutomationParameters
virtual bool SetAutomationParameters(CommandParameters &parms)=0
factory
static RegisteredToolbarFactory factory
Definition: ControlToolBar.cpp:804
EffectAutomationParameters.h
EffectClientInterface::LoadFactoryDefaults
virtual bool LoadFactoryDefaults()=0
EffectClientInterface::GetMidiInCount
virtual int GetMidiInCount()=0
EffectClientInterface::LoadFactoryPreset
virtual bool LoadFactoryPreset(int id)=0
EffectClientInterface::SetHost
virtual bool SetHost(EffectHostInterface *host)=0
ChannelNames
enum ChannelName * ChannelNames
EffectClientInterface::GetTailSize
virtual size_t GetTailSize()=0
name
const TranslatableString name
Definition: Distortion.cpp:98
EffectTypeTool
@ EffectTypeTool
Definition: EffectInterface.h:61
EffectDefinitionInterface::~EffectDefinitionInterface
virtual ~EffectDefinitionInterface()
Definition: EffectInterface.h:76
EffectDefinitionInterface::GetType
virtual EffectType GetType()=0
EffectClientInterface::EffectDialogFactory
std::function< wxDialog *(wxWindow &parent, EffectHostInterface *, EffectUIClientInterface *) > EffectDialogFactory
Definition: EffectInterface.h:149
EffectClientInterface::ProcessInitialize
virtual bool ProcessInitialize(sampleCount totalLen, ChannelNames chanMap=NULL)=0
EffectHostInterface::GetDurationFormat
virtual NumericFormatSymbol GetDurationFormat()=0
EffectTypeHidden
@ EffectTypeHidden
Definition: EffectInterface.h:57
EffectUIClientInterface::SetHostUI
virtual void SetHostUI(EffectUIHostInterface *host)=0
EffectUIHostInterface
EffectUIHostInterface has nothing in it. It is provided so that an Effect can call SetHostUI passing ...
Definition: EffectInterface.h:216
EffectDefinitionInterface::GetClassification
virtual EffectType GetClassification()
Definition: EffectInterface.h:81
Types.h
EffectClientInterface::GetLatency
virtual sampleCount GetLatency()=0
ConfigInterface.h
EffectClientInterface
EffectClientInterface provides the ident interface to Effect, and is what makes Effect into a plug-in...
Definition: EffectInterface.h:144
EffectClientInterface::LoadUserPreset
virtual bool LoadUserPreset(const RegistryPath &name)=0
EffectHostInterface::GetUserPresetsGroup
virtual RegistryPath GetUserPresetsGroup(const RegistryPath &name)=0
EffectDefinitionInterface
EffectDefinitionInterface is a ComponentInterface that additionally tracks flag-functions for interac...
Definition: EffectInterface.h:74
EffectUIClientInterface::~EffectUIClientInterface
virtual ~EffectUIClientInterface()
Definition: EffectInterface.h:232
EffectUIClientInterface::PopulateUI
virtual bool PopulateUI(ShuttleGui &S)=0
EffectClientInterface::IsReady
virtual bool IsReady()=0
sampleCount
Definition: Types.h:589
EffectUIHostInterface::~EffectUIHostInterface
virtual ~EffectUIHostInterface()
Definition: EffectInterface.h:218
EffectTypeAnalyze
@ EffectTypeAnalyze
Definition: EffectInterface.h:60
EffectUIClientInterface::CloseUI
virtual bool CloseUI()=0
EffectClientInterface::GetAudioInCount
virtual unsigned GetAudioInCount()=0
EffectClientInterface::GetBlockSize
virtual size_t GetBlockSize() const =0
EffectDefinitionInterface::IsLegacy
virtual bool IsLegacy()=0
ComponentInterface
ComponentInterface provides name / vendor / version functions to identify plugins....
Definition: ComponentInterface.h:121
EffectClientInterface::RealtimeProcess
virtual size_t RealtimeProcess(int group, float **inBuf, float **outBuf, size_t numSamples)=0
EffectUIClientInterface::CanExportPresets
virtual bool CanExportPresets()=0
RegistryPath
wxString RegistryPath
Definition: Types.h:261
EffectClientInterface::GetAutomationParameters
virtual bool GetAutomationParameters(CommandParameters &parms)=0
EffectClientInterface::RealtimeResume
virtual bool RealtimeResume()=0
EffectUIClientInterface::IsGraphicalUI
virtual bool IsGraphicalUI()=0
EffectClientInterface::RealtimeProcessStart
virtual bool RealtimeProcessStart()=0
EffectType
EffectType
Definition: EffectInterface.h:55
EffectUIClientInterface::ExportPresets
virtual void ExportPresets()=0
EffectUIClientInterface::HasOptions
virtual bool HasOptions()=0
EffectDefinitionInterface::GetFamily
virtual EffectFamilySymbol GetFamily()=0
EffectClientInterface::SaveUserPreset
virtual bool SaveUserPreset(const RegistryPath &name)=0
EffectUIClientInterface::ValidateUI
virtual bool ValidateUI()=0
EffectDefinitionInterface::IsDefault
virtual bool IsDefault()=0
EffectHostInterface::SetDuration
virtual void SetDuration(double seconds)=0
ShuttleGui
Derived from ShuttleGuiBase, an Audacity specific class for shuttling data to and from GUI.
Definition: ShuttleGui.h:638
EffectHostInterface::GetFactoryDefaultsGroup
virtual RegistryPath GetFactoryDefaultsGroup()=0