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 "StatefulEffectBase.h"
18
19#define BUILTIN_EFFECT_PREFIX wxT("Built-in Effect: ")
20
22class LabelTrack;
23class WaveTrack;
24
25class sampleCount;
26
29/*
30 Also pops the even handler stack of a window, if given to the contructor
31
32 This is a transitional class; it should be eliminated when all effect classes
33 define their own associated subclasses of EffectUIValidator, which can hold
34 state only for the lifetime of a dialog, so the effect object need not hold it
35*/
37 : public EffectUIValidator
38 // Inherit wxEvtHandler so that Un-Bind()-ing is automatic in the destructor
39 , protected wxEvtHandler
40{
41public:
48 wxWindow *pParent = nullptr);
52 bool ValidateUI() override;
54 bool IsGraphicalUI() override;
55 void Disconnect() override;
56protected:
57 wxWindow *mpParent{};
58};
59
60class AUDACITY_DLL_API Effect /* not final */
61 : public wxEvtHandler
62 , public EffectBase
63{
64 //
65 // public methods
66 //
67 // Used by the outside program to determine properties of an effect and
68 // apply the effect to one or more tracks.
69 //
70 public:
72 { return &e; }
73
74 // The constructor is called once by each subclass at the beginning of the program.
75 // Avoid allocating memory or doing time-consuming processing here.
76 Effect();
77 virtual ~Effect();
78
79 // ComponentInterface implementation
80
81 PluginPath GetPath() const override;
82 bool VisitSettings(
83 SettingsVisitor &visitor, EffectSettings &settings) override;
84 bool VisitSettings(
86 const override;
87
88 ComponentInterfaceSymbol GetSymbol() const override;
89
90 VendorSymbol GetVendor() const override;
91 wxString GetVersion() const override;
92 TranslatableString GetDescription() const override;
93
94 // EffectDefinitionInterface implementation
95
96 EffectType GetType() const override;
97 EffectFamilySymbol GetFamily() const override;
98 bool IsInteractive() const override;
99 bool IsDefault() const override;
100 RealtimeSince RealtimeSupport() const override;
101 bool SupportsAutomation() const override;
102
103 bool SaveSettings(
104 const EffectSettings &settings, CommandParameters & parms) const override;
105 bool LoadSettings(
106 const CommandParameters & parms, EffectSettings &settings) const override;
107
109 const RegistryPath & name, EffectSettings &settings) const override;
110 bool SaveUserPreset(
111 const RegistryPath & name, const EffectSettings &settings) const override;
112
113 RegistryPaths GetFactoryPresets() const override;
115 const override;
117 const override;
118
119 // VisitSettings(), SaveSettings(), and LoadSettings()
120 // use the functions of EffectParameterMethods. By default, this function
121 // defines an empty list of parameters.
122 virtual const EffectParameterMethods &Parameters() const;
123
124 int ShowClientInterface(wxWindow &parent, wxDialog &dialog,
125 EffectUIValidator *pValidator, bool forceModal) override;
126
128
129 // EffectUIClientInterface implementation
130
131 std::unique_ptr<EffectUIValidator> PopulateUI(
132 ShuttleGui &S, EffectInstance &instance, EffectSettingsAccess &access,
133 const EffectOutputs *pOutputs) override;
135 bool IsGraphicalUI() override;
136 bool ValidateUI(EffectSettings &) override;
137 bool CloseUI() override;
138
139 bool CanExportPresets() override;
140 void ExportPresets(const EffectSettings &settings) const override;
142
143 bool HasOptions() override;
144 void ShowOptions() override;
145
146 // EffectPlugin implementation
147
148 const EffectSettingsManager& GetDefinition() const override;
149 virtual NumericFormatSymbol GetSelectionFormat() /* not override? */; // time format in Selection toolbar
150
151 // EffectPlugin implementation
152
153 int ShowHostInterface( wxWindow &parent,
155 std::shared_ptr<EffectInstance> &pInstance, EffectSettingsAccess &access,
156 bool forceModal = false) override;
158 const EffectSettings &settings, wxString & parms) const override;
160 const wxString & parms, EffectSettings &settings) const override;
161 bool IsBatchProcessing() const override;
162 void SetBatchProcessing() override;
163 void UnsetBatchProcessing() override;
164 bool TransferDataToWindow(const EffectSettings &settings) override;
166
167 // Effect implementation
168
169 unsigned TestUIFlags(unsigned mask);
170
172 bool Delegate(Effect &delegate, EffectSettings &settings);
173
174 // Display a message box, using effect's (translated) name as the prefix
175 // for the title.
176 enum : long { DefaultMessageBoxStyle = wxOK | wxCENTRE };
177 int MessageBox(const TranslatableString& message,
178 long style = DefaultMessageBoxStyle,
179 const TranslatableString& titleStr = {}) const;
180
181 static void IncEffectCounter(){ nEffectsDone++;}
182
183 bool EnableApply(bool enable = true);
184
185 protected:
186
187 bool EnablePreview(bool enable = true);
188
190 bool CheckWhetherSkipEffect(const EffectSettings &settings) const override;
191
194 const EffectSettings &settings, double previewLength) const override;
195
197
201 virtual std::unique_ptr<EffectUIValidator> PopulateOrExchange(
202 ShuttleGui & S, EffectInstance &instance, EffectSettingsAccess &access,
203 const EffectOutputs *pOutputs);
204
205 // No more virtuals!
206
207 // The Progress methods all return true if the user has cancelled;
208 // you should exit immediately if this happens (cleaning up memory
209 // is okay, but don't try to undo).
210
211 // Pass a fraction between 0.0 and 1.0
212 bool TotalProgress(double frac, const TranslatableString & = {}) const;
213
214 // Pass a fraction between 0.0 and 1.0, for the current track
215 // (when doing one track at a time)
216 bool TrackProgress(
217 int whichTrack, double frac, const TranslatableString & = {}) const;
218
219 // Pass a fraction between 0.0 and 1.0, for the current track group
220 // (when doing stereo groups at a time)
221 bool TrackGroupProgress(
222 int whichGroup, double frac, const TranslatableString & = {}) const;
223
224 int GetNumWaveTracks() const { return mNumTracks; }
225 int GetNumWaveGroups() const { return mNumGroups; }
226
227 // Calculates the start time and length in samples for one or two channels
228 void GetBounds(
229 const WaveTrack &track, const WaveTrack *pRight,
230 sampleCount *start, sampleCount *len);
231
232 // Use this method to copy the input tracks to mOutputTracks, if
233 // doing the processing on them, and replacing the originals only on success (and not cancel).
234 // If not all sync-locked selected, then only selected wave tracks.
235 void CopyInputTracks(bool allSyncLockSelected = false);
236
237 // For the use of analyzers, which don't need to make output wave tracks,
238 // but may need to add label tracks.
239 class AUDACITY_DLL_API AddedAnalysisTrack {
240 friend Effect;
241 AddedAnalysisTrack(Effect *pEffect, const wxString &name);
243
244 public:
245
247
248 // So you can have a vector of them
250
251 LabelTrack *get() const { return mpTrack; }
252
253 // Call this to indicate successful completion of the analyzer.
254 void Commit();
255
256 // Destructor undoes the addition of the analysis track if not committed.
258
259 private:
260 Effect *mpEffect{};
261 LabelTrack *mpTrack{};
262 };
263
264 // Set name to given value if that is not empty, else use default name
265 std::shared_ptr<AddedAnalysisTrack> AddAnalysisTrack(const wxString &name = wxString());
266
267 // For the use of analyzers, which don't need to make output wave tracks,
268 // but may need to modify label tracks.
269 class AUDACITY_DLL_API ModifiedAnalysisTrack {
270 friend Effect;
272 (Effect *pEffect, const LabelTrack *pOrigTrack, const wxString &name);
274
275 public:
276
278
279 // So you can have a vector of them
281
282 LabelTrack *get() const { return mpTrack; }
283
284 // Call this to indicate successful completion of the analyzer.
285 void Commit();
286
287 // Destructor undoes the modification of the analysis track if not committed.
289
290 private:
291 Effect *mpEffect{};
292 LabelTrack *mpTrack{};
293 std::shared_ptr<Track> mpOrigTrack{};
294 };
295
296 // Set name to given value if that is not empty, else use default name
297 ModifiedAnalysisTrack ModifyAnalysisTrack
298 (const LabelTrack *pOrigTrack, const wxString &name = wxString());
299
300 // Use this to append a NEW output track.
301 Track *AddToOutputTracks(const std::shared_ptr<Track> &t);
302
303protected:
304 // UI
306 wxWeakRef<wxDialog> mHostUIDialog;
307 wxWindow *mUIParent{};
308
309public:
310 wxWindow* GetUIParent() { return mUIParent; }
311
312private:
313 wxString GetSavedStateGroup();
314
315 bool mIsBatch{ false };
316};
317
320template<typename Settings, typename Base>
321class EffectWithSettings : public Base {
322public:
324 {
325 return EffectSettings::Make<Settings>();
326 }
328 const EffectSettings &src, EffectSettings &dst) const override
329 {
330 return EffectSettings::Copy<Settings>(src, dst);
331 }
334 {
335 auto pSettings = settings.cast<Settings>();
336 assert(pSettings);
337 return *pSettings;
338 }
340 static inline const Settings &GetSettings(const EffectSettings &settings)
341 {
342 return GetSettings(const_cast<EffectSettings &>(settings));
343 }
344 static inline Settings *
346 return &GetSettings(s);
347 }
348};
349
353 : public StatefulEffectBase
354 , public Effect
355{
356public:
357 class AUDACITY_DLL_API Instance : public StatefulEffectBase::Instance {
358 public:
360 bool Process(EffectSettings &settings) override;
362 const EffectSettings &settings, double sampleRate) const override;
363 };
364 std::shared_ptr<EffectInstance> MakeInstance() const override;
365};
366
367// FIXME:
368// FIXME: Remove this once all effects are using the NEW dialog
369// FIXME:
370
371#define ID_EFFECT_PREVIEW ePreviewID
372
373#endif
const TranslatableString name
Definition: Distortion.cpp:82
std::optional< std::unique_ptr< EffectSettingsAccess::Message > > OptionalMessage
EffectType
std::function< DialogFactoryResults(wxWindow &parent, EffectPlugin &, EffectUIClientInterface &, EffectSettingsAccess &) > EffectDialogFactory
Type of function that creates a dialog for an effect.
Definition: EffectPlugin.h:41
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,...
bool ValidateUI() override
Calls mEffect.ValidateUI()
Definition: Effect.cpp:888
~DefaultEffectUIValidator() override
Calls Disconnect.
Definition: Effect.cpp:883
DefaultEffectUIValidator(EffectUIClientInterface &effect, EffectSettingsAccess &access, wxWindow *pParent=nullptr)
Definition: Effect.cpp:876
wxWindow * mpParent
Definition: Effect.h:57
void Disconnect() override
On the first call only, may disconnect from further event handling.
Definition: Effect.cpp:903
bool IsGraphicalUI() override
Definition: Effect.cpp:898
AddedAnalysisTrack(const AddedAnalysisTrack &) PROHIBITED
LabelTrack * get() const
Definition: Effect.h:251
ModifiedAnalysisTrack(const ModifiedAnalysisTrack &) PROHIBITED
LabelTrack * get() const
Definition: Effect.h:282
Base class for many of the effects in Audacity.
Definition: EffectBase.h:33
int mNumTracks
Definition: EffectBase.h:138
virtual bool CheckWhetherSkipEffect(const EffectSettings &settings) const =0
After Init(), tell whether Process() should be skipped.
int mNumGroups
Definition: EffectBase.h:139
virtual double CalcPreviewInputLength(const EffectSettings &settings, double previewLength) const =0
friend class Effect
Definition: EffectBase.h:118
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:63
wxWeakRef< wxDialog > mHostUIDialog
This smart pointer tracks the lifetime of the dialog.
Definition: Effect.h:306
static void IncEffectCounter()
Definition: Effect.h:181
wxWindow * GetUIParent()
Definition: Effect.h:310
static Effect * FetchParameters(Effect &e, EffectSettings &)
Definition: Effect.h:71
int GetNumWaveTracks() const
Definition: Effect.h:224
int GetNumWaveGroups() const
Definition: Effect.h:225
Performs effect computation.
uint64_t SampleCount
Hold values to send to effect output meters.
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 EffectUIClientInterface * GetEffectUIClientInterface()=0
Returns the EffectUIClientInterface instance for this effect.
virtual bool SaveSettingsAsString(const EffectSettings &settings, wxString &parms) const =0
virtual const EffectSettingsManager & GetDefinition() const =0
virtual bool IsBatchProcessing() const =0
virtual OptionalMessage 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 OptionalMessage LoadFactoryDefaults(EffectSettings &settings) const =0
virtual RegistryPaths GetFactoryPresets() const =0
Report names of factory presets.
virtual OptionalMessage LoadUserPreset(const RegistryPath &name, EffectSettings &settings) const =0
virtual bool SaveUserPreset(const RegistryPath &name, const EffectSettings &settings) const =0
Save settings in the configuration file as a user-named preset.
virtual OptionalMessage LoadFactoryPreset(int id, EffectSettings &settings) const =0
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.
EffectUIClientInterface is an abstract base class to populate a UI and validate UI values....
virtual std::unique_ptr< EffectUIValidator > PopulateUI(ShuttleGui &S, EffectInstance &instance, EffectSettingsAccess &access, const EffectOutputs *pOutputs)=0
Adds controls to a panel that is given as the parent window of S
virtual OptionalMessage ImportPresets(EffectSettings &settings)=0
virtual bool CloseUI()=0
virtual void ShowOptions()=0
virtual int ShowClientInterface(wxWindow &parent, wxDialog &dialog, EffectUIValidator *pValidator, bool forceModal=false)=0
virtual bool ValidateUI(EffectSettings &settings)=0
virtual bool IsGraphicalUI()=0
virtual void ExportPresets(const EffectSettings &settings) const =0
virtual bool CanExportPresets()=0
virtual bool HasOptions()=0
Interface for transferring values from a panel of effect controls.
static const Settings & GetSettings(const EffectSettings &settings)
Assume settings originated from MakeSettings() and copies thereof.
Definition: Effect.h:340
static Settings & GetSettings(EffectSettings &settings)
Assume settings originated from MakeSettings() and copies thereof.
Definition: Effect.h:333
static Settings * FetchParameters(Base &, EffectSettings &s)
Definition: Effect.h:345
EffectSettings MakeSettings() const override
Definition: Effect.h:323
bool CopySettingsContents(const EffectSettings &src, EffectSettings &dst) const override
Definition: Effect.h:327
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.
virtual sampleCount GetLatency() const
std::shared_ptr< EffectInstance > MakeInstance() const override
Make an object maintaining short-term state of an Effect.
Definition: Effect.cpp:132
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:19
static RegisteredToolbarFactory factory
Externalized state of a plug-in.