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 NumericFormatID &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 NumericFormatID 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
411// ----------------------------------------------------------------------------
412// Supported channel assignments
413// ----------------------------------------------------------------------------
414
415enum ChannelName : int {
416 // Use to mark end of list
418 // The default channel assignment
420 // From this point, the channels follow the 22.2 surround sound format
445};
446using ChannelNames = const ChannelName *;
447
448/***************************************************************************/
452class COMPONENTS_API EffectInstance
453 : public std::enable_shared_from_this<EffectInstance>
454{
455public:
457
458 virtual size_t GetBlockSize() const = 0;
459
460 // Suggest a block size, but the return is the size that was really set:
461 virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
462
464
468 virtual unsigned GetAudioInCount() const = 0;
469
471
474 virtual unsigned GetAudioOutCount() const = 0;
475
485 virtual bool RealtimeInitialize(EffectSettings &settings, double sampleRate);
486
491 virtual bool RealtimeAddProcessor(
493 unsigned numChannels, float sampleRate);
494
499 virtual bool RealtimeSuspend();
500
505 virtual bool RealtimeResume();
506
510
512
513 virtual std::unique_ptr<Message> MakeMessage() const;
514
515 // TODO make it just an alias for Message *
517
520
524 virtual bool UsesMessages() const noexcept;
525
527
531 virtual bool RealtimeProcessStart(MessagePackage &package);
532
537 virtual size_t RealtimeProcess(size_t group, EffectSettings &settings,
538 const float *const *inBuf, float *const *outBuf, size_t numSamples);
539
541
545 virtual bool RealtimeProcessEnd(EffectSettings &settings) noexcept;
546
551 virtual bool RealtimeFinalize(EffectSettings &settings) noexcept;
552
555 virtual size_t GetTailSize() const;
556
557 using SampleCount = uint64_t;
558
562 virtual SampleCount GetLatency(
563 const EffectSettings &settings, double sampleRate) const;
564
567 virtual bool NeedsDither() const;
568
571
576 virtual bool ProcessInitialize(EffectSettings &settings,
577 double sampleRate, ChannelNames chanMap) = 0;
578
582 virtual bool ProcessFinalize() noexcept = 0;
583
585 virtual size_t ProcessBlock(EffectSettings &settings,
586 const float *const *inBlock, float *const *outBlock, size_t blockLen)
587 = 0;
588};
589
591class COMPONENTS_API EffectInstanceWithBlockSize
592 : public virtual EffectInstance
593{
594public:
596 size_t GetBlockSize() const override;
597 size_t SetBlockSize(size_t maxBlockSize) override;
598protected:
599 size_t mBlockSize{ 0 };
600};
601
602/***************************************************************************/
605class COMPONENTS_API EffectInstanceFactory
606 : public EffectSettingsManager
607{
608public:
610
612
622 virtual std::shared_ptr<EffectInstance> MakeInstance() const = 0;
623
624};
625
627COMPONENTS_API const RegistryPath &CurrentSettingsGroup();
628
630COMPONENTS_API const RegistryPath &FactoryDefaultsGroup();
631
633COMPONENTS_API RegistryPath UserPresetsGroup(const RegistryPath & name);
634
635#endif // __AUDACITY_EFFECTINTERFACE_H__
636
const TranslatableString name
Definition: Distortion.cpp:76
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
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()
std::optional< std::unique_ptr< EffectSettingsAccess::Message > > OptionalMessage
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:69
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.
void SetDurationFormat(const NumericFormatID &durationFormat)
bool GetActive() const
void SetActive(bool value)
double GetDuration() const
const NumericFormatID & 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.
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 ...
Derived from ShuttleGuiBase, an Audacity specific class for shuttling data to and from GUI.
Definition: ShuttleGui.h:640
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:196
void swap(std::unique_ptr< Alg_seq > &a, std::unique_ptr< Alg_seq > &b)
Definition: NoteTrack.cpp:628
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)