Audacity  2.3.1
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 "audacity/Types.h"
48 #include "audacity/EffectAutomationParameters.h" // for command automation
49 
50 #include <wx/dialog.h>
51 
52 typedef enum EffectType : int
53 {
60 } EffectType;
61 
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 
83  virtual ComponentInterfaceSymbol GetFamilyId() = 0;
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 
106 
107 /*************************************************************************************/
116 class AUDACITY_DLL_API EffectHostInterface /* not final */ : public ConfigClientInterface
117 {
118 public:
119  virtual ~EffectHostInterface() {};
120 
121  virtual double GetDefaultDuration() = 0;
122  virtual double GetDuration() = 0;
123  virtual NumericFormatId GetDurationFormat() = 0;
124  virtual void SetDuration(double seconds) = 0;
125 
126  virtual bool Apply() = 0;
127  virtual void Preview() = 0;
128 
129  //
130  virtual wxDialog *CreateUI(wxWindow *parent, EffectUIClientInterface *client) = 0;
131 
132  // Preset handling
133  virtual wxString GetUserPresetsGroup(const wxString & name) = 0;
134  virtual wxString GetCurrentSettingsGroup() = 0;
135  virtual wxString GetFactoryDefaultsGroup() = 0;
136 };
137 
138 /*************************************************************************************/
147 class AUDACITY_DLL_API EffectClientInterface /* not final */ : public EffectDefinitionInterface
148 {
149 public:
151 
152  virtual bool SetHost(EffectHostInterface *host) = 0;
153 
154  virtual unsigned GetAudioInCount() = 0;
155  virtual unsigned GetAudioOutCount() = 0;
156 
157  virtual int GetMidiInCount() = 0;
158  virtual int GetMidiOutCount() = 0;
159 
160  virtual void SetSampleRate(double rate) = 0;
161  virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
162 
163  virtual sampleCount GetLatency() = 0;
164  virtual size_t GetTailSize() = 0;
165 
166  virtual bool IsReady() = 0;
167  virtual bool ProcessInitialize(sampleCount totalLen, ChannelNames chanMap = NULL) = 0;
168  // This may be called during stack unwinding:
169  virtual bool ProcessFinalize() /* noexcept */ = 0;
170  virtual size_t ProcessBlock(float **inBlock, float **outBlock, size_t blockLen) = 0;
171 
172  virtual bool RealtimeInitialize() = 0;
173  virtual bool RealtimeAddProcessor(unsigned numChannels, float sampleRate) = 0;
174  virtual bool RealtimeFinalize() = 0;
175  virtual bool RealtimeSuspend() = 0;
176  virtual bool RealtimeResume() = 0;
177  virtual bool RealtimeProcessStart() = 0;
178  virtual size_t RealtimeProcess(int group, float **inBuf, float **outBuf, size_t numSamples) = 0;
179  virtual bool RealtimeProcessEnd() = 0;
180 
181  virtual bool ShowInterface(wxWindow *parent, bool forceModal = false) = 0;
182  // Some effects will use define params to define what parameters they take.
183  // If they do, they won't need to implement Get or SetAutomation parameters.
184  // since the Effect class can do it. Or at least that is how things happen
185  // in AudacityCommand. IF we do the same in class Effect, then Effect maybe
186  // should derive by some route from AudacityCommand to pick up that
187  // functionality.
188  //virtual bool DefineParams( ShuttleParams & S){ return false;};
189  virtual bool GetAutomationParameters(CommandParameters & parms) = 0;
190  virtual bool SetAutomationParameters(CommandParameters & parms) = 0;
191 
192  virtual bool LoadUserPreset(const wxString & name) = 0;
193  virtual bool SaveUserPreset(const wxString & name) = 0;
194 
195  virtual wxArrayString GetFactoryPresets() = 0;
196  virtual bool LoadFactoryPreset(int id) = 0;
197  virtual bool LoadFactoryDefaults() = 0;
198 };
199 
200 /*************************************************************************************/
209 class AUDACITY_DLL_API EffectUIHostInterface
210 {
211 public:
213 };
214 
215 /*************************************************************************************/
223 class AUDACITY_DLL_API EffectUIClientInterface /* not final */
224 {
225 public:
227 
228  virtual void SetHostUI(EffectUIHostInterface *host) = 0;
229  virtual bool IsGraphicalUI() = 0;
230  virtual bool PopulateUI(wxWindow *parent) = 0;
231  virtual bool ValidateUI() = 0;
232  virtual bool HideUI() = 0;
233  virtual bool CloseUI() = 0;
234 
235  virtual bool CanExportPresets() = 0;
236  virtual void ExportPresets() = 0;
237  virtual void ImportPresets() = 0;
238 
239  virtual bool HasOptions() = 0;
240  virtual void ShowOptions() = 0;
241 };
242 
243 
244 /*************************************************************************************/
252 class AUDACITY_DLL_API EffectManagerInterface
253 {
254 public:
256 
257  virtual void FindFilesInPathList(const wxString & pattern,
258  const wxArrayString & pathList,
259  wxArrayString & files,
260  int searchFlags) = 0;
261 };
262 
263 #endif // __AUDACITY_EFFECTINTERFACE_H__
UNUSED. EffectManagerInterface provides a single function to find files matching a pattern in a list...
EffectUIClientInterface is an abstract base class to populate a UI and validate UI values...
virtual ~EffectHostInterface()
ConfigClientInterface is an unholy get/set configuration class, which differentiates between private ...
EffectType
virtual ~EffectUIHostInterface()
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional...
virtual ~EffectClientInterface()
EffectDefinitionInterface is a ComponentInterface that additionally tracks flag-functions for interac...
CommandParameters, derived from wxFileConfig, is essentially doing the same things as the Shuttle cla...
virtual EffectType GetClassification()
enum ChannelName * ChannelNames
EffectHostInterface is a decorator of a EffectUIClientInterface. It adds virtual (abstract) functions...
const wxChar * name
Definition: Distortion.cpp:94
EffectClientInterface provides the ident interface to Effect, and is what makes Effect into a plug-in...
EffectUIHostInterface has nothing in it. It is provided so that an Effect can call SetHostUI passing ...
ComponentInterface provides name / vendor / version functions to identify plugins. It is what makes a class a plug-in. Additionally it provides an optional parameter definitions function, for those components such as commands, effects and (soon) preference pagess that define parameters.