Mercurial > hg > pub > prymula > com

comparison DPF-Prymula-audioplugins/dpf/distrho/DistrhoPlugin.hpp @ 3:84e66ea83026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DPF-Prymula-audioplugins-0.231015-2
author prymula <prymula76@outlook.com>
date Mon, 16 Oct 2023 21:53:34 +0200
parents
children
comparison
equal deleted inserted replaced
2:cf2cb71d31dd 3:84e66ea83026
1 /*
2 * DISTRHO Plugin Framework (DPF)
3 * Copyright (C) 2012-2022 Filipe Coelho <falktx@falktx.com>
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any purpose with
6 * or without fee is hereby granted, provided that the above copyright notice and this
7 * permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
10 * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
11 * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
12 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
13 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
14 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 */
16
17 #ifndef DISTRHO_PLUGIN_HPP_INCLUDED
18 #define DISTRHO_PLUGIN_HPP_INCLUDED
19
20 #include "DistrhoDetails.hpp"
21 #include "extra/LeakDetector.hpp"
22 #include "src/DistrhoPluginChecks.h"
23
24 START_NAMESPACE_DISTRHO
25
26 /* ------------------------------------------------------------------------------------------------------------
27 * DPF Plugin */
28
29 /**
30 @defgroup MainClasses Main Classes
31 @{
32 */
33
34 /**
35 DPF Plugin class from where plugin instances are created.
36
37 The public methods (Host state) are called from the plugin to get or set host information.@n
38 They can be called from a plugin instance at anytime unless stated otherwise.@n
39 All other methods are to be implemented by the plugin and will be called by the host.
40
41 Shortly after a plugin instance is created, the various init* functions will be called by the host.@n
42 Host will call activate() before run(), and deactivate() before the plugin instance is destroyed.@n
43 The host may call deactivate right after activate and vice-versa, but never activate/deactivate consecutively.@n
44 There is no limit on how many times run() is called, only that activate/deactivate will be called in between.
45
46 The buffer size and sample rate values will remain constant between activate and deactivate.@n
47 Buffer size is only a hint though, the host might call run() with a higher or lower number of frames.
48
49 Some of this class functions are only available according to some macros.
50
51 DISTRHO_PLUGIN_WANT_PROGRAMS activates program related features.@n
52 When enabled you need to implement initProgramName() and loadProgram().
53
54 DISTRHO_PLUGIN_WANT_STATE activates internal state features.@n
55 When enabled you need to implement initState() and setState().
56
57 The process function run() changes wherever DISTRHO_PLUGIN_WANT_MIDI_INPUT is enabled or not.@n
58 When enabled it provides midi input events.
59 */
60 class Plugin
61 {
62 public:
63 /**
64 Plugin class constructor.@n
65 You must set all parameter values to their defaults, matching ParameterRanges::def.
66 */
67 Plugin(uint32_t parameterCount, uint32_t programCount, uint32_t stateCount);
68
69 /**
70 Destructor.
71 */
72 virtual ~Plugin();
73
74 /* --------------------------------------------------------------------------------------------------------
75 * Host state */
76
77 /**
78 Get the current buffer size that will probably be used during processing, in frames.@n
79 This value will remain constant between activate and deactivate.
80 @note This value is only a hint!@n
81 Hosts might call run() with a higher or lower number of frames.
82 @see bufferSizeChanged(uint32_t)
83 */
84 uint32_t getBufferSize() const noexcept;
85
86 /**
87 Get the current sample rate that will be used during processing.@n
88 This value will remain constant between activate and deactivate.
89 @see sampleRateChanged(double)
90 */
91 double getSampleRate() const noexcept;
92
93 /**
94 Get the bundle path where the plugin resides.
95 Can return null if the plugin is not available in a bundle (if it is a single binary).
96 @see getBinaryFilename
97 @see getResourcePath
98 */
99 const char* getBundlePath() const noexcept;
100
101 /**
102 Check if this plugin instance is a "dummy" one used for plugin meta-data/information export.@n
103 When true no processing will be done, the plugin is created only to extract information.@n
104 In DPF, LADSPA/DSSI, VST2 and VST3 formats create one global instance per plugin binary
105 while LV2 creates one when generating turtle meta-data.
106 */
107 bool isDummyInstance() const noexcept;
108
109 /**
110 Check if this plugin instance is a "selftest" one used for automated plugin tests.@n
111 To enable this mode build with `DPF_RUNTIME_TESTING` macro defined (i.e. set as compiler build flag),
112 and run the JACK/Standalone executable with "selftest" as its only and single argument.
113
114 A few basic DSP and UI tests will run in self-test mode, with once instance having this function returning true.@n
115 You can use this chance to do a few tests of your own as well.
116 */
117 bool isSelfTestInstance() const noexcept;
118
119 #if DISTRHO_PLUGIN_WANT_TIMEPOS
120 /**
121 Get the current host transport time position.@n
122 This function should only be called during run().@n
123 You can call this during other times, but the returned position is not guaranteed to be in sync.
124 @note TimePosition is not supported in LADSPA and DSSI plugin formats.
125 */
126 const TimePosition& getTimePosition() const noexcept;
127 #endif
128
129 #if DISTRHO_PLUGIN_WANT_LATENCY
130 /**
131 Change the plugin audio output latency to @a frames.@n
132 This function should only be called in the constructor, activate() and run().
133 @note This function is only available if DISTRHO_PLUGIN_WANT_LATENCY is enabled.
134 */
135 void setLatency(uint32_t frames) noexcept;
136 #endif
137
138 #if DISTRHO_PLUGIN_WANT_MIDI_OUTPUT
139 /**
140 Write a MIDI output event.@n
141 This function must only be called during run().@n
142 Returns false when the host buffer is full, in which case do not call this again until the next run().
143 */
144 bool writeMidiEvent(const MidiEvent& midiEvent) noexcept;
145 #endif
146
147 #if DISTRHO_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST
148 /**
149 Check if parameter value change requests will work with the current plugin host.
150 @note This function is only available if DISTRHO_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST is enabled.
151 @see requestParameterValueChange(uint32_t, float)
152 */
153 bool canRequestParameterValueChanges() const noexcept;
154
155 /**
156 Request a parameter value change from the host.
157 If successful, this function will automatically trigger a parameter update on the UI side as well.
158 This function can fail, for example if the host is busy with the parameter for read-only automation.
159 Some hosts simply do not have this functionality, which can be verified with canRequestParameterValueChanges().
160 @note This function is only available if DISTRHO_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST is enabled.
161 */
162 bool requestParameterValueChange(uint32_t index, float value) noexcept;
163 #endif
164
165 #if DISTRHO_PLUGIN_WANT_STATE
166 /**
167 Set state value and notify the host about the change.@n
168 This function will call `setState()` and also trigger an update on the UI side as necessary.@n
169 It must not be called during run.@n
170 The state must be host readable.
171 @note this function does nothing on DSSI plugin format, as DSSI only supports UI->DSP messages.
172
173 TODO API under construction
174 */
175 bool updateStateValue(const char* key, const char* value) noexcept;
176 #endif
177
178 protected:
179 /* --------------------------------------------------------------------------------------------------------
180 * Information */
181
182 /**
183 Get the plugin name.@n
184 Returns DISTRHO_PLUGIN_NAME by default.
185 */
186 virtual const char* getName() const { return DISTRHO_PLUGIN_NAME; }
187
188 /**
189 Get the plugin label.@n
190 This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters.
191 */
192 virtual const char* getLabel() const = 0;
193
194 /**
195 Get an extensive comment/description about the plugin.@n
196 Optional, returns nothing by default.
197 */
198 virtual const char* getDescription() const { return ""; }
199
200 /**
201 Get the plugin author/maker.
202 */
203 virtual const char* getMaker() const = 0;
204
205 /**
206 Get the plugin homepage.@n
207 Optional, returns nothing by default.
208 */
209 virtual const char* getHomePage() const { return ""; }
210
211 /**
212 Get the plugin license (a single line of text or a URL).@n
213 For commercial plugins this should return some short copyright information.
214 */
215 virtual const char* getLicense() const = 0;
216
217 /**
218 Get the plugin version, in hexadecimal.
219 @see d_version()
220 */
221 virtual uint32_t getVersion() const = 0;
222
223 /**
224 Get the plugin unique Id.@n
225 This value is used by LADSPA, DSSI and VST plugin formats.
226 @see d_cconst()
227 */
228 virtual int64_t getUniqueId() const = 0;
229
230 /* --------------------------------------------------------------------------------------------------------
231 * Init */
232
233 /**
234 Initialize the audio port @a index.@n
235 This function will be called once, shortly after the plugin is created.
236 */
237 virtual void initAudioPort(bool input, uint32_t index, AudioPort& port);
238
239 /**
240 Initialize the parameter @a index.@n
241 This function will be called once, shortly after the plugin is created.
242 */
243 virtual void initParameter(uint32_t index, Parameter& parameter);
244
245 /**
246 Initialize the port group @a groupId.@n
247 This function will be called once,
248 shortly after the plugin is created and all audio ports and parameters have been enumerated.
249 */
250 virtual void initPortGroup(uint32_t groupId, PortGroup& portGroup);
251
252 #if DISTRHO_PLUGIN_WANT_PROGRAMS
253 /**
254 Set the name of the program @a index.@n
255 This function will be called once, shortly after the plugin is created.@n
256 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled.
257 */
258 virtual void initProgramName(uint32_t index, String& programName) = 0;
259 #endif
260
261 #if DISTRHO_PLUGIN_WANT_STATE
262 /**
263 Initialize the state @a index.@n
264 This function will be called once, shortly after the plugin is created.@n
265 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled.
266 */
267 virtual void initState(uint32_t index, State& state);
268
269 DISTRHO_DEPRECATED_BY("initState(uint32_t,State&)")
270 virtual void initState(uint32_t, String&, String&) {}
271
272 DISTRHO_DEPRECATED_BY("initState(uint32_t,State&)")
273 virtual bool isStateFile(uint32_t) { return false; }
274 #endif
275
276 /* --------------------------------------------------------------------------------------------------------
277 * Internal data */
278
279 /**
280 Get the current value of a parameter.@n
281 The host may call this function from any context, including realtime processing.
282 */
283 virtual float getParameterValue(uint32_t index) const;
284
285 /**
286 Change a parameter value.@n
287 The host may call this function from any context, including realtime processing.@n
288 When a parameter is marked as automatable, you must ensure no non-realtime operations are performed.
289 @note This function will only be called for parameter inputs.
290 */
291 virtual void setParameterValue(uint32_t index, float value);
292
293 #if DISTRHO_PLUGIN_WANT_PROGRAMS
294 /**
295 Load a program.@n
296 The host may call this function from any context, including realtime processing.@n
297 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled.
298 */
299 virtual void loadProgram(uint32_t index);
300 #endif
301
302 #if DISTRHO_PLUGIN_WANT_FULL_STATE
303 /**
304 Get the value of an internal state.@n
305 The host may call this function from any non-realtime context.@n
306 Must be implemented by your plugin class if DISTRHO_PLUGIN_WANT_FULL_STATE is enabled.
307 @note The use of this function breaks compatibility with the DSSI format.
308 */
309 virtual String getState(const char* key) const;
310 #endif
311
312 #if DISTRHO_PLUGIN_WANT_STATE
313 /**
314 Change an internal state @a key to @a value.@n
315 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled.
316 */
317 virtual void setState(const char* key, const char* value);
318 #endif
319
320 /* --------------------------------------------------------------------------------------------------------
321 * Audio/MIDI Processing */
322
323 /**
324 Activate this plugin.
325 */
326 virtual void activate() {}
327
328 /**
329 Deactivate this plugin.
330 */
331 virtual void deactivate() {}
332
333 #if DISTRHO_PLUGIN_WANT_MIDI_INPUT
334 /**
335 Run/process function for plugins with MIDI input.
336 @note Some parameters might be null if there are no audio inputs/outputs or MIDI events.
337 */
338 virtual void run(const float** inputs, float** outputs, uint32_t frames,
339 const MidiEvent* midiEvents, uint32_t midiEventCount) = 0;
340 #else
341 /**
342 Run/process function for plugins without MIDI input.
343 @note Some parameters might be null if there are no audio inputs or outputs.
344 */
345 virtual void run(const float** inputs, float** outputs, uint32_t frames) = 0;
346 #endif
347
348 /* --------------------------------------------------------------------------------------------------------
349 * Callbacks (optional) */
350
351 /**
352 Optional callback to inform the plugin about a buffer size change.@n
353 This function will only be called when the plugin is deactivated.
354 @note This value is only a hint!@n
355 Hosts might call run() with a higher or lower number of frames.
356 @see getBufferSize()
357 */
358 virtual void bufferSizeChanged(uint32_t newBufferSize);
359
360 /**
361 Optional callback to inform the plugin about a sample rate change.@n
362 This function will only be called when the plugin is deactivated.
363 @see getSampleRate()
364 */
365 virtual void sampleRateChanged(double newSampleRate);
366
367 // -------------------------------------------------------------------------------------------------------
368
369 private:
370 struct PrivateData;
371 PrivateData* const pData;
372 friend class PluginExporter;
373
374 DISTRHO_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(Plugin)
375 };
376
377 /** @} */
378
379 /* ------------------------------------------------------------------------------------------------------------
380 * Create plugin, entry point */
381
382 /**
383 @defgroup EntryPoints Entry Points
384 @{
385 */
386
387 /**
388 Create an instance of the Plugin class.@n
389 This is the entry point for DPF plugins.@n
390 DPF will call this to either create an instance of your plugin for the host
391 or to fetch some initial information for internal caching.
392 */
393 extern Plugin* createPlugin();
394
395 /** @} */
396
397 // -----------------------------------------------------------------------------------------------------------
398
399 END_NAMESPACE_DISTRHO
400
401 #endif // DISTRHO_PLUGIN_HPP_INCLUDED