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 <optional>
52#include <type_traits>
53#include <wx/event.h>
54
55#include "Observer.h"
56
57class ShuttleGui;
58template<bool Const> class SettingsVisitorBase;
61
62typedef enum EffectType : int
63{
71
72
74
76class COMPONENTS_API EffectSettingsExtra final {
77public:
78 static const RegistryPath &DurationKey();
80 { return mDurationFormat; }
81 void SetDurationFormat(const NumericFormatSymbol &durationFormat)
82 { mDurationFormat = durationFormat; }
83
85 double GetDuration() const { return mDuration; }
86 void SetDuration(double value) { mDuration = std::max(0.0, value); }
87
88 bool GetActive() const { return mActive; }
89 void SetActive(bool value) { mActive = value; }
90private:
91 NumericFormatSymbol mDurationFormat{};
92 double mDuration{};
93 bool mActive{ true };
94};
95
97struct EffectSettings : audacity::TypedAny<EffectSettings> {
98 using TypedAny::TypedAny;
100
101 void swap(EffectSettings &other)
102 {
103 TypedAny::swap(other);
104 std::swap(extra, other.extra);
105 }
106
108 template<typename T, typename... Args>
109 static EffectSettings Make(Args &&... args)
110 {
111 return EffectSettings(std::in_place_type<T>, std::forward<Args>(args)...);
112 }
113
116 template<typename T>
117 static bool Copy(const EffectSettings &src, EffectSettings &dst)
118 {
119 const T *pSrc = src.cast<T>();
120 T *pDst = dst.cast<T>();
121 if (pSrc && pDst) {
122 *pDst = *pSrc;
123 return true;
124 }
125 return false;
126 }
127};
128
130class COMPONENTS_API EffectOutputs {
131public:
132 virtual ~EffectOutputs();
133 virtual std::unique_ptr<EffectOutputs> Clone() const = 0;
134
136
145 virtual void Assign(EffectOutputs &&src) = 0;
146};
147
150
152class COMPONENTS_API EffectSettingsAccess
153 : public std::enable_shared_from_this<EffectSettingsAccess> {
154public:
156 class COMPONENTS_API Message {
157 public:
158 virtual ~Message();
159 virtual std::unique_ptr<Message> Clone() const = 0;
160
162
172 virtual void Assign(Message &&src) = 0;
173
175
184 virtual void Merge(Message &&src) = 0;
185 };
186
188 virtual const EffectSettings &Get() = 0;
190 std::unique_ptr<Message> pMessage = nullptr) = 0;
192 virtual void Set(std::unique_ptr<Message> pMessage = nullptr) = 0;
193
195
198 virtual void Flush() = 0;
199
201 virtual bool IsSameAs(const EffectSettingsAccess &other) const = 0;
202
204
210 template<typename Function>
211 void ModifySettings(Function &&function) {
212 auto settings = this->Get();
213 auto result = std::forward<Function>(function)(settings);
214 this->Set(std::move(settings), std::move(result));
215 }
216};
217
219class COMPONENTS_API SimpleEffectSettingsAccess final
220 : public EffectSettingsAccess {
221public:
223 : mSettings{settings} {}
225 const EffectSettings &Get() override;
226 void Set(EffectSettings &&settings,
227 std::unique_ptr<Message> pMessage) override;
228 void Set(std::unique_ptr<Message> pMessage) override;
229 void Flush() override;
230 bool IsSameAs(const EffectSettingsAccess &other) const override;
231private:
233};
234
235/*************************************************************************************/
244class COMPONENTS_API EffectDefinitionInterface /* not final */
245 : public ComponentInterface
246{
247public:
249 static Identifier GetSquashedName(const Identifier &ident);
250
252
254 virtual EffectType GetType() const = 0;
255
257 virtual EffectType GetClassification() const;
258
260 virtual EffectFamilySymbol GetFamily() const = 0;
261
263 virtual bool IsInteractive() const = 0;
264
266 virtual bool IsDefault() const = 0;
267
269 enum class RealtimeSince : unsigned {
270 Never,
271 // For built-in effects that became realtime in 3.2.x or a later version
272 // but were non-realtime in an earlier version; must also increase
273 // REGVERCUR in any release with such a change
274 After_3_1,
275 Always,
276 };
277
279 virtual RealtimeSince RealtimeSupport() const = 0;
280
283 bool SupportsRealtime() const
284 { return RealtimeSupport() != RealtimeSince::Never; }
285
287 virtual bool SupportsAutomation() const = 0;
288
290 virtual bool EnablesDebug() const;
291
293 virtual ManualPageID ManualPage() const;
294
296 virtual FilePath HelpPage() const;
297
299 virtual bool IsHiddenFromMenus() const;
300};
301
303 std::optional<std::unique_ptr<EffectSettingsAccess::Message>>;
304
305/*************************************************************************************/
314class COMPONENTS_API EffectSettingsManager /* not final */
316{
317public:
319
326
329 virtual EffectSettings MakeSettings() const;
330
332
346 virtual bool CopySettingsContents(
347 const EffectSettings &src, EffectSettings &dst) const;
348
350
354 virtual bool SaveSettings(
355 const EffectSettings &settings, CommandParameters & parms) const = 0;
356
358
361 virtual bool LoadSettings(
362 const CommandParameters & parms, EffectSettings &settings) const = 0;
363
365 virtual RegistryPaths GetFactoryPresets() const = 0;
366
369 [[nodiscard]] virtual OptionalMessage LoadUserPreset(
370 const RegistryPath & name, EffectSettings &settings) const = 0;
372 virtual bool SaveUserPreset(
373 const RegistryPath & name, const EffectSettings &settings) const = 0;
374
377 [[nodiscard]] virtual OptionalMessage LoadFactoryPreset(
378 int id, EffectSettings &settings) const = 0;
382 EffectSettings &settings) const = 0;
384
388 virtual bool VisitSettings(
389 SettingsVisitor &visitor, EffectSettings &settings); // TODO const
390
394 virtual bool VisitSettings(
395 ConstSettingsVisitor &visitor, const EffectSettings &settings) const;
396
401
404 virtual std::unique_ptr<EffectOutputs> MakeOutputs() const;
406};
407
408class wxDialog;
409class wxWindow;
410
412
413// ----------------------------------------------------------------------------
414// Supported channel assignments
415// ----------------------------------------------------------------------------
416
417enum ChannelName : int {
418 // Use to mark end of list
420 // The default channel assignment
422 // From this point, the channels follow the 22.2 surround sound format
447};
448using ChannelNames = const ChannelName *;
449
450/***************************************************************************/
454class COMPONENTS_API EffectInstance
455 : public std::enable_shared_from_this<EffectInstance>
456{
457public:
459
460 virtual size_t GetBlockSize() const = 0;
461
462 // Suggest a block size, but the return is the size that was really set:
463 virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
464
466
470 virtual unsigned GetAudioInCount() const = 0;
471
473
476 virtual unsigned GetAudioOutCount() const = 0;
477
487 virtual bool RealtimeInitialize(EffectSettings &settings, double sampleRate);
488
493 virtual bool RealtimeAddProcessor(
495 unsigned numChannels, float sampleRate);
496
501 virtual bool RealtimeSuspend();
502
507 virtual bool RealtimeResume();
508
512
514
515 virtual std::unique_ptr<Message> MakeMessage() const;
516
517 // TODO make it just an alias for Message *
519
522
526 virtual bool UsesMessages() const noexcept;
527
529
533 virtual bool RealtimeProcessStart(MessagePackage &package);
534
539 virtual size_t RealtimeProcess(size_t group, EffectSettings &settings,
540 const float *const *inBuf, float *const *outBuf, size_t numSamples);
541
543
547 virtual bool RealtimeProcessEnd(EffectSettings &settings) noexcept;
548
553 virtual bool RealtimeFinalize(EffectSettings &settings) noexcept;
554
557 virtual size_t GetTailSize() const;
558
559 using SampleCount = uint64_t;
560
564 virtual SampleCount GetLatency(
565 const EffectSettings &settings, double sampleRate) const;
566
569 virtual bool NeedsDither() const;
570
573
578 virtual bool ProcessInitialize(EffectSettings &settings,
579 double sampleRate, ChannelNames chanMap) = 0;
580
584 virtual bool ProcessFinalize() noexcept = 0;
585
587 virtual size_t ProcessBlock(EffectSettings &settings,
588 const float *const *inBlock, float *const *outBlock, size_t blockLen)
589 = 0;
590};
591
593class COMPONENTS_API EffectInstanceWithBlockSize
594 : public virtual EffectInstance
595{
596public:
598 size_t GetBlockSize() const override;
599 size_t SetBlockSize(size_t maxBlockSize) override;
600protected:
601 size_t mBlockSize{ 0 };
602};
603
604/***************************************************************************/
607class COMPONENTS_API EffectInstanceFactory
608 : public EffectSettingsManager
609{
610public:
612
614
624 virtual std::shared_ptr<EffectInstance> MakeInstance() const = 0;
625
626};
627
629COMPONENTS_API const RegistryPath &CurrentSettingsGroup();
630
632COMPONENTS_API const RegistryPath &FactoryDefaultsGroup();
633
635COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath & name);
636
637#endif // __AUDACITY_EFFECTINTERFACE_H__
638
const TranslatableString name
Definition: Distortion.cpp:74
COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath &name)
Compute part of a registry path, given a name which may be empty.
std::optional< std::unique_ptr< EffectSettingsAccess::Message > > OptionalMessage
EffectType
@ EffectTypeHidden
@ EffectTypeAnalyze
@ EffectTypeGenerate
@ EffectTypeNone
@ EffectTypeTool
@ EffectTypeProcess
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:21
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?
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 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
Hold values to send to effect output meters.
virtual ~EffectOutputs()
virtual std::unique_ptr< EffectOutputs > Clone() const =0
virtual void Assign(EffectOutputs &&src)=0
Update one Outputs object from another.
Type of messages to send from main thread to processing.
virtual void Merge(Message &&src)=0
Combine one Message object with another, which is then left "empty".
virtual std::unique_ptr< Message > Clone() const =0
virtual void Assign(Message &&src)=0
Update one Message object from another, which is then left "empty".
void ModifySettings(Function &&function)
Do a correct read-modify-write of settings.
virtual const EffectSettings & Get()=0
virtual void Set(EffectSettings &&settings, std::unique_ptr< Message > pMessage=nullptr)=0
virtual void Set(std::unique_ptr< Message > pMessage=nullptr)=0
Message-only overload of Set(). In future, this should be the only one.
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 OptionalMessage LoadFactoryDefaults(EffectSettings &settings) const =0
virtual ~EffectSettingsManager()
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....
Definition: EffectPlugin.h:170
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 swap(std::unique_ptr< Alg_seq > &a, std::unique_ptr< Alg_seq > &b)
Definition: NoteTrack.cpp:752
TranslatableString Message(unsigned trackCount)
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)