Cleanup docs, add DistrhoPluginInfo.h template file

Signed-off-by: falkTX <falktx@falktx.com>

distrho/DistrhoInfo.hpp

@@ -603,6 +603,12 @@ START_NAMESPACE_DISTRHO
  */
 #define DISTRHO_PLUGIN_WANT_TIMEPOS 1
 
+/**
+   Whether the %UI uses Cairo for drawing instead of the default OpenGL mode.@n
+   When enabled your %UI instance will subclass @ref CairoTopLevelWidget instead of @ref TopLevelWidget.
+ */
+#define DISTRHO_UI_USE_CAIRO 1
+
 /**
    Whether the %UI uses a custom toolkit implementation based on OpenGL.@n
    When enabled, the macros @ref DISTRHO_UI_CUSTOM_INCLUDE_PATH and @ref DISTRHO_UI_CUSTOM_WIDGET_TYPE are required.
@@ -616,6 +622,12 @@ START_NAMESPACE_DISTRHO
  */
 #define DISTRHO_UI_CUSTOM_INCLUDE_PATH
 
+/**
+   Whether the %UI uses NanoVG for drawing instead of the default raw OpenGL mode.@n
+   When enabled your %UI instance will subclass @ref NanoTopLevelWidget instead of @ref TopLevelWidget.
+ */
+#define DISTRHO_UI_USE_NANOVG 1
+
 /**
    The top-level-widget typedef to use for the custom toolkit.
    This widget class MUST be a subclass of DGL TopLevelWindow class.
@@ -648,19 +660,25 @@ START_NAMESPACE_DISTRHO
 #define DISTRHO_UI_DEFAULT_HEIGHT 300
 
 /**
-   Whether 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
-
-/**
-   Whether the %UI is resizable to any size by the user.@n
-   By default this is false, and resizing is only allowed under the plugin UI control,@n
+   Whether the %UI is resizable to any size by the user and OS.@n
+   By default this is false, with resizing only allowed when coded from the the plugin UI side.@n
    Enabling this options makes it possible for the user to resize the plugin UI at anytime.
    @see UI::setGeometryConstraints(uint, uint, bool, bool)
  */
 #define DISTRHO_UI_USER_RESIZABLE 1
 
+/**
+   Whether to %UI is going to use file browser dialogs.@n
+   By default this is false, with the file browser APIs not available for use.
+ */
+#define DISTRHO_UI_FILE_BROWSER 1
+
+/**
+   Whether to %UI is going to use web browser views.@n
+   By default this is false, with the web browser APIs not available for use.
+ */
+#define DISTRHO_UI_WEB_VIEW 1
+
 /**
    The %UI URI when exporting in LV2 format.@n
    By default this is set to @ref DISTRHO_PLUGIN_URI with "#UI" as suffix.
@@ -865,7 +883,7 @@ START_NAMESPACE_DISTRHO
 /**
    Whether to enable runtime plugin tests.@n
    This will check, during initialization of the plugin, if parameters, programs and states are setup properly.@n
-   Useful to enable as part of CI, can safely be skipped.@n
+   Useful to enable as part of CI, can be safely skipped.@n
    Under DPF makefiles this can be enabled by using `make DPF_RUNTIME_TESTING=true`.
 
    @note Some checks are only available with the GCC compiler,
@@ -885,26 +903,12 @@ START_NAMESPACE_DISTRHO
  */
 #define DPF_VST3_DONT_USE_BRAND_ID
 
-/**
-   Disable all file browser related code.@n
-   Must be set as compiler macro when building DGL. (e.g. `CXXFLAGS="-DDGL_FILE_BROWSER_DISABLED"`)
- */
-#define DGL_FILE_BROWSER_DISABLED
-
 /**
    Disable resource files, like internally used fonts.@n
    Must be set as compiler macro when building DGL. (e.g. `CXXFLAGS="-DDGL_NO_SHARED_RESOURCES"`)
  */
 #define DGL_NO_SHARED_RESOURCES
 
-/**
-   Whether to use OpenGL3 instead of the default OpenGL2 compatility profile.
-   Under DPF makefiles this can be enabled by using `make USE_OPENGL3=true` on the dgl build step.
-
-   @note This is experimental and incomplete, contributions are welcome and appreciated.
- */
-#define DGL_USE_OPENGL3
-
 /** @} */
 
 /* ------------------------------------------------------------------------------------------------------------

distrho/DistrhoPlugin.hpp

@@ -189,30 +189,65 @@ protected:
       Get the plugin label.@n
       This label is a short restricted name consisting of only _, a-z, A-Z and 0-9 characters.
     */
