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