Envelope Class Reference

Piecewise linear or piecewise exponential function from double to double. More...

#include <Envelope.h>

Inheritance diagram for Envelope:

Collaboration diagram for Envelope:

Public Member Functions
	Envelope (bool exponential, double minValue, double maxValue, double defaultValue)
	Envelope (const Envelope &orig)
	Envelope (const Envelope &orig, double t0, double t1)
virtual	~Envelope ()
bool	IsTrivial () const
bool	ConsistencyCheck ()
double	GetOffset () const
double	GetTrackLen () const
bool	GetExponential () const
void	SetExponential (bool db)
void	Flatten (double value)
double	GetMinValue () const
double	GetMaxValue () const
void	SetRange (double minValue, double maxValue)
double	ClampValue (double value)
bool	HandleXMLTag (const std::string_view &tag, const AttributesList &attrs) override
XMLTagHandler *	HandleXMLChild (const std::string_view &tag) override
void	WriteXML (XMLWriter &xmlFile) const
void	CollapseRegion (double t0, double t1, double sampleDur) noexcept
void	PasteEnvelope (double t0, const Envelope *e, double sampleDur)
void	InsertSpace (double t0, double tlen)
void	SetOffset (double newOffset)
void	SetTrackLen (double trackLen, double sampleDur=0.0)
void	RescaleValues (double minValue, double maxValue)
void	RescaleTimes (double newLength)
void	RescaleTimesBy (double ratio)
double	GetValue (double t, double sampleDur=0) const
	Get envelope value at time t. More...
void	GetValues (double *buffer, int len, double t0, double tstep) const
	Get many envelope points at once. More...
void	Cap (double sampleDur)
double	Average (double t0, double t1) const
double	AverageOfInverse (double t0, double t1) const
double	Integral (double t0, double t1) const
double	IntegralOfInverse (double t0, double t1) const
double	SolveIntegralOfInverse (double t0, double area) const
void	Clear ()
int	InsertOrReplace (double when, double value)
	Add a point at a particular absolute time coordinate. More...
int	Reassign (double when, double value)
	Move a point at when to value. More...
void	Delete (int point)
	DELETE a point by its position in array. More...
void	Insert (int point, const EnvPoint &p) noexcept
	insert a point More...
void	Insert (double when, double value)
size_t	GetNumberOfPoints () const
	Return number of points. More...
const EnvPoint &	operator[] (int index) const
	Accessor for points. More...
double	GetDefaultValue () const
size_t	GetVersion () const
void	GetPoints (double *bufferWhen, double *bufferValue, int bufferLen) const
	Returns the sets of when and value pairs. More...
int	GetDragPoint () const
void	SetDragPoint (int dragPoint)
void	SetDragPointValid (bool valid)
bool	GetDragPointValid () const
void	MoveDragPoint (double newWhen, double value)
void	ClearDragPoint ()
Public Member Functions inherited from XMLTagHandler
	XMLTagHandler ()
virtual	~XMLTagHandler ()
virtual bool	HandleXMLTag (const std::string_view &tag, const AttributesList &attrs)=0
virtual void	HandleXMLEndTag (const std::string_view &WXUNUSED(tag))
virtual void	HandleXMLContent (const std::string_view &WXUNUSED(content))
virtual XMLTagHandler *	HandleXMLChild (const std::string_view &tag)=0
void	ReadXMLEndTag (const char *tag)
void	ReadXMLContent (const char *s, int len)
XMLTagHandler *	ReadXMLChild (const char *tag)

Private Member Functions
std::pair< int, int >	ExpandRegion (double t0, double tlen, double *pLeftVal, double *pRightVal)
void	RemoveUnneededPoints (size_t startAt, bool rightward, bool testNeighbors=true) noexcept
double	GetValueRelative (double t, bool leftLimit=false) const noexcept
void	GetValuesRelative (double *buffer, int len, double t0, double tstep, bool leftLimit=false) const noexcept
int	NumberOfPointsAfter (double t) const
double	NextPointAfter (double t) const
int	InsertOrReplaceRelative (double when, double value) noexcept
	Add a control point to the envelope. More...
std::pair< int, int >	EqualRange (double when, double sampleDur) const noexcept
void	AddPointAtEnd (double t, double val)
void	CopyRange (const Envelope &orig, size_t begin, size_t end)
void	BinarySearchForTime (int &Lo, int &Hi, double t) const noexcept
void	BinarySearchForTime_LeftLimit (int &Lo, int &Hi, double t) const noexcept
double	GetInterpolationStartValueAtPoint (int iPoint) const noexcept

Private Attributes
EnvArray	mEnv
double	mOffset { 0.0 }
	The time at which the envelope starts, i.e. the start offset. More...
double	mTrackLen { 0.0 }
	The length of the envelope, which is the same as the length of the underlying track (normally) More...
double	mTrackEpsilon { 1.0 / 200000.0 }
	The shortest distance apart that points on an envelope can be before being considered the same point. More...
bool	mDB
double	mMinValue
double	mMaxValue
double	mDefaultValue
bool	mDragPointValid { false }
int	mDragPoint { -1 }
size_t	mVersion { 0 }
int	mSearchGuess { -2 }

Detailed Description

Piecewise linear or piecewise exponential function from double to double.

This class manages an envelope - i.e. a function that the user can edit by dragging control points around. The envelope is most commonly used to control the amplitude of a waveform, but it is also used to shape the Equalization curve, and in TimeTrack to determine a time warp.

Definition at line 72 of file Envelope.h.

Constructor & Destructor Documentation

Envelope() [1/3]

Envelope::Envelope	(	bool	exponential,
		double	minValue,
		double	maxValue,
		double	defaultValue
	)

Definition at line 44 of file Envelope.cpp.

   : mDB(exponential)
   , mMinValue(minValue)
   , mMaxValue(maxValue)
   , mDefaultValue { ClampValue(defaultValue) }
{
}

Envelope() [2/3]

Envelope::Envelope

(

const Envelope &

orig

)

Definition at line 275 of file Envelope.cpp.

   : mDB(orig.mDB)
   , mMinValue(orig.mMinValue)
   , mMaxValue(orig.mMaxValue)
   , mDefaultValue(orig.mDefaultValue)
{
   mOffset = orig.mOffset;
   mTrackLen = orig.mTrackLen;
   CopyRange(orig, 0, orig.GetNumberOfPoints());
}

References CopyRange(), GetNumberOfPoints(), mOffset, and mTrackLen.

Here is the call graph for this function:

Envelope() [3/3]

Envelope::Envelope	(	const Envelope &	orig,
		double	t0,
		double	t1
	)

Definition at line 261 of file Envelope.cpp.

   : mDB(orig.mDB)
   , mMinValue(orig.mMinValue)
   , mMaxValue(orig.mMaxValue)
   , mDefaultValue(orig.mDefaultValue)
{
   mOffset = wxMax(t0, orig.mOffset);
   mTrackLen = wxMin(t1, orig.mOffset + orig.mTrackLen) - mOffset;
 
   auto range1 = orig.EqualRange( t0 - orig.mOffset, 0 );
   auto range2 = orig.EqualRange( t1 - orig.mOffset, 0 );
   CopyRange(orig, range1.first, range2.second);
}

References CopyRange(), EqualRange(), mOffset, and mTrackLen.

Here is the call graph for this function:

~Envelope()

Envelope::~Envelope ( )

virtual

Definition at line 52 of file Envelope.cpp.

{
}

Member Function Documentation

AddPointAtEnd()

void Envelope::AddPointAtEnd ( double  t, double  val  )

private

Definition at line 242 of file Envelope.cpp.

{
   mEnv.push_back( EnvPoint{ t, val } );
 
   // Assume copied points were stored by nondecreasing time.
   // Allow no more than two points at exactly the same time.
   // Maybe that happened, because extra points were inserted at the boundary
   // of the copied range, which were not in the source envelope.
   auto nn = mEnv.size() - 1;
   while ( nn >= 2 && mEnv[ nn - 2 ].GetT() == t ) {
      // Of three or more points at the same time, erase one in the middle,
      // not the one newly added.
      mEnv.erase( mEnv.begin() + nn - 1 );
      --nn;
   }
 
   ++mVersion;
}

References mEnv, and mVersion.

Referenced by CopyRange(), and SetTrackLen().

Here is the caller graph for this function:

Average()