+   #ifdef DISTRHO_PLUGIN_LABEL
+    virtual const char* getLabel() const
+    {
+         return DISTRHO_PLUGIN_LABEL;
+    }
+   #else
     virtual const char* getLabel() const = 0;
+   #endif
 
    /**
       Get an extensive comment/description about the plugin.@n
       Optional, returns nothing by default.
     */
-    virtual const char* getDescription() const { return ""; }
+    virtual const char* getDescription() const
+    {
+       #ifdef DISTRHO_PLUGIN_DESCRIPTION
+        return DISTRHO_PLUGIN_DESCRIPTION;
+       #else
+        return "";
+       #endif
+    }
 
    /**
       Get the plugin author/maker.
     */
+   #ifdef DISTRHO_PLUGIN_MAKER
+    virtual const char* getMaker() const
+    {
+         return DISTRHO_PLUGIN_MAKER;
+    }
+   #else
     virtual const char* getMaker() const = 0;
+   #endif
 
    /**
       Get the plugin homepage.@n
       Optional, returns nothing by default.
     */
-    virtual const char* getHomePage() const { return ""; }
+    virtual const char* getHomePage() const
+    {
+       #ifdef DISTRHO_PLUGIN_HOMEPAGE
+        return DISTRHO_PLUGIN_HOMEPAGE;
+       #else
+        return "";
+       #endif
+    }
 
    /**
       Get the plugin license (a single line of text or a URL).@n
       For commercial plugins this should return some short copyright information.
     */
+   #ifdef DISTRHO_PLUGIN_LICENSE
+    virtual const char* getLicense() const
+    {
+         return DISTRHO_PLUGIN_LICENSE;
+    }
+   #else
     virtual const char* getLicense() const = 0;
