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)

void	Initialize (int numPoints)

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	print () const

void	testMe ()

bool	IsDirty () 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...

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 }

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 263 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 249 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.

53{

54}

Member Function Documentation

◆ AddPointAtEnd()

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

private

Definition at line 232 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;
   }
}

References mEnv.

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 1083 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 1091 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 858 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 905 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 714 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 104 of file Envelope.h.

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

min

int min(int a, int b)

Definition: CompareAudioCommand.cpp:114

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 173 of file Envelope.h.

173{ mEnv.clear(); }

◆ ClearDragPoint()

void Envelope::ClearDragPoint ( )

Definition at line 213 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 378 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 );
}

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) {
         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 274 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 362 of file Envelope.cpp.

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

References mEnv.

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 763 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 615 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 138 of file Envelope.cpp.

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

References ClampValue(), mDefaultValue, and mEnv.

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetDragPoint()

int Envelope::GetDragPoint ( ) const

inline

Definition at line 216 of file Envelope.h.

216{ 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 221 of file Envelope.h.

221{ return mDragPointValid; }

Referenced by EnvelopeEditor::HandleDragging().

Here is the caller graph for this function:

◆ GetExponential()

bool Envelope::GetExponential ( ) const

inline

Definition at line 95 of file Envelope.h.

95{ 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 930 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 101 of file Envelope.h.

101{ return mMaxValue; }

◆ GetMinValue()

double Envelope::GetMinValue ( ) const

inline

Definition at line 100 of file Envelope.h.

100{ return mMinValue; }

◆ GetNumberOfPoints()

size_t Envelope::GetNumberOfPoints ( ) const

Return number of points.

Definition at line 695 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 92 of file Envelope.h.

92{ 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 700 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 93 of file Envelope.h.

93{ return mTrackLen; }

◆ GetValue()

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

Get envelope value at time t.

Definition at line 838 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 847 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 939 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().

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 947 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:

◆ HandleXMLChild()

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

overridevirtual

Implements XMLTagHandler.

Definition at line 334 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 309 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.

◆ Initialize()

void Envelope::Initialize ( int numPoints )

◆ Insert() [1/2]

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

Definition at line 372 of file Envelope.cpp.

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

References mEnv.

◆ Insert() [2/2]

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

noexcept

insert a point

Definition at line 367 of file Envelope.cpp.

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

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 176 of file Envelope.h.

177 { 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 729 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(), and testMe().

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 666 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 1182 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(), testMe(), 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 1245 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:

◆ IsDirty()

bool Envelope::IsDirty ( ) const

◆ 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 187 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 );
}

References mDragPoint, mDragPointValid, mEnv, min(), mTrackLen, 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 1073 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.

Referenced by testMe().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ NumberOfPointsAfter()

int Envelope::NumberOfPointsAfter ( double t ) const

private

Definition at line 1064 of file Envelope.cpp.

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

References BinarySearchForTime(), and mEnv.

Referenced by testMe().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator[]()

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

inline

Accessor for points.

Definition at line 198 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 466 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;
 
   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, and RemoveUnneededPoints().

Here is the call graph for this function:

◆ print()

void Envelope::print ( ) const

Definition at line 1411 of file Envelope.cpp.

{
   for( unsigned int i = 0; i < mEnv.size(); i++ )
      wxPrintf( "(%.2f, %.2f)\n", mEnv[i].GetT(), mEnv[i].GetVal() );
}

References mEnv.

◆ 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 675 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 );
   return 0;
}

References mEnv, and mOffset.

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 549 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
         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 815 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;
}

References mEnv, and mTrackLen.

◆ RescaleTimesBy()

void Envelope::RescaleTimesBy ( double ratio )

Definition at line 829 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 116 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 );
   }
 
}

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

Here is the call graph for this function:

◆ SetDragPoint()

void Envelope::SetDragPoint ( int dragPoint )

Definition at line 144 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 150 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() );
      }
   }
}

References mDefaultValue, mDragPoint, mDragPointValid, mEnv, 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 96 of file Envelope.h.

96{ mDB = db; }

Referenced by testMe().

Here is the caller graph for this function:

◆ SetOffset()

void Envelope::SetOffset ( double newOffset )

Exception safety guarantee:: No-fail

Definition at line 788 of file Envelope.cpp.

{
   mOffset = newOffset;
}

References mOffset.

◆ SetRange()

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

Definition at line 222 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
}

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

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 794 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 );
 
   if ( needPoint )
      AddPointAtEnd( mTrackLen, value );
}

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

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 1308 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:

◆ testMe()

void Envelope::testMe ( )

Definition at line 1426 of file Envelope.cpp.

