Audacity 3.2.0
EffectInterface.h
Go to the documentation of this file.
1/*!********************************************************************
2
3 Audacity: A Digital Audio Editor
4
5 @file 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 "ComponentInterface.h"
48
49#include "TypedAny.h"
50#include <memory>
51#include <wx/event.h>
52
53class ShuttleGui;
54template<bool Const> class SettingsVisitorBase;
57
58typedef enum EffectType : int
59{
67
68
70
72class COMPONENTS_API EffectSettingsExtra final {
73public:
74 static const RegistryPath &DurationKey();
76 { return mDurationFormat; }
77 void SetDurationFormat(const NumericFormatSymbol &durationFormat)
78 { mDurationFormat = durationFormat; }
79
81 double GetDuration() const { return mDuration; }
82 void SetDuration(double value) { mDuration = std::max(0.0, value); }
83
84 bool GetActive() const { return mActive; }
85 void SetActive(bool value) { mActive = value; }
86private:
87 NumericFormatSymbol mDurationFormat{};
88 double mDuration{};
89 bool mActive{ true };
90};
91
93struct EffectSettings : audacity::TypedAny<EffectSettings> {
94 using TypedAny::TypedAny;
96
97 void swap(EffectSettings &other)
98 {
99 TypedAny::swap(other);
100 std::swap(extra, other.extra);
101 }
102
104 template<typename T, typename... Args>
105 static EffectSettings Make(Args &&... args)
106 {
107 return EffectSettings(std::in_place_type<T>, std::forward<Args>(args)...);
108 }
109
112 template<typename T>
113 static bool Copy(const EffectSettings &src, EffectSettings &dst)
114 {
115 const T *pSrc = src.cast<T>();
116 T *pDst = dst.cast<T>();
117 if (pSrc && pDst) {
118 *pDst = *pSrc;
119 return true;
120 }
121 return false;
122 }
123};
124
127
129class COMPONENTS_API EffectSettingsAccess
130 : public std::enable_shared_from_this<EffectSettingsAccess> {
131public:
133 virtual const EffectSettings &Get() = 0;
134 virtual void Set(EffectSettings &&settings) = 0;
135
137 virtual void Flush() = 0;
138
140 virtual bool IsSameAs(const EffectSettingsAccess &other) const = 0;
141
143
148 template<typename Function>
149 void ModifySettings(Function &&function) {
150 auto settings = this->Get();
151 std::forward<Function>(function)(settings);
152 this->Set(std::move(settings));
153 }
154};
155
157class COMPONENTS_API SimpleEffectSettingsAccess final
158 : public EffectSettingsAccess {
159public:
161 : mSettings{settings} {}
163 const EffectSettings &Get() override;
164 void Set(EffectSettings &&settings) override;
165 void Flush() override;
166 bool IsSameAs(const EffectSettingsAccess &other) const override;
167private:
169};
170
171/*************************************************************************************/
180class COMPONENTS_API EffectDefinitionInterface /* not final */
181 : public ComponentInterface
182{
183public:
185 static Identifier GetSquashedName(const Identifier &ident);
186
188
190 virtual EffectType GetType() const = 0;
191
193 virtual EffectType GetClassification() const;
194
196 virtual EffectFamilySymbol GetFamily() const = 0;
197
199 virtual bool IsInteractive() const = 0;
200
202 virtual bool IsDefault() const = 0;
203
205 enum class RealtimeSince : unsigned {
206 Never,
207 Since_3_2,
208 Always,
209 };
210
212 virtual RealtimeSince RealtimeSupport() const = 0;
213
216 bool SupportsRealtime() const
217 { return RealtimeSupport() != RealtimeSince::Never; }
218
220 virtual bool SupportsAutomation() const = 0;
221
223 virtual bool EnablesDebug() const;
224
226 virtual ManualPageID ManualPage() const;
227
229 virtual FilePath HelpPage() const;
230
232 virtual bool IsHiddenFromMenus() const;
233};
234
237{
242};
243
244/*************************************************************************************/
253class COMPONENTS_API EffectSettingsManager /* not final */
255{
256public:
258
265
268 virtual EffectSettings MakeSettings() const;
269
271
285 virtual bool CopySettingsContents(
286 const EffectSettings &src, EffectSettings &dst, SettingsCopyDirection copyDirection) const;
287
289
293 virtual bool SaveSettings(
294 const EffectSettings &settings, CommandParameters & parms) const = 0;
295
297
300 virtual bool LoadSettings(
301 const CommandParameters & parms, EffectSettings &settings) const = 0;
302
304 virtual RegistryPaths GetFactoryPresets() const = 0;
305
307 virtual bool LoadUserPreset(
308 const RegistryPath & name, EffectSettings &settings) const = 0;
310 virtual bool SaveUserPreset(
311 const RegistryPath & name, const EffectSettings &settings) const = 0;
312
314 virtual bool LoadFactoryPreset(int id, EffectSettings &settings) const = 0;
318
322 virtual bool VisitSettings(
323 SettingsVisitor &visitor, EffectSettings &settings); // TODO const
324
328 virtual bool VisitSettings(
329 ConstSettingsVisitor &visitor, const EffectSettings &settings) const;
330};
331
332class wxDialog;
333class wxWindow;
334
336
337// ----------------------------------------------------------------------------
338// Supported channel assignments
339// ----------------------------------------------------------------------------
340
341enum ChannelName : int {
342 // Use to mark end of list
344 // The default channel assignment
346 // From this point, the channels follow the 22.2 surround sound format
371};
372using ChannelNames = const ChannelName *;
373
374/***************************************************************************/
378class COMPONENTS_API EffectInstance
379 : public std::enable_shared_from_this<EffectInstance>
380{
381public:
383
385
389 virtual bool Init();
390
392
395 virtual bool Process(EffectSettings &settings) = 0;
396
397 virtual size_t GetBlockSize() const = 0;
398
399 // Suggest a block size, but the return is the size that was really set:
400 virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
401
403
407 virtual unsigned GetAudioInCount() const = 0;
408
410
413 virtual unsigned GetAudioOutCount() const = 0;
414
424 virtual bool RealtimeInitialize(EffectSettings &settings, double sampleRate);
425
430 virtual bool RealtimeAddProcessor(
431 EffectSettings &settings, unsigned numChannels, float sampleRate);
432
437 virtual bool RealtimeSuspend();
438
443 virtual bool RealtimeResume();
444
446
450 virtual bool RealtimeProcessStart(EffectSettings &settings);
451
456 virtual size_t RealtimeProcess(size_t group, EffectSettings &settings,
457 const float *const *inBuf, float *const *outBuf, size_t numSamples);
458
460
464 virtual bool RealtimeProcessEnd(EffectSettings &settings) noexcept;
465
470 virtual bool RealtimeFinalize(EffectSettings &settings) noexcept;
471
474 virtual size_t GetTailSize() const;
475
477
481 virtual void AssignSettings(EffectSettings &dst, EffectSettings &&src) const;
482
483 using SampleCount = uint64_t;
484
488 virtual SampleCount GetLatency(
489 const EffectSettings &settings, double sampleRate) const;
490};
491
492/***************************************************************************/
496class COMPONENTS_API EffectInstanceEx : public virtual EffectInstance {
497public:
499
502
508 double sampleRate, ChannelNames chanMap) = 0;
509
513 virtual bool ProcessFinalize() noexcept = 0;
514
516 virtual size_t ProcessBlock(EffectSettings &settings,
517 const float *const *inBlock, float *const *outBlock, size_t blockLen)
518 = 0;
519};
520
522class COMPONENTS_API EffectInstanceWithBlockSize
523 : public virtual EffectInstance
524{
525public:
527 size_t GetBlockSize() const override;
528 size_t SetBlockSize(size_t maxBlockSize) override;
529protected:
530 size_t mBlockSize{ 0 };
531};
532
533/***************************************************************************/
536class COMPONENTS_API EffectInstanceFactory
537 : public EffectSettingsManager
538{
539public:
541
543
553 virtual std::shared_ptr<EffectInstance> MakeInstance() const = 0;
554
555};
556
557/*************************************************************************************/
564class COMPONENTS_API EffectUIValidator /* not final */
565{
566public:
569
571
573
576 virtual bool ValidateUI() = 0;
577
579
584 virtual bool UpdateUI();
585
590 virtual bool IsGraphicalUI();
591
593
596 virtual void Disconnect();
597
601 virtual void OnClose();
602
603protected:
604 // Convenience function template for binding event handler functions
605 template<typename EventTag, typename Class, typename Event>
606 void BindTo(
607 wxEvtHandler &src, const EventTag& eventType, void (Class::*pmf)(Event &))
608 {
609 src.Bind(eventType, pmf, static_cast<Class *>(this));
610 }
611
614
615 bool mUIClosed { false };
616};
617
618/*************************************************************************************/
626class COMPONENTS_API EffectUIClientInterface /* not final */
627{
628public:
630
635 virtual int ShowClientInterface(wxWindow &parent, wxDialog &dialog,
636 EffectUIValidator *pValidator, bool forceModal = false) = 0;
637
641 virtual bool IsGraphicalUI() = 0;
642
644
655 virtual std::unique_ptr<EffectUIValidator> PopulateUI(ShuttleGui &S,
656 EffectInstance &instance, EffectSettingsAccess &access) = 0;
657
658 virtual bool CanExportPresets() = 0;
659 virtual void ExportPresets(const EffectSettings &settings) const = 0;
661
662 virtual bool HasOptions() = 0;
663 virtual void ShowOptions() = 0;
664
666 virtual bool CloseUI() = 0;
667};
668
670COMPONENTS_API const RegistryPath &CurrentSettingsGroup();
671
673COMPONENTS_API const RegistryPath &FactoryDefaultsGroup();
674
676COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath & name);
677
678#endif // __AUDACITY_EFFECTINTERFACE_H__
679
const TranslatableString name
Definition: Distortion.cpp:82
COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath &name)
Compute part of a registry path, given a name which may be empty.
EffectType
@ EffectTypeHidden
@ EffectTypeAnalyze
@ EffectTypeGenerate
@ EffectTypeNone
@ EffectTypeTool
@ EffectTypeProcess
SettingsCopyDirection
Direction in which settings are copied.
@ WorkerToMain
Worker thread settings replicated to main thread.
@ MainToWorker
Main thread settings replicated to the worker thread.
COMPONENTS_API const RegistryPath & CurrentSettingsGroup()
Component of a configuration key path, for last-used destructive settings.
ChannelName
@ ChannelNameLowFrequency2
@ ChannelNameBackRight
@ ChannelNameSideLeft
@ ChannelNameTopSideLeft
@ ChannelNameFrontLeft
@ ChannelNameSideRight
@ ChannelNameFrontRightCenter
@ ChannelNameFrontLeftCenter
@ ChannelNameEOL
@ ChannelNameMono
@ ChannelNameFrontCenter
@ ChannelNameTopBackRight
@ ChannelNameTopFrontCenter
@ ChannelNameBottomFrontLeft
@ ChannelNameBackCenter
@ ChannelNameBackLeft
@ ChannelNameTopFrontRight
@ ChannelNameTopBackLeft
@ ChannelNameTopBackCenter
@ ChannelNameTopCenter
@ ChannelNameBottomFrontRight
@ ChannelNameLowFrequency1
@ ChannelNameTopFrontLeft
@ ChannelNameBottomFrontCenter
@ ChannelNameFrontRight
@ ChannelNameTopSideRight
COMPONENTS_API const RegistryPath & FactoryDefaultsGroup()
Component of a configuration key path, for default state of MakeSettings()
wxString RegistryPath
Definition: Identifier.h:218
std::vector< RegistryPath > RegistryPaths
Definition: Identifier.h:219
static CommandHandlerObject & ident(AudacityProject &project)
wxString FilePath
Definition: Project.h:20
#define S(N)
Definition: ToChars.cpp:64
static Settings & settings()
Definition: TrackInfo.cpp:87
Wrapper class for std::any, making type distinctions.
CommandParameters, derived from wxFileConfig, is essentially doing the same things as the SettingsVis...
ComponentInterface provides name / vendor / version functions to identify plugins....
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
EffectDefinitionInterface is a ComponentInterface that adds some basic read-only information about ef...
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 ~EffectDefinitionInterface()
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.
RealtimeSince
In which versions of Audacity was an effect realtime capable?
Performs effect computation.
~EffectInstanceEx() override
virtual bool ProcessInitialize(EffectSettings &settings, double sampleRate, ChannelNames chanMap)=0
virtual bool ProcessFinalize() noexcept=0
virtual std::shared_ptr< EffectInstance > MakeInstance() const =0
Make an object maintaining short-term state of an Effect.
virtual ~EffectInstanceFactory()
Performs effect computation.
virtual unsigned GetAudioInCount() const =0
How many input buffers to allocate at once.
virtual size_t SetBlockSize(size_t maxBlockSize)=0
virtual bool Process(EffectSettings &settings)=0
Actually do the effect here.
virtual unsigned GetAudioOutCount() const =0
How many output buffers to allocate at once.
virtual size_t GetBlockSize() const =0
uint64_t SampleCount
virtual ~EffectInstance()
Inherit to add a state variable to an EffectInstance subclass.
~EffectInstanceWithBlockSize() override
void ModifySettings(Function &&function)
Do a correct read-modify-write of settings.
virtual const EffectSettings & Get()=0
virtual void Set(EffectSettings &&settings)=0
virtual void Flush()=0
Make the last Set changes "persistent" in underlying storage.
virtual ~EffectSettingsAccess()
virtual bool IsSameAs(const EffectSettingsAccess &other) const =0
Non-polymorphic package of settings values common to many effects.
bool GetActive() const
void SetActive(bool value)
void SetDurationFormat(const NumericFormatSymbol &durationFormat)
double GetDuration() const
const NumericFormatSymbol & GetDurationFormat() const
void SetDuration(double value)
EffectSettingsManager is an EffectDefinitionInterface that adds a factory function for EffectSettings...
virtual bool LoadFactoryPreset(int id, EffectSettings &settings) const =0
Change settings to the preset whose name is GetFactoryPresets()[id]
virtual ~EffectSettingsManager()
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.
EffectUIClientInterface is an abstract base class to populate a UI and validate UI values....
virtual void 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 ~EffectUIClientInterface()
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
Interface for transferring values from a panel of effect controls.
EffectSettingsAccess & mAccess
virtual bool ValidateUI()=0
Get settings data from the panel; may make error dialogs and return false.
virtual ~EffectUIValidator()
void BindTo(wxEvtHandler &src, const EventTag &eventType, void(Class::*pmf)(Event &))
EffectUIClientInterface & mEffect
An explicitly nonlocalized string, not meant for the user to see.
Definition: Identifier.h:22
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
Implementation of EffectSettings for cases where there is only one thread.
SimpleEffectSettingsAccess(EffectSettings &settings)
~SimpleEffectSettingsAccess() override
Generates distinct, non-interconvertible types wrapping std::any.
Definition: TypedAny.h:25
const T * cast() const noexcept
Like pointer-valued any_cast but a non-static member function.
Definition: TypedAny.h:68
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:194
void OnClose(wxCommandEvent &e)
void swap(std::unique_ptr< Alg_seq > &a, std::unique_ptr< Alg_seq > &b)
Definition: NoteTrack.cpp:753
Externalized state of a plug-in.
EffectSettingsExtra extra
static EffectSettings Make(Args &&... args)
Like make_any but a static member function.
static bool Copy(const EffectSettings &src, EffectSettings &dst)
void swap(EffectSettings &other)