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 "ComponentInterface.h"
49 #include "ConfigInterface.h"
50 #include "EffectAutomationParameters.h" // for command automation
51 
52 class ShuttleGui;
53 
54 typedef enum EffectType : int
55 {
63 
64 
66 
67 /*************************************************************************************/
75 class COMPONENTS_API EffectDefinitionInterface /* not final */ : public ComponentInterface
76 {
77 public:
79 
80  // Type determines how it behaves.
81  virtual EffectType GetType() = 0;
82  // Classification determines which menu it appears in.
83  virtual EffectType GetClassification() { return GetType();}
84 
86 
87  // These should move to the "EffectClientInterface" class once all
88  // effects have been converted.
89  virtual bool IsInteractive() = 0;
90 
91  // I don't really like this, but couldn't think of a better way to force the
92  // effect to appear "above the line" in the menus.
93  virtual bool IsDefault() = 0;
94 
95  // This will go away when all Effects have been updated to the new
96  // interface.
97  virtual bool IsLegacy() = 0;
98 
99  // Whether the effect supports realtime previewing (while audio is playing).
100  virtual bool SupportsRealtime() = 0;
101 
102  // Can the effect be used without the UI.
103  virtual bool SupportsAutomation() = 0;
104 };
105 
106 class wxDialog;
107 class wxWindow;
110 
111 /*************************************************************************************/
120 class COMPONENTS_API EffectHostInterface /* not final */ : public ConfigClientInterface
121 {
122 public:
124 
125  virtual double GetDefaultDuration() = 0;
126  virtual double GetDuration() = 0;
128  virtual void SetDuration(double seconds) = 0;
129 
130  // Preset handling
134 };
135 
136 class sampleCount;
137 
138 // ----------------------------------------------------------------------------
139 // Supported channel assignments
140 // ----------------------------------------------------------------------------
141 
142 typedef enum
143 {
144  // Use to mark end of list
146  // The default channel assignment
148  // From this point, the channels follow the 22.2 surround sound format
174 
175 /*************************************************************************************/
184 class COMPONENTS_API EffectClientInterface /* not final */ : public EffectDefinitionInterface
185 {
186 public:
187  using EffectDialogFactory = std::function<
188  wxDialog* ( wxWindow &parent,
190  >;
191 
193 
194  virtual bool SetHost(EffectHostInterface *host) = 0;
195 
196  virtual unsigned GetAudioInCount() = 0;
197  virtual unsigned GetAudioOutCount() = 0;
198 
199  virtual int GetMidiInCount() = 0;
200  virtual int GetMidiOutCount() = 0;
201 
202  virtual void SetSampleRate(double rate) = 0;
203  // Suggest a block size, but the return is the size that was really set:
204  virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
205  virtual size_t GetBlockSize() const = 0;
206 
207  virtual sampleCount GetLatency() = 0;
208  virtual size_t GetTailSize() = 0;
209 
210  virtual bool IsReady() = 0;
211  virtual bool ProcessInitialize(sampleCount totalLen, ChannelNames chanMap = NULL) = 0;
212  // This may be called during stack unwinding:
213  virtual bool ProcessFinalize() /* noexcept */ = 0;
214  virtual size_t ProcessBlock(float **inBlock, float **outBlock, size_t blockLen) = 0;
215 
216  virtual bool RealtimeInitialize() = 0;
217  virtual bool RealtimeAddProcessor(unsigned numChannels, float sampleRate) = 0;
218  virtual bool RealtimeFinalize() = 0;
219  virtual bool RealtimeSuspend() = 0;
220  virtual bool RealtimeResume() = 0;
221  virtual bool RealtimeProcessStart() = 0;
222  virtual size_t RealtimeProcess(int group, float **inBuf, float **outBuf, size_t numSamples) = 0;
223  virtual bool RealtimeProcessEnd() = 0;
224 
225  virtual bool ShowInterface(
226  wxWindow &parent, const EffectDialogFactory &factory,
227  bool forceModal = false
228  ) = 0;
229  // Some effects will use define params to define what parameters they take.
230  // If they do, they won't need to implement Get or SetAutomation parameters.
231  // since the Effect class can do it. Or at least that is how things happen
232  // in AudacityCommand. IF we do the same in class Effect, then Effect maybe
233  // should derive by some route from AudacityCommand to pick up that
234  // functionality.
235  //virtual bool DefineParams( ShuttleParams & S){ return false;};
236  virtual bool GetAutomationParameters(CommandParameters & parms) = 0;
237  virtual bool SetAutomationParameters(CommandParameters & parms) = 0;
238 
239  virtual bool LoadUserPreset(const RegistryPath & name) = 0;
240  virtual bool SaveUserPreset(const RegistryPath & name) = 0;
241 
243  virtual bool LoadFactoryPreset(int id) = 0;
244  virtual bool LoadFactoryDefaults() = 0;
245 };
246 
247 /*************************************************************************************/
256 class COMPONENTS_API EffectUIHostInterface
257 {
258 public:
260 };
261 
262 /*************************************************************************************/
270 class COMPONENTS_API EffectUIClientInterface /* not final */
271 {
272 public:
274 
275  virtual void SetHostUI(EffectUIHostInterface *host) = 0;
276  virtual bool IsGraphicalUI() = 0;
277  virtual bool PopulateUI(ShuttleGui &S) = 0;
278  virtual bool ValidateUI() = 0;
279  virtual bool HideUI() = 0;
280  virtual bool CloseUI() = 0;
281 
282  virtual bool CanExportPresets() = 0;
283  virtual void ExportPresets() = 0;
284  virtual void ImportPresets() = 0;
285 
286  virtual bool HasOptions() = 0;
287  virtual void ShowOptions() = 0;
288 };
289 
290 #endif // __AUDACITY_EFFECTINTERFACE_H__
EffectUIClientInterface
EffectUIClientInterface is an abstract base class to populate a UI and validate UI values....
Definition: EffectInterface.h:271
ChannelNameBackRight
@ ChannelNameBackRight
Definition: EffectInterface.h:154
EffectUIClientInterface::HideUI
virtual bool HideUI()=0
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:121
ChannelNameBottomFrontCenter
@ ChannelNameBottomFrontCenter
Definition: EffectInterface.h:170
ChannelNameTopFrontRight
@ ChannelNameTopFrontRight
Definition: EffectInterface.h:162
EffectClientInterface::SetSampleRate
virtual void SetSampleRate(double rate)=0
ChannelNameTopBackLeft
@ ChannelNameTopBackLeft
Definition: EffectInterface.h:165
ChannelNameFrontRight
@ ChannelNameFrontRight
Definition: EffectInterface.h:150
EffectTypeGenerate
@ EffectTypeGenerate
Definition: EffectInterface.h:58
EffectClientInterface::RealtimeFinalize
virtual bool RealtimeFinalize()=0
RegistryPaths
std::vector< RegistryPath > RegistryPaths
Definition: Identifier.h:219
EffectUIClientInterface::ImportPresets
virtual void ImportPresets()=0
EffectClientInterface::ProcessFinalize
virtual bool ProcessFinalize()=0
EffectClientInterface::RealtimeProcessEnd
virtual bool RealtimeProcessEnd()=0
EffectTypeNone
@ EffectTypeNone
Definition: EffectInterface.h:56
ChannelNameTopBackCenter
@ ChannelNameTopBackCenter
Definition: EffectInterface.h:169
EffectDefinitionInterface::IsInteractive
virtual bool IsInteractive()=0
EffectHostInterface::~EffectHostInterface
virtual ~EffectHostInterface()
EffectHostInterface::GetCurrentSettingsGroup
virtual RegistryPath GetCurrentSettingsGroup()=0
ComponentInterfaceSymbol.h
ChannelNameFrontLeft
@ ChannelNameFrontLeft
Definition: EffectInterface.h:149
EffectClientInterface::ProcessBlock
virtual size_t ProcessBlock(float **inBlock, float **outBlock, size_t blockLen)=0
ChannelName
ChannelName
Definition: EffectInterface.h:143
ChannelNameEOL
@ ChannelNameEOL
Definition: EffectInterface.h:145
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
ComponentInterfaceSymbol
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
Definition: ComponentInterfaceSymbol.h:27
ChannelNameLowFrequency1
@ ChannelNameLowFrequency1
Definition: EffectInterface.h:152
EffectUIClientInterface::~EffectUIClientInterface
virtual ~EffectUIClientInterface()
ConfigClientInterface
ConfigClientInterface is an unholy get/set configuration class, which differentiates between private ...
Definition: ConfigInterface.h:58
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:817
EffectAutomationParameters.h
EffectClientInterface::LoadFactoryDefaults
virtual bool LoadFactoryDefaults()=0
ChannelNameTopFrontLeft
@ ChannelNameTopFrontLeft
Definition: EffectInterface.h:161
EffectClientInterface::GetMidiInCount
virtual int GetMidiInCount()=0
EffectClientInterface::LoadFactoryPreset
virtual bool LoadFactoryPreset(int id)=0
ChannelNameLowFrequency2
@ ChannelNameLowFrequency2
Definition: EffectInterface.h:158
EffectClientInterface::SetHost
virtual bool SetHost(EffectHostInterface *host)=0
ChannelNameTopFrontCenter
@ ChannelNameTopFrontCenter
Definition: EffectInterface.h:163
EffectClientInterface::GetTailSize
virtual size_t GetTailSize()=0
ChannelNameBottomFrontLeft
@ ChannelNameBottomFrontLeft
Definition: EffectInterface.h:171
ChannelNameBackLeft
@ ChannelNameBackLeft
Definition: EffectInterface.h:153
name
const TranslatableString name
Definition: Distortion.cpp:98
ChannelNameTopSideLeft
@ ChannelNameTopSideLeft
Definition: EffectInterface.h:167
EffectTypeTool
@ EffectTypeTool
Definition: EffectInterface.h:61
EffectUIHostInterface::~EffectUIHostInterface
virtual ~EffectUIHostInterface()
ChannelNameTopCenter
@ ChannelNameTopCenter
Definition: EffectInterface.h:164
EffectDefinitionInterface::~EffectDefinitionInterface
virtual ~EffectDefinitionInterface()
EffectDefinitionInterface::GetType
virtual EffectType GetType()=0
EffectClientInterface::EffectDialogFactory
std::function< wxDialog *(wxWindow &parent, EffectHostInterface *, EffectUIClientInterface *) > EffectDialogFactory
Definition: EffectInterface.h:190
EffectClientInterface::ProcessInitialize
virtual bool ProcessInitialize(sampleCount totalLen, ChannelNames chanMap=NULL)=0
EffectHostInterface::GetDurationFormat
virtual NumericFormatSymbol GetDurationFormat()=0
EffectTypeHidden
@ EffectTypeHidden
Definition: EffectInterface.h:57
ChannelNames
enum ChannelName * ChannelNames
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:257
ChannelNameTopSideRight
@ ChannelNameTopSideRight
Definition: EffectInterface.h:168
RegistryPath
wxString RegistryPath
Definition: Identifier.h:218
EffectDefinitionInterface::GetClassification
virtual EffectType GetClassification()
Definition: EffectInterface.h:83
ChannelNameTopBackRight
@ ChannelNameTopBackRight
Definition: EffectInterface.h:166
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:185
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:76
ChannelNameBackCenter
@ ChannelNameBackCenter
Definition: EffectInterface.h:157
EffectUIClientInterface::PopulateUI
virtual bool PopulateUI(ShuttleGui &S)=0
EffectClientInterface::IsReady
virtual bool IsReady()=0
ChannelNameBottomFrontRight
@ ChannelNameBottomFrontRight
Definition: EffectInterface.h:172
sampleCount
Positions or offsets within audio files need a wide type.
Definition: SampleCount.h:18
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
ChannelNameSideRight
@ ChannelNameSideRight
Definition: EffectInterface.h:160
EffectDefinitionInterface::IsLegacy
virtual bool IsLegacy()=0
ComponentInterface
ComponentInterface provides name / vendor / version functions to identify plugins....
Definition: ComponentInterface.h:62
ChannelNameFrontLeftCenter
@ ChannelNameFrontLeftCenter
Definition: EffectInterface.h:155
EffectClientInterface::RealtimeProcess
virtual size_t RealtimeProcess(int group, float **inBuf, float **outBuf, size_t numSamples)=0
ChannelNameFrontRightCenter
@ ChannelNameFrontRightCenter
Definition: EffectInterface.h:156
EffectUIClientInterface::CanExportPresets
virtual bool CanExportPresets()=0
EffectClientInterface::GetAutomationParameters
virtual bool GetAutomationParameters(CommandParameters &parms)=0
ChannelNameMono
@ ChannelNameMono
Definition: EffectInterface.h:147
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
ChannelNameFrontCenter
@ ChannelNameFrontCenter
Definition: EffectInterface.h:151
ChannelNameSideLeft
@ ChannelNameSideLeft
Definition: EffectInterface.h:159
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:631
EffectHostInterface::GetFactoryDefaultsGroup
virtual RegistryPath GetFactoryDefaultsGroup()=0
EffectClientInterface::~EffectClientInterface
virtual ~EffectClientInterface()