Audacity 3.2.0
Effect.h
Go to the documentation of this file.
1/**********************************************************************
2
3 Audacity: A Digital Audio Editor
4
5 Effect.h
6
7 Dominic Mazzoni
8 Vaughan Johnson
9
10**********************************************************************/
11
12#ifndef __AUDACITY_EFFECT__
13#define __AUDACITY_EFFECT__
14
15#include "EffectBase.h"
16
17#include "SampleCount.h"
18#include "StatefulEffectBase.h"
19
20#define BUILTIN_EFFECT_PREFIX wxT("Built-in Effect: ")
21
23class LabelTrack;
24class WaveTrack;
25
26class AUDACITY_DLL_API Effect /* not final */
27 : public wxEvtHandler
28 , public EffectBase
29{
30 //
31 // public methods
32 //
33 // Used by the outside program to determine properties of an effect and
34 // apply the effect to one or more tracks.
35 //
36 public:
38 { return &e; }
39
40 // The constructor is called once by each subclass at the beginning of the program.
41 // Avoid allocating memory or doing time-consuming processing here.
42 Effect();
43 virtual ~Effect();
44
45 // ComponentInterface implementation
46
47 PluginPath GetPath() const override;
48 bool VisitSettings(
49 SettingsVisitor &visitor, EffectSettings &settings) override;
50 bool VisitSettings(
52 const override;
53
54 ComponentInterfaceSymbol GetSymbol() const override;
55
56 VendorSymbol GetVendor() const override;
57 wxString GetVersion() const override;
58 TranslatableString GetDescription() const override;
59
60 // EffectDefinitionInterface implementation
61
62 EffectType GetType() const override;
63 EffectFamilySymbol GetFamily() const override;
64 bool IsInteractive() const override;
65 bool IsDefault() const override;
66 RealtimeSince RealtimeSupport() const override;
67 bool SupportsAutomation() const override;
68
69 bool SaveSettings(
70 const EffectSettings &settings, CommandParameters & parms) const override;
71 bool LoadSettings(
72 const CommandParameters & parms, EffectSettings &settings) const override;
73
74 bool LoadUserPreset(
75 const RegistryPath & name, EffectSettings &settings) const override;
76 bool SaveUserPreset(
77 const RegistryPath & name, const EffectSettings &settings) const override;
78
79 RegistryPaths GetFactoryPresets() const override;
80 bool LoadFactoryPreset(int id, EffectSettings &settings) const override;
81 bool LoadFactoryDefaults(EffectSettings &settings) const override;
82
83 unsigned GetAudioInCount() const override;
84 unsigned GetAudioOutCount() const override;
85
86 // VisitSettings(), SaveSettings(), and LoadSettings()
87 // use the functions of EffectParameterMethods. By default, this function
88 // defines an empty list of parameters.
89 virtual const EffectParameterMethods &Parameters() const;
90
92 wxWindow &parent, wxDialog &dialog, bool forceModal = false) override;
93
94 // EffectUIClientInterface implementation
95
96 std::unique_ptr<EffectUIValidator> PopulateUI(
98 override;
99 bool IsGraphicalUI() override;
100 bool ValidateUI(EffectSettings &) override;
101 bool CloseUI() override;
102
103 bool CanExportPresets() override;
104 void ExportPresets(const EffectSettings &settings) const override;
105 void ImportPresets(EffectSettings &settings) override;
106
107 bool HasOptions() override;
108 void ShowOptions() override;
109
110 // EffectPlugin implementation
111
112 const EffectSettingsManager& GetDefinition() const override;
113 virtual NumericFormatSymbol GetSelectionFormat() /* not override? */; // time format in Selection toolbar
114
115 // EffectPlugin implementation
116
117 int ShowHostInterface( wxWindow &parent,
119 std::shared_ptr<EffectInstance> &pInstance, EffectSettingsAccess &access,
120 bool forceModal = false) override;
122 const EffectSettings &settings, wxString & parms) const override;
124 const wxString & parms, EffectSettings &settings) const override;
125 bool IsBatchProcessing() const override;
126 void SetBatchProcessing() override;
127 void UnsetBatchProcessing() override;
128 bool TransferDataToWindow(const EffectSettings &settings) override;
130
131 // Effect implementation
132
133 unsigned TestUIFlags(unsigned mask);
134
136 bool Delegate(Effect &delegate, EffectSettings &settings);
137
138 // Display a message box, using effect's (translated) name as the prefix
139 // for the title.
140 enum : long { DefaultMessageBoxStyle = wxOK | wxCENTRE };
141 int MessageBox(const TranslatableString& message,
142 long style = DefaultMessageBoxStyle,
143 const TranslatableString& titleStr = {}) const;
144
145 static void IncEffectCounter(){ nEffectsDone++;}
146
147 bool EnableApply(bool enable = true);
148
149 protected:
150
151 bool EnablePreview(bool enable = true);
152
154 bool CheckWhetherSkipEffect(const EffectSettings &settings) const override;
155
158 const EffectSettings &settings, double previewLength) const override;
159
161
165 virtual std::unique_ptr<EffectUIValidator> PopulateOrExchange(
166 ShuttleGui & S, EffectInstance &instance, EffectSettingsAccess &access);
167
168 // No more virtuals!
169
170 // The Progress methods all return true if the user has cancelled;
171 // you should exit immediately if this happens (cleaning up memory
172 // is okay, but don't try to undo).
173
174 // Pass a fraction between 0.0 and 1.0
175 bool TotalProgress(double frac, const TranslatableString & = {}) const;
176
177 // Pass a fraction between 0.0 and 1.0, for the current track
178 // (when doing one track at a time)
179 bool TrackProgress(
180 int whichTrack, double frac, const TranslatableString & = {}) const;
181
182 // Pass a fraction between 0.0 and 1.0, for the current track group
183 // (when doing stereo groups at a time)
184 bool TrackGroupProgress(
185 int whichGroup, double frac, const TranslatableString & = {}) const;
186
187 int GetNumWaveTracks() const { return mNumTracks; }
188 int GetNumWaveGroups() const { return mNumGroups; }
189
190 // Calculates the start time and length in samples for one or two channels
191 void GetBounds(
192 const WaveTrack &track, const WaveTrack *pRight,
193 sampleCount *start, sampleCount *len);
194
195 // Use this method to copy the input tracks to mOutputTracks, if
196 // doing the processing on them, and replacing the originals only on success (and not cancel).
197 // If not all sync-locked selected, then only selected wave tracks.
198 void CopyInputTracks(bool allSyncLockSelected = false);
199
200 // For the use of analyzers, which don't need to make output wave tracks,
201 // but may need to add label tracks.
202 class AUDACITY_DLL_API AddedAnalysisTrack {
203 friend Effect;
204 AddedAnalysisTrack(Effect *pEffect, const wxString &name);
206
207 public:
208
210
211 // So you can have a vector of them
213
214 LabelTrack *get() const { return mpTrack; }
215
216 // Call this to indicate successful completion of the analyzer.
217 void Commit();
218
219 // Destructor undoes the addition of the analysis track if not committed.
221
222 private:
223 Effect *mpEffect{};
224 LabelTrack *mpTrack{};
225 };
226
227 // Set name to given value if that is not empty, else use default name
228 std::shared_ptr<AddedAnalysisTrack> AddAnalysisTrack(const wxString &name = wxString());
229
230 // For the use of analyzers, which don't need to make output wave tracks,
231 // but may need to modify label tracks.
232 class AUDACITY_DLL_API ModifiedAnalysisTrack {
233 friend Effect;
235 (Effect *pEffect, const LabelTrack *pOrigTrack, const wxString &name);
237
238 public:
239
241
242 // So you can have a vector of them
244
245 LabelTrack *get() const { return mpTrack; }
246
247 // Call this to indicate successful completion of the analyzer.
248 void Commit();
249
250 // Destructor undoes the modification of the analysis track if not committed.
252
253 private:
254 Effect *mpEffect{};
255 LabelTrack *mpTrack{};
256 std::shared_ptr<Track> mpOrigTrack{};
257 };
258
259 // Set name to given value if that is not empty, else use default name
260 ModifiedAnalysisTrack ModifyAnalysisTrack
261 (const LabelTrack *pOrigTrack, const wxString &name = wxString());
262
263 // Use this to append a NEW output track.
264 Track *AddToOutputTracks(const std::shared_ptr<Track> &t);
265
266protected:
267 // UI
269 wxWeakRef<wxDialog> mHostUIDialog;
270 wxWindow *mUIParent{};
271
272public:
273 wxWindow* GetUIParent() { return mUIParent; }
274
275private:
276 wxString GetSavedStateGroup();
277
278 bool mIsBatch{ false };
279};
280
283template<typename Settings, typename Base>
284class EffectWithSettings : public Base {
285public:
287 {
288 return EffectSettings::Make<Settings>();
289 }
291 const EffectSettings &src, EffectSettings &dst) const override
292 {
293 return EffectSettings::Copy<Settings>(src, dst);
294 }
297 {
298 auto pSettings = settings.cast<Settings>();
299 assert(pSettings);
300 return *pSettings;
301 }
303 static inline const Settings &GetSettings(const EffectSettings &settings)
304 {
305 return GetSettings(const_cast<EffectSettings &>(settings));
306 }
307 static inline Settings *
309 return &GetSettings(s);
310 }
311};
312
316 : public StatefulEffectBase
317 , public Effect
318{
319public:
320 class AUDACITY_DLL_API Instance : public StatefulEffectBase::Instance {
321 public:
323 bool Process(EffectSettings &settings) override;
324 };
325 std::shared_ptr<EffectInstance> MakeInstance() const override;
326};
327
328// FIXME:
329// FIXME: Remove this once all effects are using the NEW dialog
330// FIXME:
331
332#define ID_EFFECT_PREVIEW ePreviewID
333
334#endif
static RegisteredToolbarFactory factory
const TranslatableString name
Definition: Distortion.cpp:82
EffectType
std::function< wxDialog *(wxWindow &parent, EffectPlugin &, EffectUIClientInterface &, std::shared_ptr< EffectInstance > &, EffectSettingsAccess &) > EffectDialogFactory
Type of function that creates a dialog for an effect.
Definition: EffectPlugin.h:39
wxString RegistryPath
Definition: Identifier.h:218
wxString PluginPath
type alias for identifying a Plugin supplied by a module, each module defining its own interpretation...
Definition: Identifier.h:214
std::vector< RegistryPath > RegistryPaths
Definition: Identifier.h:219
#define S(N)
Definition: ToChars.cpp:64
static Settings & settings()
Definition: TrackInfo.cpp:87
CommandParameters, derived from wxFileConfig, is essentially doing the same things as the SettingsVis...
virtual wxString GetVersion() const =0
virtual PluginPath GetPath() const =0
virtual VendorSymbol GetVendor() const =0
virtual ComponentInterfaceSymbol GetSymbol() const =0
virtual TranslatableString GetDescription() const =0
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
AddedAnalysisTrack(const AddedAnalysisTrack &) PROHIBITED
LabelTrack * get() const
Definition: Effect.h:214
ModifiedAnalysisTrack(const ModifiedAnalysisTrack &) PROHIBITED
LabelTrack * get() const
Definition: Effect.h:245
Base class for many of the effects in Audacity.
Definition: EffectBase.h:33
int mNumTracks
Definition: EffectBase.h:136
virtual bool CheckWhetherSkipEffect(const EffectSettings &settings) const =0
After Init(), tell whether Process() should be skipped.
int mNumGroups
Definition: EffectBase.h:137
virtual double CalcPreviewInputLength(const EffectSettings &settings, double previewLength) const =0
friend class Effect
Definition: EffectBase.h:116
virtual EffectType GetType() const =0
Type determines how it behaves.
virtual bool IsDefault() const =0
Whether the effect sorts "above the line" in the menus.
virtual bool IsInteractive() const =0
Whether the effect needs a dialog for entry of settings.
virtual bool SupportsAutomation() const =0
Whether the effect has any automatable controls.
virtual RealtimeSince RealtimeSupport() const =0
Since which version of Audacity has the effect supported realtime?
virtual EffectFamilySymbol GetFamily() const =0
Report identifier and user-visible name of the effect protocol.
Base class for many of the effects in Audacity.
Definition: Effect.h:29
wxWeakRef< wxDialog > mHostUIDialog
This smart pointer tracks the lifetime of the dialog.
Definition: Effect.h:269
static void IncEffectCounter()
Definition: Effect.h:145
wxWindow * GetUIParent()
Definition: Effect.h:273
static Effect * FetchParameters(Effect &e, EffectSettings &)
Definition: Effect.h:37
int GetNumWaveTracks() const
Definition: Effect.h:187
int GetNumWaveGroups() const
Definition: Effect.h:188
virtual unsigned GetAudioOutCount() const =0
How many output buffers to allocate at once.
virtual unsigned GetAudioInCount() const =0
How many input buffers to allocate at once.
Performs effect computation.
Interface for manipulations of an Effect's settings.
virtual void SetBatchProcessing()=0
virtual bool TransferDataToWindow(const EffectSettings &settings)=0
Update controls for the settings.
virtual bool TransferDataFromWindow(EffectSettings &settings)=0
Update the given settings from controls.
virtual void UnsetBatchProcessing()=0
virtual int ShowHostInterface(wxWindow &parent, const EffectDialogFactory &factory, std::shared_ptr< EffectInstance > &pInstance, EffectSettingsAccess &access, bool forceModal=false)=0
Usually applies factory to self and given access.
virtual bool SaveSettingsAsString(const EffectSettings &settings, wxString &parms) const =0
virtual const EffectSettingsManager & GetDefinition() const =0
virtual bool IsBatchProcessing() const =0
virtual bool LoadSettingsFromString(const wxString &parms, EffectSettings &settings) const =0
EffectSettingsManager is an EffectDefinitionInterface that adds a factory function for EffectSettings...
virtual bool VisitSettings(SettingsVisitor &visitor, EffectSettings &settings)
virtual bool LoadFactoryPreset(int id, EffectSettings &settings) const =0
Change settings to the preset whose name is GetFactoryPresets()[id]
virtual bool LoadFactoryDefaults(EffectSettings &settings) const =0
Change settings back to "factory default".
virtual RegistryPaths GetFactoryPresets() const =0
Report names of factory presets.
virtual bool SaveUserPreset(const RegistryPath &name, const EffectSettings &settings) const =0
Save settings in the configuration file as a user-named preset.
virtual bool LoadUserPreset(const RegistryPath &name, EffectSettings &settings) const =0
Change settings to a user-named preset.
virtual bool LoadSettings(const CommandParameters &parms, EffectSettings &settings) const =0
Restore settings from keys and values.
virtual bool SaveSettings(const EffectSettings &settings, CommandParameters &parms) const =0
Store settings as keys and values.
virtual void ImportPresets(EffectSettings &settings)=0
virtual bool CloseUI()=0
virtual void ShowOptions()=0
virtual bool ValidateUI(EffectSettings &settings)=0
virtual int ShowClientInterface(wxWindow &parent, wxDialog &dialog, bool forceModal=false)=0
virtual bool IsGraphicalUI()=0
virtual void ExportPresets(const EffectSettings &settings) const =0
virtual std::unique_ptr< EffectUIValidator > PopulateUI(ShuttleGui &S, EffectInstance &instance, EffectSettingsAccess &access)=0
Adds controls to a panel that is given as the parent window of S
virtual bool CanExportPresets()=0
virtual bool HasOptions()=0
static const Settings & GetSettings(const EffectSettings &settings)
Assume settings originated from MakeSettings() and copies thereof.
Definition: Effect.h:303
static Settings & GetSettings(EffectSettings &settings)
Assume settings originated from MakeSettings() and copies thereof.
Definition: Effect.h:296
static Settings * FetchParameters(Base &, EffectSettings &s)
Definition: Effect.h:308
EffectSettings MakeSettings() const override
Definition: Effect.h:286
bool CopySettingsContents(const EffectSettings &src, EffectSettings &dst) const override
Definition: Effect.h:290
A LabelTrack is a Track that holds labels (LabelStruct).
Definition: LabelTrack.h:89
Visitor of effect or command parameters. This is a base class with lots of virtual functions that do ...
Definition: Shuttle.h:115
Derived from ShuttleGuiBase, an Audacity specific class for shuttling data to and from GUI.
Definition: ShuttleGui.h:628
Calls through to members of StatefulEffectBase.
Instance(StatefulEffectBase &effect)
virtual bool Process(EffectInstance &instance, EffectSettings &settings)=0
Actually do the effect here.
std::shared_ptr< EffectInstance > MakeInstance() const override
Make an object maintaining short-term state of an Effect.
Definition: Effect.cpp:128
Abstract base class for an object holding data associated with points on a time axis.
Definition: Track.h:225
Holds a msgid for the translation catalog; may also bind format arguments.
A Track that contains audio waveform data.
Definition: WaveTrack.h:57
Positions or offsets within audio files need a wide type.
Definition: SampleCount.h:18
Externalized state of a plug-in.