double Envelope::Average	(	double	t0,
		double	t1
	)		const

Definition at line 1125 of file Envelope.cpp.

{
  if( t0 == t1 )
    return GetValue( t0 );
  else
    return Integral( t0, t1 ) / (t1 - t0);
}

References GetValue(), and Integral().

Here is the call graph for this function:

AverageOfInverse()

double Envelope::AverageOfInverse	(	double	t0,
		double	t1
	)		const

Definition at line 1133 of file Envelope.cpp.

{
  if( t0 == t1 )
    return 1.0 / GetValue( t0 );
  else
    return IntegralOfInverse( t0, t1 ) / (t1 - t0);
}

References GetValue(), and IntegralOfInverse().

Referenced by anonymous_namespace{MixerSource.cpp}::ComputeWarpFactor().

Here is the call graph for this function:

Here is the caller graph for this function:

BinarySearchForTime()

void Envelope::BinarySearchForTime ( int &  Lo, int &  Hi, double  t  ) const

privatenoexcept

Parameters

Lo	returns last index at or before this time, maybe -1
Hi	returns first index after this time, maybe past the end

Definition at line 900 of file Envelope.cpp.

{
   // Optimizations for the usual pattern of repeated calls with
   // small increases of t.
   {
      if (mSearchGuess >= 0 && mSearchGuess < (int)mEnv.size()) {
         if (t >= mEnv[mSearchGuess].GetT() &&
             (1 + mSearchGuess == (int)mEnv.size() ||
              t < mEnv[1 + mSearchGuess].GetT())) {
            Lo = mSearchGuess;
            Hi = 1 + mSearchGuess;
            return;
         }
      }
 
      ++mSearchGuess;
      if (mSearchGuess >= 0 && mSearchGuess < (int)mEnv.size()) {
         if (t >= mEnv[mSearchGuess].GetT() &&
             (1 + mSearchGuess == (int)mEnv.size() ||
              t < mEnv[1 + mSearchGuess].GetT())) {
            Lo = mSearchGuess;
            Hi = 1 + mSearchGuess;
            return;
         }
      }
   }
 
   Lo = -1;
   Hi = mEnv.size();
 
   // Invariants:  Lo is not less than -1, Hi not more than size
   while (Hi > (Lo + 1)) {
      int mid = (Lo + Hi) / 2;
      // mid must be strictly between Lo and Hi, therefore a valid index
      if (t < mEnv[mid].GetT())
         Hi = mid;
      else
         Lo = mid;
   }
   wxASSERT( Hi == ( Lo+1 ));
 
   mSearchGuess = Lo;
}

Referenced by Integral(), IntegralOfInverse(), NextPointAfter(), NumberOfPointsAfter(), and SolveIntegralOfInverse().

Here is the caller graph for this function:

BinarySearchForTime_LeftLimit()

void Envelope::BinarySearchForTime_LeftLimit ( int &  Lo, int &  Hi, double  t  ) const

privatenoexcept

Parameters

Lo	returns last index before this time, maybe -1
Hi	returns first index at or after this time, maybe past the end

Definition at line 947 of file Envelope.cpp.

{
   Lo = -1;
   Hi = mEnv.size();
 
   // Invariants:  Lo is not less than -1, Hi not more than size
   while (Hi > (Lo + 1)) {
      int mid = (Lo + Hi) / 2;
      // mid must be strictly between Lo and Hi, therefore a valid index
      if (t <= mEnv[mid].GetT())
         Hi = mid;
      else
         Lo = mid;
   }
   wxASSERT( Hi == ( Lo+1 ));
 
   mSearchGuess = Lo;
}

Cap()

void Envelope::Cap

(

double

sampleDur

)

Definition at line 752 of file Envelope.cpp.

{
   auto range = EqualRange( mTrackLen, sampleDur );
   if ( range.first == range.second )
      InsertOrReplaceRelative( mTrackLen, GetValueRelative( mTrackLen ) );
}

References EqualRange(), GetValueRelative(), InsertOrReplaceRelative(), and mTrackLen.

Here is the call graph for this function:

ClampValue()

double Envelope::ClampValue ( double  value )

inline

Definition at line 102 of file Envelope.h.

{ return std::max(mMinValue, std::min(mMaxValue, value)); }

References min().

Referenced by Flatten(), RescaleValues(), SetRange(), EnvPoint::SetVal(), and EnvelopeEditor::ValueOfPixel().

Here is the call graph for this function:

Here is the caller graph for this function:

Clear()

void Envelope::Clear ( )

inline

Definition at line 166 of file Envelope.h.

{ mEnv.clear(); }

ClearDragPoint()

void Envelope::ClearDragPoint

(

)

Definition at line 221 of file Envelope.cpp.

{
   if (!mDragPointValid && mDragPoint >= 0)
      Delete(mDragPoint);
 
   mDragPoint = -1;
   mDragPointValid = false;
}

References Delete(), mDragPoint, and mDragPointValid.

Referenced by EnvelopeEditor::HandleMouseButtonUp().

Here is the call graph for this function:

Here is the caller graph for this function:

CollapseRegion()

void Envelope::CollapseRegion ( double  t0, double  t1, double  sampleDur  )

noexcept

Exception safety guarantee:

No-fail

Definition at line 396 of file Envelope.cpp.

{
   if ( t1 <= t0 )
      return;
 
   // This gets called when somebody clears samples.
 
   // Snip points in the interval (t0, t1), shift values left at times after t1.
   // For the boundaries of the interval, preserve the left-side limit at the
   // start and right-side limit at the end.
 
   const auto epsilon = sampleDur / 2;
   t0 = std::max( 0.0, std::min( mTrackLen, t0 - mOffset ) );
   t1 = std::max( 0.0, std::min( mTrackLen, t1 - mOffset ) );
   bool leftPoint = true, rightPoint = true;
 
   // Determine the start of the range of points to remove from the array.
   auto range0 = EqualRange(t0, 0);
   auto begin = range0.first;
   if ( begin == range0.second ) {
      if ( t0 > epsilon ) {
         // There was no point exactly at t0;
         // insert a point to preserve the value.
         auto val = GetValueRelative( t0 );
         InsertOrReplaceRelative( t0, val );
         ++begin;
      }
      else
         leftPoint = false;
   }
   else
      // We will keep the first (or only) point that was at t0.
      ++begin;
 
   // We want end to be the index one past the range of points to remove from
   // the array.
   // At first, find index of the first point after t1:
   auto range1 = EqualRange( t1, 0 );
   auto end = range1.second;
   if ( range1.first == end ) {
      if ( mTrackLen - t1 > epsilon ) {
         // There was no point exactly at t1; insert a point to preserve the value.
         auto val = GetValueRelative( t1 );
         InsertOrReplaceRelative( t1, val );
         // end is now the index of this NEW point and that is correct.
      }
      else
         rightPoint = false;
   }
   else
      // We will keep the last (or only) point that was at t1.
      --end;
 
   if ( end < begin ) {
      if ( leftPoint )
         rightPoint = false;
   }
   else
      mEnv.erase( mEnv.begin() + begin, mEnv.begin() + end );
 
   // Shift points left after deleted region.
   auto len = mEnv.size();
   for ( size_t i = begin; i < len; ++i ) {
      auto &point = mEnv[i];
      if (rightPoint && (int)i == begin)
         // Avoid roundoff error.
         // Make exactly equal times of neighboring points so that we have
         // a real discontinuity.
         point.SetT( t0 );
      else
         point.SetT( point.GetT() - (t1 - t0) );
   }
 
   // See if the discontinuity is removable.
   if ( rightPoint )
      RemoveUnneededPoints( begin, true );
   if ( leftPoint )
      RemoveUnneededPoints( begin - 1, false );
 
   mTrackLen -= (t1 - t0);
 
   ++mVersion;
}

References details::begin(), details::end(), and min().

Referenced by WaveClip::ClearAndAddCutLine(), and WaveClip::ClearSequenceFinisher::~ClearSequenceFinisher().

Here is the call graph for this function:

Here is the caller graph for this function:

ConsistencyCheck()

bool Envelope::ConsistencyCheck

(

)

Definition at line 61 of file Envelope.cpp.

