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 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 DISTRHO_DECLARE_NON_COPY_STRUCT(ParameterEnumerationValues) 370 }; 371 372 /** 373 Parameter. 374 */ 375 struct Parameter { 376 /** 377 Hints describing this parameter. 378 @see ParameterHints 379 */ 380 uint32_t hints; 381 382 /** 383 The name of this parameter.@n 384 A parameter name can contain any character, but hosts might have a hard time with non-ascii ones.@n 385 The name doesn't have to be unique within a plugin instance, but it's recommended. 386 */ 387 String name; 388 389 /** 390 The short name of this parameter.@n 391 Used when displaying the parameter name in a very limited space. 392 @note This value is optional, the full name is used when the short one is missing. 393 */ 394 String shortName; 395 396 /** 397 The symbol of this parameter.@n 398 A parameter symbol is a short restricted name used as a machine and human readable identifier.@n 399 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. 400 @note Parameter symbols MUST be unique within a plugin instance. 401 */ 402 String symbol; 403 404 /** 405 The unit of this parameter.@n 406 This means something like "dB", "kHz" and "ms".@n 407 Can be left blank if a unit does not apply to this parameter. 408 */ 409 String unit; 410 411 /** 412 An extensive description/comment about the parameter. 413 @note This value is optional and only used for LV2. 414 */ 415 String description; 416 417 /** 418 Ranges of this parameter.@n 419 The ranges describe the default, minimum and maximum values. 420 */ 421 ParameterRanges ranges; 422 423 /** 424 Enumeration values.@n 425 Can be used to give meaning to parameter values, working as an enumeration. 426 */ 427 ParameterEnumerationValues enumValues; 428 429 /** 430 Designation for this parameter. 431 */ 432 ParameterDesignation designation; 433 434 /** 435 MIDI CC to use by default on this parameter.@n 436 A value of 0 or 32 (bank change) is considered invalid.@n 437 Must also be less or equal to 120. 438 @note This value is only a hint! Hosts might map it automatically or completely ignore it. 439 */ 440 uint8_t midiCC; 441 442 /** 443 Default constructor for a null parameter. 444 */ ParameterParameter445 Parameter() noexcept 446 : hints(0x0), 447 name(), 448 shortName(), 449 symbol(), 450 unit(), 451 ranges(), 452 enumValues(), 453 designation(kParameterDesignationNull), 454 midiCC(0) {} 455 456 /** 457 Constructor using custom values. 458 */ ParameterParameter459 Parameter(uint32_t h, const char* n, const char* s, const char* u, float def, float min, float max) noexcept 460 : hints(h), 461 name(n), 462 shortName(), 463 symbol(s), 464 unit(u), 465 ranges(def, min, max), 466 enumValues(), 467 designation(kParameterDesignationNull), 468 midiCC(0) {} 469 470 /** 471 Initialize a parameter for a specific designation. 472 */ initDesignationParameter473 void initDesignation(ParameterDesignation d) noexcept 474 { 475 designation = d; 476 477 switch (d) 478 { 479 case kParameterDesignationNull: 480 break; 481 case kParameterDesignationBypass: 482 hints = kParameterIsAutomable|kParameterIsBoolean|kParameterIsInteger; 483 name = "Bypass"; 484 shortName = "Bypass"; 485 symbol = "dpf_bypass"; 486 unit = ""; 487 midiCC = 0; 488 ranges.def = 0.0f; 489 ranges.min = 0.0f; 490 ranges.max = 1.0f; 491 break; 492 } 493 } 494 }; 495 496 /** 497 MIDI event. 498 */ 499 struct MidiEvent { 500 /** 501 Size of internal data. 502 */ 503 static const uint32_t kDataSize = 4; 504 505 /** 506 Time offset in frames. 507 */ 508 uint32_t frame; 509 510 /** 511 Number of bytes used. 512 */ 513 uint32_t size; 514 515 /** 516 MIDI data.@n 517 If size > kDataSize, dataExt is used (otherwise null). 518 */ 519 uint8_t data[kDataSize]; 520 const uint8_t* dataExt; 521 }; 522 523 /** 524 Time position.@n 525 The @a playing and @a frame values are always valid.@n 526 BBT values are only valid when @a bbt.valid is true. 527 528 This struct is inspired by the JACK Transport API. 529 */ 530 struct TimePosition { 531 /** 532 Wherever the host transport is playing/rolling. 533 */ 534 bool playing; 535 536 /** 537 Current host transport position in frames. 538 */ 539 uint64_t frame; 540 541 /** 542 Bar-Beat-Tick time position. 543 */ 544 struct BarBeatTick { 545 /** 546 Wherever the host transport is using BBT.@n 547 If false you must not read from this struct. 548 */ 549 bool valid; 550 551 /** 552 Current bar.@n 553 Should always be > 0.@n 554 The first bar is bar '1'. 555 */ 556 int32_t bar; 557 558 /** 559 Current beat within bar.@n 560 Should always be > 0 and <= @a beatsPerBar.@n 561 The first beat is beat '1'. 562 */ 563 int32_t beat; 564 565 /** 566 Current tick within beat.@n 567 Should always be >= 0 and < @a ticksPerBeat.@n 568 The first tick is tick '0'. 569 */ 570 int32_t tick; 571 572 /** 573 Number of ticks that have elapsed between frame 0 and the first beat of the current measure. 574 */ 575 double barStartTick; 576 577 /** 578 Time signature "numerator". 579 */ 580 float beatsPerBar; 581 582 /** 583 Time signature "denominator". 584 */ 585 float beatType; 586 587 /** 588 Number of ticks within a beat.@n 589 Usually a moderately large integer with many denominators, such as 1920.0. 590 */ 591 double ticksPerBeat; 592 593 /** 594 Number of beats per minute. 595 */ 596 double beatsPerMinute; 597 598 /** 599 Default constructor for a null BBT time position. 600 */ BarBeatTickTimePosition::BarBeatTick601 BarBeatTick() noexcept 602 : valid(false), 603 bar(0), 604 beat(0), 605 tick(0), 606 barStartTick(0.0), 607 beatsPerBar(0.0f), 608 beatType(0.0f), 609 ticksPerBeat(0.0), 610 beatsPerMinute(0.0) {} 611 612 /** 613 Reinitialize this position using the default null initialization. 614 */ clearTimePosition::BarBeatTick615 void clear() noexcept 616 { 617 valid = false; 618 bar = 0; 619 beat = 0; 620 tick = 0; 621 barStartTick = 0.0; 622 beatsPerBar = 0.0f; 623 beatType = 0.0f; 624 ticksPerBeat = 0.0; 625 beatsPerMinute = 0.0; 626 } 627 } bbt; 628 629 /** 630 Default constructor for a time position. 631 */ TimePositionTimePosition632 TimePosition() noexcept 633 : playing(false), 634 frame(0), 635 bbt() {} 636 637 /** 638 Reinitialize this position using the default null initialization. 639 */ clearTimePosition640 void clear() noexcept 641 { 642 playing = false; 643 frame = 0; 644 bbt.clear(); 645 } 646 }; 647 648 /** @} */ 649 650 /* ------------------------------------------------------------------------------------------------------------ 651 * DPF Plugin */ 652 653 /** 654 @defgroup MainClasses Main Classes 655 @{ 656 */ 657 658 /** 659 DPF Plugin class from where plugin instances are created. 660 661 The public methods (Host state) are called from the plugin to get or set host information.@n 662 They can be called from a plugin instance at anytime unless stated otherwise.@n 663 All other methods are to be implemented by the plugin and will be called by the host. 664 665 Shortly after a plugin instance is created, the various init* functions will be called by the host.@n 666 Host will call activate() before run(), and deactivate() before the plugin instance is destroyed.@n 667 The host may call deactivate right after activate and vice-versa, but never activate/deactivate consecutively.@n 668 There is no limit on how many times run() is called, only that activate/deactivate will be called in between. 669 670 The buffer size and sample rate values will remain constant between activate and deactivate.@n 671 Buffer size is only a hint though, the host might call run() with a higher or lower number of frames. 672 673 Some of this class functions are only available according to some macros. 674 675 DISTRHO_PLUGIN_WANT_PROGRAMS activates program related features.@n 676 When enabled you need to implement initProgramName() and loadProgram(). 677 678 DISTRHO_PLUGIN_WANT_STATE activates internal state features.@n 679 When enabled you need to implement initStateKey() and setState(). 680 681 The process function run() changes wherever DISTRHO_PLUGIN_WANT_MIDI_INPUT is enabled or not.@n 682 When enabled it provides midi input events. 683 */ 684 class Plugin 685 { 686 public: 687 /** 688 Plugin class constructor.@n 689 You must set all parameter values to their defaults, matching ParameterRanges::def. 690 */ 691 Plugin(uint32_t parameterCount, uint32_t programCount, uint32_t stateCount); 692 693 /** 694 Destructor. 695 */ 696 virtual ~Plugin(); 697 698 /* -------------------------------------------------------------------------------------------------------- 699 * Host state */ 700 701 /** 702 Get the current buffer size that will probably be used during processing, in frames.@n 703 This value will remain constant between activate and deactivate. 704 @note This value is only a hint!@n 705 Hosts might call run() with a higher or lower number of frames. 706 @see bufferSizeChanged(uint32_t) 707 */ 708 uint32_t getBufferSize() const noexcept; 709 710 /** 711 Get the current sample rate that will be used during processing.@n 712 This value will remain constant between activate and deactivate. 713 @see sampleRateChanged(double) 714 */ 715 double getSampleRate() const noexcept; 716 717 #if DISTRHO_PLUGIN_WANT_TIMEPOS 718 /** 719 Get the current host transport time position.@n 720 This function should only be called during run().@n 721 You can call this during other times, but the returned position is not guaranteed to be in sync. 722 @note TimePosition is not supported in LADSPA and DSSI plugin formats. 723 */ 724 const TimePosition& getTimePosition() const noexcept; 725 #endif 726 727 #if DISTRHO_PLUGIN_WANT_LATENCY 728 /** 729 Change the plugin audio output latency to @a frames.@n 730 This function should only be called in the constructor, activate() and run(). 731 @note This function is only available if DISTRHO_PLUGIN_WANT_LATENCY is enabled. 732 */ 733 void setLatency(uint32_t frames) noexcept; 734 #endif 735 736 #if DISTRHO_PLUGIN_WANT_MIDI_OUTPUT 737 /** 738 Write a MIDI output event.@n 739 This function must only be called during run().@n 740 Returns false when the host buffer is full, in which case do not call this again until the next run(). 741 */ 742 bool writeMidiEvent(const MidiEvent& midiEvent) noexcept; 743 #endif 744 745 protected: 746 /* -------------------------------------------------------------------------------------------------------- 747 * Information */ 748 749 /** 750 Get the plugin name.@n 751 Returns DISTRHO_PLUGIN_NAME by default. 752 */ getName() const753 virtual const char* getName() const { return DISTRHO_PLUGIN_NAME; } 754 755 /** 756 Get the plugin label.@n 757 This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters. 758 */ 759 virtual const char* getLabel() const = 0; 760 761 /** 762 Get an extensive comment/description about the plugin.@n 763 Optional, returns nothing by default. 764 */ getDescription() const765 virtual const char* getDescription() const { return ""; } 766 767 /** 768 Get the plugin author/maker. 769 */ 770 virtual const char* getMaker() const = 0; 771 772 /** 773 Get the plugin homepage.@n 774 Optional, returns nothing by default. 775 */ getHomePage() const776 virtual const char* getHomePage() const { return ""; } 777 778 /** 779 Get the plugin license (a single line of text or a URL).@n 780 For commercial plugins this should return some short copyright information. 781 */ 782 virtual const char* getLicense() const = 0; 783 784 /** 785 Get the plugin version, in hexadecimal. 786 @see d_version() 787 */ 788 virtual uint32_t getVersion() const = 0; 789 790 /** 791 Get the plugin unique Id.@n 792 This value is used by LADSPA, DSSI and VST plugin formats. 793 @see d_cconst() 794 */ 795 virtual int64_t getUniqueId() const = 0; 796 797 /* -------------------------------------------------------------------------------------------------------- 798 * Init */ 799 800 /** 801 Initialize the audio port @a index.@n 802 This function will be called once, shortly after the plugin is created. 803 */ 804 virtual void initAudioPort(bool input, uint32_t index, AudioPort& port); 805 806 /** 807 Initialize the parameter @a index.@n 808 This function will be called once, shortly after the plugin is created. 809 */ 810 virtual void initParameter(uint32_t index, Parameter& parameter) = 0; 811 812 #if DISTRHO_PLUGIN_WANT_PROGRAMS 813 /** 814 Set the name of the program @a index.@n 815 This function will be called once, shortly after the plugin is created.@n 816 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled. 817 */ 818 virtual void initProgramName(uint32_t index, String& programName) = 0; 819 #endif 820 821 #if DISTRHO_PLUGIN_WANT_STATE 822 /** 823 Set the state key and default value of @a index.@n 824 This function will be called once, shortly after the plugin is created.@n 825 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled. 826 */ 827 virtual void initState(uint32_t index, String& stateKey, String& defaultStateValue) = 0; 828 #endif 829 830 /* -------------------------------------------------------------------------------------------------------- 831 * Internal data */ 832 833 /** 834 Get the current value of a parameter.@n 835 The host may call this function from any context, including realtime processing. 836 */ 837 virtual float getParameterValue(uint32_t index) const = 0; 838 839 /** 840 Change a parameter value.@n 841 The host may call this function from any context, including realtime processing.@n 842 When a parameter is marked as automable, you must ensure no non-realtime operations are performed. 843 @note This function will only be called for parameter inputs. 844 */ 845 virtual void setParameterValue(uint32_t index, float value) = 0; 846 847 #if DISTRHO_PLUGIN_WANT_PROGRAMS 848 /** 849 Load a program.@n 850 The host may call this function from any context, including realtime processing.@n 851 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled. 852 */ 853 virtual void loadProgram(uint32_t index) = 0; 854 #endif 855 856 #if DISTRHO_PLUGIN_WANT_FULL_STATE 857 /** 858 Get the value of an internal state.@n 859 The host may call this function from any non-realtime context.@n 860 Must be implemented by your plugin class if DISTRHO_PLUGIN_WANT_FULL_STATE is enabled. 861 @note The use of this function breaks compatibility with the DSSI format. 862 */ 863 virtual String getState(const char* key) const = 0; 864 #endif 865 866 #if DISTRHO_PLUGIN_WANT_STATE 867 /** 868 Change an internal state @a key to @a value.@n 869 Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled. 870 */ 871 virtual void setState(const char* key, const char* value) = 0; 872 #endif 873 874 /* -------------------------------------------------------------------------------------------------------- 875 * Audio/MIDI Processing */ 876 877 /** 878 Activate this plugin. 879 */ activate()880 virtual void activate() {} 881 882 /** 883 Deactivate this plugin. 884 */ deactivate()885 virtual void deactivate() {} 886 887 #if DISTRHO_PLUGIN_WANT_MIDI_INPUT 888 /** 889 Run/process function for plugins with MIDI input. 890 @note Some parameters might be null if there are no audio inputs/outputs or MIDI events. 891 */ 892 virtual void run(const float** inputs, float** outputs, uint32_t frames, 893 const MidiEvent* midiEvents, uint32_t midiEventCount) = 0; 894 #else 895 /** 896 Run/process function for plugins without MIDI input. 897 @note Some parameters might be null if there are no audio inputs or outputs. 898 */ 899 virtual void run(const float** inputs, float** outputs, uint32_t frames) = 0; 900 #endif 901 902 /* -------------------------------------------------------------------------------------------------------- 903 * Callbacks (optional) */ 904 905 /** 906 Optional callback to inform the plugin about a buffer size change.@n 907 This function will only be called when the plugin is deactivated. 908 @note This value is only a hint!@n 909 Hosts might call run() with a higher or lower number of frames. 910 @see getBufferSize() 911 */ 912 virtual void bufferSizeChanged(uint32_t newBufferSize); 913 914 /** 915 Optional callback to inform the plugin about a sample rate change.@n 916 This function will only be called when the plugin is deactivated. 917 @see getSampleRate() 918 */ 919 virtual void sampleRateChanged(double newSampleRate); 920 921 // ------------------------------------------------------------------------------------------------------- 922 923 private: 924 struct PrivateData; 925 PrivateData* const pData; 926 friend class PluginExporter; 927 928 DISTRHO_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(Plugin) 929 }; 930 931 /** @} */ 932 933 /* ------------------------------------------------------------------------------------------------------------ 934 * Create plugin, entry point */ 935 936 /** 937 @defgroup EntryPoints Entry Points 938 @{ 939 */ 940 941 /** 942 TODO. 943 */ 944 extern Plugin* createPlugin(); 945 946 /** @} */ 947 948 // ----------------------------------------------------------------------------------------------------------- 949 950 END_NAMESPACE_DISTRHO 951 952 #endif // DISTRHO_PLUGIN_HPP_INCLUDED 953