diff --git a/distrho/DistrhoInfo.hpp b/distrho/DistrhoInfo.hpp new file mode 100644 index 00000000..61c1e098 --- /dev/null +++ b/distrho/DistrhoInfo.hpp @@ -0,0 +1,571 @@ +/* + * DISTRHO Plugin Framework (DPF) + * Copyright (C) 2012-2015 Filipe Coelho + * + * Permission to use, copy, modify, and/or distribute this software for any purpose with + * or without fee is hereby granted, provided that the above copyright notice and this + * permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD + * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN + * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL + * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER + * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#ifdef DOXYGEN + +#include "src/DistrhoDefines.h" + +START_NAMESPACE_DISTRHO + +/* ------------------------------------------------------------------------------------------------------------ + * Intro */ + +/** + @mainpage DISTRHO %Plugin Framework + + DISTRHO %Plugin Framework (or @b DPF for short) + is a plugin framework designed to make development of new plugins an easy and enjoyable task.@n + It allows developers to create plugins with custom UIs using a simple C++ API.@n + The framework facilitates exporting various different plugin formats from the same code-base. + + DPF can build for LADSPA, DSSI, LV2 and VST2 formats.@n + A JACK/Standalone mode is also available, allowing you to quickly test plugins. + + @section Macros + You start by creating a "DistrhoPluginInfo.h" file describing the plugin via macros, see @ref PluginMacros.@n + This file is included in the main DPF code to select which features to activate for each plugin format. + + For example, a plugin (with %UI) that use states will require LV2 hosts to support Atom and Worker extensions for + message passing from the %UI to the plugin.@n + If your plugin does not make use of states, the Worker extension is not set as a required feature. + + @section Plugin + The next step is to create your plugin code by subclassing DPF's Plugin class.@n + You need to pass the number of parameters in the constructor and also the number of programs and states, if any. + + Here's an example of an audio plugin that simply mutes the host output: + @code + class MutePlugin : public Plugin + { + public: + /** + Plugin class constructor. + */ + MutePlugin() + : Plugin(0, 0, 0) // 0 parameters, 0 programs and 0 states + { + } + + protected: + /* ---------------------------------------------------------------------------------------- + * Information */ + + /** + Get the plugin label. + This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters. + */ + const char* getLabel() const override + { + return "Mute"; + } + + /** + Get the plugin author/maker. + */ + const char* getMaker() const override + { + return "DPF"; + } + + /** + Get the plugin license name (a single line of text). + For commercial plugins this should return some short copyright information. + */ + const char* getLicense() const override + { + return "MIT"; + } + + /** + Get the plugin version, in hexadecimal. + TODO format to be defined + */ + uint32_t getVersion() const override + { + return 0x1000; + } + + /** + Get the plugin unique Id. + This value is used by LADSPA, DSSI and VST plugin formats. + */ + int64_t getUniqueId() const override + { + return cconst('M', 'u', 't', 'e'); + } + + /* ---------------------------------------------------------------------------------------- + * This example has no parameters, so skip parameter stuff */ + + void initParameter(uint32_t, Parameter&) override {} + float getParameterValue(uint32_t) const override { return 0.0f; } + void setParameterValue(uint32_t, float) override {} + + /* ---------------------------------------------------------------------------------------- + * Audio/MIDI Processing */ + + /** + Run/process function for plugins without MIDI input. + NOTE: Some parameters might be null if there are no audio inputs or outputs. + */ + void run(const float**, float** outputs, uint32_t frames) override + { + // get the left and right audio outputs + float* const outL = outputs[0]; + float* const outR = outputs[1]; + + // mute audio + std::memset(outL, 0, sizeof(float)*frames); + std::memset(outR, 0, sizeof(float)*frames); + } + + }; + @endcode + + See the Plugin class for more information and to understand what each function does. + + @section Parameters + A plugin is nothing without parameters.@n + In DPF parameters can be inputs or outputs.@n + They have hints to describe how they behave plus a name and a symbol identifying them.@n + Parameters also have 'ranges' – a minimum, maximum and default value. + + Input parameters are "read-only": the plugin can read them but not change them. + (the exception being when changing programs, more on that below)@n + It's the host responsibility to save, restore and set input parameters. + + Output parameters can be changed at anytime by the plugin.@n + The host will simply read their values and not change them. + + Here's an example of an audio plugin that has 1 input parameter: + @code + class GainPlugin : public Plugin + { + public: + /** + Plugin class constructor. + You must set all parameter values to their defaults, matching ParameterRanges::def. + */ + GainPlugin() + : Plugin(1, 0, 0), // 1 parameter, 0 programs and 0 states + fGain(1.0f) + { + } + + protected: + /* ---------------------------------------------------------------------------------------- + * Information */ + + const char* getLabel() const override + { + return "Gain"; + } + + const char* getMaker() const override + { + return "DPF"; + } + + const char* getLicense() const override + { + return "MIT"; + } + + uint32_t getVersion() const override + { + return 0x1000; + } + + int64_t getUniqueId() const override + { + return cconst('G', 'a', 'i', 'n'); + } + + /* ---------------------------------------------------------------------------------------- + * Init */ + + /** + Initialize a parameter. + This function will be called once, shortly after the plugin is created. + */ + void initParameter(uint32_t index, Parameter& parameter) override + { + // we only have one parameter so we can skip checking the index + + parameter.hints = kParameterIsAutomable; + parameter.name = "Gain"; + parameter.symbol = "gain"; + parameter.ranges.min = 0.0f; + parameter.ranges.max = 2.0f; + parameter.ranges.def = 1.0f; + } + + /* ---------------------------------------------------------------------------------------- + * Internal data */ + + /** + Get the current value of a parameter. + */ + float getParameterValue(uint32_t index) const override + { + // same as before, ignore index check + + return fGain; + } + + /** + Change a parameter value. + */ + void setParameterValue(uint32_t index, float value) override + { + // same as before, ignore index check + + fGain = value; + } + + /* ---------------------------------------------------------------------------------------- + * Audio/MIDI Processing */ + + void run(const float**, float** outputs, uint32_t frames) override + { + // get the mono input and output + const float* const in = inputs[0]; + /* */ float* const out = outputs[0]; + + // apply gain against all samples + for (uint32_t i=0; i < frames; ++i) + out[i] = in[i] * fGain; + } + + private: + float fGain; + }; + @endcode + + See the Parameter struct for more information about parameters. + + @section Programs + Programs in DPF refer to plugin-side presets (usually called "factory presets"), + an initial set of presets provided by plugin authors included in the actual plugin. + + To use programs you must first enable them by setting @ref DISTRHO_PLUGIN_WANT_PROGRAMS to 1 in your DistrhoPluginInfo.h file.@n + When enabled you'll need to override 2 new function in your plugin code, + Plugin::initProgramName(uint32_t, String&) and Plugin::loadProgram(uint32_t). + + Here's an example of a plugin with a "default" program: + @code + class PluginWithPresets : public Plugin + { + public: + PluginWithPresets() + : Plugin(2, 1, 0), // 2 parameters, 1 program and 0 states + fGainL(1.0f), + fGainR(1.0f), + { + } + + protected: + /* ---------------------------------------------------------------------------------------- + * Information */ + + const char* getLabel() const override + { + return "Prog"; + } + + const char* getMaker() const override + { + return "DPF"; + } + + const char* getLicense() const override + { + return "MIT"; + } + + uint32_t getVersion() const override + { + return 0x1000; + } + + int64_t getUniqueId() const override + { + return cconst('P', 'r', 'o', 'g'); + } + + /* ---------------------------------------------------------------------------------------- + * Init */ + + /** + Initialize a parameter. + This function will be called once, shortly after the plugin is created. + */ + void initParameter(uint32_t index, Parameter& parameter) override + { + parameter.hints = kParameterIsAutomable; + parameter.ranges.min = 0.0f; + parameter.ranges.max = 2.0f; + parameter.ranges.def = 1.0f; + + switch (index) + { + case 0; + parameter.name = "Gain Right"; + parameter.symbol = "gainR"; + break; + case 1; + parameter.name = "Gain Left"; + parameter.symbol = "gainL"; + break; + } + } + + /** + Set the name of the program @a index. + This function will be called once, shortly after the plugin is created. + */ + void initProgramName(uint32_t index, d_string& programName) + { + switch(index) + { + case 0: + programName = "Default"; + break; + } + } + + /* ---------------------------------------------------------------------------------------- + * Internal data */ + + /** + Get the current value of a parameter. + */ + float getParameterValue(uint32_t index) const override + { + switch (index) + { + case 0; + return fGainL; + case 1; + return fGainR; + } + } + + /** + Change a parameter value. + */ + void setParameterValue(uint32_t index, float value) override + { + switch (index) + { + case 0; + fGainL = value; + break; + case 1; + fGainR = value; + break; + } + } + + /** + Load a program. + */ + void loadProgram(uint32_t index) + { + switch(index) + { + case 0: + fGainL = 1.0f; + fGainR = 1.0f; + break; + } + } + + /* ---------------------------------------------------------------------------------------- + * Audio/MIDI Processing */ + + void run(const float**, float** outputs, uint32_t frames) override + { + // get the left and right audio buffers + const float* const inL = inputs[0]; + const float* const inR = inputs[0]; + /* */ float* const outL = outputs[0]; + /* */ float* const outR = outputs[0]; + + // apply gain against all samples + for (uint32_t i=0; i < frames; ++i) + { + outL[i] = inL[i] * fGainL; + outR[i] = inR[i] * fGainR; + } + } + + private: + float fGainL, fGainR; + }; + @endcode + + @section States + describe them + + @section MIDI + describe them + + @section Latency + describe it + + @section Time-Position + describe it + + @section UI + describe them +*/ + +/* ------------------------------------------------------------------------------------------------------------ + * Plugin Macros */ + +/** + @defgroup PluginMacros Plugin Macros + + C Macros that describe your plugin. (defined in the "DistrhoPluginInfo.h" file) + + With these macros you can tell the host what features your plugin requires.@n + Depending on which macros you enable, new functions will be available to call and/or override. + + All values are either integer or strings.@n + For boolean-like values 1 means 'on' and 0 means 'off'. + + The values defined in this group are for documentation purposes only.@n + All macros are disabled by default. + + Only 4 macros are required, they are: + - @ref DISTRHO_PLUGIN_NAME + - @ref DISTRHO_PLUGIN_NUM_INPUTS + - @ref DISTRHO_PLUGIN_NUM_OUTPUTS + - @ref DISTRHO_PLUGIN_URI + @{ + */ + +/** + The plugin name.@n + This is used to identify your plugin before a Plugin instance can be created. + @note This macro is required. + */ +#define DISTRHO_PLUGIN_NAME "Plugin Name" + +/** + Number of audio inputs the plugin has. + @note This macro is required. + */ +#define DISTRHO_PLUGIN_NUM_INPUTS 2 + +/** + Number of audio outputs the plugin has. + @note This macro is required. + */ +#define DISTRHO_PLUGIN_NUM_OUTPUTS 2 + +/** + The plugin URI when exporting in LV2 format. + @note This macro is required. + */ +#define DISTRHO_PLUGIN_URI "urn:distrho:name" + +/** + Wherever the plugin has a custom %UI. + @see DISTRHO_UI_USE_NANOVG + @see UI + */ +#define DISTRHO_PLUGIN_HAS_UI 1 + +/** + Wherever the plugin processing is realtime-safe.@n + TODO - list rtsafe requirements + */ +#define DISTRHO_PLUGIN_IS_RT_SAFE 1 + +/** + Wherever the plugin is a synth.@n + @ref DISTRHO_PLUGIN_WANT_MIDI_INPUT is automatically enabled when this is too. + @see DISTRHO_PLUGIN_WANT_MIDI_INPUT + */ +#define DISTRHO_PLUGIN_IS_SYNTH 1 + +/** + Enable direct access between the %UI and plugin code. + @see UI::getPluginInstancePointer() + @note DO NOT USE THIS UNLESS STRICTLY NECESSARY!! + Try to avoid it at all costs! + */ +#define DISTRHO_PLUGIN_WANT_DIRECT_ACCESS 0 + +/** + Wherever the plugin introduces latency during audio or midi processing. + @see Plugin::setLatency(uint32_t) + */ +#define DISTRHO_PLUGIN_WANT_LATENCY 1 + +/** + Wherever the plugin wants MIDI input.@n + This is automatically enabled if @ref DISTRHO_PLUGIN_IS_SYNTH is true. + */ +#define DISTRHO_PLUGIN_WANT_MIDI_INPUT 1 + +/** + Wherever the plugin wants MIDI output. + @see Plugin::writeMidiEvent(const MidiEvent&) + */ +#define DISTRHO_PLUGIN_WANT_MIDI_OUTPUT 1 + +/** + Wherever the plugin provides its own internal programs. + @see Plugin::initProgramName(uint32_t, String&) + @see Plugin::setProgram(uint32_t) + */ +#define DISTRHO_PLUGIN_WANT_PROGRAMS 1 + +/** + Wherever the plugin uses internal non-parameter data. + @see Plugin::initState(uint32_t, String&, String&) + @see Plugin::setState(const char*, const char*) + */ +#define DISTRHO_PLUGIN_WANT_STATE 1 + +/** + Wherever the plugin wants time position information from the host. + @see Plugin::getTimePosition() + */ +#define DISTRHO_PLUGIN_WANT_TIMEPOS 1 + +/** + Wherever the %UI uses NanoVG for drawing instead of the default raw OpenGL calls.@n + When enabled your %UI instance will subclass @ref NanoWidget instead of @ref Widget. + */ +#define DISTRHO_UI_USE_NANOVG 1 + +/** + The %UI URI when exporting in LV2 format.@n + By default this is set to @ref DISTRHO_PLUGIN_URI with "#UI" as suffix. + */ +#define DISTRHO_UI_URI DISTRHO_PLUGIN_URI "#UI" + +/** @} */ + +// ----------------------------------------------------------------------------------------------------------- + +END_NAMESPACE_DISTRHO + +#endif // DOXYGEN diff --git a/distrho/DistrhoPlugin.hpp b/distrho/DistrhoPlugin.hpp index 4c2f4d0b..bf1f8cd5 100644 --- a/distrho/DistrhoPlugin.hpp +++ b/distrho/DistrhoPlugin.hpp @@ -20,171 +20,8 @@ #include "extra/d_string.hpp" #include "src/DistrhoPluginChecks.h" -#include - -#ifdef DISTRHO_PROPER_CPP11_SUPPORT -# include -#else -# include -#endif - -#ifndef M_PI -# define M_PI 3.14159265358979323846 -#endif - START_NAMESPACE_DISTRHO -/** - @mainpage DISTRHO %Plugin Framework - - DISTRHO %Plugin Framework (or @b DPF for short) - is a plugin framework designed to make development of new plugins an easy and enjoyable task.@n - It allows developers to create plugins with custom UIs using a simple C++ API. - - @section Macros - You start by creating a "DistrhoPluginInfo.h" file describing the plugin via macros, see @ref PluginMacros. - - @section Plugin - TODO - - @section Parameters - describe input and output, automable and rt safe, boolean etc, cv -*/ - -/* ------------------------------------------------------------------------------------------------------------ - * Plugin Macros */ - -#ifdef DOXYGEN - -/** - @defgroup PluginMacros Plugin Macros - - C Macros that describe your plugin. (defined in the "DistrhoPluginInfo.h" file) - - With these macros you can tell the host what features your plugin requires.@n - Depending on which macros you enable, new functions will be available to call and/or override. - - All values are either integer or strings.@n - For boolean-like values 1 means 'on' and 0 means 'off'. - - The values defined in this file are for documentation purposes only.@n - All macros are disabled by default. - - Only 4 macros are required, they are: - - @ref DISTRHO_PLUGIN_NAME - - @ref DISTRHO_PLUGIN_NUM_INPUTS - - @ref DISTRHO_PLUGIN_NUM_OUTPUTS - - @ref DISTRHO_PLUGIN_URI - @{ - */ - -/** - The plugin name.@n - This is used to identify your plugin before a Plugin instance can be created. - @note This macro is required. - */ -#define DISTRHO_PLUGIN_NAME "Plugin Name" - -/** - Number of audio inputs the plugin has. - @note This macro is required. - */ -#define DISTRHO_PLUGIN_NUM_INPUTS 2 - -/** - Number of audio outputs the plugin has. - @note This macro is required. - */ -#define DISTRHO_PLUGIN_NUM_OUTPUTS 2 - -/** - The plugin URI when exporting in LV2 format. - @note This macro is required. - */ -#define DISTRHO_PLUGIN_URI "urn:distrho:name" - -/** - Wherever the plugin has a custom %UI. - @see DISTRHO_UI_USE_NANOVG - @see UI - */ -#define DISTRHO_PLUGIN_HAS_UI 1 - -/** - Wherever the plugin processing is realtime-safe.@n - TODO - list rtsafe requirements - */ -#define DISTRHO_PLUGIN_IS_RT_SAFE 1 - -/** - Wherever the plugin is a synth.@n - @ref DISTRHO_PLUGIN_WANT_MIDI_INPUT is automatically enabled when this is too. - @see DISTRHO_PLUGIN_WANT_MIDI_INPUT - */ -#define DISTRHO_PLUGIN_IS_SYNTH 1 - -/** - Enable direct access between the %UI and plugin code. - @see UI::d_getPluginInstancePointer() - @note DO NOT USE THIS UNLESS STRICTLY NECESSARY!! - Try to avoid it at all costs! - */ -#define DISTRHO_PLUGIN_WANT_DIRECT_ACCESS 0 - -/** - Wherever the plugin introduces latency during audio or midi processing. - @see Plugin::d_setLatency(uint32_t) - */ -#define DISTRHO_PLUGIN_WANT_LATENCY 1 - -/** - Wherever the plugin wants MIDI input.@n - This is automatically enabled if @ref DISTRHO_PLUGIN_IS_SYNTH is true. - */ -#define DISTRHO_PLUGIN_WANT_MIDI_INPUT 1 - -/** - Wherever the plugin wants MIDI output. - @see Plugin::d_writeMidiEvent(const MidiEvent&) - */ -#define DISTRHO_PLUGIN_WANT_MIDI_OUTPUT 1 - -/** - Wherever the plugin provides its own internal programs. - @see Plugin::d_initProgramName(uint32_t, d_string&) - @see Plugin::d_setProgram(uint32_t) - */ -#define DISTRHO_PLUGIN_WANT_PROGRAMS 1 - -/** - Wherever the plugin uses internal non-parameter data. - @see Plugin::d_initState(uint32_t, d_string&, d_string&) - @see Plugin::d_setState(const char*, const char*) - */ -#define DISTRHO_PLUGIN_WANT_STATE 1 - -/** - Wherever the plugin wants time position information from the host. - @see Plugin::d_getTimePosition() - */ -#define DISTRHO_PLUGIN_WANT_TIMEPOS 1 - -/** - Wherever the %UI uses NanoVG for drawing instead of the default raw OpenGL calls.@n - When enabled your %UI instance will subclass @ref NanoWidget instead of @ref Widget. - */ -#define DISTRHO_UI_USE_NANOVG 1 - -/** - The %UI URI when exporting in LV2 format.@n - By default this is set to @ref DISTRHO_PLUGIN_URI with "#UI" as suffix. - */ -#define DISTRHO_UI_URI DISTRHO_PLUGIN_URI "#UI" - -/** @} */ - -#endif - /* ------------------------------------------------------------------------------------------------------------ * Audio Port Hints */ @@ -221,12 +58,12 @@ static const uint32_t kAudioPortIsSidechain = 0x2; /** Parameter is automable (real-time safe). - @see Plugin::d_setParameterValue() + @see Plugin::setParameterValue(uint32_t, float) */ static const uint32_t kParameterIsAutomable = 0x01; /** - Parameter value is boolean. + Parameter value is boolean.@n It's always at either minimum or maximum value. */ static const uint32_t kParameterIsBoolean = 0x02; @@ -242,27 +79,22 @@ static const uint32_t kParameterIsInteger = 0x04; static const uint32_t kParameterIsLogarithmic = 0x08; /** - Parameter is of output type. + Parameter is of output type.@n When unset, parameter is assumed to be of input type. - Parameter inputs are changed by the host and must not be changed by the plugin. - The only exception being when changing programs, see Plugin::d_setProgram(). + Parameter inputs are changed by the host and must not be changed by the plugin.@n + The only exception being when changing programs, see Plugin::setProgram().@n Outputs are changed by the plugin and never modified by the host. */ static const uint32_t kParameterIsOutput = 0x10; -/** - Parameter can be used as control voltage (LV2 only). - */ -static const uint32_t kParameterIsCV = 0x20; - /** @} */ /* ------------------------------------------------------------------------------------------------------------ - * DPF Base structs */ + * Base Plugin structs */ /** - @defgroup BaseStructs Base Structs + @defgroup BasePluginStructs Base Plugin Structs @{ */ @@ -277,19 +109,19 @@ struct AudioPort { uint32_t hints; /** - The name of this audio port. - An audio port name can contain any character, but hosts might have a hard time with non-ascii ones. + The name of this audio port.@n + An audio port name can contain any character, but hosts might have a hard time with non-ascii ones.@n The name doesn't have to be unique within a plugin instance, but it's recommended. */ - d_string name; + String name; /** - The symbol of this audio port. - An audio port symbol is a short restricted name used as a machine and human readable identifier. + The symbol of this audio port.@n + An audio port symbol is a short restricted name used as a machine and human readable identifier.@n 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. - @note: Audio port and parameter symbols MUST be unique within a plugin instance. + @note Audio port and parameter symbols MUST be unique within a plugin instance. */ - d_string symbol; + String symbol; /** Default constructor for a regular audio port. @@ -301,10 +133,10 @@ struct AudioPort { }; /** - Parameter ranges. + Parameter ranges.@n This is used to set the default, minimum and maximum values of a parameter. - By default a parameter has 0.0 as minimum, 1.0 as maximum and 0.0 as default. + By default a parameter has 0.0 as minimum, 1.0 as maximum and 0.0 as default.@n When changing this struct values you must ensure maximum > minimum and default is within range. */ struct ParameterRanges { @@ -429,29 +261,29 @@ struct Parameter { uint32_t hints; /** - The name of this parameter. - A parameter name can contain any character, but hosts might have a hard time with non-ascii ones. + The name of this parameter.@n + A parameter name can contain any character, but hosts might have a hard time with non-ascii ones.@n The name doesn't have to be unique within a plugin instance, but it's recommended. */ - d_string name; + String name; /** - The symbol of this parameter. - A parameter symbol is a short restricted name used as a machine and human readable identifier. + The symbol of this parameter.@n + A parameter symbol is a short restricted name used as a machine and human readable identifier.@n 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. - @note: Parameter symbols MUST be unique within a plugin instance. + @note Parameter symbols MUST be unique within a plugin instance. */ - d_string symbol; + String symbol; /** - The unit of this parameter. - This means something like "dB", "kHz" and "ms". + The unit of this parameter.@n + This means something like "dB", "kHz" and "ms".@n Can be left blank if a unit does not apply to this parameter. */ - d_string unit; + String unit; /** - Ranges of this parameter. + Ranges of this parameter.@n The ranges describe the default, minimum and maximum values. */ ParameterRanges ranges; @@ -487,7 +319,7 @@ struct MidiEvent { uint32_t size; /** - MIDI data. + MIDI data.@n If size > kDataSize, dataExt is used (otherwise null). */ uint8_t data[kDataSize]; @@ -495,8 +327,8 @@ struct MidiEvent { }; /** - Time position. - The @a playing and @a frame values are always valid. + Time position.@n + The @a playing and @a frame values are always valid.@n BBT values are only valid when @a bbt.valid is true. This struct is inspired by the JACK Transport API. @@ -517,28 +349,28 @@ struct TimePosition { */ struct BarBeatTick { /** - Wherever the host transport is using BBT. + Wherever the host transport is using BBT.@n If false you must not read from this struct. */ bool valid; /** - Current bar. - Should always be > 0. + Current bar.@n + Should always be > 0.@n The first bar is bar '1'. */ int32_t bar; /** - Current beat within bar. - Should always be > 0 and <= @a beatsPerBar. + Current beat within bar.@n + Should always be > 0 and <= @a beatsPerBar.@n The first beat is beat '1'. */ int32_t beat; /** - Current tick within beat. - Should always be > 0 and <= @a ticksPerBeat. + Current tick within beat.@n + Should always be > 0 and <= @a ticksPerBeat.@n The first tick is tick '0'. */ int32_t tick; @@ -559,7 +391,7 @@ struct TimePosition { float beatType; /** - Number of ticks within a bar. + Number of ticks within a bar.@n Usually a moderately large integer with many denominators, such as 1920.0. */ double ticksPerBeat; @@ -598,37 +430,42 @@ struct TimePosition { /* ------------------------------------------------------------------------------------------------------------ * DPF Plugin */ +/** + @defgroup MainClasses Main Classes + @{ + */ + /** DPF Plugin class from where plugin instances are created. - The public methods (Host state) are called from the plugin to get or set host information. - They can be called from a plugin instance at anytime unless stated otherwise. + The public methods (Host state) are called from the plugin to get or set host information.@n + They can be called from a plugin instance at anytime unless stated otherwise.@n All other methods are to be implemented by the plugin and will be called by the host. - Shortly after a plugin instance is created, the various d_init* functions will be called by the host. - Host will call d_activate() before d_run(), and d_deactivate() before the plugin instance is destroyed. - The host may call deactivate right after activate and vice-versa, but never activate/deactivate consecutively. - There is no limit on how many times d_run() is called, only that activate/deactivate will be called in between. + Shortly after a plugin instance is created, the various init* functions will be called by the host.@n + Host will call activate() before run(), and deactivate() before the plugin instance is destroyed.@n + The host may call deactivate right after activate and vice-versa, but never activate/deactivate consecutively.@n + There is no limit on how many times run() is called, only that activate/deactivate will be called in between. - The buffer size and sample rate values will remain constant between activate and deactivate. - Buffer size is only a hint though, the host might call d_run() with a higher or lower number of frames. + The buffer size and sample rate values will remain constant between activate and deactivate.@n + Buffer size is only a hint though, the host might call run() with a higher or lower number of frames. Some of this class functions are only available according to some macros. - DISTRHO_PLUGIN_WANT_PROGRAMS activates program related features. - When enabled you need to implement d_initProgramName() and d_setProgram(). + DISTRHO_PLUGIN_WANT_PROGRAMS activates program related features.@n + When enabled you need to implement initProgramName() and setProgram(). - DISTRHO_PLUGIN_WANT_STATE activates internal state features. - When enabled you need to implement d_initStateKey() and d_setState(). + DISTRHO_PLUGIN_WANT_STATE activates internal state features.@n + When enabled you need to implement initStateKey() and setState(). - The process function d_run() changes wherever DISTRHO_PLUGIN_WANT_MIDI_INPUT is enabled or not. + The process function run() changes wherever DISTRHO_PLUGIN_WANT_MIDI_INPUT is enabled or not.@n When enabled it provides midi input events. */ class Plugin { public: /** - Plugin class constructor. + Plugin class constructor.@n You must set all parameter values to their defaults, matching ParameterRanges::def. */ Plugin(const uint32_t parameterCount, const uint32_t programCount, const uint32_t stateCount); @@ -642,47 +479,47 @@ public: * Host state */ /** - Get the current buffer size that will probably be used during processing, in frames. + Get the current buffer size that will probably be used during processing, in frames.@n This value will remain constant between activate and deactivate. - @note: This value is only a hint! - Hosts might call d_run() with a higher or lower number of frames. - @see d_bufferSizeChanged(uint32_t) + @note This value is only a hint!@n + Hosts might call run() with a higher or lower number of frames. + @see bufferSizeChanged(uint32_t) */ - uint32_t d_getBufferSize() const noexcept; + uint32_t getBufferSize() const noexcept; /** - Get the current sample rate that will be used during processing. + Get the current sample rate that will be used during processing.@n This value will remain constant between activate and deactivate. - @see d_sampleRateChanged(double) + @see sampleRateChanged(double) */ - double d_getSampleRate() const noexcept; + double getSampleRate() const noexcept; #if DISTRHO_PLUGIN_WANT_TIMEPOS /** - Get the current host transport time position. - This function should only be called during d_run(). + Get the current host transport time position.@n + This function should only be called during run().@n You can call this during other times, but the returned position is not guaranteed to be in sync. - @note: TimePosition is not supported in LADSPA and DSSI plugin formats. + @note TimePosition is not supported in LADSPA and DSSI plugin formats. */ - const TimePosition& d_getTimePosition() const noexcept; + const TimePosition& getTimePosition() const noexcept; #endif #if DISTRHO_PLUGIN_WANT_LATENCY /** - Change the plugin audio output latency to @a frames. - This function should only be called in the constructor, d_activate() and d_run(). + Change the plugin audio output latency to @a frames.@n + This function should only be called in the constructor, activate() and run(). @note This function is only available if DISTRHO_PLUGIN_WANT_LATENCY is enabled. */ - void d_setLatency(uint32_t frames) noexcept; + void setLatency(uint32_t frames) noexcept; #endif #if DISTRHO_PLUGIN_WANT_MIDI_OUTPUT /** - Write a MIDI output event. - This function must only be called during d_run(). - Returns false when the host buffer is full, in which case do not call this again until the next d_run(). + Write a MIDI output event.@n + This function must only be called during run().@n + Returns false when the host buffer is full, in which case do not call this again until the next run(). */ - bool d_writeMidiEvent(const MidiEvent& midiEvent) noexcept; + bool writeMidiEvent(const MidiEvent& midiEvent) noexcept; #endif protected: @@ -690,153 +527,153 @@ protected: * Information */ /** - Get the plugin name. + Get the plugin name.@n Returns DISTRHO_PLUGIN_NAME by default. */ - virtual const char* d_getName() const { return DISTRHO_PLUGIN_NAME; } + virtual const char* getName() const { return DISTRHO_PLUGIN_NAME; } /** - Get the plugin label. - A plugin label follows the same rules as Parameter::symbol, with the exception that it can start with numbers. + Get the plugin label.@n + This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters. */ - virtual const char* d_getLabel() const = 0; + virtual const char* getLabel() const = 0; /** Get the plugin author/maker. */ - virtual const char* d_getMaker() const = 0; + virtual const char* getMaker() const = 0; /** Get the plugin license name (a single line of text).@n - For commercial plugins this should return some copyright information. + For commercial plugins this should return some short copyright information. */ - virtual const char* d_getLicense() const = 0; + virtual const char* getLicense() const = 0; /** - Get the plugin version, in hexadecimal. + Get the plugin version, in hexadecimal.@n TODO format to be defined */ - virtual uint32_t d_getVersion() const = 0; + virtual uint32_t getVersion() const = 0; /** - Get the plugin unique Id. + Get the plugin unique Id.@n This value is used by LADSPA, DSSI and VST plugin formats. */ - virtual int64_t d_getUniqueId() const = 0; + virtual int64_t getUniqueId() const = 0; /* -------------------------------------------------------------------------------------------------------- * Init */ /** - Initialize the audio port @a index. + Initialize the audio port @a index.@n This function will be called once, shortly after the plugin is created. */ - virtual void d_initAudioPort(bool input, uint32_t index, AudioPort& port); + virtual void initAudioPort(bool input, uint32_t index, AudioPort& port); /** - Initialize the parameter @a index. + Initialize the parameter @a index.@n This function will be called once, shortly after the plugin is created. */ - virtual void d_initParameter(uint32_t index, Parameter& parameter) = 0; + virtual void initParameter(uint32_t index, Parameter& parameter) = 0; #if DISTRHO_PLUGIN_WANT_PROGRAMS /** - Set the name of the program @a index. - This function will be called once, shortly after the plugin is created. + Set the name of the program @a index.@n + This function will be called once, shortly after the plugin is created.@n Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled. */ - virtual void d_initProgramName(uint32_t index, d_string& programName) = 0; + virtual void initProgramName(uint32_t index, String& programName) = 0; #endif #if DISTRHO_PLUGIN_WANT_STATE /** - Set the state key and default value of @a index. - This function will be called once, shortly after the plugin is created. + Set the state key and default value of @a index.@n + This function will be called once, shortly after the plugin is created.@n Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled. */ - virtual void d_initState(uint32_t index, d_string& stateKey, d_string& defaultStateValue) = 0; + virtual void initState(uint32_t index, String& stateKey, String& defaultStateValue) = 0; #endif /* -------------------------------------------------------------------------------------------------------- * Internal data */ /** - Get the current value of a parameter. + Get the current value of a parameter.@n The host may call this function from any context, including realtime processing. */ - virtual float d_getParameterValue(uint32_t index) const = 0; + virtual float getParameterValue(uint32_t index) const = 0; /** - Change a parameter value. - The host may call this function from any context, including realtime processing. + Change a parameter value.@n + The host may call this function from any context, including realtime processing.@n When a parameter is marked as automable, you must ensure no non-realtime operations are performed. @note This function will only be called for parameter inputs. */ - virtual void d_setParameterValue(uint32_t index, float value) = 0; + virtual void setParameterValue(uint32_t index, float value) = 0; #if DISTRHO_PLUGIN_WANT_PROGRAMS /** - Change the currently used program to @a index. - The host may call this function from any context, including realtime processing. + Load a program.@n + The host may call this function from any context, including realtime processing.@n Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_PROGRAMS is enabled. */ - virtual void d_setProgram(uint32_t index) = 0; + virtual void loadProgram(uint32_t index) = 0; #endif #if DISTRHO_PLUGIN_WANT_STATE /** - Change an internal state @a key to @a value. + Change an internal state @a key to @a value.@n Must be implemented by your plugin class only if DISTRHO_PLUGIN_WANT_STATE is enabled. */ - virtual void d_setState(const char* key, const char* value) = 0; + virtual void setState(const String& key, const String& value) = 0; #endif /* -------------------------------------------------------------------------------------------------------- - * Process */ + * Audio/MIDI Processing */ /** Activate this plugin. */ - virtual void d_activate() {} + virtual void activate() {} /** Deactivate this plugin. */ - virtual void d_deactivate() {} + virtual void deactivate() {} #if DISTRHO_PLUGIN_WANT_MIDI_INPUT /** Run/process function for plugins with MIDI input. - @note: Some parameters might be null if there are no audio inputs/outputs or MIDI events. + @note Some parameters might be null if there are no audio inputs/outputs or MIDI events. */ - virtual void d_run(const float** inputs, float** outputs, uint32_t frames, - const MidiEvent* midiEvents, uint32_t midiEventCount) = 0; + virtual void run(const float** inputs, float** outputs, uint32_t frames, + const MidiEvent* midiEvents, uint32_t midiEventCount) = 0; #else /** Run/process function for plugins without MIDI input. - @note: Some parameters might be null if there are no audio inputs or outputs. + @note Some parameters might be null if there are no audio inputs or outputs. */ - virtual void d_run(const float** inputs, float** outputs, uint32_t frames) = 0; + virtual void run(const float** inputs, float** outputs, uint32_t frames) = 0; #endif /* -------------------------------------------------------------------------------------------------------- * Callbacks (optional) */ /** - Optional callback to inform the plugin about a buffer size change. + Optional callback to inform the plugin about a buffer size change.@n This function will only be called when the plugin is deactivated. - @note: This value is only a hint! - Hosts might call d_run() with a higher or lower number of frames. - @see d_getBufferSize() + @note This value is only a hint!@n + Hosts might call run() with a higher or lower number of frames. + @see getBufferSize() */ - virtual void d_bufferSizeChanged(uint32_t newBufferSize); + virtual void bufferSizeChanged(uint32_t newBufferSize); /** - Optional callback to inform the plugin about a sample rate change. + Optional callback to inform the plugin about a sample rate change.@n This function will only be called when the plugin is deactivated. - @see d_getSampleRate() + @see getSampleRate() */ - virtual void d_sampleRateChanged(double newSampleRate); + virtual void sampleRateChanged(double newSampleRate); // ------------------------------------------------------------------------------------------------------- @@ -848,14 +685,23 @@ private: DISTRHO_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(Plugin) }; +/** @} */ + /* ------------------------------------------------------------------------------------------------------------ * Create plugin, entry point */ +/** + @defgroup EntryPoints Entry Points + @{ + */ + /** TODO. */ extern Plugin* createPlugin(); +/** @} */ + // ----------------------------------------------------------------------------------------------------------- END_NAMESPACE_DISTRHO diff --git a/distrho/DistrhoUI.hpp b/distrho/DistrhoUI.hpp index c3a03006..5dd45a12 100644 --- a/distrho/DistrhoUI.hpp +++ b/distrho/DistrhoUI.hpp @@ -33,6 +33,11 @@ START_NAMESPACE_DISTRHO /* ------------------------------------------------------------------------------------------------------------ * DPF UI */ +/** + @addtogroup MainClasses + @{ + */ + /** DPF UI class from where UI instances are created. @@ -59,32 +64,32 @@ public: /** Get the current sample rate used in plugin processing. - @see d_sampleRateChanged(double) + @see sampleRateChanged(double) */ - double d_getSampleRate() const noexcept; + double getSampleRate() const noexcept; /** TODO: Document this. */ - void d_editParameter(const uint32_t index, const bool started); + void editParameter(const uint32_t index, const bool started); /** TODO: Document this. */ - void d_setParameterValue(const uint32_t index, const float value); + void setParameterValue(const uint32_t index, const float value); #if DISTRHO_PLUGIN_WANT_STATE /** TODO: Document this. */ - void d_setState(const char* const key, const char* const value); + void setState(const char* const key, const char* const value); #endif #if DISTRHO_PLUGIN_IS_SYNTH /** TODO: Document this. */ - void d_sendNote(const uint8_t channel, const uint8_t note, const uint8_t velocity); + void sendNote(const uint8_t channel, const uint8_t note, const uint8_t velocity); #endif #if DISTRHO_PLUGIN_WANT_DIRECT_ACCESS @@ -94,7 +99,7 @@ public: /** TODO: Document this. */ - void* d_getPluginInstancePointer() const noexcept; + void* getPluginInstancePointer() const noexcept; #endif protected: @@ -105,14 +110,14 @@ protected: A parameter has changed on the plugin side. This is called by the host to inform the UI about parameter changes. */ - virtual void d_parameterChanged(uint32_t index, float value) = 0; + virtual void parameterChanged(uint32_t index, float value) = 0; #if DISTRHO_PLUGIN_WANT_PROGRAMS /** The current program has changed on the plugin side. This is called by the host to inform the UI about program changes. */ - virtual void d_programChanged(uint32_t index) = 0; + virtual void programChanged(uint32_t index) = 0; #endif #if DISTRHO_PLUGIN_WANT_STATE @@ -120,7 +125,7 @@ protected: A state has changed on the plugin side. This is called by the host to inform the UI about state changes. */ - virtual void d_stateChanged(const char* key, const char* value) = 0; + virtual void stateChanged(const char* key, const char* value) = 0; #endif /* -------------------------------------------------------------------------------------------------------- @@ -128,9 +133,9 @@ protected: /** Optional callback to inform the UI about a sample rate change on the plugin side. - @see d_getSampleRate() + @see getSampleRate() */ - virtual void d_sampleRateChanged(double newSampleRate); + virtual void sampleRateChanged(double newSampleRate); /* -------------------------------------------------------------------------------------------------------- * UI Callbacks (optional) */ @@ -138,20 +143,20 @@ protected: /** TODO: Document this. */ - virtual void d_uiIdle() {} + virtual void uiIdle() {} /** File browser selected function. @see Window::fileBrowserSelected(const char*) */ - virtual void d_uiFileBrowserSelected(const char* filename); + virtual void uiFileBrowserSelected(const char* filename); /** OpenGL window reshape function, called when parent window is resized. You can reimplement this function for a custom OpenGL state. @see Window::onReshape(uint,uint) */ - virtual void d_uiReshape(uint width, uint height); + virtual void uiReshape(uint width, uint height); /* -------------------------------------------------------------------------------------------------------- * UI Resize Handling, internal */ @@ -181,14 +186,23 @@ private: DISTRHO_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR(UI) }; +/** @} */ + /* ------------------------------------------------------------------------------------------------------------ * Create UI, entry point */ +/** + @addtogroup EntryPoints + @{ + */ + /** TODO. */ extern UI* createUI(); +/** @} */ + // ----------------------------------------------------------------------------------------------------------- END_NAMESPACE_DISTRHO diff --git a/distrho/DistrhoUtils.hpp b/distrho/DistrhoUtils.hpp index 55861e81..b07282cb 100644 --- a/distrho/DistrhoUtils.hpp +++ b/distrho/DistrhoUtils.hpp @@ -46,6 +46,10 @@ inline float round(float __x) } #endif +#ifndef M_PI +# define M_PI 3.14159265358979323846 +#endif + // ----------------------------------------------------------------------- // misc functions diff --git a/distrho/src/DistrhoPlugin.cpp b/distrho/src/DistrhoPlugin.cpp index b411a519..beadb955 100644 --- a/distrho/src/DistrhoPlugin.cpp +++ b/distrho/src/DistrhoPlugin.cpp @@ -27,7 +27,7 @@ double d_lastSampleRate = 0.0; /* ------------------------------------------------------------------------------------------------------------ * Static fallback data, see DistrhoPluginInternal.hpp */ -const d_string PluginExporter::sFallbackString; +const String PluginExporter::sFallbackString; const AudioPort PluginExporter::sFallbackAudioPort; const ParameterRanges PluginExporter::sFallbackRanges; @@ -51,7 +51,7 @@ Plugin::Plugin(const uint32_t parameterCount, const uint32_t programCount, const if (programCount > 0) { pData->programCount = programCount; - pData->programNames = new d_string[programCount]; + pData->programNames = new String[programCount]; } #else DISTRHO_SAFE_ASSERT(programCount == 0); @@ -61,8 +61,8 @@ Plugin::Plugin(const uint32_t parameterCount, const uint32_t programCount, const if (stateCount > 0) { pData->stateCount = stateCount; - pData->stateKeys = new d_string[stateCount]; - pData->stateDefValues = new d_string[stateCount]; + pData->stateKeys = new String[stateCount]; + pData->stateDefValues = new String[stateCount]; } #else DISTRHO_SAFE_ASSERT(stateCount == 0); @@ -77,32 +77,32 @@ Plugin::~Plugin() /* ------------------------------------------------------------------------------------------------------------ * Host state */ -uint32_t Plugin::d_getBufferSize() const noexcept +uint32_t Plugin::getBufferSize() const noexcept { return pData->bufferSize; } -double Plugin::d_getSampleRate() const noexcept +double Plugin::getSampleRate() const noexcept { return pData->sampleRate; } #if DISTRHO_PLUGIN_WANT_TIMEPOS -const TimePosition& Plugin::d_getTimePosition() const noexcept +const TimePosition& Plugin::getTimePosition() const noexcept { return pData->timePosition; } #endif #if DISTRHO_PLUGIN_WANT_LATENCY -void Plugin::d_setLatency(const uint32_t frames) noexcept +void Plugin::setLatency(const uint32_t frames) noexcept { pData->latency = frames; } #endif #if DISTRHO_PLUGIN_WANT_MIDI_OUTPUT -bool Plugin::d_writeMidiEvent(const MidiEvent& /*midiEvent*/) noexcept +bool Plugin::writeMidiEvent(const MidiEvent& /*midiEvent*/) noexcept { // TODO return false; @@ -112,29 +112,29 @@ bool Plugin::d_writeMidiEvent(const MidiEvent& /*midiEvent*/) noexcept /* ------------------------------------------------------------------------------------------------------------ * Init */ -void Plugin::d_initAudioPort(bool input, uint32_t index, AudioPort& port) +void Plugin::initAudioPort(bool input, uint32_t index, AudioPort& port) { if (port.hints & kAudioPortIsCV) { port.name = input ? "CV Input " : "CV Output "; - port.name += d_string(index+1); + port.name += String(index+1); port.symbol = input ? "cv_in_" : "cv_out_"; - port.symbol += d_string(index+1); + port.symbol += String(index+1); } else { port.name = input ? "Audio Input " : "Audio Output "; - port.name += d_string(index+1); + port.name += String(index+1); port.symbol = input ? "audio_in_" : "audio_out_"; - port.symbol += d_string(index+1); + port.symbol += String(index+1); } } /* ------------------------------------------------------------------------------------------------------------ * Callbacks (optional) */ -void Plugin::d_bufferSizeChanged(uint32_t) {} -void Plugin::d_sampleRateChanged(double) {} +void Plugin::bufferSizeChanged(uint32_t) {} +void Plugin::sampleRateChanged(double) {} // ----------------------------------------------------------------------------------------------------------- diff --git a/distrho/src/DistrhoUI.cpp b/distrho/src/DistrhoUI.cpp index 78bfd88e..1cfd5336 100644 --- a/distrho/src/DistrhoUI.cpp +++ b/distrho/src/DistrhoUI.cpp @@ -46,30 +46,30 @@ UI::~UI() /* ------------------------------------------------------------------------------------------------------------ * Host state */ -double UI::d_getSampleRate() const noexcept +double UI::getSampleRate() const noexcept { return pData->sampleRate; } -void UI::d_editParameter(const uint32_t index, const bool started) +void UI::editParameter(const uint32_t index, const bool started) { pData->editParamCallback(index + pData->parameterOffset, started); } -void UI::d_setParameterValue(const uint32_t index, const float value) +void UI::setParameterValue(const uint32_t index, const float value) { pData->setParamCallback(index + pData->parameterOffset, value); } #if DISTRHO_PLUGIN_WANT_STATE -void UI::d_setState(const char* const key, const char* const value) +void UI::setState(const char* const key, const char* const value) { pData->setStateCallback(key, value); } #endif #if DISTRHO_PLUGIN_IS_SYNTH -void UI::d_sendNote(const uint8_t channel, const uint8_t note, const uint8_t velocity) +void UI::sendNote(const uint8_t channel, const uint8_t note, const uint8_t velocity) { pData->sendNoteCallback(channel, note, velocity); } @@ -79,7 +79,7 @@ void UI::d_sendNote(const uint8_t channel, const uint8_t note, const uint8_t vel /* ------------------------------------------------------------------------------------------------------------ * Direct DSP access */ -void* UI::d_getPluginInstancePointer() const noexcept +void* UI::getPluginInstancePointer() const noexcept { return pData->dspPtr; } @@ -88,16 +88,16 @@ void* UI::d_getPluginInstancePointer() const noexcept /* ------------------------------------------------------------------------------------------------------------ * DSP/Plugin Callbacks (optional) */ -void UI::d_sampleRateChanged(double) {} +void UI::sampleRateChanged(double) {} /* ------------------------------------------------------------------------------------------------------------ * UI Callbacks (optional) */ -void UI::d_uiFileBrowserSelected(const char*) +void UI::uiFileBrowserSelected(const char*) { } -void UI::d_uiReshape(uint width, uint height) +void UI::uiReshape(uint width, uint height) { glEnable(GL_BLEND); glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); diff --git a/dpf.doxygen b/dpf.doxygen index 39f8379d..2dfa18d3 100644 --- a/dpf.doxygen +++ b/dpf.doxygen @@ -95,7 +95,7 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = distrho +INPUT = distrho distrho/extra dgl INPUT_ENCODING = UTF-8 FILE_PATTERNS = RECURSIVE = NO