Audacity 3.2.0
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"
23
24class SampleBlock;
26using SampleBlockFactoryPtr = std::shared_ptr<SampleBlockFactory>;
27
28// This is an internal data structure! For advanced use only.
29class SeqBlock {
30 public:
31 using SampleBlockPtr = std::shared_ptr<SampleBlock>;
35
37 : sb{}, start(0)
38 {}
39
41 : sb(sb_), start(start_)
42 {}
43
44 // Construct a SeqBlock with changed start, same file
46 {
47 return SeqBlock(sb, start + delta);
48 }
49};
50class BlockArray : public std::vector<SeqBlock> {};
51using BlockPtrArray = std::vector<SeqBlock*>; // non-owning pointers
52
53class WAVE_TRACK_API Sequence final : public XMLTagHandler{
54 public:
55
56 //
57 // Static methods
58 //
59
60 static void SetMaxDiskBlockSize(size_t bytes);
61 static size_t GetMaxDiskBlockSize();
62
64 static bool IsValidSampleFormat(const int nValue);
65
66 //
67 // Constructor / Destructor / Duplicator
68 //
69
70 Sequence(const SampleBlockFactoryPtr &pFactory, SampleFormats formats);
71
73 Sequence(const Sequence &orig, const SampleBlockFactoryPtr &pFactory);
74
75 Sequence( const Sequence& ) = delete;
76 Sequence& operator= (const Sequence&) = delete;
77
78 ~Sequence();
79
80 //
81 // Editing
82 //
83
84 sampleCount GetNumSamples() const { return mNumSamples; }
85
86 bool Get(samplePtr buffer, sampleFormat format,
87 sampleCount start, size_t len, bool mayThrow) const;
88
94 GetFloatSampleView(sampleCount start, size_t len, bool mayThrow) const;
95
97
100 void SetSamples(constSamplePtr buffer, sampleFormat format,
101 sampleCount start, sampleCount len,
102 sampleFormat effectiveFormat
108 );
109
110 // Return non-null, or else throw!
111 // Must pass in the correct factory for the result. If it's not the same
112 // as in this, then block contents must be copied.
113 std::unique_ptr<Sequence> Copy( const SampleBlockFactoryPtr &pFactory,
114 sampleCount s0, sampleCount s1) const;
116 void Paste(sampleCount s0, const Sequence *src);
117
118 size_t GetIdealAppendLen() const;
119
128 bool Append(
129 constSamplePtr buffer, sampleFormat format, size_t len, size_t stride,
130 sampleFormat effectiveFormat
136 );
137
143 void Flush();
144
147
148 SeqBlock::SampleBlockPtr AppendNewBlock(
149 constSamplePtr buffer, sampleFormat format, size_t len);
151
152 void AppendSharedBlock(const SeqBlock::SampleBlockPtr &pBlock);
154 void Delete(sampleCount start, sampleCount len);
155
157 void SetSilence(sampleCount s0, sampleCount len);
159 void InsertSilence(sampleCount s0, sampleCount len);
160
162 {
163 return mpFactory;
164 }
165
166 //
167 // XMLTagHandler callback methods for loading and saving
168 //
169
170 bool HandleXMLTag(const std::string_view& tag, const AttributesList& attrs) override;
171 void HandleXMLEndTag(const std::string_view& tag) override;
172 XMLTagHandler *HandleXMLChild(const std::string_view& tag) override;
173 void WriteXML(XMLWriter &xmlFile) const /* not override */;
174
175 bool GetErrorOpening() { return mErrorOpening; }
176
177 //
178 // Lock all of this sequence's sample blocks, keeping them
179 // from being destroyed when closing.
180
182
183 bool CloseLock() noexcept;
184
185 //
186 // Manipulating Sample Format
187 //
188
189 SampleFormats GetSampleFormats() const;
190
192
193 bool ConvertToSampleFormat(sampleFormat format,
194 const std::function<void(size_t)> & progressReport = {});
195
196 //
197 // Retrieving summary info
198 //
199
200 std::pair<float, float> GetMinMax(
201 sampleCount start, sampleCount len, bool mayThrow) const;
202 float GetRMS(sampleCount start, sampleCount len, bool mayThrow) const;
203
204 //
205 // Getting block size and alignment information
206 //
207
208 // These return a nonnegative number of samples meant to size a memory buffer
209 size_t GetBestBlockSize(sampleCount start) const;
210 size_t GetMaxBlockSize() const;
211 size_t GetIdealBlockSize() const;
212
213 //
214 // This should only be used if you really, really know what
215 // you're doing!
216 //
217
218 BlockArray &GetBlockArray() { return mBlock; }
219 const BlockArray &GetBlockArray() const { return mBlock; }
220
221 size_t GetAppendBufferLen() const { return mAppendBufferLen; }
222 constSamplePtr GetAppendBuffer() const { return mAppendBuffer.ptr(); }
223
224 private:
225
226 //
227 // Private static variables
228 //
229
230 static size_t sMaxDiskBlockSize;
231
232 //
233 // Private variables
234 //
235
237
240
241 // Not size_t! May need to be large:
242 sampleCount mNumSamples{ 0 };
243
244 size_t mMinSamples; // min samples per block
245 size_t mMaxSamples; // max samples per block
246
247 SampleBuffer mAppendBuffer {};
248 size_t mAppendBufferLen { 0 };
249 sampleFormat mAppendEffectiveFormat{ narrowestSampleFormat };
250
251 bool mErrorOpening{ false };
252
253 //
254 // Private methods
255 //
256
258 sampleCount GetBlockStart(sampleCount position) const;
259
261
263 constSamplePtr buffer, sampleFormat format, size_t len, bool coalesce);
264
265 static void AppendBlock(SampleBlockFactory *pFactory, sampleFormat format,
266 BlockArray &blocks,
267 sampleCount &numSamples,
268 const SeqBlock &b);
269
270 // Accumulate NEW block files onto the end of a block array.
271 // Does not change this sequence. The intent is to use
272 // CommitChangesIfConsistent later.
273 static void Blockify(SampleBlockFactory &factory,
274 size_t maxSamples,
276 BlockArray &list,
277 sampleCount start,
278 constSamplePtr buffer,
279 size_t len);
280
281 bool Get(int b,
282 samplePtr buffer,
284 sampleCount start,
285 size_t len,
286 bool mayThrow) const;
287
288public:
289
290 //
291 // Public methods
292 //
293
294 int FindBlock(sampleCount pos) const;
295
296 static bool Read(samplePtr buffer, sampleFormat format,
297 const SeqBlock &b,
298 size_t blockRelativeStart, size_t len, bool mayThrow);
299
300 // This function throws if the track is messed up
301 // because of inconsistent block starts & lengths
302 void ConsistencyCheck (const wxChar *whereStr, bool mayThrow = true) const;
303
304 // This function prints information to stdout about the blocks in the
305 // tracks and indicates if there are inconsistencies.
306 static void DebugPrintf
307 (const BlockArray &block, sampleCount numSamples, wxString *dest);
308
309private:
311 (const BlockArray &block, size_t maxSamples, size_t from,
312 sampleCount numSamples, const wxChar *whereStr,
313 bool mayThrow = true);
314
315 // The next two are used in methods that give a strong guarantee.
316 // They either throw because final consistency check fails, or swap the
317 // changed contents into place.
318
319 void CommitChangesIfConsistent
320 (BlockArray &newBlock, sampleCount numSamples, const wxChar *whereStr);
321
322 void AppendBlocksIfConsistent
323 (BlockArray &additionalBlocks, bool replaceLast,
324 sampleCount numSamples, const wxChar *whereStr);
325
326};
327
328#endif // __AUDACITY_SEQUENCE__
329
An audio segment is either a whole clip or the silence between clips. Views allow shared references t...
gPrefs Read(wxT("/GUI/VerticalZooming"), &bVZoom, false)
std::shared_ptr< SampleBlockFactory > SampleBlockFactoryPtr
Definition: SampleBlock.h:30
sampleFormat
The ordering of these values with operator < agrees with the order of increasing bit width.
Definition: SampleFormat.h:30
@ narrowestSampleFormat
Two synonyms for previous values that might change if more values were added.
char * samplePtr
Definition: SampleFormat.h:57
const char * constSamplePtr
Definition: SampleFormat.h:58
std::vector< SeqBlock * > BlockPtrArray
Definition: Sequence.h:51
Append(Adapt< My >([](My &table) { return(WaveChannelSubViews::numFactories() > 1) ? 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=WaveChannelView::Get(track);menu.Check(id, view.GetMultiView());}) :nullptr;}))
std::vector< Attribute > AttributesList
Definition: XMLTagHandler.h:40
abstract base class with methods to produce SampleBlock objects
Definition: SampleBlock.h:117
Abstract class allows access to contents of a block of sound samples, serialization as XML,...
Definition: SampleBlock.h:46
Two sample formats, remembering format of original source and describing stored format.
Definition: SampleFormat.h:79
Data structure containing pointer to a sample block and a start time. Element of a BlockArray.
Definition: Sequence.h:29
sampleCount start
the sample in the global wavetrack that this block starts at.
Definition: Sequence.h:34
SampleBlockPtr sb
Definition: Sequence.h:32
SeqBlock()
Definition: Sequence.h:36
std::shared_ptr< SampleBlock > SampleBlockPtr
Definition: Sequence.h:31
SeqBlock(const SampleBlockPtr &sb_, sampleCount start_)
Definition: Sequence.h:40
SeqBlock Plus(sampleCount delta) const
Definition: Sequence.h:45
A WaveTrack contains WaveClip(s). A WaveClip contains a Sequence. A Sequence is primarily an interfac...
Definition: Sequence.h:53
bool GetErrorOpening()
Definition: Sequence.h:175
size_t GetAppendBufferLen() const
Definition: Sequence.h:221
BlockArray mBlock
Definition: Sequence.h:238
const BlockArray & GetBlockArray() const
Definition: Sequence.h:219
const SampleBlockFactoryPtr & GetFactory() const
Definition: Sequence.h:161
SampleBlockFactoryPtr mpFactory
Definition: Sequence.h:236
static void ConsistencyCheck(const BlockArray &block, size_t maxSamples, size_t from, sampleCount numSamples, const wxChar *whereStr, bool mayThrow=true)
static size_t sMaxDiskBlockSize
Definition: Sequence.h:230
sampleCount GetNumSamples() const
Definition: Sequence.h:84
constSamplePtr GetAppendBuffer() const
Definition: Sequence.h:222
size_t mMinSamples
Definition: Sequence.h:244
Sequence(const Sequence &)=delete
size_t mMaxSamples
Definition: Sequence.h:245
BlockArray & GetBlockArray()
Definition: Sequence.h:218
SampleFormats mSampleFormats
Definition: Sequence.h:239
This class is an interface which should be implemented by classes which wish to be able to load and s...
Definition: XMLTagHandler.h:42
virtual XMLTagHandler * HandleXMLChild(const std::string_view &tag)=0
virtual void HandleXMLEndTag(const std::string_view &WXUNUSED(tag))
Definition: XMLTagHandler.h:59
virtual bool HandleXMLTag(const std::string_view &tag, const AttributesList &attrs)=0
Base class for XMLFileWriter and XMLStringWriter that provides the general functionality for creating...
Definition: XMLWriter.h:25
Positions or offsets within audio files need a wide type.
Definition: SampleCount.h:19
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:196
static RegisteredToolbarFactory factory
STL namespace.