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

   1 //------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstphysicalui.h
   6 // Created by  : Steinberg, 06/2018
   7 // Description : VST Physical User Interface support
   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/vst/ivstnoteexpression.h"
  20
  21 //------------------------------------------------------------------------
  22 #include "pluginterfaces/base/falignpush.h"
  23 //------------------------------------------------------------------------
  24
  25 //------------------------------------------------------------------------
  26 namespace Steinberg {
  27 namespace Vst {
  28
  29 //------------------------------------------------------------------------
  30 /** \defgroup vst3typedef VST 3 Data Types */
  31 /*@{*/
  32 //------------------------------------------------------------------------
  33 /** Physical UI Type */
  34 typedef uint32 PhysicalUITypeID;
  35 /*@}*/
  36
  37 //------------------------------------------------------------------------
  38 /** PhysicalUITypeIDs describes the type of Physical UI (PUI) which could be associated to a note
  39 expression.
  40 \see PhysicalUIMap
  41 */
  42 enum PhysicalUITypeIDs
  43 {
  44         /** absolute X position when touching keys of PUIs. Range [0=left, 0.5=middle, 1=right] */
  45         kPUIXMovement = 0,
  46         /** absolute Y position when touching keys of PUIs. Range [0=bottom/near, 0.5=center, 1=top/far] */
  47         kPUIYMovement,
  48         /** pressing a key down on keys of PUIs. Range [0=No Pressure, 1=Full Pressure] */
  49         kPUIPressure,
  50
  51         kPUITypeCount, ///< count of current defined PUIs
  52
  53         kInvalidPUITypeID = 0xFFFFFFFF ///< indicates an invalid or not initialized PUI type
  54 };
  55
  56 //------------------------------------------------------------------------
  57 /** PhysicalUIMap describes a mapping of a noteExpression Type to a Physical UI Type.
  58 It is used in PhysicalUIMapList.
  59 \see PhysicalUIMapList
  60 */
  61 struct PhysicalUIMap
  62 {
  63         /** This represents the physical UI. /see PhysicalUITypeIDs, this is set by the caller of
  64          * getPhysicalUIMapping */
  65         PhysicalUITypeID physicalUITypeID;
  66
  67         /** This represents the associated noteExpression TypeID to the given physicalUITypeID. This
  68          * will be filled by the plug-in in the call getPhysicalUIMapping, set it to kInvalidTypeID if
  69          * no Note Expression is associated to the given PUI. */
  70         NoteExpressionTypeID noteExpressionTypeID;
  71 };
  72
  73 //------------------------------------------------------------------------
  74 /** PhysicalUIMapList describes a list of PhysicalUIMap
  75 \see INoteExpressionPhysicalUIMapping
  76 */
  77 struct PhysicalUIMapList
  78 {
  79         /** Count of entries in the map array, set by the caller of getPhysicalUIMapping. */
  80         uint32 count;
  81
  82         /** Pointer to a list of PhysicalUIMap containing count entries. */
  83         PhysicalUIMap* map;
  84 };
  85
  86 //------------------------------------------------------------------------
  87 /** Extended plug-in interface IEditController for note expression event support: Vst::INoteExpressionPhysicalUIMapping
  88 \ingroup vstIPlug vst3611
  89 - [plug imp]
  90 - [extends IEditController]
  91 - [released: 3.6.11]
  92 - [optional]
  93
  94 With this plug-in interface, the host can retrieve the preferred physical mapping associated to note
  95 expression supported by the plug-in.
  96 When the mapping changes (for example when switching presets) the plug-in needs
  97 to inform the host about it via \ref IComponentHandler::restartComponent (kNoteExpressionChanged).
  98
  99 \section INoteExpressionPhysicalUIMappingExample Example
 100
 101 \code{.cpp}
 102 //------------------------------------------------------------------------
 103 // here an example of how a VST3 plug-in could support this INoteExpressionPhysicalUIMapping interface.
 104 // we need to define somewhere the iids:
 105
 106 //in MyController class declaration
 107 class MyController : public Vst::EditController, public Vst::INoteExpressionPhysicalUIMapping
 108 {
 109         // ...
 110         //--- INoteExpressionPhysicalUIMapping ---------------------------------
 111         tresult PLUGIN_API getPhysicalUIMapping (int32 busIndex, int16 channel, PhysicalUIMapList& list) SMTG_OVERRIDE;
 112         // ...
 113
 114         OBJ_METHODS (MyController, Vst::EditController)
 115         DEFINE_INTERFACES
 116                 // ...
 117                 DEF_INTERFACE (Vst::INoteExpressionPhysicalUIMapping)
 118         END_DEFINE_INTERFACES (Vst::EditController)
 119         //...
 120 }
 121
 122 // In mycontroller.cpp
 123 #include "pluginterfaces/vst/ivstnoteexpression.h"
 124
 125 namespace Steinberg {
 126         namespace Vst {
 127                 DEF_CLASS_IID (INoteExpressionPhysicalUIMapping)
 128         }
 129 }
 130 //------------------------------------------------------------------------
 131 tresult PLUGIN_API MyController::getPhysicalUIMapping (int32 busIndex, int16 channel, PhysicalUIMapList& list)
 132 {
 133         if (busIndex == 0 && channel == 0)
 134         {
 135                 for (uint32 i = 0; i < list.count; ++i)
 136                 {
 137                         NoteExpressionTypeID type = kInvalidTypeID;
 138                         if (kPUIXMovement == list.map[i].physicalUITypeID)
 139                                 list.map[i].noteExpressionTypeID = kCustomStart + 1;
 140                         else if (kPUIYMovement == list.map[i].physicalUITypeID)
 141                                 list.map[i].noteExpressionTypeID = kCustomStart + 2;
 142                 }
 143                 return kResultTrue;
 144         }
 145         return kResultFalse;
 146 }
 147 \endcode
 148 */
 149 class INoteExpressionPhysicalUIMapping : public FUnknown
 150 {
 151 public:
 152         /** Fills the list of mapped [physical UI (in) - note expression (out)] for a given bus index
 153          * and channel. */
 154         virtual tresult PLUGIN_API getPhysicalUIMapping (int32 busIndex, int16 channel,
 155                                                          PhysicalUIMapList& list) = 0;
 156
 157 //------------------------------------------------------------------------
 158         static const FUID iid;
 159 };
 160
 161 DECLARE_CLASS_IID (INoteExpressionPhysicalUIMapping, 0xB03078FF, 0x94D24AC8, 0x90CCD303, 0xD4133324)
 162
 163 //------------------------------------------------------------------------
 164 } // namespace Vst
 165 } // namespace Steinberg
 166
 167 //------------------------------------------------------------------------
 168 #include "pluginterfaces/base/falignpop.h"
 169 //------------------------------------------------------------------------