{
   bool consistent = true;
 
   bool disorder;
   do {
      disorder = false;
      for ( size_t ii = 0, count = mEnv.size(); ii < count; ) {
         // Find range of points with equal T
         const double thisT = mEnv[ii].GetT();
         double nextT = 0.0f;
         auto nextI = ii + 1;
         while ( nextI < count && thisT == ( nextT = mEnv[nextI].GetT() ) )
            ++nextI;
 
         if ( nextI < count && nextT < thisT )
            disorder = true;
 
         while ( nextI - ii > 2 ) {
            // too many coincident time values
            if ((int)ii == mDragPoint || (int)nextI - 1 == mDragPoint)
               // forgivable
               ;
            else {
               consistent = false;
               // repair it
               Delete( nextI - 2 );
               if (mDragPoint >= (int)nextI - 2)
                  --mDragPoint;
               --nextI, --count;
               // wxLogError
            }
         }
 
         ii = nextI;
      }
 
      if (disorder) {
         ++mVersion;
         consistent = false;
         // repair it
         std::stable_sort( mEnv.begin(), mEnv.end(),
            []( const EnvPoint &a, const EnvPoint &b )
               { return a.GetT() < b.GetT(); } );
      }
   } while ( disorder );
 
   return consistent;
}

References mEnv.

Referenced by PasteEnvelope().

Here is the caller graph for this function:

CopyRange()

void Envelope::CopyRange ( const Envelope &  orig, size_t  begin, size_t  end  )

private

Definition at line 286 of file Envelope.cpp.

{
   size_t len = orig.mEnv.size();
   size_t i = begin;
 
   // Create the point at 0 if it needs interpolated representation
   if ( i > 0 )
      AddPointAtEnd(0, orig.GetValue(mOffset));
 
   // Copy points from inside the copied region
   for (; i < end; ++i) {
      const EnvPoint &point = orig[i];
      const double when = point.GetT() + (orig.mOffset - mOffset);
      AddPointAtEnd(when, point.GetVal());
   }
 
   // Create the final point if it needs interpolated representation
   // If the last point of e was exactly at t1, this effectively copies it too.
   if (mTrackLen > 0 && i < len)
      AddPointAtEnd( mTrackLen, orig.GetValue(mOffset + mTrackLen));
}

References AddPointAtEnd(), details::begin(), details::end(), EnvPoint::GetT(), EnvPoint::GetVal(), GetValue(), mEnv, mOffset, and mTrackLen.

Referenced by Envelope().

Here is the call graph for this function:

Here is the caller graph for this function:

Delete()

void Envelope::Delete

(

int

point

)

DELETE a point by its position in array.

Definition at line 374 of file Envelope.cpp.

{
   mEnv.erase(mEnv.begin() + point);
 
   ++mVersion;
}

References mEnv, and mVersion.

Referenced by ClearDragPoint(), and BoundedEnvelope::Envelope().

Here is the caller graph for this function:

EqualRange()

std::pair< int, int > Envelope::EqualRange ( double  when, double  sampleDur  ) const

privatenoexcept

Definition at line 801 of file Envelope.cpp.

{
   // Find range of envelope points matching the given time coordinate
   // (within an interval of length sampleDur)
   // by binary search; if empty, it still indicates where to
   // insert.
   const auto tolerance = sampleDur / 2;
   auto begin = mEnv.begin();
   auto end = mEnv.end();
   auto first = std::lower_bound(
      begin, end,
      EnvPoint{ when - tolerance, 0.0 },
      []( const EnvPoint &point1, const EnvPoint &point2 )
         { return point1.GetT() < point2.GetT(); }
   );
   auto after = first;
   while ( after != end && after->GetT() <= when + tolerance )
      ++after;
   return { first - begin, after - begin };
}

References details::begin(), details::end(), and EnvPoint::GetT().

Referenced by Cap(), Envelope(), ExpandRegion(), PasteEnvelope(), and SetTrackLen().

Here is the call graph for this function:

Here is the caller graph for this function:

ExpandRegion()

std::pair< int, int > Envelope::ExpandRegion ( double  t0, double  tlen, double *  pLeftVal, double *  pRightVal  )

private

Exception safety guarantee:

No-fail

Definition at line 640 of file Envelope.cpp.

{
   // t0 is relative time
 
   double val = GetValueRelative( t0 );
   const auto range = EqualRange( t0, 0 );
 
   // Preserve the left-side limit.
   int index = 1 + range.first;
   if ( index <= range.second )
      // There is already a control point.
      ;
   else {
      // Make a control point.
      Insert( range.first, EnvPoint{ t0, val } );
   }
 
   // Shift points.
   auto len = mEnv.size();
   for ( unsigned int ii = index; ii < len; ++ii ) {
      auto &point = mEnv[ ii ];
      point.SetT( point.GetT() + tlen );
   }
 
   mTrackLen += tlen;
 
   // Preserve the right-side limit.
   if ( index < range.second )
      // There was a control point already.
      ;
   else
      // Make a control point.
      Insert( index, EnvPoint{ t0 + tlen, val } );
 
   // Make discontinuities at ends, maybe:
 
   if ( pLeftVal )
      // Make a discontinuity at the left side of the expansion
      Insert( index++, EnvPoint{ t0, *pLeftVal } );
 
   if ( pRightVal )
      // Make a discontinuity at the right side of the expansion
      Insert( index++, EnvPoint{ t0 + tlen, *pRightVal } );
 
   // Return the range of indices that includes the inside limiting points,
   // none, one, or two
   return { 1 + range.first, index };
}

References EqualRange(), GetValueRelative(), Insert(), mEnv, and mTrackLen.

Referenced by InsertSpace(), and PasteEnvelope().

Here is the call graph for this function:

Here is the caller graph for this function:

Flatten()

void Envelope::Flatten

(

double

value

)

Flatten removes all points from the envelope to make it horizontal at a chosen y-value. @value - the y-value for the flat envelope.

Definition at line 140 of file Envelope.cpp.

{
   mEnv.clear();
   mDefaultValue = ClampValue(value);
 
   ++mVersion;
}

References ClampValue(), mDefaultValue, mEnv, and mVersion.

Referenced by EqualizationBandSliders::GraphicEQ(), and TimeTrack::testMe().

Here is the call graph for this function:

Here is the caller graph for this function:

GetDefaultValue()

double Envelope::GetDefaultValue

(

)

const

Definition at line 728 of file Envelope.cpp.

{
   return mDefaultValue;
}

References mDefaultValue.

GetDragPoint()

int Envelope::GetDragPoint ( ) const

inline

Definition at line 214 of file Envelope.h.

{ return mDragPoint; }

Referenced by EnvelopeEditor::DrawPoints(), and EnvelopeEditor::MouseEvent().

Here is the caller graph for this function:

GetDragPointValid()

bool Envelope::GetDragPointValid ( ) const

inline

Definition at line 219 of file Envelope.h.

{ return mDragPointValid; }

Referenced by EnvelopeEditor::HandleDragging().

Here is the caller graph for this function:

GetExponential()

bool Envelope::GetExponential ( ) const

inline

Definition at line 93 of file Envelope.h.

{ return mDB; }

Referenced by CommonChannelView::GetEnvelopeValues().

Here is the caller graph for this function:

GetInterpolationStartValueAtPoint()

double Envelope::GetInterpolationStartValueAtPoint ( int  iPoint ) const

privatenoexcept

GetInterpolationStartValueAtPoint() is used to select either the envelope value or its log depending on whether we are doing linear or log interpolation.

Parameters

iPoint

index in env array to look at.

Returns

value there, or its (safe) log10.

Definition at line 972 of file Envelope.cpp.

{
   double v = mEnv[ iPoint ].GetVal();
   if( !mDB )
      return v;
   else
      return log10(v);
}

GetMaxValue()

double Envelope::GetMaxValue ( ) const

inline

Definition at line 99 of file Envelope.h.

{ return mMaxValue; }

GetMinValue()

double Envelope::GetMinValue ( ) const

inline

Definition at line 98 of file Envelope.h.

{ return mMinValue; }

GetNumberOfPoints()

size_t Envelope::GetNumberOfPoints

(

)

const

Return number of points.

Definition at line 723 of file Envelope.cpp.

{
   return mEnv.size();
}

References mEnv.

Referenced by EnvelopeEditor::DrawPoints(), Envelope(), EqualizationCurvesList::EnvelopeUpdated(), EqualizationBandSliders::EnvLinToLog(), EqualizationBandSliders::EnvLogToLin(), and EnvelopeEditor::HandleMouseButtonDown().

