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); }
83private:
84 NumericFormatSymbol mDurationFormat{};
85 double mDuration{};
86};
87
89struct EffectSettings : audacity::TypedAny<EffectSettings> {
90 using TypedAny::TypedAny;
92
93 void swap(EffectSettings &other)
94 {
95 TypedAny::swap(other);
96 std::swap(extra, other.extra);
97 }
98
100 template<typename T, typename... Args>
101 static EffectSettings Make(Args &&... args)
102 {
103 return EffectSettings(std::in_place_type<T>, std::forward<Args>(args)...);
104 }
105
108 template<typename T>
109 static bool Copy(const EffectSettings &src, EffectSettings &dst)
110 {
111 const T *pSrc = src.cast<T>();
112 T *pDst = dst.cast<T>();
113 if (pSrc && pDst) {
114 *pDst = *pSrc;
115 return true;
116 }
117 return false;
118 }
119};
120
123
125class COMPONENTS_API EffectSettingsAccess
126 : public std::enable_shared_from_this<EffectSettingsAccess> {
127public:
129 virtual const EffectSettings &Get() = 0;
130 virtual void Set(EffectSettings &&settings) = 0;
131
133
138 template<typename Function>
139 void ModifySettings(Function &&function) {
140 auto settings = this->Get();
141 std::forward<Function>(function)(settings);
142 this->Set(std::move(settings));
143 }
144};
145
147class COMPONENTS_API SimpleEffectSettingsAccess final
148 : public EffectSettingsAccess {
149public:
151 : mSettings{settings} {}
153 const EffectSettings &Get() override;
154 void Set(EffectSettings &&settings) override;
155private:
157};
158
159/*************************************************************************************/
168class COMPONENTS_API EffectDefinitionInterface /* not final */
169 : public ComponentInterface
170{
171public:
173 static Identifier GetSquashedName(const Identifier &ident);
174
176
178 virtual EffectType GetType() const = 0;
179
181 virtual EffectType GetClassification() const;
182
184 virtual EffectFamilySymbol GetFamily() const = 0;
185
187 virtual bool IsInteractive() const = 0;
188
190 virtual bool IsDefault() const = 0;
191
193 virtual bool SupportsRealtime() const = 0;
194
196 virtual bool SupportsAutomation() const = 0;
197
199 virtual bool EnablesDebug() const;
200
202 virtual ManualPageID ManualPage() const;
203
205 virtual FilePath HelpPage() const;
206
208 virtual bool IsHiddenFromMenus() const;
209};
210
211/*************************************************************************************/
220class COMPONENTS_API EffectSettingsManager /* not final */
222{
223public:
225
232
235 virtual EffectSettings MakeSettings() const;
236
238
251 virtual bool CopySettingsContents(
252 const EffectSettings &src, EffectSettings &dst) const;
253
255
258 virtual bool SaveSettings(
259 const EffectSettings &settings, CommandParameters & parms) const = 0;
260
262
265 virtual bool LoadSettings(
266 const CommandParameters & parms, EffectSettings &settings) const = 0;
267
269 virtual RegistryPaths GetFactoryPresets() const = 0;
270
272 virtual bool LoadUserPreset(
273 const RegistryPath & name, EffectSettings &settings) const = 0;
275 virtual bool SaveUserPreset(
276 const RegistryPath & name, const EffectSettings &settings) const = 0;
277
279 virtual bool LoadFactoryPreset(int id, EffectSettings &settings) const = 0;
283
287 virtual bool VisitSettings(
288 SettingsVisitor &visitor, EffectSettings &settings); // TODO const
289
293 virtual bool VisitSettings(
294 ConstSettingsVisitor &visitor, const EffectSettings &settings) const;
295};
296
297class wxDialog;
298class wxWindow;
299
301
302class sampleCount;
303
304// ----------------------------------------------------------------------------
305// Supported channel assignments
306// ----------------------------------------------------------------------------
307
308typedef enum
309{
310 // Use to mark end of list
312 // The default channel assignment
314 // From this point, the channels follow the 22.2 surround sound format
340
341/***************************************************************************/
345class COMPONENTS_API EffectInstance
346 : public std::enable_shared_from_this<EffectInstance>
347{
348public:
350
352
356 virtual bool Init();
357
359
362 virtual bool Process(EffectSettings &settings) = 0;
363
364 virtual void SetSampleRate(double rate) = 0;
365
366 virtual size_t GetBlockSize() const = 0;
367
368 // Suggest a block size, but the return is the size that was really set:
369 virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
370
378 virtual bool RealtimeInitialize(EffectSettings &settings);
379
384 virtual bool RealtimeAddProcessor(
385 EffectSettings &settings, unsigned numChannels, float sampleRate);
386
391 virtual bool RealtimeSuspend();
392
397 virtual bool RealtimeResume() noexcept;
398
400
404 virtual bool RealtimeProcessStart(EffectSettings &settings);
405
410 virtual size_t RealtimeProcess(int group, EffectSettings &settings,
411 const float *const *inBuf, float *const *outBuf, size_t numSamples);
412
414
418 virtual bool RealtimeProcessEnd(EffectSettings &settings) noexcept;
419
424 virtual bool RealtimeFinalize(EffectSettings &settings) noexcept;
425
428 virtual size_t GetTailSize() const;
429};
430
432class COMPONENTS_API EffectInstanceWithBlockSize
433 : public virtual EffectInstance
434{
435public:
437 size_t GetBlockSize() const override;
438 size_t SetBlockSize(size_t maxBlockSize) override;
439protected:
440 size_t mBlockSize{ 0 };
441};
442
445 : public virtual EffectInstance
446{
447public:
449 void SetSampleRate(double rate) override;
450protected:
451 double mSampleRate{ 0 };
452};
453
454/***************************************************************************/
457class COMPONENTS_API EffectInstanceFactory
458 : public EffectSettingsManager
459{
460public:
462
464
472 virtual std::shared_ptr<EffectInstance> MakeInstance() const = 0;
473
475
478 virtual unsigned GetAudioInCount() const = 0;
479
481 virtual unsigned GetAudioOutCount() const = 0;
482
484 virtual int GetMidiInCount() const;
485
487 virtual int GetMidiOutCount() const;
488};
489
490/*************************************************************************************/
497class COMPONENTS_API EffectUIValidator /* not final */
498{
499public:
502
503 virtual ~EffectUIValidator();
504
506
509 virtual bool ValidateUI() = 0;
510
512
517 virtual bool UpdateUI();
518
519protected:
520 // Convenience function template for binding event handler functions
521 template<typename EventTag, typename Class, typename Event>
522 void BindTo(
523 wxEvtHandler &src, const EventTag& eventType, void (Class::*pmf)(Event &))
524 {
525 src.Bind(eventType, pmf, static_cast<Class *>(this));
526 }
527
530};
531
532/*************************************************************************************/
544class COMPONENTS_API DefaultEffectUIValidator
545 : public EffectUIValidator
546 // Inherit wxEvtHandler so that Un-Bind()-ing is automatic in the destructor
547 , wxEvtHandler
548{
549public:
553 bool ValidateUI() override;
554};
555
556/*************************************************************************************/
564class COMPONENTS_API EffectUIClientInterface /* not final */
565{
566public:
568
574 wxWindow &parent, wxDialog &dialog, bool forceModal = false
575 ) = 0;
576
577 virtual bool IsGraphicalUI() = 0;
578
580
591 virtual std::unique_ptr<EffectUIValidator> PopulateUI(ShuttleGui &S,
592 EffectInstance &instance, EffectSettingsAccess &access) = 0;
593
594 virtual bool CanExportPresets() = 0;
595 virtual void ExportPresets(const EffectSettings &settings) const = 0;
597
598 virtual bool HasOptions() = 0;
599 virtual void ShowOptions() = 0;
600
601protected:
605 virtual bool CloseUI() = 0;
606};
607
609COMPONENTS_API const RegistryPath &CurrentSettingsGroup();
610
612COMPONENTS_API const RegistryPath &FactoryDefaultsGroup();
613
615COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath & name);
616
617#endif // __AUDACITY_EFFECTINTERFACE_H__
618
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
enum ChannelName * ChannelNames
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,...
Default implementation of EffectUIValidator invokes ValidateUI method of an EffectUIClientInterface.
~DefaultEffectUIValidator() override
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 SupportsRealtime() const =0
Whether the effect supports realtime previewing (while audio is playing).
virtual bool SupportsAutomation() const =0
Whether the effect has any automatable controls.
virtual EffectFamilySymbol GetFamily() const =0
Report identifier and user-visible name of the effect protocol.
virtual std::shared_ptr< EffectInstance > MakeInstance() const =0
Make an object maintaining short-term state of an Effect.
virtual unsigned GetAudioOutCount() const =0
How many output buffers to allocate at once.
virtual ~EffectInstanceFactory()
virtual unsigned GetAudioInCount() const =0
How many input buffers to allocate at once.
Performs effect computation.
virtual void SetSampleRate(double rate)=0
virtual size_t SetBlockSize(size_t maxBlockSize)=0
virtual bool Process(EffectSettings &settings)=0
Actually do the effect here.
virtual size_t GetBlockSize() const =0
virtual ~EffectInstance()
Inherit to add a state variable to an EffectInstance subclass.
~EffectInstanceWithBlockSize() override
Inherit to add a state variable to an EffectInstance subclass.
~EffectInstanceWithSampleRate() 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 ~EffectSettingsAccess()
Non-polymorphic package of settings values common to many effects.
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 bool ValidateUI(EffectSettings &settings)=0
virtual int ShowClientInterface(wxWindow &parent, wxDialog &dialog, bool forceModal=false)=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
EffectUIValidator(EffectUIClientInterface &effect, EffectSettingsAccess &access)
virtual bool ValidateUI()=0
Get settings data from the panel; may make error dialogs and return false.
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:631
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:24
const T * cast() const noexcept
Like pointer-valued any_cast but a non-static member function.
Definition: TypedAny.h:57
Positions or offsets within audio files need a wide type.
Definition: SampleCount.h:18
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
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)