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