WaveClip.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  WaveClip.h
 
  ?? Dominic Mazzoni
  ?? Markus Meyer
 
*******************************************************************/
 
#ifndef __AUDACITY_WAVECLIP__
#define __AUDACITY_WAVECLIP__
 
 
 
#include "ClientData.h"
#include "SampleFormat.h"
#include "ClipInterface.h"
#include "XMLTagHandler.h"
#include "SampleCount.h"
#include "AudioSegmentSampleView.h"
 
#include <wx/longlong.h>
 
#include <cassert>
#include <functional>
#include <optional>
#include <vector>
 
class BlockArray;
class Envelope;
class ProgressDialog;
class sampleCount;
class SampleBlock;
class SampleBlockFactory;
using SampleBlockFactoryPtr = std::shared_ptr<SampleBlockFactory>;
class Sequence;
class wxFileNameWrapper;
namespace BasicUI { class ProgressDialog; }
 
class WaveClip;
 
// Array of pointers that assume ownership
using WaveClipHolder = std::shared_ptr< WaveClip >;
using WaveClipHolders = std::vector < WaveClipHolder >;
using WaveClipConstHolders = std::vector < std::shared_ptr< const WaveClip > >;
using ProgressReporter = std::function<void(double)>;
 
// A bundle of arrays needed for drawing waveforms.  The object may or may not
// own the storage for those arrays.  If it does, it destroys them.
class WaveDisplay
{
public:
   int width;
   sampleCount *where;
   float *min, *max, *rms;
 
   std::vector<sampleCount> ownWhere;
   std::vector<float> ownMin, ownMax, ownRms;
 
public:
   WaveDisplay(int w)
      : width(w), where(0), min(0), max(0), rms(0)
   {
   }
 
   // Create "own" arrays.
   void Allocate()
   {
      ownWhere.resize(width + 1);
      ownMin.resize(width);
      ownMax.resize(width);
      ownRms.resize(width);
 
      where = &ownWhere[0];
      if (width > 0) {
         min = &ownMin[0];
         max = &ownMax[0];
         rms = &ownRms[0];
      }
      else {
         min = max = rms = 0;
      }
   }
 
   ~WaveDisplay()
   {
   }
};
 
struct WAVE_TRACK_API WaveClipListener
{
   virtual ~WaveClipListener() = 0;
   virtual void MarkChanged() = 0;
   virtual void Invalidate() = 0;
};
 
