DISTRHO Plugin Framework
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

DistrhoPlugin.hpp 26KB

8 years ago
8 years ago
7 years ago
8 years ago
8 years ago
8 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
5 years ago
8 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962
  1. /*
  2. * DISTRHO Plugin Framework (DPF)
  3. * Copyright (C) 2012-2020 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. #ifndef DISTRHO_PLUGIN_HPP_INCLUDED
  17. #define DISTRHO_PLUGIN_HPP_INCLUDED
  18. #include "extra/String.hpp"
  19. #include "extra/LeakDetector.hpp"
  20. #include "src/DistrhoPluginChecks.h"
  21. START_NAMESPACE_DISTRHO
  22. /* ------------------------------------------------------------------------------------------------------------
  23. * Audio Port Hints */
  24. /**
  25. @defgroup AudioPortHints Audio Port Hints
  26. Various audio port hints.
  27. @see AudioPort::hints
  28. @{
  29. */
  30. /**
  31. Audio port can be used as control voltage (LV2 and JACK standalone only).
  32. */
  33. static const uint32_t kAudioPortIsCV = 0x1;
  34. /**
  35. Audio port should be used as sidechan (LV2 only).
  36. */
  37. static const uint32_t kAudioPortIsSidechain = 0x2;
  38. /** @} */
  39. /* ------------------------------------------------------------------------------------------------------------
  40. * Parameter Hints */
  41. /**
  42. @defgroup ParameterHints Parameter Hints
  43. Various parameter hints.
  44. @see Parameter::hints
  45. @{
  46. */
  47. /**
  48. Parameter is automable (real-time safe).
  49. @see Plugin::setParameterValue(uint32_t, float)
  50. */
  51. static const uint32_t kParameterIsAutomable = 0x01;
  52. /**
  53. Parameter value is boolean.@n
  54. It's always at either minimum or maximum value.
  55. */
  56. static const uint32_t kParameterIsBoolean = 0x02;
  57. /**
  58. Parameter value is integer.
  59. */
  60. static const uint32_t kParameterIsInteger = 0x04;
  61. /**
  62. Parameter value is logarithmic.
  63. */
  64. static const uint32_t kParameterIsLogarithmic = 0x08;
  65. /**
  66. Parameter is of output type.@n
  67. When unset, parameter is assumed to be of input type.
  68. Parameter inputs are changed by the host and must not be changed by the plugin.@n
  69. The only exception being when changing programs, see Plugin::loadProgram().@n
  70. Outputs are changed by the plugin and never modified by the host.
  71. */
  72. static const uint32_t kParameterIsOutput = 0x10;
  73. /**
  74. Parameter value is a trigger.@n
  75. This means the value resets back to its default after each process/run call.@n
  76. Cannot be used for output parameters.
  77. @note Only officially supported under LV2. For other formats DPF simulates the behaviour.
  78. */
  79. static const uint32_t kParameterIsTrigger = 0x20 | kParameterIsBoolean;
  80. /** @} */
  81. /* ------------------------------------------------------------------------------------------------------------
  82. * Base Plugin structs */
  83. /**
  84. @defgroup BasePluginStructs Base Plugin Structs
  85. @{
  86. */
  87. /**
  88. Audio Port.
  89. Can be used as CV port by specifying kAudioPortIsCV in hints,@n
  90. but this is only supported in LV2 and JACK standalone formats.
  91. */
  92. struct AudioPort {
  93. /**
  94. Hints describing this audio port.
  95. @see AudioPortHints
  96. */
  97. uint32_t hints;
  98. /**
  99. The name of this audio port.@n
  100. An audio port name can contain any character, but hosts might have a hard time with non-ascii ones.@n
  101. The name doesn't have to be unique within a plugin instance, but it's recommended.
  102. */
  103. String name;
  104. /**
  105. The symbol of this audio port.@n
  106. An audio port symbol is a short restricted name used as a machine and human readable identifier.@n
  107. The first character must be one of _, a-z or A-Z and subsequent characters can be from _, a-z, A-Z and 0-9.
  108. @note Audio port and parameter symbols MUST be unique within a plugin instance.
  109. */
  110. String symbol;
  111. /**
  112. Default constructor for a regular audio port.
  113. */
  114. AudioPort() noexcept
  115. : hints(0x0),
  116. name(),
  117. symbol() {}
  118. };
  119. /**
  120. Parameter designation.@n
  121. Allows a parameter to be specially designated for a task, like bypass.
  122. Each designation is unique, there must be only one parameter that uses it.@n
  123. The use of designated parameters is completely optional.
  124. @note Designated parameters have strict ranges.
  125. @see ParameterRanges::adjustForDesignation()
  126. */
  127. enum ParameterDesignation {
  128. /**
  129. Null or unset designation.
  130. */
  131. kParameterDesignationNull = 0,
  132. /**
  133. Bypass designation.@n
  134. When on (> 0.5f), it means the plugin must run in a bypassed state.
  135. */
  136. kParameterDesignationBypass = 1
  137. };
  138. /**
  139. Parameter ranges.@n
  140. This is used to set the default, minimum and maximum values of a parameter.
  141. By default a parameter has 0.0 as minimum, 1.0 as maximum and 0.0 as default.@n
  142. When changing this struct values you must ensure maximum > minimum and default is within range.
  143. */
  144. struct ParameterRanges {
  145. /**
  146. Default value.
  147. */
  148. float def;
  149. /**
  150. Minimum value.
  151. */
  152. float min;
  153. /**
  154. Maximum value.
  155. */
  156. float max;
  157. /**
  158. Default constructor, using 0.0 as default, 0.0 as minimum, 1.0 as maximum.
  159. */
  160. ParameterRanges() noexcept
  161. : def(0.0f),
  162. min(0.0f),
  163. max(1.0f) {}
  164. /**
  165. Constructor using custom values.
  166. */
  167. ParameterRanges(float df, float mn, float mx) noexcept
  168. : def(df),
  169. min(mn),
  170. max(mx) {}
  171. /**
  172. Fix the default value within range.
  173. */
  174. void fixDefault() noexcept
  175. {
  176. fixValue(def);
  177. }
  178. /**
  179. Fix a value within range.
  180. */
  181. void fixValue(float& value) const noexcept
  182. {
  183. if (value < min)
  184. value = min;
  185. else if (value > max)
  186. value = max;
  187. }
  188. /**
  189. Get a fixed value within range.
  190. */
  191. float getFixedValue(const float& value) const noexcept
  192. {
  193. if (value <= min)
  194. return min;
  195. if (value >= max)
  196. return max;
  197. return value;
  198. }
  199. /**
  200. Get a value normalized to 0.0<->1.0.
  201. */
  202. float getNormalizedValue(const float& value) const noexcept
  203. {
  204. const float normValue((value - min) / (max - min));
  205. if (normValue <= 0.0f)
  206. return 0.0f;
  207. if (normValue >= 1.0f)
  208. return 1.0f;
  209. return normValue;
  210. }
  211. /**
  212. Get a value normalized to 0.0<->1.0, fixed within range.
  213. */
  214. float getFixedAndNormalizedValue(const float& value) const noexcept
  215. {
  216. if (value <= min)
  217. return 0.0f;
  218. if (value >= max)
  219. return 1.0f;
  220. const float normValue((value - min) / (max - min));
  221. if (normValue <= 0.0f)
  222. return 0.0f;
  223. if (normValue >= 1.0f)
  224. return 1.0f;
  225. return normValue;
  226. }
  227. /**
  228. Get a proper value previously normalized to 0.0<->1.0.
  229. */
  230. float getUnnormalizedValue(const float& value) const noexcept
  231. {
  232. if (value <= 0.0f)
  233. return min;
  234. if (value >= 1.0f)
  235. return max;
  236. return value * (max - min) + min;
  237. }
  238. };
  239. /**
  240. Parameter enumeration value.@n
  241. A string representation of a plugin parameter value.@n
  242. Used together can be used to give meaning to parameter values, working as an enumeration.
  243. */
  244. struct ParameterEnumerationValue {
  245. /**
  246. Parameter value.
  247. */
  248. float value;
  249. /**
  250. String representation of this value.
  251. */
  252. String label;
  253. /**
  254. Default constructor, using 0.0 as value and empty label.
  255. */
  256. ParameterEnumerationValue() noexcept
  257. : value(0.0f),
  258. label() {}
  259. /**
  260. Constructor using custom values.
  261. */
  262. ParameterEnumerationValue(float v, const char* l) noexcept
  263. : value(v),
  264. label(l) {}
  265. };
  266. /**
  267. Collection of parameter enumeration values.@n
  268. Handy class to handle the lifetime and count of all enumeration values.
  269. */
  270. struct ParameterEnumerationValues {
  271. /**
  272. Number of elements allocated in @values.
  273. */
  274. uint8_t count;
  275. /**
  276. Wherever the host is to be restricted to only use enumeration values.
  277. @note This mode is only a hint! Not all hosts and plugin formats support this mode.
  278. */
  279. bool restrictedMode;
  280. /**
  281. Array of @ParameterEnumerationValue items.@n
  282. This pointer must be null or have been allocated on the heap with `new`.
  283. */
  284. const ParameterEnumerationValue* values;
  285. /**
  286. Default constructor, for zero enumeration values.
  287. */
  288. ParameterEnumerationValues() noexcept
  289. : count(0),
  290. restrictedMode(false),
  291. values() {}
  292. /**
  293. Constructor using custom values.@n
  294. The pointer to @values must have been allocated on the heap with `new`.
  295. */
  296. ParameterEnumerationValues(uint32_t c, bool r, const ParameterEnumerationValue* v) noexcept
  297. : count(c),
  298. restrictedMode(r),
  299. values(v) {}
  300. ~ParameterEnumerationValues() noexcept
  301. {
  302. count = 0;
  303. restrictedMode = false;
  304. if (values != nullptr)
  305. {
  306. delete[] values;
  307. values = nullptr;
  308. }
  309. }
  310. DISTRHO_DECLARE_NON_COPY_STRUCT(ParameterEnumerationValues)
  311. };
  312. /**
  313. Parameter.
  314. */
  315. struct Parameter {
  316. /**
  317. Hints describing this parameter.
  318. @see ParameterHints
  319. */
  320. uint32_t hints;
  321. /**
  322. The name of this parameter.@n
  323. A parameter name can contain any character, but hosts might have a hard time with non-ascii ones.@n
  324. The name doesn't have to be unique within a plugin instance, but it's recommended.
  325. */
  326. String name;
  327. /**
  328. The short name of this parameter.@n
  329. Used when displaying the parameter name in a very limited space.
  330. @note This value is optional, the full name is used when the short one is missing.
  331. */
  332. String shortName;
  333. /**
  334. The symbol of this parameter.@n
  335. A parameter symbol is a short restricted name used as a machine and human readable identifier.@n
  336. The first character must be one of _, a-z or A-Z and subsequent characters can be from _, a-z, A-Z and 0-9.
  337. @note Parameter symbols MUST be unique within a plugin instance.
  338. */
  339. String symbol;
  340. /**
  341. The unit of this parameter.@n
  342. This means something like "dB", "kHz" and "ms".@n
  343. Can be left blank if a unit does not apply to this parameter.
  344. */
  345. String unit;
  346. /**
  347. An extensive description/comment about the parameter.
  348. @note This value is optional and only used for LV2.
  349. */
  350. String description;
  351. /**
  352. Ranges of this parameter.@n
  353. The ranges describe the default, minimum and maximum values.
  354. */
  355. ParameterRanges ranges;
  356. /**
  357. Enumeration values.@n
  358. Can be used to give meaning to parameter values, working as an enumeration.
  359. */
  360. ParameterEnumerationValues enumValues;
  361. /**
  362. Designation for this parameter.
  363. */
  364. ParameterDesignation designation;
  365. /**
  366. MIDI CC to use by default on this parameter.@n
  367. A value of 0 or 32 (bank change) is considered invalid.@n
  368. Must also be less or equal to 120.
  369. @note This value is only a hint! Hosts might map it automatically or completely ignore it.
  370. */
  371. uint8_t midiCC;
  372. /**
  373. Default constructor for a null parameter.
  374. */
  375. Parameter() noexcept
  376. : hints(0x0),
  377. name(),
  378. shortName(),
  379. symbol(),
  380. unit(),
  381. ranges(),
  382. enumValues(),
  383. designation(kParameterDesignationNull),
  384. midiCC(0) {}
  385. /**
  386. Constructor using custom values.
  387. */
  388. Parameter(uint32_t h, const char* n, const char* s, const char* u, float def, float min, float max) noexcept
  389. : hints(h),
  390. name(n),
  391. shortName(),
  392. symbol(s),
  393. unit(u),
  394. ranges(def, min, max),
  395. enumValues(),
  396. designation(kParameterDesignationNull),
  397. midiCC(0) {}
  398. /**
  399. Initialize a parameter for a specific designation.
  400. */
  401. void initDesignation(ParameterDesignation d) noexcept
  402. {
  403. designation = d;
  404. switch (d)
  405. {
  406. case kParameterDesignationNull:
  407. break;
  408. case kParameterDesignationBypass:
  409. hints = kParameterIsAutomable|kParameterIsBoolean|kParameterIsInteger;
  410. name = "Bypass";
  411. shortName = "Bypass";
  412. symbol = "dpf_bypass";
  413. unit = "";
  414. midiCC = 0;
  415. ranges.def = 0.0f;
  416. ranges.min = 0.0f;
  417. ranges.max = 1.0f;
  418. break;
  419. }
  420. }
  421. };
  422. /**
  423. MIDI event.
  424. */
  425. struct MidiEvent {
  426. /**
  427. Size of internal data.
  428. */
  429. static const uint32_t kDataSize = 4;
  430. /**
  431. Time offset in frames.
  432. */
  433. uint32_t frame;
  434. /**
  435. Number of bytes used.
  436. */
  437. uint32_t size;
  438. /**
  439. MIDI data.@n
  440. If size > kDataSize, dataExt is used (otherwise null).
  441. */
  442. uint8_t data[kDataSize];
  443. const uint8_t* dataExt;
  444. };
  445. /**
  446. Time position.@n
  447. The @a playing and @a frame values are always valid.@n
  448. BBT values are only valid when @a bbt.valid is true.
  449. This struct is inspired by the JACK Transport API.
  450. */
  451. struct TimePosition {
  452. /**
  453. Wherever the host transport is playing/rolling.
  454. */
  455. bool playing;
  456. /**
  457. Current host transport position in frames.
  458. */
  459. uint64_t frame;
  460. /**
  461. Bar-Beat-Tick time position.
  462. */
  463. struct BarBeatTick {
  464. /**
  465. Wherever the host transport is using BBT.@n
  466. If false you must not read from this struct.
  467. */
  468. bool valid;
  469. /**
  470. Current bar.@n
  471. Should always be > 0.@n
  472. The first bar is bar '1'.
  473. */
  474. int32_t bar;
  475. /**
  476. Current beat within bar.@n
  477. Should always be > 0 and <= @a beatsPerBar.@n
  478. The first beat is beat '1'.
  479. */
  480. int32_t beat;
  481. /**
  482. Current tick within beat.@n
  483. Should always be >= 0 and < @a ticksPerBeat.@n
  484. The first tick is tick '0'.
  485. */
  486. int32_t tick;
  487. /**
  488. Number of ticks that have elapsed between frame 0 and the first beat of the current measure.
  489. */
  490. double barStartTick;
  491. /**
  492. Time signature "numerator".
  493. */
  494. float beatsPerBar;
  495. /**
  496. Time signature "denominator".
  497. */
  498. float beatType;
  499. /**
  500. Number of ticks within a beat.@n
  501. Usually a moderately large integer with many denominators, such as 1920.0.
  502. */
  503. double ticksPerBeat;
  504. /**
  505. Number of beats per minute.
  506. */
  507. double beatsPerMinute;
  508. /**
  509. Default constructor for a null BBT time position.
  510. */
  511. BarBeatTick() noexcept
  512. : valid(false),
  513. bar(0),
  514. beat(0),
  515. tick(0),
  516. barStartTick(0.0),
  517. beatsPerBar(0.0f),
  518. beatType(0.0f),
  519. ticksPerBeat(0.0),
  520. beatsPerMinute(0.0) {}
  521. /**
  522. Reinitialize this position using the default null initialization.
  523. */
  524. void clear() noexcept
  525. {
  526. valid = false;
  527. bar = 0;
  528. beat = 0;
  529. tick = 0;
  530. barStartTick = 0.0;
  531. beatsPerBar = 0.0f;
  532. beatType = 0.0f;
  533. ticksPerBeat = 0.0;
  534. beatsPerMinute = 0.0;
  535. }
  536. } bbt;
  537. /**
  538. Default constructor for a time position.
  539. */
  540. TimePosition() noexcept
  541. : playing(false),
  542. frame(0),
  543. bbt() {}
  544. /**
  545. Reinitialize this position using the default null initialization.
  546. */
  547. void clear() noexcept
  548. {
  549. playing = false;
  550. frame = 0;
  551. bbt.clear();
  552. }
  553. };
  554. /** @} */
  555. /* ------------------------------------------------------------------------------------------------------------
  556. * DPF Plugin */
  557. /**
  558. @defgroup MainClasses Main Classes
  559. @{
  560. */
  561. /**
  562. DPF Plugin class from where plugin instances are created.
  563. The public methods (Host state) are called from the plugin to get or set host information.@n
  564. They can be called from a plugin instance at anytime unless stated otherwise.@n
  565. All other methods are to be implemented by the plugin and will be called by the host.
  566. Shortly after a plugin instance is created, the various init* functions will be called by the host.@n
  567. Host will call activate() before run(), and deactivate() before the plugin instance is destroyed.@n
  568. The host may call deactivate right after activate and vice-versa, but never activate/deactivate consecutively.@n
  569. There is no limit on how many times run() is called, only that activate/deactivate will be called in between.
  570. The buffer size and sample rate values will remain constant between activate and deactivate.@n
  571. Buffer size is only a hint though, the host might call run() with a higher or lower number of frames.
  572. Some of this class functions are only available according to some macros.
  573. DISTRHO_PLUGIN_WANT_PROGRAMS activates program related features.@n
  574. When enabled you need to implement initProgramName() and loadProgram().
  575. DISTRHO_PLUGIN_WANT_STATE activates internal state features.@n
  576. When enabled you need to implement initStateKey() and setState().
  577. The process function run() changes wherever DISTRHO_PLUGIN_WANT_MIDI_INPUT is enabled or not.@n
  578. When enabled it provides midi input events.
  579. */
  580. class Plugin
  581. {
  582. public:
  583. /**
  584. Plugin class constructor.@n
  585. You must set all parameter values to their defaults, matching ParameterRanges::def.
  586. */
  587. Plugin(uint32_t parameterCount, uint32_t programCount, uint32_t stateCount);
  588. /**
  589. Destructor.
  590. */
  591. virtual ~Plugin();
  592. /* --------------------------------------------------------------------------------------------------------
  593. * Host state */
  594. /**
  595. Get the current buffer size that will probably be used during processing, in frames.@n
  596. This value will remain constant between activate and deactivate.
  597. @note This value is only a hint!@n
  598. Hosts might call run() with a higher or lower number of frames.
  599. @see bufferSizeChanged(uint32_t)
  600. */
  601. uint32_t getBufferSize() const noexcept;
  602. /**
  603. Get the current sample rate that will be used during processing.@n
  604. This value will remain constant between activate and deactivate.
  605. @see sampleRateChanged(double)
  606. */
  607. double getSampleRate() const noexcept;
  608. #if DISTRHO_PLUGIN_WANT_TIMEPOS
  609. /**
  610. Get the current host transport time position.@n
  611. This function should only be called during run().@n
  612. You can call this during other times, but the returned position is not guaranteed to be in sync.
  613. @note TimePosition is not supported in LADSPA and DSSI plugin formats.
  614. */
  615. const TimePosition& getTimePosition() const noexcept;
  616. #endif
  617. #if DISTRHO_PLUGIN_WANT_LATENCY
  618. /**
  619. Change the plugin audio output latency to @a frames.@n
  620. This function should only be called in the constructor, activate() and run().
  621. @note This function is only available if DISTRHO_PLUGIN_WANT_LATENCY is enabled.
  622. */
  623. void setLatency(uint32_t frames) noexcept;
  624. #endif
  625. #if DISTRHO_PLUGIN_WANT_MIDI_OUTPUT
  626. /**
  627. Write a MIDI output event.@n
  628. This function must only be called during run().@n
  629. Returns false when the host buffer is full, in which case do not call this again until the next run().
  630. */
  631. bool writeMidiEvent(const MidiEvent& midiEvent) noexcept;
  632. #endif
  633. protected:
  634. /* --------------------------------------------------------------------------------------------------------
  635. * Information */
  636. /**
  637. Get the plugin name.@n
  638. Returns DISTRHO_PLUGIN_NAME by default.
  639. */
  640. virtual const char* getName() const { return DISTRHO_PLUGIN_NAME; }
  641. /**
  642. Get the plugin label.@n
  643. This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters.
  644. */
  645. virtual const char* getLabel() const = 0;
  646. /**
  647. Get an extensive comment/description about the plugin.@n
  648. Optional, returns nothing by default.
  649. */
  650. virtual const char* getDescription() const { return ""; }
  651. /**
  652. Get the plugin author/maker.
  653. */
  654. virtual const char* getMaker() const = 0;
  655. /**
  656. Get the plugin homepage.@n
  657. Optional, returns nothing by default.
  658. */
  659. virtual const char* getHomePage() const { return ""; }
  660. /**
  661. Get the plugin license (a single line of text or a URL).@n
  662. For commercial plugins this should return some short copyright information.
  663. */
  664. virtual const char* getLicense() const = 0;
  665. /**
  666. Get the plugin version, in hexadecimal.
  667. @see d_version()
  668. */
  669. virtual uint32_t getVersion() const = 0;
  670. /**
  671. Get the plugin unique Id.@n
  672. This value is used by LADSPA, DSSI and VST plugin formats.
  673. @see d_cconst()
  674. */
  675. virtual int64_t getUniqueId() const = 0;
  676. /* --------------------------------------------------------------------------------------------------------
  677. * Init */
  678. /**
  679. Initialize the audio port @a index.@n
  680. This function will be called once, shortly after the plugin is created.
  681. */
  682. virtual void initAudioPort(bool input, uint32_t index, AudioPort& port);
  683. /**
  684. Initialize the parameter @a index.@n
  685. This function will be called once, shortly after the plugin is created.
  686. */
  687. virtual void initParameter(uint32_t index, Parameter& parameter) = 0;
  688. #if DISTRHO_PLUGIN_WANT_PROGRAMS
  689. /**
  690. Set the name of the program @a index.@n
  691. This function will be called once, shortly after the plugin is created.@n
  692. Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled.
  693. */
  694. virtual void initProgramName(uint32_t index, String& programName) = 0;
  695. #endif
  696. #if DISTRHO_PLUGIN_WANT_STATE
  697. /**
  698. Set the state key and default value of @a index.@n
  699. This function will be called once, shortly after the plugin is created.@n
  700. Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled.
  701. */
  702. virtual void initState(uint32_t index, String& stateKey, String& defaultStateValue) = 0;
  703. #endif
  704. #if DISTRHO_PLUGIN_WANT_STATEFILES
  705. /**
  706. TODO API under construction
  707. */
  708. virtual bool isStateFile(uint32_t index) = 0;
  709. #endif
  710. /* --------------------------------------------------------------------------------------------------------
  711. * Internal data */
  712. /**
  713. Get the current value of a parameter.@n
  714. The host may call this function from any context, including realtime processing.
  715. */
  716. virtual float getParameterValue(uint32_t index) const = 0;
  717. /**
  718. Change a parameter value.@n
  719. The host may call this function from any context, including realtime processing.@n
  720. When a parameter is marked as automable, you must ensure no non-realtime operations are performed.
  721. @note This function will only be called for parameter inputs.
  722. */
  723. virtual void setParameterValue(uint32_t index, float value) = 0;
  724. #if DISTRHO_PLUGIN_WANT_PROGRAMS
  725. /**
  726. Load a program.@n
  727. The host may call this function from any context, including realtime processing.@n
  728. Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled.
  729. */
  730. virtual void loadProgram(uint32_t index) = 0;
  731. #endif
  732. #if DISTRHO_PLUGIN_WANT_FULL_STATE
  733. /**
  734. Get the value of an internal state.@n
  735. The host may call this function from any non-realtime context.@n
  736. Must be implemented by your plugin class if DISTRHO_PLUGIN_WANT_FULL_STATE is enabled.
  737. @note The use of this function breaks compatibility with the DSSI format.
  738. */
  739. virtual String getState(const char* key) const = 0;
  740. #endif
  741. #if DISTRHO_PLUGIN_WANT_STATE
  742. /**
  743. Change an internal state @a key to @a value.@n
  744. Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled.
  745. */
  746. virtual void setState(const char* key, const char* value) = 0;
  747. #endif
  748. /* --------------------------------------------------------------------------------------------------------
  749. * Audio/MIDI Processing */
  750. /**
  751. Activate this plugin.
  752. */
  753. virtual void activate() {}
  754. /**
  755. Deactivate this plugin.
  756. */
  757. virtual void deactivate() {}
  758. #if DISTRHO_PLUGIN_WANT_MIDI_INPUT
  759. /**
  760. Run/process function for plugins with MIDI input.
  761. @note Some parameters might be null if there are no audio inputs/outputs or MIDI events.
  762. */
  763. virtual void run(const float** inputs, float** outputs, uint32_t frames,
  764. const MidiEvent* midiEvents, uint32_t midiEventCount) = 0;
  765. #else
  766. /**
  767. Run/process function for plugins without MIDI input.
  768. @note Some parameters might be null if there are no audio inputs or outputs.
  769. */
  770. virtual void run(const float** inputs, float** outputs, uint32_t frames) = 0;
  771. #endif
  772. /* --------------------------------------------------------------------------------------------------------
  773. * Callbacks (optional) */
  774. /**
  775. Optional callback to inform the plugin about a buffer size change.@n
  776. This function will only be called when the plugin is deactivated.
  777. @note This value is only a hint!@n
  778. Hosts might call run() with a higher or lower number of frames.
  779. @see getBufferSize()
  780. */
  781. virtual void bufferSizeChanged(uint32_t newBufferSize);
  782. /**
  783. Optional callback to inform the plugin about a sample rate change.@n
  784. This function will only be called when the plugin is deactivated.
  785. @see getSampleRate()
  786. */
  787. virtual void sampleRateChanged(double newSampleRate);
  788. // -------------------------------------------------------------------------------------------------------
  789. private:
  790. struct PrivateData;
  791. PrivateData* const pData;
  792. friend class PluginExporter;
  793. DISTRHO_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(Plugin)
  794. };
  795. /** @} */
  796. /* ------------------------------------------------------------------------------------------------------------
  797. * Create plugin, entry point */
  798. /**
  799. @defgroup EntryPoints Entry Points
  800. @{
  801. */
  802. /**
  803. TODO.
  804. */
  805. extern Plugin* createPlugin();
  806. /** @} */
  807. // -----------------------------------------------------------------------------------------------------------
  808. END_NAMESPACE_DISTRHO
  809. #endif // DISTRHO_PLUGIN_HPP_INCLUDED