Here is the caller graph for this function:

GetOffset()

double Envelope::GetOffset ( ) const

inline

Definition at line 90 of file Envelope.h.

{ return mOffset; }

Referenced by EnvelopeEditor::DrawPoints(), EnvelopeEditor::HandleMouseButtonDown(), and EnvelopeEditor::MoveDragPoint().

Here is the caller graph for this function:

GetPoints()

void Envelope::GetPoints	(	double *	bufferWhen,
		double *	bufferValue,
		int	bufferLen
	)		const

Returns the sets of when and value pairs.

Definition at line 738 of file Envelope.cpp.

{
   int n = mEnv.size();
   if (n > bufferLen)
      n = bufferLen;
   int i;
   for (i = 0; i < n; i++) {
      bufferWhen[i] = mEnv[i].GetT() - mOffset;
      bufferValue[i] = mEnv[i].GetVal();
   }
}

References mEnv, and mOffset.

Referenced by EqualizationCurvesList::EnvelopeUpdated().

Here is the caller graph for this function:

GetTrackLen()

double Envelope::GetTrackLen ( ) const

inline

Definition at line 91 of file Envelope.h.

{ return mTrackLen; }

GetValue()

double Envelope::GetValue	(	double	t,
		double	sampleDur = 0
	)		const

Get envelope value at time t.

Definition at line 880 of file Envelope.cpp.

{
   // t is absolute time
   double temp;
 
   GetValues( &temp, 1, t, sampleDur );
   return temp;
}

References GetValues().

Referenced by Average(), AverageOfInverse(), EqualizationFilter::CalcFilter(), CopyRange(), anonymous_namespace{WaveformView.cpp}::DrawIndividualSamples(), EqualizationBandSliders::ErrMin(), CommonChannelView::GetEnvelopeValues(), EnvelopeEditor::HandleMouseButtonDown(), EnvelopeHandle::HitEnvelope(), and PasteEnvelope().

Here is the call graph for this function:

Here is the caller graph for this function:

GetValueRelative()

double Envelope::GetValueRelative ( double  t, bool  leftLimit = false  ) const

privatenoexcept

Definition at line 889 of file Envelope.cpp.

{
   double temp;
 
   GetValuesRelative(&temp, 1, t, 0.0, leftLimit);
   return temp;
}

Referenced by Cap(), ExpandRegion(), PasteEnvelope(), and SetTrackLen().

Here is the caller graph for this function:

GetValues()

void Envelope::GetValues	(	double *	buffer,
		int	len,
		double	t0,
		double	tstep
	)		const

Get many envelope points at once.

This is much faster than calling GetValue() multiple times if you need more than one value in a row.

Definition at line 981 of file Envelope.cpp.

{
   // Convert t0 from absolute to clip-relative time
   t0 -= mOffset;
   GetValuesRelative( buffer, bufferLen, t0, tstep);
}

References GetValuesRelative(), and mOffset.

Referenced by GetValue(), and WaveBitmapCache::LookupHelper::PerformLookup().

Here is the call graph for this function:

Here is the caller graph for this function:

GetValuesRelative()

void Envelope::GetValuesRelative ( double *  buffer, int  len, double  t0, double  tstep, bool  leftLimit = false  ) const

privatenoexcept

Definition at line 989 of file Envelope.cpp.

{
   // JC: If bufferLen ==0 we have probably just allocated a zero sized buffer.
   // wxASSERT( bufferLen > 0 );
 
   const auto epsilon = tstep / 2;
   int len = mEnv.size();
 
   double t = t0;
   double increment = 0;
   if ( len > 1 && t <= mEnv[0].GetT() && mEnv[0].GetT() == mEnv[1].GetT() )
      increment = leftLimit ? -epsilon : epsilon;
 
   double tprev, vprev, tnext = 0, vnext, vstep = 0;
 
   for (int b = 0; b < bufferLen; b++) {
 
      // Get easiest cases out the way first...
      // IF empty envelope THEN default value
      if (len <= 0) {
         buffer[b] = mDefaultValue;
         t += tstep;
         continue;
      }
 
      auto tplus = t + increment;
 
      // IF before envelope THEN first value
      if ( leftLimit ? tplus <= mEnv[0].GetT() : tplus < mEnv[0].GetT() ) {
         buffer[b] = mEnv[0].GetVal();
         t += tstep;
         continue;
      }
      // IF after envelope THEN last value
      if ( leftLimit
            ? tplus > mEnv[len - 1].GetT() : tplus >= mEnv[len - 1].GetT() ) {
         buffer[b] = mEnv[len - 1].GetVal();
         t += tstep;
         continue;
      }
 
      // be careful to get the correct limit even in case epsilon == 0
      if ( b == 0 ||
           ( leftLimit ? tplus > tnext : tplus >= tnext ) ) {
 
         // We're beyond our tnext, so find the next one.
         // Don't just increment lo or hi because we might
         // be zoomed far out and that could be a large number of
         // points to move over.  That's why we binary search.
 
         int lo,hi;
         if ( leftLimit )
            BinarySearchForTime_LeftLimit( lo, hi, tplus );
         else
            BinarySearchForTime( lo, hi, tplus );
 
         // mEnv[0] is before tplus because of eliminations above, therefore lo >= 0
         // mEnv[len - 1] is after tplus, therefore hi <= len - 1
         wxASSERT( lo >= 0 && hi <= len - 1 );
 
         tprev = mEnv[lo].GetT();
         tnext = mEnv[hi].GetT();
 
         if ( hi + 1 < len && tnext == mEnv[ hi + 1 ].GetT() )
            // There is a discontinuity after this point-to-point interval.
            // Usually will stop evaluating in this interval when time is slightly
            // before tNext, then use the right limit.
            // This is the right intent
            // in case small roundoff errors cause a sample time to be a little
            // before the envelope point time.
            // Less commonly we want a left limit, so we continue evaluating in
            // this interval until shortly after the discontinuity.
            increment = leftLimit ? -epsilon : epsilon;
         else
            increment = 0;
 
         vprev = GetInterpolationStartValueAtPoint( lo );
         vnext = GetInterpolationStartValueAtPoint( hi );
 
         // Interpolate, either linear or log depending on mDB.
         double dt = (tnext - tprev);
         double to = t - tprev;
         double v;
         if (dt > 0.0)
         {
            v = (vprev * (dt - to) + vnext * to) / dt;
            vstep = (vnext - vprev) * tstep / dt;
         }
         else
         {
            v = vnext;
            vstep = 0.0;
         }
 
         // An adjustment if logarithmic scale.
         if( mDB )
         {
            v = pow(10.0, v);
            vstep = pow( 10.0, vstep );
         }
 
         buffer[b] = v;
      } else {
         if (mDB){
            buffer[b] = buffer[b - 1] * vstep;
         }else{
            buffer[b] = buffer[b - 1] + vstep;
         }
      }
 
      t += tstep;
   }
}

Referenced by GetValues().

Here is the caller graph for this function:

GetVersion()

size_t Envelope::GetVersion

(

)

const

Definition at line 733 of file Envelope.cpp.

{
   return mVersion;
}

References mVersion.

Referenced by WaveBitmapCache::CheckCache(), and WaveBitmapCache::SetPaintParameters().

Here is the caller graph for this function:

HandleXMLChild()

XMLTagHandler * Envelope::HandleXMLChild ( const std::string_view &  tag )

overridevirtual

Implements XMLTagHandler.

Definition at line 346 of file Envelope.cpp.

{
   if (tag != "controlpoint")
      return NULL;
 
   mEnv.push_back( EnvPoint{} );
   return &mEnv.back();
}

References mEnv.

Referenced by AUPImportFileHandle::HandleControlPoint().

Here is the caller graph for this function:

HandleXMLTag()

bool Envelope::HandleXMLTag ( const std::string_view &  tag, const AttributesList &  attrs  )

overridevirtual

Implements XMLTagHandler.

Definition at line 321 of file Envelope.cpp.

{
   // Return unless it's the envelope tag.
   if (tag != "envelope")
      return false;
 
   int numPoints = -1;
 
   for (auto pair : attrs)
   {
      auto attr = pair.first;
      auto value = pair.second;
 
      if (attr == "numpoints")
         value.TryGet(numPoints);
   }
 
   if (numPoints < 0)
      return false;
 
   mEnv.clear();
   mEnv.reserve(numPoints);
   return true;
}

