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

   1 //------------------------------------------------------------------------
   2 // Project     : VST SDK
   3 //
   4 // Category    : Interfaces
   5 // Filename    : pluginterfaces/vst/ivstparameterchanges.h
   6 // Created by  : Steinberg, 09/2005
   7 // Description : VST Parameter Change Interfaces
   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 /** Queue of changes for a specific parameter: Vst::IParamValueQueue
  31 \ingroup vstIHost vst300
  32 - [host imp]
  33 - [released: 3.0.0]
  34 - [mandatory]
  35
  36 The change queue can be interpreted as segment of an automation curve. For each
  37 processing block, a segment with the size of the block is transmitted to the processor.
  38 The curve is expressed as sampling points of a linear approximation of
  39 the original automation curve. If the original already is a linear curve, it can
  40 be transmitted precisely. A non-linear curve has to be converted to a linear
  41 approximation by the host. Every point of the value queue defines a linear
  42 section of the curve as a straight line from the previous point of a block to
  43 the new one. So the plug-in can calculate the value of the curve for any sample
  44 position in the block.
  45
  46 <b>Implicit Points:</b> \n
  47 In each processing block, the section of the curve for each parameter is transmitted.
  48 In order to reduce the amount of points, the point at block position 0 can be omitted.
  49 - If the curve has a slope of 0 over a period of multiple blocks, only one point is
  50 transmitted for the block where the constant curve section starts. The queue for the following
  51 blocks will be empty as long as the curve slope is 0.
  52 - If the curve has a constant slope other than 0 over the period of several blocks, only
  53 the value for the last sample of the block is transmitted. In this case, the last valid point
  54 is at block position -1. The processor can calculate the value for each sample in the block
  55 by using a linear interpolation:
  56
  57 \code{.cpp}
  58 //------------------------------------------------------------------------
  59 double x1 = -1; // position of last point related to current buffer
  60 double y1 = currentParameterValue; // last transmitted value
  61
  62 int32 pointTime = 0;
  63 ParamValue pointValue = 0;
  64 IParamValueQueue::getPoint (0, pointTime, pointValue);
  65
  66 double x2 = pointTime;
  67 double y2 = pointValue;
  68
  69 double slope = (y2 - y1) / (x2 - x1);
  70 double offset = y1 - (slope * x1);
  71
  72 double curveValue = (slope * bufferTime) + offset; // bufferTime is any position in buffer
  73 \endcode
  74
  75 \b Jumps:
  76 \n
  77 A jump in the automation curve has to be transmitted as two points: one with the
  78 old value and one with the new value at the next sample position.
  79
  80 \image html "automation.jpg"
  81
  82 See \ref IParameterChanges, \ref ProcessData
  83 */
  84 class IParamValueQueue : public FUnknown
  85 {
  86 public:
  87 //------------------------------------------------------------------------
  88         /** Returns its associated ID. */
  89         virtual ParamID PLUGIN_API getParameterId () = 0;
  90
  91         /** Returns count of points in the queue. */
  92         virtual int32 PLUGIN_API getPointCount () = 0;
  93
  94         /** Gets the value and offset at a given index. */
  95         virtual tresult PLUGIN_API getPoint (int32 index, int32& sampleOffset /*out*/, ParamValue& value /*out*/) = 0;
  96
  97         /** Adds a new value at the end of the queue, its index is returned. */
  98         virtual tresult PLUGIN_API addPoint (int32 sampleOffset, ParamValue value, int32& index /*out*/) = 0;
  99
 100 //------------------------------------------------------------------------
 101         static const FUID iid;
 102 };
 103
 104 DECLARE_CLASS_IID (IParamValueQueue, 0x01263A18, 0xED074F6F, 0x98C9D356, 0x4686F9BA)
 105
 106 //----------------------------------------------------------------------
 107 /** All parameter changes of a processing block: Vst::IParameterChanges
 108 \ingroup vstIHost vst300
 109 - [host imp]
 110 - [released: 3.0.0]
 111 - [mandatory]
 112
 113 This interface is used to transmit any changes to be applied to parameters
 114 in the current processing block. A change can be caused by GUI interaction as
 115 well as automation. They are transmitted as a list of queues (\ref IParamValueQueue)
 116 containing only queues for parameters that actually did change.
 117 See \ref IParamValueQueue, \ref ProcessData
 118 */
 119 class IParameterChanges : public FUnknown
 120 {
 121 public:
 122 //------------------------------------------------------------------------
 123         /** Returns count of Parameter changes in the list. */
 124         virtual int32 PLUGIN_API getParameterCount () = 0;
 125
 126         /** Returns the queue at a given index. */
 127         virtual IParamValueQueue* PLUGIN_API getParameterData (int32 index) = 0;
 128
 129         /** Adds a new parameter queue with a given ID at the end of the list,
 130         returns it and its index in the parameter changes list. */
 131         virtual IParamValueQueue* PLUGIN_API addParameterData (const Vst::ParamID& id, int32& index /*out*/) = 0;
 132
 133 //------------------------------------------------------------------------
 134         static const FUID iid;
 135 };
 136
 137 DECLARE_CLASS_IID (IParameterChanges, 0xA4779663, 0x0BB64A56, 0xB44384A8, 0x466FEB9D)
 138
 139 //------------------------------------------------------------------------
 140 } // namespace Vst
 141 } // namespace Steinberg
 142
 143 //------------------------------------------------------------------------
 144 #include "pluginterfaces/base/falignpop.h"
 145 //------------------------------------------------------------------------