+   #endif
 
    /**
       Get the plugin version, in hexadecimal.

distrho/DistrhoPluginInfo.h.template

@@ -0,0 +1,392 @@
+#pragma once
+
+/**
+   This file contains C Macros that describe this plugin.
+   With these macros we can tell the host what features the plugin requires.
+   New functions will be available to call and/or override depending on which macros are enabled.
+
+   All values are either integer or strings.
+   For boolean-like values 1 means 'on' and 0 means 'off'.
+ */
+
+/**
+   The plugin name.
+   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.
+   TODO describe what a URI is
+   @note This macro is required.
+ */
+#define DISTRHO_PLUGIN_URI "urn:distrho:name"
+
+/**
+   Whether the plugin has a custom UI.
+ */
+// #define DISTRHO_PLUGIN_HAS_UI 0
+
+/**
+   Whether the plugin processing is realtime-safe.
+   TODO - list rtsafe requirements
+ */
+// #define DISTRHO_PLUGIN_IS_RT_SAFE 0
+
+/**
+   Whether the plugin is a synth.
+   @ref DISTRHO_PLUGIN_WANT_MIDI_INPUT is automatically enabled when this is too.
+   @see DISTRHO_PLUGIN_WANT_MIDI_INPUT
+ */
+// #define DISTRHO_PLUGIN_IS_SYNTH 0
+
+/**
+   Request the minimum buffer size for the input and output event ports.
+   Currently only used in LV2, with a default value of 2048 if unset.
+ */
+// #define DISTRHO_PLUGIN_MINIMUM_BUFFER_SIZE 2048
+
+/**
+   Whether the plugin has an LV2 modgui.
+
+   This will simply add a "rdfs:seeAlso <modgui.ttl>" on the LV2 manifest.
+   It is up to you to create this file.
+ */
+// #define DISTRHO_PLUGIN_USES_MODGUI 0
+
+/**
+   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
+
+/**
+   Whether the plugin introduces latency during audio or midi processing.
+   @see Plugin::setLatency(uint32_t)
+ */
+// #define DISTRHO_PLUGIN_WANT_LATENCY 0
+
+/**
+   Whether the plugin wants MIDI input.
+   This is automatically enabled if @ref DISTRHO_PLUGIN_IS_SYNTH is true.
+ */
+// #define DISTRHO_PLUGIN_WANT_MIDI_INPUT 0
+
+/**
+   Whether the plugin wants MIDI output.
+   @see Plugin::writeMidiEvent(const MidiEvent&)
+ */
+// #define DISTRHO_PLUGIN_WANT_MIDI_OUTPUT 0
+
+/**
+   Whether the plugin wants to change its own parameter inputs.
+   Not all hosts or plugin formats support this,
+   so Plugin::canRequestParameterValueChanges() can be used to query support at runtime.
+   @see Plugin::requestParameterValueChange(uint32_t, float)
+ */
+// #define DISTRHO_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST 0
+
+/**
+   Whether the plugin provides its own internal programs.
+   @see Plugin::initProgramName(uint32_t, String&)
+   @see Plugin::loadProgram(uint32_t)
+ */
+// #define DISTRHO_PLUGIN_WANT_PROGRAMS 0
+
+/**
+   Whether 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 0
+
+/**
+   Whether the plugin implements the full state API.
+   When this macro is enabled, the plugin must implement a new getState(const char* key) function, which the host calls when saving its session/project.
+   This is useful for plugins that have custom internal values not exposed to the host as key-value state pairs or parameters.
+   Most simple effects and synths will not need this.
+   @note this macro is automatically enabled if a plugin has programs and state, as the key-value state pairs need to be updated when the current program changes.
+   @see Plugin::getState(const char*)
+ */
+// #define DISTRHO_PLUGIN_WANT_FULL_STATE 0
+
+/**
+   Whether the plugin wants time position information from the host.
+   @see Plugin::getTimePosition()
+ */
+// #define DISTRHO_PLUGIN_WANT_TIMEPOS 0
+
+/**
+   Whether the UI uses Cairo for drawing instead of the default OpenGL mode.
+   When enabled your UI instance will subclass CairoTopLevelWidget instead of TopLevelWidget.
+ */
+// #define DISTRHO_UI_USE_CAIRO 0
+
+/**
+   Whether the UI uses a custom toolkit implementation based on OpenGL.
+   When enabled, the macros DISTRHO_UI_CUSTOM_INCLUDE_PATH and DISTRHO_UI_CUSTOM_WIDGET_TYPE are required.
+ */
+// #define DISTRHO_UI_USE_CUSTOM 0
+
+/**
+   The include path to the header file used by the custom toolkit implementation.
+   This path must be relative to dpf/distrho/DistrhoUI.hpp
+ */
+// #define DISTRHO_UI_CUSTOM_INCLUDE_PATH
+
+/**
+   The top-level-widget typedef to use for the custom toolkit.
+   This widget class MUST be a subclass of DGL TopLevelWindow class.
+   It is recommended that you keep this widget class inside the DGL namespace,
+   and define widget type as e.g. DGL_NAMESPACE::MyCustomTopLevelWidget.
+ */
+// #define DISTRHO_UI_CUSTOM_WIDGET_TYPE
+
+/**
+   Whether the %UI uses NanoVG for drawing instead of the default raw OpenGL mode.@n
+   When enabled your %UI instance will subclass NanoTopLevelWidget instead of TopLevelWidget.
+ */
+// #define DISTRHO_UI_USE_NANOVG 0
+
+/**
+   Default UI width to use when creating initial and temporary windows.
+   Setting this macro allows to skip a temporary UI from being created in certain VST2 and VST3 hosts.
+   (which would normally be done for knowing the UI size before host creates a window for it)
+
+   Value must match 1x scale factor.
+
+   When this macro is defined, the companion DISTRHO_UI_DEFAULT_HEIGHT macro must be defined as well.
+ */
+// #define DISTRHO_UI_DEFAULT_WIDTH 300
+
+/**
+   Default UI height to use when creating initial and temporary windows.
+   Setting this macro allows to skip a temporary UI from being created in certain VST2 and VST3 hosts.
+   (which would normally be done for knowing the UI size before host creates a window for it)
+
+   Value must match 1x scale factor.
+
+   When this macro is defined, the companion DISTRHO_UI_DEFAULT_WIDTH macro must be defined as well.
+ */
+// #define DISTRHO_UI_DEFAULT_HEIGHT 300
+
+/**
+   Whether the UI is resizable to any size by the user and OS.
+   By default this is false, with resizing only allowed when coded from the the plugin UI side.
+   Enabling this options makes it possible for the user to resize the plugin UI at anytime.
+   @see UI::setGeometryConstraints(uint, uint, bool, bool)
+ */
+// #define DISTRHO_UI_USER_RESIZABLE 0
+
+/**
+   Whether to UI is going to use file browser dialogs.
+   By default this is false, with the file browser APIs not available for use.
+ */
+// #define DISTRHO_UI_FILE_BROWSER 0
+
+/**
+   Whether to UI is going to use web browser views.
+   By default this is false, with the web browser APIs not available for use.
+ */
+// #define DISTRHO_UI_WEB_VIEW 0
+
+/**
+   The UI URI when exporting in LV2 format.
+   By default this is set to @ref DISTRHO_PLUGIN_URI with "#UI" as suffix.
+ */
+// #define DISTRHO_UI_URI DISTRHO_PLUGIN_URI "#UI"
+
+/**
+   The AudioUnit type for a plugin.
+   This is a 4-character symbol, automatically set by DPF based on other plugin macros.
+   See https://developer.apple.com/documentation/audiotoolbox/1584142-audio_unit_types for more information.
+ */
+// #define DISTRHO_PLUGIN_AU_TYPE aufx
+
+/**
+   A 4-character symbol that identifies a brand or manufacturer, with at least one non-lower case character.
+   Plugins from the same brand should use the same symbol.
+   @note This macro is required when building AU plugins, and used for VST3 if present
+   @note Setting this macro will change the uid of a VST3 plugin.
+         If you already released a DPF-based VST3 plugin make sure to also enable DPF_VST3_DONT_USE_BRAND_ID
+ */
+#define DISTRHO_PLUGIN_BRAND_ID Dstr
+
+/**
+   A 4-character symbol which identifies a plugin.
+   It must be unique within at least a set of plugins from the brand.
+   @note This macro is required when building AU plugins
+ */
+// #define DISTRHO_PLUGIN_UNIQUE_ID test
+
+/**
+   Custom LV2 category for the plugin.
+   This is a single string, and can be one of the following values:
+
+      - lv2:AllpassPlugin
+      - lv2:AmplifierPlugin
+      - lv2:AnalyserPlugin
+      - lv2:BandpassPlugin
+      - lv2:ChorusPlugin
+      - lv2:CombPlugin
+      - lv2:CompressorPlugin
+      - lv2:ConstantPlugin
+      - lv2:ConverterPlugin
+      - lv2:DelayPlugin
+      - lv2:DistortionPlugin
+      - lv2:DynamicsPlugin
+      - lv2:EQPlugin
+      - lv2:EnvelopePlugin
+      - lv2:ExpanderPlugin
+      - lv2:FilterPlugin
+      - lv2:FlangerPlugin
+      - lv2:FunctionPlugin
+      - lv2:GatePlugin
+      - lv2:GeneratorPlugin
+      - lv2:HighpassPlugin
+      - lv2:InstrumentPlugin
+      - lv2:LimiterPlugin
+      - lv2:LowpassPlugin
+      - lv2:MIDIPlugin
+      - lv2:MixerPlugin
+      - lv2:ModulatorPlugin
+      - lv2:MultiEQPlugin
+      - lv2:OscillatorPlugin
+      - lv2:ParaEQPlugin
+      - lv2:PhaserPlugin
+      - lv2:PitchPlugin
+      - lv2:ReverbPlugin
+      - lv2:SimulatorPlugin
+      - lv2:SpatialPlugin
+      - lv2:SpectralPlugin
+      - lv2:UtilityPlugin
+      - lv2:WaveshaperPlugin
+
+   See http://lv2plug.in/ns/lv2core for more information.
+ */
+// #define DISTRHO_PLUGIN_LV2_CATEGORY "lv2:Plugin"
+
+/**
+   Custom VST3 categories for the plugin.
+   This is a single concatenated string of categories, separated by a @c |.
+
+   Each effect category can be one of the following values:
+
+      - Fx
+      - Fx|Ambisonics
+      - Fx|Analyzer
+      - Fx|Delay
+      - Fx|Distortion
+      - Fx|Dynamics
+      - Fx|EQ
+      - Fx|Filter
+      - Fx|Instrument
+      - Fx|Instrument|External
+      - Fx|Spatial
+      - Fx|Generator
+      - Fx|Mastering
+      - Fx|Modulation
+      - Fx|Network
+      - Fx|Pitch Shift
+      - Fx|Restoration
+      - Fx|Reverb
+      - Fx|Surround
+      - Fx|Tools
+
+   Each instrument category can be one of the following values:
+
+      - Instrument
+      - Instrument|Drum
+      - Instrument|External
+      - Instrument|Piano
+      - Instrument|Sampler
+      - Instrument|Synth
+      - Instrument|Synth|Sampler
+
+   And extra categories possible for any plugin type:
+
+      - Mono
+      - Stereo
+ */
+// #define DISTRHO_PLUGIN_VST3_CATEGORIES "Fx|Stereo"
+
+/**
+   Custom CLAP features for the plugin.
+   This is a list of features defined as a string array body, without the terminating @c , or nullptr.
+
+   A top-level category can be set as feature and be one of the following values:
+
+      - instrument
+      - audio-effect
+      - note-effect
+      - analyzer
+
+   The following sub-categories can also be set:
+
+      - synthesizer
+      - sampler
+      - drum
+      - drum-machine
+
+      - filter
+      - phaser
+      - equalizer
+      - de-esser
+      - phase-vocoder
+      - granular
+      - frequency-shifter
+      - pitch-shifter
+
+      - distortion
+      - transient-shaper
+      - compressor
+      - limiter
+
+      - flanger
+      - chorus
+      - delay
+      - reverb
+
+      - tremolo
+      - glitch
+
+      - utility
+      - pitch-correction
+      - restoration
+
+      - multi-effects
+
+      - mixing
+      - mastering
+
+   And finally the following audio capabilities can be set:
+
+      - mono
+      - stereo
+      - surround
+      - ambisonic
+*/
+// #define DISTRHO_PLUGIN_CLAP_FEATURES "audio-effect", "stereo"
+
+/**
+   The plugin id when exporting in CLAP format, in reverse URI form.
+   @note This macro is required when building CLAP plugins
+*/
+// #define DISTRHO_PLUGIN_CLAP_ID "studio.kx.distrho.effect"
+
+/** @} */

