Audacity  3.0.3
Sequence.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  Sequence.h
6 
7  Dominic Mazzoni
8 
9 **********************************************************************/
10 
11 #ifndef __AUDACITY_SEQUENCE__
12 #define __AUDACITY_SEQUENCE__
13 
14 
15 #include <vector>
16 #include <functional>
17 
18 #include "SampleFormat.h"
19 #include "XMLTagHandler.h"
20 
21 #include "SampleCount.h"
22 
23 class SampleBlock;
24 class SampleBlockFactory;
25 using SampleBlockFactoryPtr = std::shared_ptr<SampleBlockFactory>;
26 
27 // This is an internal data structure! For advanced use only.
28 class SeqBlock {
29  public:
30  using SampleBlockPtr = std::shared_ptr<SampleBlock>;
34 
36  : sb{}, start(0)
37  {}
38 
39  SeqBlock(const SampleBlockPtr &sb_, sampleCount start_)
40  : sb(sb_), start(start_)
41  {}
42 
43  // Construct a SeqBlock with changed start, same file
44  SeqBlock Plus(sampleCount delta) const
45  {
46  return SeqBlock(sb, start + delta);
47  }
48 };
49 class BlockArray : public std::vector<SeqBlock> {};
50 using BlockPtrArray = std::vector<SeqBlock*>; // non-owning pointers
51 
52 // Put extra symbol information in the release build, for the purpose of gathering
53 // profiling information (as from Windows Process Monitor), when there otherwise
54 // isn't a need for AUDACITY_DLL_API.
55 #ifdef IS_ALPHA
56  #define PROFILE_DLL_API AUDACITY_DLL_API
57 #else
58  #define PROFILE_DLL_API
59 #endif
60 
61 class PROFILE_DLL_API Sequence final : public XMLTagHandler{
62  public:
63 
64  //
65  // Static methods
66  //
67 
68  static void SetMaxDiskBlockSize(size_t bytes);
69  static size_t GetMaxDiskBlockSize();
70 
72  static bool IsValidSampleFormat(const int nValue);
73 
74  //
75  // Constructor / Destructor / Duplicator
76  //
77 
79 
80  Sequence(const Sequence &orig, const SampleBlockFactoryPtr &pFactory);
81 
82  Sequence( const Sequence& ) = delete;
83  Sequence& operator= (const Sequence&) PROHIBITED;
84 
85  ~Sequence();
86 
87  //
88  // Editing
89  //
90 
91  sampleCount GetNumSamples() const { return mNumSamples; }
92 
93  bool Get(samplePtr buffer, sampleFormat format,
94  sampleCount start, size_t len, bool mayThrow) const;
95 
96  // Note that len is not size_t, because nullptr may be passed for buffer, in
97  // which case, silence is inserted, possibly a large amount.
98  void SetSamples(constSamplePtr buffer, sampleFormat format,
99  sampleCount start, sampleCount len);
100 
101  // where is input, assumed to be nondecreasing, and its size is len + 1.
102  // min, max, rms, bl are outputs, and their lengths are len.
103  // Each position in the output arrays corresponds to one column of pixels.
104  // The column for pixel p covers samples from
105  // where[p] up to (but excluding) where[p + 1].
106  // bl is negative wherever data are not yet available.
107  // Return true if successful.
108  bool GetWaveDisplay(float *min, float *max, float *rms, int* bl,
109  size_t len, const sampleCount *where) const;
110 
111  // Return non-null, or else throw!
112  // Must pass in the correct factory for the result. If it's not the same
113  // as in this, then block contents must be copied.
114  std::unique_ptr<Sequence> Copy( const SampleBlockFactoryPtr &pFactory,
115  sampleCount s0, sampleCount s1) const;
116  void Paste(sampleCount s0, const Sequence *src);
117 
118  size_t GetIdealAppendLen() const;
119  void Append(constSamplePtr buffer, sampleFormat format, size_t len);
120 
122  SeqBlock::SampleBlockPtr AppendNewBlock(
123  constSamplePtr buffer, sampleFormat format, size_t len);
125  void AppendSharedBlock(const SeqBlock::SampleBlockPtr &pBlock);
126  void Delete(sampleCount start, sampleCount len);
127 
128  void SetSilence(sampleCount s0, sampleCount len);
129  void InsertSilence(sampleCount s0, sampleCount len);
130 
131  const SampleBlockFactoryPtr &GetFactory() { return mpFactory; }
132 
133  //
134  // XMLTagHandler callback methods for loading and saving
135  //
136 
137  bool HandleXMLTag(const wxChar *tag, const wxChar **attrs) override;
138  void HandleXMLEndTag(const wxChar *tag) override;
139  XMLTagHandler *HandleXMLChild(const wxChar *tag) override;
140  void WriteXML(XMLWriter &xmlFile) const /* not override */;
141 
142  bool GetErrorOpening() { return mErrorOpening; }
143 
144  //
145  // Lock all of this sequence's sample blocks, keeping them
146  // from being destroyed when closing.
147 
148  bool CloseLock();//should be called upon project close.
149  // not balanced by unlocking calls.
150 
151  //
152  // Manipulating Sample Format
153  //
154 
155  sampleFormat GetSampleFormat() const;
156 
157  // Return true iff there is a change
158  bool ConvertToSampleFormat(sampleFormat format,
159  const std::function<void(size_t)> & progressReport = {});
160 
161  //
162  // Retrieving summary info
163  //
164 
165  std::pair<float, float> GetMinMax(
166  sampleCount start, sampleCount len, bool mayThrow) const;
167  float GetRMS(sampleCount start, sampleCount len, bool mayThrow) const;
168 
169  //
170  // Getting block size and alignment information
171  //
172 
173  // This returns a possibly large or negative value
174  sampleCount GetBlockStart(sampleCount position) const;
175 
176  // These return a nonnegative number of samples meant to size a memory buffer
177  size_t GetBestBlockSize(sampleCount start) const;
178  size_t GetMaxBlockSize() const;
179  size_t GetIdealBlockSize() const;
180 
181  //
182  // This should only be used if you really, really know what
183  // you're doing!
184  //
185 
186  BlockArray &GetBlockArray() { return mBlock; }
187  const BlockArray &GetBlockArray() const { return mBlock; }
188 
189  private:
190 
191  //
192  // Private static variables
193  //
194 
195  static size_t sMaxDiskBlockSize;
196 
197  //
198  // Private variables
199  //
200 
202 
205 
206  // Not size_t! May need to be large:
207  sampleCount mNumSamples{ 0 };
208 
209  size_t mMinSamples; // min samples per block
210  size_t mMaxSamples; // max samples per block
211 
212  bool mErrorOpening{ false };
213 
214  //
215  // Private methods
216  //
217 
218  int FindBlock(sampleCount pos) const;
219 
220  SeqBlock::SampleBlockPtr DoAppend(
221  constSamplePtr buffer, sampleFormat format, size_t len, bool coalesce);
222 
223  static void AppendBlock(SampleBlockFactory *pFactory, sampleFormat format,
224  BlockArray &blocks,
225  sampleCount &numSamples,
226  const SeqBlock &b);
227 
228  static bool Read(samplePtr buffer,
230  const SeqBlock &b,
231  size_t blockRelativeStart,
232  size_t len,
233  bool mayThrow);
234 
235  // Accumulate NEW block files onto the end of a block array.
236  // Does not change this sequence. The intent is to use
237  // CommitChangesIfConsistent later.
238  static void Blockify(SampleBlockFactory &factory,
239  size_t maxSamples,
241  BlockArray &list,
242  sampleCount start,
243  constSamplePtr buffer,
244  size_t len);
245 
246  bool Get(int b,
247  samplePtr buffer,
249  sampleCount start,
250  size_t len,
251  bool mayThrow) const;
252 
253 public:
254 
255  //
256  // Public methods
257  //
258 
259  // This function throws if the track is messed up
260  // because of inconsistent block starts & lengths
261  void ConsistencyCheck (const wxChar *whereStr, bool mayThrow = true) const;
262 
263  // This function prints information to stdout about the blocks in the
264  // tracks and indicates if there are inconsistencies.
265  static void DebugPrintf
266  (const BlockArray &block, sampleCount numSamples, wxString *dest);
267 
268 private:
269  static void ConsistencyCheck
270  (const BlockArray &block, size_t maxSamples, size_t from,
271  sampleCount numSamples, const wxChar *whereStr,
272  bool mayThrow = true);
273 
274  // The next two are used in methods that give a strong guarantee.
275  // They either throw because final consistency check fails, or swap the
276  // changed contents into place.
277 
278  void CommitChangesIfConsistent
279  (BlockArray &newBlock, sampleCount numSamples, const wxChar *whereStr);
280 
281  void AppendBlocksIfConsistent
282  (BlockArray &additionalBlocks, bool replaceLast,
283  sampleCount numSamples, const wxChar *whereStr);
284 
285 };
286 
287 #endif // __AUDACITY_SEQUENCE__
288 
XMLWriter
Base class for XMLFileWriter and XMLStringWriter that provides the general functionality for creating...
Definition: XMLWriter.h:23
Sequence::sMaxDiskBlockSize
static size_t sMaxDiskBlockSize
Definition: Sequence.h:195
SeqBlock::Plus
SeqBlock Plus(sampleCount delta) const
Definition: Sequence.h:44
Sequence::mMaxSamples
size_t mMaxSamples
Definition: Sequence.h:210
PROFILE_DLL_API
#define PROFILE_DLL_API
Definition: Sequence.h:58
Sequence::mMinSamples
size_t mMinSamples
Definition: Sequence.h:209
Sequence::mBlock
BlockArray mBlock
Definition: Sequence.h:203
XMLTagHandler::HandleXMLEndTag
virtual void HandleXMLEndTag(const wxChar *WXUNUSED(tag))
Definition: XMLTagHandler.h:79
Sequence::GetBlockArray
BlockArray & GetBlockArray()
Definition: Sequence.h:186
Sequence
A WaveTrack contains WaveClip(s). A WaveClip contains a Sequence. A Sequence is primarily an interfac...
Definition: Sequence.h:61
SeqBlock::SeqBlock
SeqBlock()
Definition: Sequence.h:35
SeqBlock::SampleBlockPtr
std::shared_ptr< SampleBlock > SampleBlockPtr
Definition: Sequence.h:30
SampleCount.h
Sequence::ConsistencyCheck
static void ConsistencyCheck(const BlockArray &block, size_t maxSamples, size_t from, sampleCount numSamples, const wxChar *whereStr, bool mayThrow=true)
Sequence::mSampleFormat
sampleFormat mSampleFormat
Definition: Sequence.h:204
XMLTagHandler.h
factory
static RegisteredToolbarFactory factory
Definition: ControlToolBar.cpp:806
Sequence::GetFactory
const SampleBlockFactoryPtr & GetFactory()
Definition: Sequence.h:131
SeqBlock::sb
SampleBlockPtr sb
Definition: Sequence.h:31
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
Sequence::Sequence
Sequence(const Sequence &)=delete
BlockPtrArray
std::vector< SeqBlock * > BlockPtrArray
Definition: Sequence.h:50
constSamplePtr
const char * constSamplePtr
Definition: SampleFormat.h:50
Append
Append([](My &table) -> Registry::BaseItemPtr { if(WaveTrackSubViews::slots() > 1) return std::make_unique< Entry >("MultiView", Entry::CheckItem, OnMultiViewID, XXO("&Multi-view"), POPUP_MENU_FN(OnMultiView), table, [](PopupMenuHandler &handler, wxMenu &menu, int id){ auto &table=static_cast< WaveTrackMenuTable & >(handler);auto &track=table.FindWaveTrack();const auto &view=WaveTrackView::Get(track);menu.Check(id, view.GetMultiView());});else return nullptr;})
format
int format
Definition: ExportPCM.cpp:56
Sequence::mpFactory
SampleBlockFactoryPtr mpFactory
Definition: Sequence.h:201
XMLTagHandler
This class is an interface which should be implemented by classes which wish to be able to load and s...
Definition: XMLTagHandler.h:62
Sequence::GetErrorOpening
bool GetErrorOpening()
Definition: Sequence.h:142
sampleFormat
sampleFormat
Definition: SampleFormat.h:29
samplePtr
char * samplePtr
Definition: SampleFormat.h:49
min
int min(int a, int b)
Definition: CompareAudioCommand.cpp:106
SeqBlock
Data structure containing pointer to a sample block and a start time. Element of a BlockArray.
Definition: Sequence.h:28
Read
gPrefs Read(wxT("/GUI/VerticalZooming"), &bVZoom, false)
BlockArray
Definition: Sequence.h:49
Sequence::GetBlockArray
const BlockArray & GetBlockArray() const
Definition: Sequence.h:187
sampleCount
Positions or offsets within audio files need a wide type.
Definition: SampleCount.h:18
SampleBlock
Abstract class allows access to contents of a block of sound samples, serialization as XML,...
Definition: SampleBlock.h:45
SeqBlock::SeqBlock
SeqBlock(const SampleBlockPtr &sb_, sampleCount start_)
Definition: Sequence.h:39
XMLTagHandler::HandleXMLTag
virtual bool HandleXMLTag(const wxChar *tag, const wxChar **attrs)=0
Sequence::GetNumSamples
sampleCount GetNumSamples() const
Definition: Sequence.h:91
XMLTagHandler::HandleXMLChild
virtual XMLTagHandler * HandleXMLChild(const wxChar *tag)=0
SampleBlockFactory
abstract base class with methods to produce SampleBlock objects
Definition: SampleBlock.h:106
SampleBlockFactoryPtr
std::shared_ptr< SampleBlockFactory > SampleBlockFactoryPtr
Definition: SampleBlock.h:25
SampleFormat.h
SeqBlock::start
sampleCount start
the sample in the global wavetrack that this block starts at.
Definition: Sequence.h:33