source/includes/vst3sdk/pluginterfaces/vst/ivstparameterfunctionname.h

   1 //------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstparameterfunctionname.h
   6 // Created by  : Steinberg, 03/2020
   7 // Description : VST Parameter Function Name Interface
   8 //
   9 //-----------------------------------------------------------------------------
  10 // This file is part of a Steinberg SDK. It is subject to the license terms
  11 // in the LICENSE file found in the top-level directory of this distribution
  12 // and at www.steinberg.net/sdklicenses.
  13 // No part of the SDK, including this file, may be copied, modified, propagated,
  14 // or distributed except according to the terms contained in the LICENSE file.
  15 //-----------------------------------------------------------------------------
  16
  17 #pragma once
  18
  19 #include "pluginterfaces/base/funknown.h"
  20 #include "pluginterfaces/vst/vsttypes.h"
  21
  22 //------------------------------------------------------------------------
  23 #include "pluginterfaces/base/falignpush.h"
  24 //------------------------------------------------------------------------
  25
  26 //------------------------------------------------------------------------
  27 namespace Steinberg {
  28 namespace Vst {
  29
  30 namespace FunctionNameType {
  31 //--------------------------------------------------------------------
  32         const CString kCompGainReduction                        = "Comp:GainReduction"; /**  */
  33         const CString kCompGainReductionMax                     = "Comp:GainReductionMax";
  34         const CString kCompGainReductionPeakHold        = "Comp:GainReductionPeakHold";
  35         const CString kCompResetGainReductionMax        = "Comp:ResetGainReductionMax";
  36
  37     const CString kLowLatencyMode = "LowLatencyMode"; /** Useful for live situation where low
  38                                                                                                                  latency is required:
  39                                                                                                                  0 means LowLatency disable,
  40                                                                                                                  1 means LowLatency enable */
  41     const CString kDryWetMix = "DryWetMix"; /** Allowing to mix the original (Dry) Signal with the processed one (Wet):
  42                                                                                         0.0 means Dry Signal only,
  43                                                                                         0.5 means 50% Dry Signal + 50% Wet Signal,
  44                                                                                         1.0 means Wet Signal only */
  45     const CString kRandomize = "Randomize"; /** Allow to assign some randomized values to some
  46                                                parameters in a controlled way*/
  47
  48 } // FunctionNameType
  49
  50 //------------------------------------------------------------------------
  51 /** Edit controller component interface extension: Vst::IParameterFunctionName
  52 \ingroup vstIPlug vst370
  53 - [plug imp]
  54 - [extends IEditController]
  55 - [released: 3.7.0]
  56 - [optional]
  57
  58 This interface allows the host to get a parameter associated to a specific meaning (a functionName) for a given unit.
  59 The host can use this information, for example, for drawing a Gain Reduction meter in its own UI.
  60 In order to get the plain value of this parameter, the host should use the IEditController::normalizedParamToPlain.
  61 The host can automatically map parameters to dedicated UI controls, such as the wet-dry mix knob or Randomize button.
  62
  63 \section IParameterFunctionNameExample Example
  64
  65 \code{.cpp}
  66 //------------------------------------------------------------------------
  67 // here an example of how a VST3 plug-in could support this IParameterFunctionName interface.
  68 // we need to define somewhere the iids:
  69
  70 in MyController class declaration
  71 class MyController : public Vst::EditController, public Vst::IParameterFunctionName
  72 {
  73         ...
  74         tresult PLUGIN_API getParameterIDFromFunctionName (UnitID unitID, FIDString functionName,
  75                                                                                                         Vst::ParamID& paramID) override;
  76         ...
  77
  78         OBJ_METHODS (MyController, Vst::EditController)
  79         DEFINE_INTERFACES
  80                 ...
  81                 DEF_INTERFACE (Vst::IParameterFunctionName)
  82         END_DEFINE_INTERFACES (Vst::EditController)
  83         ...
  84 }
  85
  86 #include "ivstparameterfunctionname.h"
  87 namespace Steinberg {
  88         namespace Vst {
  89                 DEF_CLASS_IID (IParameterFunctionName)
  90         }
  91 }
  92
  93 //------------------------------------------------------------------------
  94 tresult PLUGIN_API MyController::getParameterIDFromFunctionName (UnitID unitID, FIDString functionName,
  95                                                                  Vst::ParamID& paramID)
  96 {
  97         using namespace Vst;
  98
  99         paramID = kNoParamId;
 100
 101         if (unitID == kRootUnitId && FIDStringsEqual (functionName, kCompGainReduction))
 102                 paramID = kMyGainReductionId;
 103
 104         return (paramID != kNoParamId) ? kResultOk : kResultFalse;
 105 }
 106
 107 //--- a host implementation example: --------------------
 108 ...
 109 FUnknownPtr<Vst::IParameterFunctionName> functionName (mEditController->getIEditController ());
 110 if (functionName)
 111 {
 112         Vst::ParamID paramID;
 113         if (functionName->getParameterIDFromFunctionName (Vst::FunctionNameType::kCompGainReduction, paramID) == kResultTrue)
 114         {
 115                 // paramID could be cached for performance issue
 116                 ParamValue norm = mEditController->getIEditController ()->getParamNormalized (paramID);
 117                 ParamValue plain = mEditController->getIEditController ()->normalizedParamToPlain (paramID, norm);
 118                 // plain is something like -6 (-6dB)
 119         }
 120 }
 121 \endcode
 122 */
 123 class IParameterFunctionName : public FUnknown
 124 {
 125 public:
 126         //------------------------------------------------------------------------
 127         /** Gets for the given unitID the associated paramID to a function Name.
 128                 Returns kResultFalse when no found parameter (paramID is set to kNoParamId in this case). */
 129         virtual tresult PLUGIN_API getParameterIDFromFunctionName (UnitID unitID, FIDString functionName, ParamID& paramID) = 0;
 130
 131         //------------------------------------------------------------------------
 132         static const FUID iid;
 133 };
 134
 135 DECLARE_CLASS_IID (IParameterFunctionName, 0x6D21E1DC, 0x91199D4B, 0xA2A02FEF, 0x6C1AE55C)
 136
 137 //------------------------------------------------------------------------
 138 } // namespace Vst
 139 } // namespace Steinberg
 140
 141 //------------------------------------------------------------------------
 142 #include "pluginterfaces/base/falignpop.h"
 143 //------------------------------------------------------------------------