{
   double t0=0, t1=0;
 
   SetExponential(false);
 
   Flatten(0.5);
   checkResult( 1, Integral(0.0,100.0), 50);
   checkResult( 2, Integral(-10.0,10.0), 10);
 
   Flatten(0.5);
   checkResult( 3, Integral(0.0,100.0), 50);
   checkResult( 4, Integral(-10.0,10.0), 10);
   checkResult( 5, Integral(-20.0,-10.0), 5);
 
   Flatten(0.5);
   InsertOrReplaceRelative( 5.0, 0.5 );
   checkResult( 6, Integral(0.0,100.0), 50);
   checkResult( 7, Integral(-10.0,10.0), 10);
 
   Flatten(0.0);
   InsertOrReplaceRelative( 0.0, 0.0 );
   InsertOrReplaceRelative( 5.0, 1.0 );
   InsertOrReplaceRelative( 10.0, 0.0 );
   t0 = 10.0 - .1;
   t1 = 10.0 + .1;
   double result = Integral(0.0,t1);
   double resulta = Integral(0.0,t0);
   double resultb = Integral(t0,t1);
   // Integrals should be additive
   checkResult( 8, result - resulta - resultb, 0);
 
   Flatten(0.0);
   InsertOrReplaceRelative( 0.0, 0.0 );
   InsertOrReplaceRelative( 5.0, 1.0 );
   InsertOrReplaceRelative( 10.0, 0.0 );
   t0 = 10.0 - .1;
   t1 = 10.0 + .1;
   checkResult( 9, Integral(0.0,t1), 5);
   checkResult( 10, Integral(0.0,t0), 4.999);
   checkResult( 11, Integral(t0,t1), .001);
 
   mEnv.clear();
   InsertOrReplaceRelative( 0.0, 0.0 );
   InsertOrReplaceRelative( 5.0, 1.0 );
   InsertOrReplaceRelative( 10.0, 0.0 );
   checkResult( 12, NumberOfPointsAfter( -1 ), 3 );
   checkResult( 13, NumberOfPointsAfter( 0 ), 2 );
   checkResult( 14, NumberOfPointsAfter( 1 ), 2 );
   checkResult( 15, NumberOfPointsAfter( 5 ), 1 );
   checkResult( 16, NumberOfPointsAfter( 7 ), 1 );
   checkResult( 17, NumberOfPointsAfter( 10 ), 0 );
   checkResult( 18, NextPointAfter( 0 ), 5 );
   checkResult( 19, NextPointAfter( 5 ), 10 );
}

References checkResult(), Flatten(), InsertOrReplaceRelative(), Integral(), mEnv, NextPointAfter(), NumberOfPointsAfter(), and SetExponential().

Here is the call graph for this function:

◆ WriteXML()

void Envelope::WriteXML ( XMLWriter & xmlFile ) const

Definition at line 343 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 251 of file Envelope.h.

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

◆ mDefaultValue

double Envelope::mDefaultValue

private

Definition at line 253 of file Envelope.h.

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

◆ mDragPoint

int Envelope::mDragPoint { -1 }

private

Definition at line 257 of file Envelope.h.

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

◆ mDragPointValid

bool Envelope::mDragPointValid { false }

private

Definition at line 256 of file Envelope.h.

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

◆ mEnv

EnvArray Envelope::mEnv

private

Definition at line 238 of file Envelope.h.

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

◆ mMaxValue

double Envelope::mMaxValue

private

Definition at line 252 of file Envelope.h.

Referenced by RescaleValues(), and SetRange().

◆ mMinValue

double Envelope::mMinValue

private

Definition at line 252 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 241 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 259 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 250 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 244 of file Envelope.h.

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

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

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Envelope() [1/3]

◆ Envelope() [2/3]

◆ Envelope() [3/3]

◆ ~Envelope()

Member Function Documentation

◆ AddPointAtEnd()

◆ Average()

◆ AverageOfInverse()

◆ BinarySearchForTime()

◆ BinarySearchForTime_LeftLimit()

◆ Cap()

◆ ClampValue()

◆ Clear()

◆ ClearDragPoint()

◆ CollapseRegion()

◆ ConsistencyCheck()

◆ CopyRange()

◆ Delete()

◆ EqualRange()

◆ ExpandRegion()

◆ Flatten()

◆ GetDragPoint()

◆ GetDragPointValid()

◆ GetExponential()

◆ GetInterpolationStartValueAtPoint()

◆ GetMaxValue()

◆ GetMinValue()

◆ GetNumberOfPoints()

◆ GetOffset()

◆ GetPoints()

◆ GetTrackLen()

◆ GetValue()

◆ GetValueRelative()

◆ GetValues()

◆ GetValuesRelative()

◆ HandleXMLChild()

◆ HandleXMLTag()

◆ Initialize()

◆ Insert() [1/2]

◆ Insert() [2/2]

◆ InsertOrReplace()

◆ InsertOrReplaceRelative()

◆ InsertSpace()

◆ Integral()

◆ IntegralOfInverse()

◆ IsDirty()

◆ IsTrivial()

◆ MoveDragPoint()

◆ NextPointAfter()

◆ NumberOfPointsAfter()

◆ operator[]()

◆ PasteEnvelope()

◆ print()

◆ Reassign()

◆ RemoveUnneededPoints()

◆ RescaleTimes()

◆ RescaleTimesBy()

◆ RescaleValues()

◆ SetDragPoint()

◆ SetDragPointValid()

◆ SetExponential()

◆ SetOffset()

◆ SetRange()

◆ SetTrackLen()

◆ SolveIntegralOfInverse()

◆ testMe()

◆ WriteXML()

Member Data Documentation

◆ mDB

◆ mDefaultValue

◆ mDragPoint

◆ mDragPointValid

◆ mEnv

◆ mMaxValue

◆ mMinValue