References mEnv.

Insert() [1/2]

void Envelope::Insert	(	double	when,
		double	value
	)

Definition at line 388 of file Envelope.cpp.

{
   mEnv.push_back(EnvPoint { when, value });
 
   ++mVersion;
}

References mEnv, and mVersion.

Insert() [2/2]

void Envelope::Insert ( int  point, const EnvPoint &  p  )

noexcept

insert a point

Definition at line 381 of file Envelope.cpp.

{
   mEnv.insert(mEnv.begin() + point, p);
 
   ++mVersion;
}

Referenced by ExpandRegion(), and EqualizationBandSliders::GraphicEQ().

Here is the caller graph for this function:

InsertOrReplace()

int Envelope::InsertOrReplace ( double  when, double  value  )

inline

Add a point at a particular absolute time coordinate.

Definition at line 169 of file Envelope.h.

   { return InsertOrReplaceRelative( when - mOffset, value ); }

Referenced by EnvelopeEditor::HandleMouseButtonDown(), and TimeTrack::testMe().

Here is the caller graph for this function:

InsertOrReplaceRelative()

int Envelope::InsertOrReplaceRelative ( double  when, double  value  )

privatenoexcept

Add a control point to the envelope.

Parameters

when	the time in seconds when the envelope point should be created.
value	the envelope value to use at the given point.

Returns

the index of the NEW envelope point within array of envelope points.

Definition at line 767 of file Envelope.cpp.

{
#if defined(_DEBUG)
   // in debug builds, do a spot of argument checking
   if(when > mTrackLen + 0.0000001)
   {
      wxString msg;
      msg = wxString::Format(wxT("when %.20f mTrackLen %.20f diff %.20f"), when, mTrackLen, when-mTrackLen);
      wxASSERT_MSG(when <= (mTrackLen), msg);
   }
   if(when < 0)
   {
      wxString msg;
      msg = wxString::Format(wxT("when %.20f mTrackLen %.20f"), when, mTrackLen);
      wxASSERT_MSG(when >= 0, msg);
   }
#endif
 
   when = std::max( 0.0, std::min( mTrackLen, when ) );
 
   auto range = EqualRange( when, 0 );
   int index = range.first;
 
   if ( index < range.second )
      // modify existing
      // In case of a discontinuity, ALWAYS CHANGING LEFT LIMIT ONLY!
      mEnv[ index ].SetVal( this, value );
   else
     // Add NEW
      Insert( index, EnvPoint { when, value } );
 
   return index;
}

References min(), and wxT().

Referenced by Cap().

Here is the call graph for this function:

Here is the caller graph for this function:

InsertSpace()

void Envelope::InsertSpace	(	double	t0,
		double	tlen
	)

Exception safety guarantee:

No-fail

Definition at line 691 of file Envelope.cpp.

{
   auto range = ExpandRegion( t0 - mOffset, tlen, nullptr, nullptr );
 
   // Simplify the boundaries if possible
   RemoveUnneededPoints( range.second, true );
   RemoveUnneededPoints( range.first - 1, false );
}

References ExpandRegion(), mOffset, and RemoveUnneededPoints().

Here is the call graph for this function:

Integral()

double Envelope::Integral	(	double	t0,
		double	t1
	)		const

Definition at line 1224 of file Envelope.cpp.

{
   if(t0 == t1)
      return 0.0;
   if(t0 > t1)
   {
      return -Integral(t1, t0); // this makes more sense than returning the default value
   }
 
   unsigned int count = mEnv.size();
   if(count == 0) // 'empty' envelope
      return (t1 - t0) * mDefaultValue;
 
   t0 -= mOffset;
   t1 -= mOffset;
 
   double total = 0.0, lastT, lastVal;
   unsigned int i; // this is the next point to check
   if(t0 < mEnv[0].GetT()) // t0 preceding the first point
   {
      if(t1 <= mEnv[0].GetT())
         return (t1 - t0) * mEnv[0].GetVal();
      i = 1;
      lastT = mEnv[0].GetT();
      lastVal = mEnv[0].GetVal();
      total += (lastT - t0) * lastVal;
   }
   else if(t0 >= mEnv[count - 1].GetT()) // t0 at or following the last point
   {
      return (t1 - t0) * mEnv[count - 1].GetVal();
   }
   else // t0 enclosed by points
   {
      // Skip any points that come before t0 using binary search
      int lo, hi;
      BinarySearchForTime(lo, hi, t0);
      lastVal = InterpolatePoints(mEnv[lo].GetVal(), mEnv[hi].GetVal(), (t0 - mEnv[lo].GetT()) / (mEnv[hi].GetT() - mEnv[lo].GetT()), mDB);
      lastT = t0;
      i = hi; // the point immediately after t0.
   }
 
   // loop through the rest of the envelope points until we get to t1
   while (1)
   {
      if(i >= count) // the requested range extends beyond the last point
      {
         return total + (t1 - lastT) * lastVal;
      }
      else if(mEnv[i].GetT() >= t1) // this point follows the end of the range
      {
         double thisVal = InterpolatePoints(mEnv[i - 1].GetVal(), mEnv[i].GetVal(), (t1 - mEnv[i - 1].GetT()) / (mEnv[i].GetT() - mEnv[i - 1].GetT()), mDB);
         return total + IntegrateInterpolated(lastVal, thisVal, t1 - lastT, mDB);
      }
      else // this point precedes the end of the range
      {
         total += IntegrateInterpolated(lastVal, mEnv[i].GetVal(), mEnv[i].GetT() - lastT, mDB);
         lastT = mEnv[i].GetT();
         lastVal = mEnv[i].GetVal();
         i++;
      }
   }
}

References BinarySearchForTime(), Integral(), IntegrateInterpolated(), InterpolatePoints(), mDB, mDefaultValue, mEnv, and mOffset.

Referenced by Average(), Integral(), and TimeTrack::testMe().

Here is the call graph for this function:

Here is the caller graph for this function:

IntegralOfInverse()

double Envelope::IntegralOfInverse	(	double	t0,
		double	t1
	)		const

Definition at line 1287 of file Envelope.cpp.

{
   if(t0 == t1)
      return 0.0;
   if(t0 > t1)
   {
      return -IntegralOfInverse(t1, t0); // this makes more sense than returning the default value
   }
 
   unsigned int count = mEnv.size();
   if(count == 0) // 'empty' envelope
      return (t1 - t0) / mDefaultValue;
 
   t0 -= mOffset;
   t1 -= mOffset;
 
   double total = 0.0, lastT, lastVal;
   unsigned int i; // this is the next point to check
   if(t0 < mEnv[0].GetT()) // t0 preceding the first point
   {
      if(t1 <= mEnv[0].GetT())
         return (t1 - t0) / mEnv[0].GetVal();
      i = 1;
      lastT = mEnv[0].GetT();
      lastVal = mEnv[0].GetVal();
      total += (lastT - t0) / lastVal;
   }
   else if(t0 >= mEnv[count - 1].GetT()) // t0 at or following the last point
   {
      return (t1 - t0) / mEnv[count - 1].GetVal();
   }
   else // t0 enclosed by points
   {
      // Skip any points that come before t0 using binary search
      int lo, hi;
      BinarySearchForTime(lo, hi, t0);
      lastVal = InterpolatePoints(mEnv[lo].GetVal(), mEnv[hi].GetVal(), (t0 - mEnv[lo].GetT()) / (mEnv[hi].GetT() - mEnv[lo].GetT()), mDB);
      lastT = t0;
      i = hi; // the point immediately after t0.
   }
 
   // loop through the rest of the envelope points until we get to t1
   while (1)
   {
      if(i >= count) // the requested range extends beyond the last point
      {
         return total + (t1 - lastT) / lastVal;
      }
      else if(mEnv[i].GetT() >= t1) // this point follows the end of the range
      {
         double thisVal = InterpolatePoints(mEnv[i - 1].GetVal(), mEnv[i].GetVal(), (t1 - mEnv[i - 1].GetT()) / (mEnv[i].GetT() - mEnv[i - 1].GetT()), mDB);
         return total + IntegrateInverseInterpolated(lastVal, thisVal, t1 - lastT, mDB);
      }
      else // this point precedes the end of the range
      {
         total += IntegrateInverseInterpolated(lastVal, mEnv[i].GetVal(), mEnv[i].GetT() - lastT, mDB);
         lastT = mEnv[i].GetT();
         lastVal = mEnv[i].GetVal();
         i++;
      }
   }
}

