Audacity  2.2.0
Envelope Class Referencefinal

Draggable curve used in TrackPanel for varying amplification. More...

#include <Envelope.h>

Inheritance diagram for Envelope:
XMLTagHandler

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 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 wxChar *tag, const wxChar **attrs) override
 
XMLTagHandlerHandleXMLChild (const wxChar *tag) override
 
void WriteXML (XMLWriter &xmlFile) const
 
void DrawPoints (TrackPanelDrawingContext &context, const wxRect &r, const ZoomInfo &zoomInfo, bool dB, double dBRange, float zoomMin, float zoomMax, bool mirrored) const
 TODO: This should probably move to track artist. More...
 
void CollapseRegion (double t0, double t1, double sampleDur)
 
void Paste (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)
 
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 GetValues (double aligned_time, double sampleDur, double *buffer, int bufferLen, int leftOffset, const ZoomInfo &zoomInfo) const
 Get many envelope points for pixel columns at once, but don't assume uniform time per pixel. 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
 
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)
 insert a point More...
 
size_t GetNumberOfPoints () const
 Return number of 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
 
- Public Member Functions inherited from XMLTagHandler
 XMLTagHandler ()
 
virtual ~XMLTagHandler ()
 
virtual void HandleXMLEndTag (const wxChar *WXUNUSED(tag))
 
virtual void HandleXMLContent (const wxString &WXUNUSED(content))
 
bool ReadXMLTag (const char *tag, const char **attrs)
 
void ReadXMLEndTag (const char *tag)
 
void ReadXMLContent (const char *s, int len)
 
XMLTagHandlerReadXMLChild (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)
 
double GetValueRelative (double t, bool leftLimit=false) const
 
void GetValuesRelative (double *buffer, int len, double t0, double tstep, bool leftLimit=false) const
 
int NumberOfPointsAfter (double t) const
 
double NextPointAfter (double t) const
 
int InsertOrReplaceRelative (double when, double value)
 Add a control point to the envelope. More...
 
const EnvPointoperator[] (int index) const
 Accessor for points. More...
 
std::pair< int, int > EqualRange (double when, double sampleDur) const
 
void MoveDragPoint (double newWhen, double value)
 
void ClearDragPoint ()
 
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
 
void BinarySearchForTime_LeftLimit (int &Lo, int &Hi, double t) const
 
double GetInterpolationStartValueAtPoint (int iPoint) const
 

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 appart 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 }
 

Friends

class EnvelopeEditor
 

Detailed Description

Draggable curve used in TrackPanel for varying amplification.

This class manages an envelope - i.e. a piecewise linear funtion 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.

Constructor & Destructor Documentation

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

References ClampValue().

Envelope::Envelope ( const Envelope orig)
Envelope::Envelope ( const Envelope orig,
double  t0,
double  t1 
)
Envelope::~Envelope ( )
virtual

Member Function Documentation

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

References mEnv.

Referenced by CopyRange(), and SetTrackLen().

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

References GetValue(), and Integral().

double Envelope::AverageOfInverse ( double  t0,
double  t1 
) const
void Envelope::BinarySearchForTime ( int &  Lo,
int &  Hi,
double  t 
) const
private
Parameters
Loreturns last index at or before this time, maybe -1
Hireturns first index after this time, maybe past the end

References mEnv, and mSearchGuess.

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

void Envelope::BinarySearchForTime_LeftLimit ( int &  Lo,
int &  Hi,
double  t 
) const
private
Parameters
Loreturns last index before this time, maybe -1
Hireturns first index at or after this time, maybe past the end

References mEnv, and mSearchGuess.

void Envelope::Cap ( double  sampleDur)
double Envelope::ClampValue ( double  value)
inline
void Envelope::ClearDragPoint ( )
private
void Envelope::CollapseRegion ( double  t0,
double  t1,
double  sampleDur 
)
bool Envelope::ConsistencyCheck ( )

References Delete(), EnvPoint::GetT(), mDragPoint, and mEnv.

Referenced by Paste().

void Envelope::CopyRange ( const Envelope orig,
size_t  begin,
size_t  end 
)
private
void Envelope::Delete ( int  point)

DELETE a point by its position in array.

References mEnv.

Referenced by ClearDragPoint(), and ConsistencyCheck().

void Envelope::DrawPoints ( TrackPanelDrawingContext context,
const wxRect &  r,
const ZoomInfo zoomInfo,
bool  dB,
double  dBRange,
float  zoomMin,
float  zoomMax,
bool  mirrored 
) const
std::pair< int, int > Envelope::EqualRange ( double  when,
double  sampleDur 
) const
private
std::pair< int, int > Envelope::ExpandRegion ( double  t0,
double  tlen,
double *  pLeftVal,
double *  pRightVal 
)
private

Referenced by InsertSpace(), and Paste().

void Envelope::Flatten ( double  value)

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

References ClampValue(), mDefaultValue, and mEnv.

Referenced by EffectEqualization::GraphicEQ(), EffectEqualization::setCurve(), TimeTrack::testMe(), and testMe().

int Envelope::GetDragPoint ( ) const
inline

References mDragPoint.

