1 /**********************************************************************
2 
3    Audacity: A Digital Audio Editor
4 
5    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 <functional>
46 
47 #include "ComponentInterface.h"
48 #include "ComponentInterfaceSymbol.h"
49 #include "ConfigInterface.h"
50 #include "EffectAutomationParameters.h" // for command automation
51 
52 class ShuttleGui;
53 
54 typedef enum EffectType : int
55 {
56    EffectTypeNone,
57    EffectTypeHidden,
58    EffectTypeGenerate,
59    EffectTypeProcess,
60    EffectTypeAnalyze,
61    EffectTypeTool,
62 } EffectType;
63 
64 
65 using EffectFamilySymbol = ComponentInterfaceSymbol;
66 
67 /*************************************************************************************//**
68 
69 \class EffectDefinitionInterface
70 
71 \brief EffectDefinitionInterface is a ComponentInterface that additionally tracks
72 flag-functions for interactivity, play-preview and whether the effect can run without a GUI.
73 
74 *******************************************************************************************/
75 class COMPONENTS_API EffectDefinitionInterface  /* not final */ : public ComponentInterface
76 {
77 public:
78    virtual ~EffectDefinitionInterface();
79 
80    // Type determines how it behaves.
81    virtual EffectType GetType() = 0;
82    // Classification determines which menu it appears in.
GetClassification()83    virtual EffectType GetClassification() { return GetType();}
84 
85    virtual EffectFamilySymbol GetFamily() = 0;
86 
87    // These should move to the "EffectClientInterface" class once all
88    // effects have been converted.
89    virtual bool IsInteractive() = 0;
90 
91    // I don't really like this, but couldn't think of a better way to force the
92    // effect to appear "above the line" in the menus.
93    virtual bool IsDefault() = 0;
94 
95    // This will go away when all Effects have been updated to the new
96    // interface.
97    virtual bool IsLegacy() = 0;
98 
99    // Whether the effect supports realtime previewing (while audio is playing).
100    virtual bool SupportsRealtime() = 0;
101 
102    // Can the effect be used without the UI.
103    virtual bool SupportsAutomation() = 0;
104 };
105 
106 class wxDialog;
107 class wxWindow;
108 class EffectUIHostInterface;
109 class EffectUIClientInterface;
110 
111 /*************************************************************************************//**
112 
113 \class EffectHostInterface
114 
115 \brief EffectHostInterface is a decorator of a EffectUIClientInterface.  It adds
116 virtual (abstract) functions to get presets and actually apply the effect.  It uses
117 ConfigClientInterface to add Getters/setters for private and shared configs.
118 
119 *******************************************************************************************/
120 class COMPONENTS_API EffectHostInterface  /* not final */ : public ConfigClientInterface
121 {
122 public:
123    virtual ~EffectHostInterface();
124 
125    virtual double GetDefaultDuration() = 0;
126    virtual double GetDuration() = 0;
127    virtual NumericFormatSymbol GetDurationFormat() = 0;
128    virtual void SetDuration(double seconds) = 0;
129 
130    // Preset handling
131    virtual RegistryPath GetUserPresetsGroup(const RegistryPath & name) = 0;
132    virtual RegistryPath GetCurrentSettingsGroup() = 0;
133    virtual RegistryPath GetFactoryDefaultsGroup() = 0;
134 };
135 
136 class sampleCount;
137 
138 // ----------------------------------------------------------------------------
139 // Supported channel assignments
140 // ----------------------------------------------------------------------------
141 
142 typedef enum
143 {
144    // Use to mark end of list
145    ChannelNameEOL = -1,
146    // The default channel assignment
147    ChannelNameMono,
148    // From this point, the channels follow the 22.2 surround sound format
149    ChannelNameFrontLeft,
150    ChannelNameFrontRight,
151    ChannelNameFrontCenter,
152    ChannelNameLowFrequency1,
153    ChannelNameBackLeft,
154    ChannelNameBackRight,
155    ChannelNameFrontLeftCenter,
156    ChannelNameFrontRightCenter,
157    ChannelNameBackCenter,
158    ChannelNameLowFrequency2,
159    ChannelNameSideLeft,
160    ChannelNameSideRight,
161    ChannelNameTopFrontLeft,
162    ChannelNameTopFrontRight,
163    ChannelNameTopFrontCenter,
164    ChannelNameTopCenter,
165    ChannelNameTopBackLeft,
166    ChannelNameTopBackRight,
167    ChannelNameTopSideLeft,
168    ChannelNameTopSideRight,
169    ChannelNameTopBackCenter,
170    ChannelNameBottomFrontCenter,
171    ChannelNameBottomFrontLeft,
172    ChannelNameBottomFrontRight,
173 } ChannelName, *ChannelNames;
174 
175 /*************************************************************************************//**
176 
177 \class EffectClientInterface
178 
179 \brief EffectClientInterface provides the ident interface to Effect, and is what makes
180 Effect into a plug-in command.  It has functions for realtime that are not part of
181 AudacityCommand.
182 
183 *******************************************************************************************/
184 class COMPONENTS_API EffectClientInterface  /* not final */ : public EffectDefinitionInterface
185 {
186 public:
187    using EffectDialogFactory = std::function<
188       wxDialog* ( wxWindow &parent,
189          EffectHostInterface*, EffectUIClientInterface* )
190    >;
191 
192    virtual ~EffectClientInterface();
193 
194    virtual bool SetHost(EffectHostInterface *host) = 0;
195 
196    virtual unsigned GetAudioInCount() = 0;
197    virtual unsigned GetAudioOutCount() = 0;
198 
199    virtual int GetMidiInCount() = 0;
200    virtual int GetMidiOutCount() = 0;
201 
202    virtual void SetSampleRate(double rate) = 0;
203    // Suggest a block size, but the return is the size that was really set:
204    virtual size_t SetBlockSize(size_t maxBlockSize) = 0;
205    virtual size_t GetBlockSize() const = 0;
206 
207    virtual sampleCount GetLatency() = 0;
208    virtual size_t GetTailSize() = 0;
209 
210    virtual bool IsReady() = 0;
211    virtual bool ProcessInitialize(sampleCount totalLen, ChannelNames chanMap = NULL) = 0;
212    // This may be called during stack unwinding:
213    virtual bool ProcessFinalize() /* noexcept */ = 0;
214    virtual size_t ProcessBlock(float **inBlock, float **outBlock, size_t blockLen) = 0;
215 
216    virtual bool RealtimeInitialize() = 0;
217    virtual bool RealtimeAddProcessor(unsigned numChannels, float sampleRate) = 0;
218    virtual bool RealtimeFinalize() = 0;
219    virtual bool RealtimeSuspend() = 0;
220    virtual bool RealtimeResume() = 0;
221    virtual bool RealtimeProcessStart() = 0;
222    virtual size_t RealtimeProcess(int group, float **inBuf, float **outBuf, size_t numSamples) = 0;
223    virtual bool RealtimeProcessEnd() = 0;
224 
225    virtual bool ShowInterface(
226       wxWindow &parent, const EffectDialogFactory &factory,
227       bool forceModal = false
228    ) = 0;
229    // Some effects will use define params to define what parameters they take.
230    // If they do, they won't need to implement Get or SetAutomation parameters.
231    // since the Effect class can do it.  Or at least that is how things happen
232    // in AudacityCommand.  IF we do the same in class Effect, then Effect maybe
233    // should derive by some route from AudacityCommand to pick up that
234    // functionality.
235    //virtual bool DefineParams( ShuttleParams & S){ return false;};
236    virtual bool GetAutomationParameters(CommandParameters & parms) = 0;
237    virtual bool SetAutomationParameters(CommandParameters & parms) = 0;
238 
239    virtual bool LoadUserPreset(const RegistryPath & name) = 0;
240    virtual bool SaveUserPreset(const RegistryPath & name) = 0;
241 
242    virtual RegistryPaths GetFactoryPresets() = 0;
243    virtual bool LoadFactoryPreset(int id) = 0;
244    virtual bool LoadFactoryDefaults() = 0;
245 };
246 
247 /*************************************************************************************//**
248 
249 \class EffectUIHostInterface
250 
251 \brief EffectUIHostInterface has nothing in it.  It is provided so that an Effect
252 can call SetHostUI passing in a pointer to an EffectUIHostInterface.  It contains no
253 functionality and is provided, apparently, for type checking.  Since only EffectUIHost
254 uses it, EffectUIHost could be used instead.
255 *******************************************************************************************/
256 class COMPONENTS_API EffectUIHostInterface
257 {
258 public:
259    virtual ~EffectUIHostInterface();
260 };
261 
262 /*************************************************************************************//**
263 
264 \class EffectUIClientInterface
265 
266 \brief EffectUIClientInterface is an abstract base class to populate a UI and validate UI
267 values.  It can import and export presets.
268 
269 *******************************************************************************************/
270 class COMPONENTS_API EffectUIClientInterface /* not final */
271 {
272 public:
273    virtual ~EffectUIClientInterface();
274 
275    virtual void SetHostUI(EffectUIHostInterface *host) = 0;
276    virtual bool IsGraphicalUI() = 0;
277    virtual bool PopulateUI(ShuttleGui &S) = 0;
278    virtual bool ValidateUI() = 0;
279    virtual bool HideUI() = 0;
280    virtual bool CloseUI() = 0;
281 
282    virtual bool CanExportPresets() = 0;
283    virtual void ExportPresets() = 0;
284    virtual void ImportPresets() = 0;
285 
286    virtual bool HasOptions() = 0;
287    virtual void ShowOptions() = 0;
288 };
289 
290 #endif // __AUDACITY_EFFECTINTERFACE_H__
291