References BinarySearchForTime(), IntegralOfInverse(), IntegrateInverseInterpolated(), InterpolatePoints(), mDB, mDefaultValue, mEnv, and mOffset.

Referenced by AverageOfInverse(), GeneratedUpdater::ComputeWarpedLength(), PlaybackSchedule::ComputeWarpedLength(), IntegralOfInverse(), and TimeTrack::testMe().

Here is the call graph for this function:

Here is the caller graph for this function:

IsTrivial()

bool Envelope::IsTrivial

(

)

const

Definition at line 56 of file Envelope.cpp.

{
   return mDefaultValue == 1.0 && mEnv.empty();
}

References mDefaultValue, and mEnv.

MoveDragPoint()

void Envelope::MoveDragPoint	(	double	newWhen,
		double	value
	)

Definition at line 193 of file Envelope.cpp.

{
   SetDragPointValid(true);
   if (!mDragPointValid)
      return;
 
   // We'll limit the drag point time to be between those of the preceding
   // and next envelope point.
   double limitLo = 0.0;
   double limitHi = mTrackLen;
 
   if (mDragPoint > 0)
      limitLo = std::max(limitLo, mEnv[mDragPoint - 1].GetT());
   if (mDragPoint + 1 < (int)mEnv.size())
      limitHi = std::min(limitHi, mEnv[mDragPoint + 1].GetT());
 
   EnvPoint &dragPoint = mEnv[mDragPoint];
   const double tt =
      std::max(limitLo, std::min(limitHi, newWhen));
 
   // This might temporary violate the constraint that at most two
   // points share a time value.
   dragPoint.SetT(tt);
   dragPoint.SetVal( this, value );
 
   ++mVersion;
}

References mDragPoint, mDragPointValid, mEnv, min(), mTrackLen, mVersion, SetDragPointValid(), EnvPoint::SetT(), and EnvPoint::SetVal().

Referenced by EnvelopeEditor::MoveDragPoint().

Here is the call graph for this function:

Here is the caller graph for this function:

NextPointAfter()

double Envelope::NextPointAfter ( double  t ) const

private

Definition at line 1115 of file Envelope.cpp.

{
   int lo,hi;
   BinarySearchForTime( lo, hi, t );
   if (hi >= (int)mEnv.size())
      return t;
   else
      return mEnv[hi].GetT();
}

References BinarySearchForTime(), and mEnv.

Here is the call graph for this function:

NumberOfPointsAfter()

int Envelope::NumberOfPointsAfter ( double  t ) const

private

Definition at line 1106 of file Envelope.cpp.

{
   int lo,hi;
   BinarySearchForTime( lo, hi, t );
 
   return mEnv.size() - hi;
}

References BinarySearchForTime(), and mEnv.

Here is the call graph for this function:

operator[]()

const EnvPoint & Envelope::operator[] ( int  index ) const

inline

Accessor for points.

Definition at line 191 of file Envelope.h.

   {
      return mEnv[index];
   }

PasteEnvelope()

void Envelope::PasteEnvelope	(	double	t0,
		const Envelope *	e,
		double	sampleDur
	)

Exception safety guarantee:

No-fail

Definition at line 486 of file Envelope.cpp.

{
   const bool wasEmpty = (this->mEnv.size() == 0);
   auto otherSize = e->mEnv.size();
   const double otherDur = e->mTrackLen;
   const auto otherOffset = e->mOffset;
   const auto deltat = otherOffset + otherDur;
 
   ++mVersion;
 
   if ( otherSize == 0 && wasEmpty && e->mDefaultValue == this->mDefaultValue )
   {
      // msmeyer: The envelope is empty and has the same default value, so
      // there is nothing that must be inserted, just return. This avoids
      // the creation of unnecessary duplicate control points
      // MJS: but the envelope does get longer
      // PRL:  Assuming t0 is in the domain of the envelope
      mTrackLen += deltat;
      return;
   }
 
   // Make t0 relative to the offset of the envelope we are pasting into,
   // and trim it to the domain of this
   t0 = std::min( mTrackLen, std::max( 0.0, t0 - mOffset ) );
 
   // Adjust if the insertion point rounds off near a discontinuity in this
   if ( true )
   {
      double newT0;
      auto range = EqualRange( t0, sampleDur );
      auto index = range.first;
      if ( index + 2 == range.second &&
           ( newT0 = mEnv[ index ].GetT() ) == mEnv[ 1 + index ].GetT() )
         t0 = newT0;
   }
 
   // Open up a space
   double leftVal = e->GetValue( 0 );
   double rightVal = e->GetValueRelative( otherDur );
   // This range includes the right-side limit of the left end of the space,
   // and the left-side limit of the right end:
   const auto range = ExpandRegion( t0, deltat, &leftVal, &rightVal );
   // Where to put the copied points from e -- after the first of the
   // two points in range:
   auto insertAt = range.first + 1;
 
   // Copy points from e -- maybe skipping those at the extremes
   auto end = e->mEnv.end();
   if ( otherSize != 0 && e->mEnv[ otherSize - 1 ].GetT() == otherDur )
      // ExpandRegion already made an equivalent limit point
      --end, --otherSize;
   auto begin = e->mEnv.begin();
   if ( otherSize != 0 && otherOffset == 0.0 && e->mEnv[ 0 ].GetT() == 0.0 )
      ++begin, --otherSize;
   mEnv.insert( mEnv.begin() + insertAt, begin, end );
 
   // Adjust their times
   for ( size_t index = insertAt, last = insertAt + otherSize;
         index < last; ++index ) {
      auto &point = mEnv[ index ];
      // The mOffset of the envelope-pasted-from is irrelevant.
      // The GetT() times in it are relative to its start.
      // The new GetT() times are relative to the envelope-pasted-to start.
      // We are pasting at t0 relative to the envelope-pasted-to start.
      // Hence we adjust by just t0.
      // Bug 1844 was that we also adjusted by the envelope-pasted-from offset.
      point.SetT( point.GetT() + /*otherOffset +*/ t0 );
   }
 
   // Treat removable discontinuities
   // Right edge outward:
   RemoveUnneededPoints( insertAt + otherSize + 1, true );
   // Right edge inward:
   RemoveUnneededPoints( insertAt + otherSize, false, false );
 
   // Left edge inward:
   RemoveUnneededPoints( range.first, true, false );
   // Left edge outward:
   RemoveUnneededPoints( range.first - 1, false );
 
   // Guarantee monotonicity of times, against little round-off mistakes perhaps
   ConsistencyCheck();
}

References details::begin(), ConsistencyCheck(), details::end(), EqualRange(), ExpandRegion(), GetValue(), GetValueRelative(), mDefaultValue, mEnv, min(), mOffset, mTrackLen, mVersion, and RemoveUnneededPoints().

Here is the call graph for this function:

Reassign()

int Envelope::Reassign	(	double	when,
		double	value
	)

Move a point at when to value.

Returns 0 if point moved, -1 if not found.

Definition at line 700 of file Envelope.cpp.

{
   when -= mOffset;
 
   int len = mEnv.size();
   if (len == 0)
      return -1;
 
   int i = 0;
   while (i < len && when > mEnv[i].GetT())
      i++;
 
   if (i >= len || when < mEnv[i].GetT())
      return -1;
 
   mEnv[i].SetVal(this, value);
 
   ++mVersion;
 
   return 0;
}

References mEnv, mOffset, and mVersion.

Referenced by EqualizationBandSliders::GraphicEQ().

Here is the caller graph for this function:

RemoveUnneededPoints()

void Envelope::RemoveUnneededPoints ( size_t  startAt, bool  rightward, bool  testNeighbors = true  )

privatenoexcept

Exception safety guarantee:

No-fail

Definition at line 571 of file Envelope.cpp.