class WAVE_TRACK_API WaveClip final :
    public ClipInterface,
    public XMLTagHandler,
    public ClientData::Site<WaveClip, WaveClipListener>
{
private:
   // It is an error to copy a WaveClip without specifying the
   // sample block factory.
 
   WaveClip(const WaveClip&) = delete;
   WaveClip& operator= (const WaveClip&) = delete;
 
public:
   using Caches = Site< WaveClip, WaveClipListener >;
 
 
   WaveClip(size_t width,
      const SampleBlockFactoryPtr &factory, sampleFormat format,
      int rate, int colourIndex);
 
 
   WaveClip(const WaveClip& orig,
            const SampleBlockFactoryPtr &factory,
            bool copyCutlines);
 
 
   WaveClip(const WaveClip& orig,
            const SampleBlockFactoryPtr &factory,
            bool copyCutlines,
            double t0, double t1);
 
   virtual ~WaveClip();
 
   bool CheckInvariants() const;
 
   size_t GetWidth() const override;
 
   void ConvertToSampleFormat(sampleFormat format,
      const std::function<void(size_t)> & progressReport = {});
 
   int GetRate() const override
   {
      return mRate;
   }
 
   // Set rate without resampling. This will change the length of the clip
   void SetRate(int rate);
 
   void StretchLeftTo(double to);
   void StretchRightTo(double to);
 
   double GetStretchRatio() const override;
 
   bool HasEqualStretchRatio(const WaveClip& other) const;
   bool StretchRatioEquals(double value) const;
 
   // Resample clip. This also will set the rate, but without changing
   // the length of the clip
   void Resample(int rate, BasicUI::ProgressDialog *progress = nullptr);
 
   void SetColourIndex(int index) { mColourIndex = index; }
   int GetColourIndex() const { return mColourIndex; }
 
   double GetSequenceStartTime() const noexcept;
   void SetSequenceStartTime(double startTime);
   double GetSequenceEndTime() const;
   sampleCount GetSequenceStartSample() const;
   sampleCount GetSequenceSamplesCount() const;
 
   double GetPlayStartTime() const noexcept override;
   void SetPlayStartTime(double time);
 
   double GetPlayEndTime() const override;
 
   double GetPlayDuration() const;
 
   bool IsEmpty() const;
 
   sampleCount GetPlayStartSample() const;
   sampleCount GetPlayEndSample() const;
 
   sampleCount GetVisibleSampleCount() const override;
 
   void SetTrimLeft(double trim);
   double GetTrimLeft() const noexcept;
 
   void SetTrimRight(double trim);
   double GetTrimRight() const noexcept;
 
   void TrimLeft(double deltaTime);
   void TrimRight(double deltaTime);
 
   void TrimLeftTo(double to);
   void TrimRightTo(double to);
 
   void ShiftBy(double delta) noexcept;
 
 
   bool SplitsPlayRegion(double t) const;
   bool WithinPlayRegion(double t) const;
   bool BeforePlayRegion(double t) const;
   bool AtOrBeforePlayRegion(double t) const;
   bool AfterPlayRegion(double t) const;
   bool EntirelyWithinPlayRegion(double t0, double t1) const;
   bool PartlyWithinPlayRegion(double t0, double t1) const;
   bool IntersectsPlayRegion(double t0, double t1) const;
   bool CoversEntirePlayRegion(double t0, double t1) const;
 
   sampleCount CountSamples(double t0, double t1) const;
 
   AudioSegmentSampleView GetSampleView(
      size_t iChannel, sampleCount start, size_t length,
      bool mayThrow = true) const override;
 
   AudioSegmentSampleView GetSampleView(
      size_t iChannel, double t0, double t1, bool mayThrow = true) const;
 
 
   bool GetSamples(size_t ii, samplePtr buffer, sampleFormat format,
                   sampleCount start, size_t len, bool mayThrow = true) const;
 
 
   bool GetSamples(samplePtr buffers[], sampleFormat format,
                   sampleCount start, size_t len, bool mayThrow = true) const;
 
 
   void SetSamples(size_t ii, constSamplePtr buffer, sampleFormat format,
      sampleCount start, size_t len,
      sampleFormat effectiveFormat 
   );
 
   bool
   GetFloatAtTime(double t, size_t iChannel, float& value, bool mayThrow) const;
 
   // clang-format off
   // clang-format on
   void SetFloatsFromTime(
      double t, size_t iChannel, const float* buffer, size_t numSamples,
      sampleFormat effectiveFormat);
 
   void SetFloatsCenteredAroundTime(
      double t, size_t iChannel, const float* buffer, size_t numSideSamples,
      sampleFormat effectiveFormat);
 
   void SetFloatAtTime(
      double t, size_t iChannel, float value, sampleFormat effectiveFormat);
 
   Envelope* GetEnvelope() { return mEnvelope.get(); }
   const Envelope* GetEnvelope() const { return mEnvelope.get(); }
   void SetEnvelope(std::unique_ptr<Envelope> p);
 
 
   BlockArray* GetSequenceBlockArray(size_t ii);
   const BlockArray* GetSequenceBlockArray(size_t ii) const;
 
 
   Sequence* GetSequence(size_t ii) {
      assert(ii < GetWidth());
      return mSequences[ii].get();
   }
   const Sequence* GetSequence(size_t ii) const { return mSequences[ii].get(); }
 
   void MarkChanged();
 
   std::pair<float, float> GetMinMax(size_t ii,
      double t0, double t1, bool mayThrow) const;
   float GetRMS(size_t ii, double t0, double t1, bool mayThrow) const;
 
   void UpdateEnvelopeTrackLen();
 
   std::shared_ptr<SampleBlock>
   AppendNewBlock(constSamplePtr buffer, sampleFormat format, size_t len);
 
   void AppendSharedBlock(const std::shared_ptr<SampleBlock> &pBlock);
 
 
   bool Append(constSamplePtr buffers[], sampleFormat format,
      size_t len, unsigned int stride,
      sampleFormat effectiveFormat 
   );
 
 
   void Flush();
 
   void Clear(double t0, double t1);
 
   void ClearLeft(double t);
   void ClearRight(double t);
 
   void ClearAndAddCutLine(double t0, double t1);
 
   bool Paste(double t0, const WaveClip& other);
 
   void InsertSilence( double t, double len, double *pEnvelopeValue = nullptr );
 
   void AppendSilence( double len, double envelopeValue );
 
   WaveClipHolders &GetCutLines() { return mCutLines; }
   const WaveClipConstHolders &GetCutLines() const
      { return reinterpret_cast< const WaveClipConstHolders& >( mCutLines ); }
   size_t NumCutLines() const { return mCutLines.size(); }
 
   bool FindCutLine(double cutLinePosition,
                    double* cutLineStart = NULL,
                    double *cutLineEnd = NULL) const;
 
   void ExpandCutLine(double cutLinePosition);
 
   bool RemoveCutLine(double cutLinePosition);
 
   void OffsetCutLines(double t0, double len);
 
 
   void CloseLock() noexcept;
 
   //
   // XMLTagHandler callback methods for loading and saving
   //
 
   bool HandleXMLTag(const std::string_view& tag, const AttributesList &attrs) override;
   void HandleXMLEndTag(const std::string_view& tag) override;
   XMLTagHandler *HandleXMLChild(const std::string_view& tag) override;
   void WriteXML(XMLWriter &xmlFile) const /* not override */;
 
   // AWD, Oct 2009: for pasting whitespace at the end of selection
   bool GetIsPlaceholder() const { return mIsPlaceholder; }
   void SetIsPlaceholder(bool val) { mIsPlaceholder = val; }
 
   // used by commands which interact with clips using the keyboard
   bool SharesBoundaryWithNextClip(const WaveClip* next) const;
 
   void SetName(const wxString& name);
   const wxString& GetName() const;
 
   // TimeToSamples and SamplesToTime take clip stretch ratio into account.
   // Use them to convert time / sample offsets.
   sampleCount TimeToSamples(double time) const override;
   double SamplesToTime(sampleCount s) const noexcept;
 
   void SetSilence(sampleCount offset, sampleCount length);
 
 
   constSamplePtr GetAppendBuffer(size_t ii) const;
   size_t GetAppendBufferLen() const;
 
   void
   OnProjectTempoChange(const std::optional<double>& oldTempo, double newTempo);
 
private:
   // Always gives non-negative answer, not more than sample sequence length
   // even if t0 really falls outside that range
   sampleCount TimeToSequenceSamples(double t) const;
 
   sampleCount GetNumSamples() const;
   SampleFormats GetSampleFormats() const;
   const SampleBlockFactoryPtr &GetFactory();
   std::vector<std::unique_ptr<Sequence>> GetEmptySequenceCopies() const;
   void StretchCutLines(double ratioChange);
   double SnapToTrackSample(double time) const noexcept;
 
   void ClearSequence(double t0, double t1);
 
   struct Transaction {
      explicit Transaction(WaveClip &clip);
      ~Transaction();
      void Commit() { committed = true; }
 
      WaveClip &clip;
      std::vector<std::unique_ptr<Sequence>> sequences;
      const double mTrimLeft,
         mTrimRight;
      bool committed{ false };
   };
 
   double mSequenceOffset { 0 };
   double mTrimLeft { 0 };
   double mTrimRight { 0 };
 
   // Used in GetStretchRatio which computes the factor, by which the sample
   // interval is multiplied, to get a realtime duration.
   double mClipStretchRatio = 1.;
   std::optional<double> mRawAudioTempo;
   std::optional<double> mProjectTempo;
 
   int mRate;
   int mColourIndex;
 
   std::vector<std::unique_ptr<Sequence>> mSequences;
   std::unique_ptr<Envelope> mEnvelope;
 
 
   WaveClipHolders mCutLines {};
 
   // AWD, Oct. 2009: for whitespace-at-end-of-selection pasting
   bool mIsPlaceholder { false };
 
private:
   wxString mName;
};
 
#endif