Referenced by EnvelopeEditor::MouseEvent().

bool Envelope::GetDragPointValid ( ) const
inline
bool Envelope::GetExponential ( ) const
inline

References mDB.

double Envelope::GetInterpolationStartValueAtPoint ( int  iPoint) const
private

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

Parameters
iPointindex in env array to look at.
Returns
value there, or its (safe) log10.

References mDB, and mEnv.

double Envelope::GetMaxValue ( ) const
inline

References mMaxValue.

double Envelope::GetMinValue ( ) const
inline

References mMinValue.

size_t Envelope::GetNumberOfPoints ( ) const

Return number of points.

References mEnv.

Referenced by Envelope(), EffectEqualization::EnvelopeUpdated(), and EnvelopeEditor::HandleMouseButtonDown().

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

Returns the sets of when and value pairs.

References mEnv, and mOffset.

Referenced by EffectEqualization::EnvelopeUpdated().

double Envelope::GetTrackLen ( ) const
inline

References mTrackLen.

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

References GetValuesRelative().

Referenced by Cap(), CollapseRegion(), Paste(), and SetTrackLen().

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.

References GetValuesRelative(), and mOffset.

Referenced by TrackArtist::DrawClipWaveform(), WaveTrack::GetEnvelopeValues(), GetValue(), and EqualizationPanel::OnPaint().

void Envelope::GetValues ( double  aligned_time,
double  sampleDur,
double *  buffer,
int  bufferLen,
int  leftOffset,
const ZoomInfo zoomInfo 
) const

Get many envelope points for pixel columns at once, but don't assume uniform time per pixel.

References ZoomInfo::PositionToTime().

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

Referenced by GetValueRelative(), and GetValues().

XMLTagHandler * Envelope::HandleXMLChild ( const wxChar *  tag)
overridevirtual

Implements XMLTagHandler.

References mEnv.

bool Envelope::HandleXMLTag ( const wxChar *  tag,
const wxChar **  attrs 
)
overridevirtual

Implements XMLTagHandler.

References XMLValueChecker::IsGoodInt(), and mEnv.

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

insert a point

References mEnv.

Referenced by InsertOrReplaceRelative().

int Envelope::InsertOrReplace ( double  when,
double  value 
)
inline
int Envelope::InsertOrReplaceRelative ( double  when,
double  value 
)
private

Add a control point to the envelope.

Parameters
whenthe time in seconds when the envelope point should be created.
valuethe envelope value to use at the given point.
Returns
the index of the NEW envelope point within array of envelope points.

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

Referenced by Cap(), CollapseRegion(), InsertOrReplace(), and testMe().

void Envelope::InsertSpace ( double  t0,
double  tlen 
)
double Envelope::Integral ( double  t0,
double  t1 
) const
double Envelope::IntegralOfInverse ( double  t0,
double  t1 
) const
bool Envelope::IsDirty ( ) const
void Envelope::MoveDragPoint ( double  newWhen,
double  value 
)
private
double Envelope::NextPointAfter ( double  t) const
private

References BinarySearchForTime(), and mEnv.

Referenced by testMe().

int Envelope::NumberOfPointsAfter ( double  t) const
private

References BinarySearchForTime(), and mEnv.

Referenced by testMe().

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

Accessor for points.

References mEnv.

void Envelope::Paste ( double  t0,
const Envelope e,
double  sampleDur 
)
void Envelope::print ( ) const

References mEnv.

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

Move a point at when to value.

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

References mEnv, and mOffset.

Referenced by EffectEqualization::GraphicEQ().

void Envelope::RemoveUnneededPoints ( size_t  startAt,
bool  rightward,
bool  testNeighbors = true 
)
private
void Envelope::RescaleTimes ( double  newLength)

References mEnv, and mTrackLen.

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). - the NEW minimum value - the NEW maximum value

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

void Envelope::SetDragPoint ( int  dragPoint)
void Envelope::SetDragPointValid ( bool  valid)
void Envelope::SetExponential ( bool  db)
inline

References mDB.

Referenced by testMe().

void Envelope::SetOffset ( double  newOffset)

References mOffset.

void Envelope::SetRange ( double  minValue,
double  maxValue 
)
void Envelope::SetTrackLen ( double  trackLen,
double  sampleDur = 0.0 
)
double Envelope::SolveIntegralOfInverse ( double  t0,
double  area 
) const
void Envelope::WriteXML ( XMLWriter xmlFile) const

Friends And Related Function Documentation

friend class EnvelopeEditor
friend

Member Data Documentation

int Envelope::mDragPoint { -1 }
private
bool Envelope::mDragPointValid { false }
private
double Envelope::mMaxValue
private
double Envelope::mMinValue
private
double Envelope::mOffset { 0.0 }
private
int Envelope::mSearchGuess { -2 }
mutableprivate
double Envelope::mTrackEpsilon { 1.0 / 200000.0 }
private

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

double Envelope::mTrackLen { 0.0 }
private

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

Referenced by Cap(), CollapseRegion(), CopyRange(), Envelope(), GetTrackLen(), InsertOrReplaceRelative(), MoveDragPoint(), Paste(), RescaleTimes(), and SetTrackLen().


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