{
   // startAt is the index of a recently inserted point which might make no
   // difference in envelope evaluation, or else might cause nearby points to
   // make no difference.
 
   auto isDiscontinuity = [this]( size_t index ) noexcept {
      // Assume array accesses are in-bounds
      const EnvPoint &point1 = mEnv[ index ];
      const EnvPoint &point2 = mEnv[ index + 1 ];
      return point1.GetT() == point2.GetT() &&
         fabs( point1.GetVal() - point2.GetVal() ) > VALUE_TOLERANCE;
   };
 
   auto remove = [this]( size_t index, bool leftLimit ) noexcept {
      // Assume array accesses are in-bounds
      const auto &point = mEnv[ index ];
      auto when = point.GetT();
      auto val = point.GetVal();
      Delete( index );  // try it to see if it's doing anything
      auto val1 = GetValueRelative ( when, leftLimit );
      if( fabs( val - val1 ) > VALUE_TOLERANCE ) {
         // put it back, we needed it
         Insert( index, EnvPoint{ when, val } );
         return false;
      }
      else
      {
         ++mVersion;
         return true;
      }
   };
 
   auto len = mEnv.size();
 
   bool leftLimit =
      !rightward && startAt + 1 < len && isDiscontinuity( startAt );
 
   bool removed = remove( startAt, leftLimit );
 
   if ( removed )
      // The given point was removable.  Done!
      return;
 
   if ( !testNeighbors )
      return;
 
   // The given point was not removable.  But did its insertion make nearby
   // points removable?
 
   int index = startAt + ( rightward ? 1 : -1 );
   while ( index >= 0 && index < (int)len ) {
      // Stop at any discontinuity
      if ( index > 0       && isDiscontinuity( index - 1 ) )
         break;
      if ( (index + 1) < (int)len && isDiscontinuity( index ) )
         break;
 
      if ( ! remove( index, false ) )
         break;
 
      --len;
      if ( ! rightward )
         --index;
   }
}

References EnvPoint::GetT(), EnvPoint::GetVal(), and VALUE_TOLERANCE.

Referenced by InsertSpace(), and PasteEnvelope().

Here is the call graph for this function:

Here is the caller graph for this function:

RescaleTimes()

void Envelope::RescaleTimes

(

double

newLength

)

Exception safety guarantee:

No-fail

Definition at line 855 of file Envelope.cpp.

{
   if ( mTrackLen == 0 ) {
      for ( auto &point : mEnv )
         point.SetT( 0 );
   }
   else {
      auto ratio = newLength / mTrackLen;
      for ( auto &point : mEnv )
         point.SetT( point.GetT() * ratio );
   }
   mTrackLen = newLength;
 
   ++mVersion;
}

References mEnv, mTrackLen, and mVersion.

RescaleTimesBy()

void Envelope::RescaleTimesBy

(

double

ratio

)

Definition at line 871 of file Envelope.cpp.

{
   for (auto& point : mEnv)
      point.SetT(point.GetT() * ratio);
   if (mTrackLen != DBL_MAX)
      mTrackLen *= ratio;
}

References mEnv, and mTrackLen.

Referenced by DEFINE_ATTACHED_VIRTUAL_OVERRIDE().

Here is the caller graph for this function:

RescaleValues()

void Envelope::RescaleValues	(	double	minValue,
		double	maxValue
	)

Rescale function for time tracks (could also be used for other tracks though). This is used to load old time track project files where the envelope used a 0 to 1 range instead of storing the actual time track values. This function will change the range of the envelope and rescale all envelope points accordingly (unlike SetRange, which clamps the envelope points to the NEW range). @minValue - the NEW minimum value @maxValue - the NEW maximum value

Definition at line 117 of file Envelope.cpp.

{
   double oldMinValue = mMinValue;
   double oldMaxValue = mMaxValue;
   mMinValue = minValue;
   mMaxValue = maxValue;
 
   // rescale the default value
   double factor = (mDefaultValue - oldMinValue) / (oldMaxValue - oldMinValue);
   mDefaultValue = ClampValue(mMinValue + (mMaxValue - mMinValue) * factor);
 
   // rescale all points
   for( unsigned int i = 0; i < mEnv.size(); i++ ) {
      factor = (mEnv[i].GetVal() - oldMinValue) / (oldMaxValue - oldMinValue);
      mEnv[i].SetVal( this, mMinValue + (mMaxValue - mMinValue) * factor );
   }
 
   ++mVersion;
}

References ClampValue(), mDefaultValue, mEnv, mMaxValue, mMinValue, and mVersion.

Here is the call graph for this function:

SetDragPoint()

void Envelope::SetDragPoint

(

int

dragPoint

)

Definition at line 148 of file Envelope.cpp.

{
   mDragPoint = std::max(-1, std::min(int(mEnv.size() - 1), dragPoint));
   mDragPointValid = (mDragPoint >= 0);
}

References mDragPoint, mDragPointValid, mEnv, and min().

Referenced by EnvelopeEditor::HandleMouseButtonDown().

Here is the call graph for this function:

Here is the caller graph for this function:

SetDragPointValid()

void Envelope::SetDragPointValid

(

bool

valid

)

Definition at line 154 of file Envelope.cpp.

{
   mDragPointValid = (valid && mDragPoint >= 0);
   if (mDragPoint >= 0 && !valid) {
      // We're going to be deleting the point; On
      // screen we show this by having the envelope move to
      // the position it will have after deletion of the point.
      // Without deleting the point we move it left or right
      // to the same position as the previous or next point.
 
      static const double big = std::numeric_limits<double>::max();
      auto size = mEnv.size();
 
      if( size <= 1) {
         // There is only one point - just move it
         // off screen and at default height.
         // temporary state when dragging only!
         mEnv[mDragPoint].SetT(big);
         mEnv[mDragPoint].SetVal( this, mDefaultValue );
         return;
      }
      else if ( mDragPoint + 1 == (int)size ) {
         // Put the point at the height of the last point, but also off screen.
         mEnv[mDragPoint].SetT(big);
         mEnv[mDragPoint].SetVal( this, mEnv[ size - 1 ].GetVal() );
      }
      else {
         // Place it exactly on its right neighbour.
         // That way the drawing code will overpaint the dark dot with
         // a light dot, as if it were deleted.
         const auto &neighbor = mEnv[mDragPoint + 1];
         mEnv[mDragPoint].SetT(neighbor.GetT());
         mEnv[mDragPoint].SetVal( this, neighbor.GetVal() );
      }
   }
 
   ++mVersion;
}

References mDefaultValue, mDragPoint, mDragPointValid, mEnv, mVersion, and size.

Referenced by EnvelopeEditor::HandleDragging(), and MoveDragPoint().

Here is the caller graph for this function:

SetExponential()

void Envelope::SetExponential ( bool  db )

inline

Definition at line 94 of file Envelope.h.

{ mDB = db; }

SetOffset()

void Envelope::SetOffset

(

double

newOffset

)

Exception safety guarantee:

No-fail

Definition at line 826 of file Envelope.cpp.

{
   mOffset = newOffset;
}

References mOffset.

SetRange()

void Envelope::SetRange	(	double	minValue,
		double	maxValue
	)

Definition at line 230 of file Envelope.cpp.

                                                        {
   mMinValue = minValue;
   mMaxValue = maxValue;
   mDefaultValue = ClampValue(mDefaultValue);
   for( unsigned int i = 0; i < mEnv.size(); i++ )
      mEnv[i].SetVal( this, mEnv[i].GetVal() ); // this clamps the value to the NEW range
 
   ++mVersion;
}

References ClampValue(), mDefaultValue, mEnv, mMaxValue, mMinValue, and mVersion.

Here is the call graph for this function:

SetTrackLen()

void Envelope::SetTrackLen	(	double	trackLen,
		double	sampleDur = 0.0
	)

Exception safety guarantee:

No-fail

Definition at line 832 of file Envelope.cpp.

{
   // Preserve the left-side limit at trackLen.
   auto range = EqualRange( trackLen, sampleDur );
   bool needPoint = ( range.first == range.second && trackLen < mTrackLen );
   double value=0.0;
   if ( needPoint )
      value = GetValueRelative( trackLen );
 
   mTrackLen = trackLen;
 
   // Shrink the array.
   // If more than one point already at the end, keep only the first of them.
   int newLen = std::min( 1 + range.first, range.second );
   mEnv.resize( newLen );
 
   ++mVersion;
 
   if ( needPoint )
      AddPointAtEnd( mTrackLen, value );
}

References AddPointAtEnd(), EqualRange(), GetValueRelative(), mEnv, min(), mTrackLen, and mVersion.

Referenced by EqualizationFilter::EqualizationFilter(), and EqualizationBandSliders::GraphicEQ().

Here is the call graph for this function:

Here is the caller graph for this function:

SolveIntegralOfInverse()

double Envelope::SolveIntegralOfInverse	(	double	t0,
		double	area
	)		const

Definition at line 1350 of file Envelope.cpp.

{
   if(area == 0.0)
      return t0;
 
   const auto count = mEnv.size();
   if(count == 0) // 'empty' envelope
      return t0 + area * mDefaultValue;
 
   // Correct for offset!
   t0 -= mOffset;
   return mOffset + [&] {
      // Now we can safely assume t0 is relative time!
      double lastT, lastVal;
      int i; // this is the next point to check
      if(t0 < mEnv[0].GetT()) // t0 preceding the first point
      {
         if (area < 0) {
            return t0 + area * mEnv[0].GetVal();
         }
         else {
            i = 1;
            lastT = mEnv[0].GetT();
            lastVal = mEnv[0].GetVal();
            double added = (lastT - t0) / lastVal;
            if(added >= area)
               return t0 + area * mEnv[0].GetVal();
            area -= added;
         }
      }
      else if(t0 >= mEnv[count - 1].GetT()) // t0 at or following the last point
      {
         if (area < 0) {
            i = (int)count - 2;
            lastT = mEnv[count - 1].GetT();
            lastVal = mEnv[count - 1].GetVal();
            double added = (lastT - t0) / lastVal; // negative
            if(added <= area)
               return t0 + area * mEnv[count - 1].GetVal();
            area -= added;
         }
         else {
            return t0 + area * mEnv[count - 1].GetVal();
         }
      }
      else // t0 enclosed by points
      {
         // Skip any points that come before t0 using binary search
         int lo, hi;
         BinarySearchForTime(lo, hi, t0);
         lastVal = InterpolatePoints(mEnv[lo].GetVal(), mEnv[hi].GetVal(), (t0 - mEnv[lo].GetT()) / (mEnv[hi].GetT() - mEnv[lo].GetT()), mDB);
         lastT = t0;
         if (area < 0)
            i = lo;
         else
            i = hi; // the point immediately after t0.
      }
 
      if (area < 0) {
         // loop BACKWARDS through the rest of the envelope points until we get to t1
         // (which is less than t0)
         while (1)
         {
            if(i < 0) // the requested range extends beyond the leftmost point
            {
               return lastT + area * lastVal;
            }
            else
            {
               double added =
                  -IntegrateInverseInterpolated(mEnv[i].GetVal(), lastVal, lastT - mEnv[i].GetT(), mDB);
               if(added <= area)
                  return lastT - SolveIntegrateInverseInterpolated(lastVal, mEnv[i].GetVal(), lastT - mEnv[i].GetT(), -area, mDB);
               area -= added;
               lastT = mEnv[i].GetT();
               lastVal = mEnv[i].GetVal();
               --i;
            }
         }
      }
      else {
         // loop through the rest of the envelope points until we get to t1
         while (1)
         {
            if(i >= (int)count) // the requested range extends beyond the last point
            {
               return lastT + area * lastVal;
            }
            else
            {
               double added = IntegrateInverseInterpolated(lastVal, mEnv[i].GetVal(), mEnv[i].GetT() - lastT, mDB);
               if(added >= area)
                  return lastT + SolveIntegrateInverseInterpolated(lastVal, mEnv[i].GetVal(), mEnv[i].GetT() - lastT, area, mDB);
               area -= added;
               lastT = mEnv[i].GetT();
               lastVal = mEnv[i].GetVal();
               i++;
            }
         }
      }
   }();
}

References BinarySearchForTime(), IntegrateInverseInterpolated(), InterpolatePoints(), mDB, mDefaultValue, mEnv, mOffset, and SolveIntegrateInverseInterpolated().

Referenced by PlaybackSchedule::SolveWarpedLength().

Here is the call graph for this function:

Here is the caller graph for this function:

WriteXML()

void Envelope::WriteXML

(

XMLWriter &

xmlFile

)

const

Definition at line 355 of file Envelope.cpp.

{
   unsigned int ctrlPt;
 
   xmlFile.StartTag(wxT("envelope"));
   xmlFile.WriteAttr(wxT("numpoints"), mEnv.size());
 
   for (ctrlPt = 0; ctrlPt < mEnv.size(); ctrlPt++) {
      const EnvPoint &point = mEnv[ctrlPt];
      xmlFile.StartTag(wxT("controlpoint"));
      xmlFile.WriteAttr(wxT("t"), point.GetT(), 12);
      xmlFile.WriteAttr(wxT("val"), point.GetVal(), 12);
      xmlFile.EndTag(wxT("controlpoint"));
   }
 
   xmlFile.EndTag(wxT("envelope"));
}

References EnvPoint::GetT(), EnvPoint::GetVal(), and wxT().

Here is the call graph for this function:

Member Data Documentation

mDB

bool Envelope::mDB

private

Definition at line 249 of file Envelope.h.

Referenced by Integral(), IntegralOfInverse(), and SolveIntegralOfInverse().

mDefaultValue

double Envelope::mDefaultValue

private

Definition at line 251 of file Envelope.h.

Referenced by Flatten(), GetDefaultValue(), Integral(), IntegralOfInverse(), IsTrivial(), PasteEnvelope(), RescaleValues(), SetDragPointValid(), SetRange(), and SolveIntegralOfInverse().

mDragPoint

int Envelope::mDragPoint { -1 }

private

Definition at line 255 of file Envelope.h.

Referenced by ClearDragPoint(), BoundedEnvelope::Envelope(), MoveDragPoint(), SetDragPoint(), and SetDragPointValid().

mDragPointValid

bool Envelope::mDragPointValid { false }

private

Definition at line 254 of file Envelope.h.

Referenced by ClearDragPoint(), MoveDragPoint(), SetDragPoint(), and SetDragPointValid().

mEnv

EnvArray Envelope::mEnv

private

Definition at line 236 of file Envelope.h.

Referenced by AddPointAtEnd(), ConsistencyCheck(), CopyRange(), Delete(), ExpandRegion(), Flatten(), GetNumberOfPoints(), GetPoints(), HandleXMLChild(), HandleXMLTag(), Insert(), Integral(), IntegralOfInverse(), IsTrivial(), MoveDragPoint(), NextPointAfter(), NumberOfPointsAfter(), PasteEnvelope(), Reassign(), RescaleTimes(), RescaleTimesBy(), RescaleValues(), SetDragPoint(), SetDragPointValid(), SetRange(), SetTrackLen(), and SolveIntegralOfInverse().

mMaxValue

double Envelope::mMaxValue

private

Definition at line 250 of file Envelope.h.

Referenced by RescaleValues(), and SetRange().

mMinValue

double Envelope::mMinValue

private

Definition at line 250 of file Envelope.h.

Referenced by RescaleValues(), and SetRange().

mOffset

double Envelope::mOffset { 0.0 }

private

The time at which the envelope starts, i.e. the start offset.

Definition at line 239 of file Envelope.h.

Referenced by CopyRange(), Envelope(), GetPoints(), GetValues(), InsertSpace(), Integral(), IntegralOfInverse(), PasteEnvelope(), Reassign(), SetOffset(), and SolveIntegralOfInverse().

mSearchGuess

int Envelope::mSearchGuess { -2 }

mutableprivate

Definition at line 258 of file Envelope.h.

mTrackEpsilon

double Envelope::mTrackEpsilon { 1.0 / 200000.0 }

private

The shortest distance apart that points on an envelope can be before being considered the same point.

Definition at line 248 of file Envelope.h.

mTrackLen

double Envelope::mTrackLen { 0.0 }

private

The length of the envelope, which is the same as the length of the underlying track (normally)

Definition at line 242 of file Envelope.h.

Referenced by Cap(), CopyRange(), Envelope(), ExpandRegion(), MoveDragPoint(), PasteEnvelope(), RescaleTimes(), RescaleTimesBy(), and SetTrackLen().

mVersion

size_t Envelope::mVersion { 0 }

private

Definition at line 256 of file Envelope.h.

Referenced by AddPointAtEnd(), Delete(), Flatten(), GetVersion(), Insert(), MoveDragPoint(), PasteEnvelope(), Reassign(), RescaleTimes(), RescaleValues(), SetDragPointValid(), SetRange(), and SetTrackLen().

---

The documentation for this class was generated from the following files:

• Envelope.h
• Envelope.cpp