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

   1 //------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstchannelcontextinfo.h
   6 // Created by  : Steinberg, 02/2014
   7 // Description : VST Channel Context Info 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/vst/vsttypes.h"
  20 #include "pluginterfaces/vst/ivstattributes.h"
  21
  22 //------------------------------------------------------------------------
  23 #include "pluginterfaces/base/falignpush.h"
  24 //------------------------------------------------------------------------
  25
  26 //------------------------------------------------------------------------
  27 namespace Steinberg {
  28 namespace Vst {
  29
  30 /** For Channel Context Info Interface */
  31 namespace ChannelContext {
  32
  33 //------------------------------------------------------------------------
  34 //------------------------------------------------------------------------
  35 //------------------------------------------------------------------------
  36
  37 //------------------------------------------------------------------------
  38 //------------------------------------------------------------------------
  39 /** Channel context interface: Vst::IInfoListener
  40 \ingroup vstIHost vst365
  41 - [plug imp]
  42 - [extends IEditController]
  43 - [released: 3.6.5]
  44 - [optional]
  45
  46 Allows the host to inform the plug-in about the context in which the plug-in is instantiated,
  47 mainly channel based info (color, name, index,...). Index can be defined inside a namespace
  48 (for example, index start from 1 to N for Type Input/Output Channel (Index namespace) and index
  49 start from 1 to M for Type Audio Channel).\n
  50 As soon as the plug-in provides this IInfoListener interface, the host will call setChannelContextInfos
  51 for each change occurring to this channel (new name, new color, new indexation,...)
  52
  53 \section IChannelContextExample Example
  54
  55 \code{.cpp}
  56 //------------------------------------------------------------------------
  57 tresult PLUGIN_API MyPlugin::setChannelContextInfos (IAttributeList* list)
  58 {
  59         if (list)
  60         {
  61                 // optional we can ask for the Channel Name Length
  62                 int64 length;
  63                 if (list->getInt (ChannelContext::kChannelNameLengthKey, length) == kResultTrue)
  64                 {
  65                         ...
  66                 }
  67
  68                 // get the Channel Name where we, as plug-in, are instantiated
  69                 String128 name;
  70                 if (list->getString (ChannelContext::kChannelNameKey, name, sizeof (name)) == kResultTrue)
  71                 {
  72                         ...
  73                 }
  74
  75                 // get the Channel UID
  76                 if (list->getString (ChannelContext::kChannelUIDKey, name, sizeof (name)) == kResultTrue)
  77                 {
  78                         ...
  79                 }
  80
  81                 // get Channel Index
  82                 int64 index;
  83                 if (list->getInt (ChannelContext::kChannelIndexKey, index) == kResultTrue)
  84                 {
  85                         ...
  86                 }
  87
  88                 // get the Channel Color
  89                 int64 color;
  90                 if (list->getInt (ChannelContext::kChannelColorKey, color) == kResultTrue)
  91                 {
  92                         uint32 channelColor = (uint32)color;
  93                         String str;
  94                         str.printf ("%x%x%x%x", ChannelContext::GetAlpha (channelColor),
  95                         ChannelContext::GetRed (channelColor),
  96                         ChannelContext::GetGreen (channelColor),
  97                         ChannelContext::GetBlue (channelColor));
  98                         String128 string128;
  99                         Steinberg::UString (string128, 128).fromAscii (str);
 100                         ...
 101                 }
 102
 103                 // get Channel Index Namespace Order of the current used index namespace
 104                 if (list->getInt (ChannelContext::kChannelIndexNamespaceOrderKey, index) == kResultTrue)
 105                 {
 106                         ...
 107                 }
 108
 109                 // get the channel Index Namespace Length
 110                 if (list->getInt (ChannelContext::kChannelIndexNamespaceLengthKey, length) == kResultTrue)
 111                 {
 112                         ...
 113                 }
 114
 115                 // get the channel Index Namespace
 116                 String128 namespaceName;
 117                 if (list->getString (ChannelContext::kChannelIndexNamespaceKey, namespaceName, sizeof (namespaceName)) == kResultTrue)
 118                 {
 119                         ...
 120                 }
 121
 122                 // get plug-in Channel Location
 123                 int64 location;
 124                 if (list->getInt (ChannelContext::kChannelPluginLocationKey, location) == kResultTrue)
 125                 {
 126                         String128 string128;
 127                         switch (location)
 128                         {
 129                                 case ChannelContext::kPreVolumeFader:
 130                                         Steinberg::UString (string128, 128).fromAscii ("PreVolFader");
 131                                 break;
 132                                 case ChannelContext::kPostVolumeFader:
 133                                         Steinberg::UString (string128, 128).fromAscii ("PostVolFader");
 134                                 break;
 135                                 case ChannelContext::kUsedAsPanner:
 136                                         Steinberg::UString (string128, 128).fromAscii ("UsedAsPanner");
 137                                 break;
 138                                 default: Steinberg::UString (string128, 128).fromAscii ("unknown!");
 139                                 break;
 140                         }
 141                 }
 142
 143                 // do not forget to call addRef () if you want to keep this list
 144         }
 145 }
 146 \endcode
 147 */
 148 class IInfoListener : public FUnknown
 149 {
 150 public:
 151         /** Receive the channel context infos from host. */
 152         virtual tresult PLUGIN_API setChannelContextInfos (IAttributeList* list) = 0;
 153
 154         static const FUID iid;
 155 };
 156
 157 DECLARE_CLASS_IID (IInfoListener, 0x0F194781, 0x8D984ADA, 0xBBA0C1EF, 0xC011D8D0)
 158
 159
 160 //------------------------------------------------------------------------
 161 /** Values used for kChannelPluginLocationKey */
 162 enum ChannelPluginLocation
 163 {
 164         kPreVolumeFader = 0,
 165         kPostVolumeFader,
 166         kUsedAsPanner
 167 };
 168
 169 //------------------------------------------------------------------------
 170 //------------------------------------------------------------------------
 171 // Colors
 172 //------------------------------------------------------------------------
 173 /** \defgroup vst3typedef VST 3 Data Types */
 174 /*@{*/
 175 //------------------------------------------------------------------------
 176 /** ARGB (Alpha-Red-Green-Blue) */
 177 typedef uint32 ColorSpec;
 178 typedef uint8 ColorComponent;
 179 /*@}*/
 180
 181 /** Returns the Blue part of the given ColorSpec */
 182 inline ColorComponent GetBlue (ColorSpec cs)    {return (ColorComponent)(cs & 0x000000FF); }
 183 /** Returns the Green part of the given ColorSpec */
 184 inline ColorComponent GetGreen (ColorSpec cs)   {return (ColorComponent)((cs >> 8) & 0x000000FF); }
 185 /** Returns the Red part of the given ColorSpec */
 186 inline ColorComponent GetRed (ColorSpec cs)             {return (ColorComponent)((cs >> 16) & 0x000000FF); }
 187 /** Returns the Alpha part of the given ColorSpec */
 188 inline ColorComponent GetAlpha (ColorSpec cs)   {return (ColorComponent)((cs >> 24) & 0x000000FF); }
 189
 190 //------------------------------------------------------------------------
 191 /** Keys used as AttrID (Attribute ID) in the return IAttributeList of
 192  * IInfoListener::setChannelContextInfos  */
 193 //------------------------------------------------------------------------
 194 /** string (TChar) [optional]: unique id string used to identify a channel */
 195 const CString kChannelUIDKey = "channel uid";
 196
 197 /** integer (int64) [optional]: number of characters in kChannelUIDKey */
 198 const CString kChannelUIDLengthKey = "channel uid length";
 199
 200 /** string (TChar) [optional]: name of the channel like displayed in the mixer */
 201 const CString kChannelNameKey = "channel name";
 202
 203 /** integer (int64) [optional]: number of characters in kChannelNameKey */
 204 const CString kChannelNameLengthKey = "channel name length";
 205
 206 /** color (ColorSpec) [optional]: used color for the channel in mixer or track */
 207 const CString kChannelColorKey = "channel color";
 208
 209 /** integer (int64) [optional]: index of the channel in a channel index namespace, start with 1 not * 0! */
 210 const CString kChannelIndexKey = "channel index";
 211
 212 /** integer (int64) [optional]: define the order of the current used index namespace, start with 1 not 0!
 213         For example:
 214         index namespace is "Input"   -> order 1,
 215         index namespace is "Channel" -> order 2,
 216         index namespace is "Output"  -> order 3 */
 217 const CString kChannelIndexNamespaceOrderKey = "channel index namespace order";
 218
 219 /** string (TChar) [optional]: name of the channel index namespace for example "Input", "Output", "Channel", ... */
 220 const CString kChannelIndexNamespaceKey = "channel index namespace";
 221
 222 /** integer (int64) [optional]: number of characters in kChannelIndexNamespaceKey */
 223 const CString kChannelIndexNamespaceLengthKey = "channel index namespace length";
 224
 225 /** PNG image representation as binary [optional] */
 226 const CString kChannelImageKey = "channel image";
 227
 228 /** integer (int64) [optional]: routing position of the plug-in in the channel (see ChannelPluginLocation) */
 229 const CString kChannelPluginLocationKey = "channel plugin location";
 230
 231 //------------------------------------------------------------------------
 232 } // namespace ChannelContext
 233 } // namespace Vst
 234 } // namespace Steinberg
 235
 236 //------------------------------------------------------------------------
 237 #include "pluginterfaces/base/falignpop.h"
 238 //------------------------------------------------------------------------