distrho/src/DistrhoPluginChecks.h

@@ -152,7 +152,7 @@
 #endif
 
 #ifdef DISTRHO_UI_FILEBROWSER
-# error typo detected use DGL_USE_FILE_BROWSER instead of DISTRHO_UI_FILEBROWSER
+# error typo detected use DISTRHO_UI_FILE_BROWSER instead of DISTRHO_UI_FILEBROWSER
 #endif
 
 #ifdef DISTRHO_UI_WEBVIEW

examples/CairoUI/CairoExampleUI.cpp

@@ -74,19 +74,11 @@ public:
         fButton->setCallback(this);
         fButton->setId(kParameterButton);
 
-#if 0
-        // we can use this if/when our resources are scalable, for now they are PNGs
-        const double scaleFactor = getScaleFactor();
-        if (scaleFactor != 1.0)
-            setSize(200 * scaleFactor, 200 * scaleFactor);
-#else
-        // without scalable resources, let DPF handle the scaling internally
         setGeometryConstraints(DISTRHO_UI_DEFAULT_WIDTH, DISTRHO_UI_DEFAULT_HEIGHT, true, true);
-#endif
     }
 
 protected:
-    void onCairoDisplay(const CairoGraphicsContext& context)
+    void onCairoDisplay(const CairoGraphicsContext& context) override
     {
         cairo_t* const cr = context.handle;
         cairo_set_source_rgb(cr, 1.0, 0.8, 0.5);

examples/CairoUI/DistrhoPluginInfo.h

@@ -1,21 +1,16 @@
-/*
- * DISTRHO Plugin Framework (DPF)
- * Copyright (C) 2012-2024 Filipe Coelho <falktx@falktx.com>
- *
- * 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.
- */
-
-/**
-   The plugin name.@n
+#pragma once
+
+/**
+   This file contains C Macros that describe this plugin.
+   With these macros we can tell the host what features the plugin requires.
+   New functions will be available to call and/or override depending on which macros are enabled.
+
+   All values are either integer or strings.
+   For boolean-like values 1 means 'on' and 0 means 'off'.
+ */
+
+/**
+   The plugin name.
    This is used to identify your plugin before a Plugin instance can be created.
    @note This macro is required.
  */
@@ -35,106 +30,141 @@
 
 /**
    The plugin URI when exporting in LV2 format.
+   TODO describe what a URI is
    @note This macro is required.
  */
 #define DISTRHO_PLUGIN_URI "http://distrho.sf.net/examples/CairoUI"
 
 /**
-   The AudioUnit manufacturer for a plugin.
-   This is a 4-character symbol with at least one non-lower case character.
-   Plugins from the same brand/maker should use the same symbol.
-   @note This macro is required when building AU plugins
+   Whether the plugin has a custom UI.
  */
-#define DISTRHO_PLUGIN_BRAND_ID Dstr
+#define DISTRHO_PLUGIN_HAS_UI 1
 
 /**
-   The AudioUnit subtype for a plugin.
-   This is a 4-character symbol which identifies a plugin.
-   It must be unique within a manufacturer's plugins, but different manufacturers can use the same subtype.
-   @note This macro is required when building AU plugins
+   Whether the plugin processing is realtime-safe.
+   TODO - list rtsafe requirements
  */
-#define DISTRHO_PLUGIN_UNIQUE_ID dCai
-
-/**
-   The plugin id when exporting in CLAP format, in reverse URI form.
-   @note This macro is required when building CLAP plugins
-*/
-#define DISTRHO_PLUGIN_CLAP_ID "studio.kx.distrho.examples.cairo-ui"
+#define DISTRHO_PLUGIN_IS_RT_SAFE 1
 
 /**
-   Wherever the plugin has a custom %UI.
-   @see DISTRHO_UI_USE_NANOVG
-   @see UI
+   Whether the plugin is a synth.
+   @ref DISTRHO_PLUGIN_WANT_MIDI_INPUT is automatically enabled when this is too.
+   @see DISTRHO_PLUGIN_WANT_MIDI_INPUT
  */
-#define DISTRHO_PLUGIN_HAS_UI 1
+// #define DISTRHO_PLUGIN_IS_SYNTH 0
 
 /**
-   Wherever the plugin processing is realtime-safe.@n
-   TODO - list rtsafe requirements
+   Request the minimum buffer size for the input and output event ports.
+   Currently only used in LV2, with a default value of 2048 if unset.
  */
-#define DISTRHO_PLUGIN_IS_RT_SAFE 1
+// #define DISTRHO_PLUGIN_MINIMUM_BUFFER_SIZE 2048
 
 /**
-   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
+   Whether the plugin has an LV2 modgui.
+
+   This will simply add a "rdfs:seeAlso <modgui.ttl>" on the LV2 manifest.
+   It is up to you to create this file.
  */
-#define DISTRHO_PLUGIN_IS_SYNTH 0
+// #define DISTRHO_PLUGIN_USES_MODGUI 0
 
 /**
-   Enable direct access between the %UI and plugin code.
+   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
+// #define DISTRHO_PLUGIN_WANT_DIRECT_ACCESS 0
 
 /**
-   Wherever the plugin introduces latency during audio or midi processing.
+   Whether the plugin introduces latency during audio or midi processing.
    @see Plugin::setLatency(uint32_t)
  */
-#define DISTRHO_PLUGIN_WANT_LATENCY 0
+// #define DISTRHO_PLUGIN_WANT_LATENCY 0
 
 /**
-   Wherever the plugin wants MIDI input.@n
+   Whether the plugin wants MIDI input.
    This is automatically enabled if @ref DISTRHO_PLUGIN_IS_SYNTH is true.
  */
-#define DISTRHO_PLUGIN_WANT_MIDI_INPUT 0
+// #define DISTRHO_PLUGIN_WANT_MIDI_INPUT 0
 
 /**
-   Wherever the plugin wants MIDI output.
+   Whether the plugin wants MIDI output.
    @see Plugin::writeMidiEvent(const MidiEvent&)
  */
-#define DISTRHO_PLUGIN_WANT_MIDI_OUTPUT 0
+// #define DISTRHO_PLUGIN_WANT_MIDI_OUTPUT 0
 
 /**
-   Wherever the plugin provides its own internal programs.
+   Whether the plugin wants to change its own parameter inputs.
+   Not all hosts or plugin formats support this,
+   so Plugin::canRequestParameterValueChanges() can be used to query support at runtime.
+   @see Plugin::requestParameterValueChange(uint32_t, float)
+ */
+// #define DISTRHO_PLUGIN_WANT_PARAMETER_VALUE_CHANGE_REQUEST 0
+
+/**
+   Whether the plugin provides its own internal programs.
    @see Plugin::initProgramName(uint32_t, String&)
    @see Plugin::loadProgram(uint32_t)
  */
-#define DISTRHO_PLUGIN_WANT_PROGRAMS 0
+// #define DISTRHO_PLUGIN_WANT_PROGRAMS 0
 
 /**
-   Wherever the plugin uses internal non-parameter data.
+   Whether 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 0
+// #define DISTRHO_PLUGIN_WANT_STATE 0
 
 /**
-   Wherever the plugin wants time position information from the host.
+   Whether the plugin implements the full state API.
+   When this macro is enabled, the plugin must implement a new getState(const char* key) function, which the host calls when saving its session/project.
+   This is useful for plugins that have custom internal values not exposed to the host as key-value state pairs or parameters.
+   Most simple effects and synths will not need this.
+   @note this macro is automatically enabled if a plugin has programs and state, as the key-value state pairs need to be updated when the current program changes.
+   @see Plugin::getState(const char*)
+ */
+// #define DISTRHO_PLUGIN_WANT_FULL_STATE 0
+
+/**
+   Whether the plugin wants time position information from the host.
    @see Plugin::getTimePosition()
  */
-#define DISTRHO_PLUGIN_WANT_TIMEPOS 0
+// #define DISTRHO_PLUGIN_WANT_TIMEPOS 0
+
+/**
+   Whether the UI uses Cairo for drawing instead of the default OpenGL mode.
+   When enabled your UI instance will subclass CairoTopLevelWidget instead of TopLevelWidget.
+ */
+#define DISTRHO_UI_USE_CAIRO 1
+
+/**
+   Whether the UI uses a custom toolkit implementation based on OpenGL.
+   When enabled, the macros DISTRHO_UI_CUSTOM_INCLUDE_PATH and DISTRHO_UI_CUSTOM_WIDGET_TYPE are required.
+ */
+// #define DISTRHO_UI_USE_CUSTOM 0
 
 /**
-   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.
+   The include path to the header file used by the custom toolkit implementation.
+   This path must be relative to dpf/distrho/DistrhoUI.hpp
  */
-#define DISTRHO_UI_USE_NANOVG 0
+// #define DISTRHO_UI_CUSTOM_INCLUDE_PATH
 
 /**
-   Default UI width to use when creating initial and temporary windows.@n
+   The top-level-widget typedef to use for the custom toolkit.
+   This widget class MUST be a subclass of DGL TopLevelWindow class.
+   It is recommended that you keep this widget class inside the DGL namespace,
+   and define widget type as e.g. DGL_NAMESPACE::MyCustomTopLevelWidget.
+ */
+// #define DISTRHO_UI_CUSTOM_WIDGET_TYPE
+
+/**
+   Whether the %UI uses NanoVG for drawing instead of the default raw OpenGL mode.@n
+   When enabled your %UI instance will subclass NanoTopLevelWidget instead of TopLevelWidget.
+ */
+// #define DISTRHO_UI_USE_NANOVG 0
+
+/**
+   Default UI width to use when creating initial and temporary windows.
    Setting this macro allows to skip a temporary UI from being created in certain VST2 and VST3 hosts.
    (which would normally be done for knowing the UI size before host creates a window for it)
 
@@ -145,7 +175,7 @@
 #define DISTRHO_UI_DEFAULT_WIDTH 200
 
 /**
-   Default UI height to use when creating initial and temporary windows.@n
+   Default UI height to use when creating initial and temporary windows.
    Setting this macro allows to skip a temporary UI from being created in certain VST2 and VST3 hosts.
    (which would normally be done for knowing the UI size before host creates a window for it)
 
@@ -155,11 +185,209 @@
  */
 #define DISTRHO_UI_DEFAULT_HEIGHT 200
 
-// TODO document this
-#define DISTRHO_UI_USE_CAIRO 1
+/**
+   Whether the UI is resizable to any size by the user and OS.
+   By default this is false, with resizing only allowed when coded from the the plugin UI side.
+   Enabling this options makes it possible for the user to resize the plugin UI at anytime.
+   @see UI::setGeometryConstraints(uint, uint, bool, bool)
+ */
+// #define DISTRHO_UI_USER_RESIZABLE 0
+
+/**
+   Whether to UI is going to use file browser dialogs.
+   By default this is false, with the file browser APIs not available for use.
+ */
+// #define DISTRHO_UI_FILE_BROWSER 0
 
-// TODO document this
-#define DISTRHO_UI_FILE_BROWSER 0
+/**
+   Whether to UI is going to use web browser views.
+   By default this is false, with the web browser APIs not available for use.
+ */
+// #define DISTRHO_UI_WEB_VIEW 0
+
+/**
+   The UI URI when exporting in LV2 format.
+   By default this is set to @ref DISTRHO_PLUGIN_URI with "#UI" as suffix.
+ */
+// #define DISTRHO_UI_URI DISTRHO_PLUGIN_URI "#UI"
+
+/**
+   The AudioUnit type for a plugin.
+   This is a 4-character symbol, automatically set by DPF based on other plugin macros.
+   See https://developer.apple.com/documentation/audiotoolbox/1584142-audio_unit_types for more information.
+ */
+// #define DISTRHO_PLUGIN_AU_TYPE aufx
+
+/**
+   A 4-character symbol that identifies a brand or manufacturer, with at least one non-lower case character.
+   Plugins from the same brand should use the same symbol.
+   @note This macro is required when building AU plugins, and used for VST3 if present
+   @note Setting this macro will change the uid of a VST3 plugin.
+         If you already released a DPF-based VST3 plugin make sure to also enable DPF_VST3_DONT_USE_BRAND_ID
+ */
+#define DISTRHO_PLUGIN_BRAND_ID Dstr
+
+/**
+   A 4-character symbol which identifies a plugin.
+   It must be unique within at least a set of plugins from the brand.
+   @note This macro is required when building AU plugins
+ */
+#define DISTRHO_PLUGIN_UNIQUE_ID dCai
+
+/**
+   Custom LV2 category for the plugin.
+   This is a single string, and can be one of the following values:
+
+      - lv2:AllpassPlugin
+      - lv2:AmplifierPlugin
+      - lv2:AnalyserPlugin
+      - lv2:BandpassPlugin
+      - lv2:ChorusPlugin
+      - lv2:CombPlugin
+      - lv2:CompressorPlugin
+      - lv2:ConstantPlugin
+      - lv2:ConverterPlugin
+      - lv2:DelayPlugin
+      - lv2:DistortionPlugin
+      - lv2:DynamicsPlugin
+      - lv2:EQPlugin
+      - lv2:EnvelopePlugin
+      - lv2:ExpanderPlugin
+      - lv2:FilterPlugin
+      - lv2:FlangerPlugin
+      - lv2:FunctionPlugin
+      - lv2:GatePlugin
+      - lv2:GeneratorPlugin
+      - lv2:HighpassPlugin
+      - lv2:InstrumentPlugin
+      - lv2:LimiterPlugin
+      - lv2:LowpassPlugin
+      - lv2:MIDIPlugin
+      - lv2:MixerPlugin
+      - lv2:ModulatorPlugin
+      - lv2:MultiEQPlugin
+      - lv2:OscillatorPlugin
+      - lv2:ParaEQPlugin
+      - lv2:PhaserPlugin
+      - lv2:PitchPlugin
+      - lv2:ReverbPlugin
+      - lv2:SimulatorPlugin
+      - lv2:SpatialPlugin
+      - lv2:SpectralPlugin
+      - lv2:UtilityPlugin
+      - lv2:WaveshaperPlugin
+
+   See http://lv2plug.in/ns/lv2core for more information.
+ */
+#define DISTRHO_PLUGIN_LV2_CATEGORY "lv2:UtilityPlugin"
+
+/**
+   Custom VST3 categories for the plugin.
+   This is a single concatenated string of categories, separated by a @c |.
+
+   Each effect category can be one of the following values:
+
+      - Fx
+      - Fx|Ambisonics
+      - Fx|Analyzer
+      - Fx|Delay
+      - Fx|Distortion
+      - Fx|Dynamics
+      - Fx|EQ
+      - Fx|Filter
+      - Fx|Instrument
+      - Fx|Instrument|External
+      - Fx|Spatial
+      - Fx|Generator
+      - Fx|Mastering
+      - Fx|Modulation
+      - Fx|Network
+      - Fx|Pitch Shift
+      - Fx|Restoration
+      - Fx|Reverb
+      - Fx|Surround
+      - Fx|Tools
+
+   Each instrument category can be one of the following values:
+
+      - Instrument
+      - Instrument|Drum
+      - Instrument|External
+      - Instrument|Piano
+      - Instrument|Sampler
+      - Instrument|Synth
+      - Instrument|Synth|Sampler
+
+   And extra categories possible for any plugin type:
+
+      - Mono
+      - Stereo
+ */
+#define DISTRHO_PLUGIN_VST3_CATEGORIES "Fx|Tools|Mono"
+
+/**
+   Custom CLAP features for the plugin.
+   This is a list of features defined as a string array body, without the terminating @c , or nullptr.
+
+   A top-level category can be set as feature and be one of the following values:
+
+      - instrument
+      - audio-effect
+      - note-effect
+      - analyzer
+
+   The following sub-categories can also be set:
+
+      - synthesizer
+      - sampler
+      - drum
+      - drum-machine
+
+      - filter
+      - phaser
+      - equalizer
+      - de-esser
+      - phase-vocoder
+      - granular
+      - frequency-shifter
+      - pitch-shifter
+
+      - distortion
+      - transient-shaper
+      - compressor
+      - limiter
+
+      - flanger
+      - chorus
+      - delay
+      - reverb
+
+      - tremolo
+      - glitch
+
+      - utility
+      - pitch-correction
+      - restoration
+
+      - multi-effects
+
+      - mixing
+      - mastering
+
+   And finally the following audio capabilities can be set:
+
+      - mono
+      - stereo
+      - surround
+      - ambisonic
+*/
+#define DISTRHO_PLUGIN_CLAP_FEATURES "audio-effect", "utility", "mono"
+
+/**
+   The plugin id when exporting in CLAP format, in reverse URI form.
+   @note This macro is required when building CLAP plugins
+*/
+#define DISTRHO_PLUGIN_CLAP_ID "studio.kx.distrho.examples.cairo-ui"
 
 enum Parameters {
    kParameterKnob,