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"
22
23class SampleBlock;
25using SampleBlockFactoryPtr = std::shared_ptr<SampleBlockFactory>;
26
27// This is an internal data structure! For advanced use only.
28class SeqBlock {
29 public:
30 using SampleBlockPtr = std::shared_ptr<SampleBlock>;
34
36 : sb{}, start(0)
37 {}
38
40 : sb(sb_), start(start_)
41 {}
42
43 // Construct a SeqBlock with changed start, same file
45 {
46 return SeqBlock(sb, start + delta);
47 }
48};
49class BlockArray : public std::vector<SeqBlock> {};
50using 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 WAVE_TRACK_API.
55#ifdef IS_ALPHA
56 #define PROFILE_DLL_API WAVE_TRACK_API
57#else
58 #define PROFILE_DLL_API
59#endif
60
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
78 Sequence(const SampleBlockFactoryPtr &pFactory, SampleFormats formats);
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
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
161 const SampleBlockFactoryPtr &GetFactory() { return mpFactory; }
162
163 //
164 // XMLTagHandler callback methods for loading and saving
165 //
166
167 bool HandleXMLTag(const std::string_view& tag, const AttributesList& attrs) override;
168 void HandleXMLEndTag(const std::string_view& tag) override;
169 XMLTagHandler *HandleXMLChild(const std::string_view& tag) override;
170 void WriteXML(XMLWriter &xmlFile) const /* not override */;
171
172 bool GetErrorOpening() { return mErrorOpening; }
173
174 //
175 // Lock all of this sequence's sample blocks, keeping them
176 // from being destroyed when closing.
177
178 bool CloseLock();//should be called upon project close.
179 // not balanced by unlocking calls.
180
181 //
182 // Manipulating Sample Format
183 //
184
185 SampleFormats GetSampleFormats() const;
186
188
189 bool ConvertToSampleFormat(sampleFormat format,
190 const std::function<void(size_t)> & progressReport = {});
191
192 //
193 // Retrieving summary info
194 //
195
196 std::pair<float, float> GetMinMax(
197 sampleCount start, sampleCount len, bool mayThrow) const;
198 float GetRMS(sampleCount start, sampleCount len, bool mayThrow) const;
199
200 //
201 // Getting block size and alignment information
202 //
203
205 sampleCount GetBlockStart(sampleCount position) const;
206
207 // These return a nonnegative number of samples meant to size a memory buffer
208 size_t GetBestBlockSize(sampleCount start) const;
209 size_t GetMaxBlockSize() const;
210 size_t GetIdealBlockSize() const;
211
212 //
213 // This should only be used if you really, really know what
214 // you're doing!
215 //
216
217 BlockArray &GetBlockArray() { return mBlock; }
218 const BlockArray &GetBlockArray() const { return mBlock; }
219
220 size_t GetAppendBufferLen() const { return mAppendBufferLen; }
221 constSamplePtr GetAppendBuffer() const { return mAppendBuffer.ptr(); }
222
223 private:
224
225 //
226 // Private static variables
227 //
228
229 static size_t sMaxDiskBlockSize;
230
231 //
232 // Private variables
233 //
234
236
239
240 // Not size_t! May need to be large:
241 sampleCount mNumSamples{ 0 };
242
243 size_t mMinSamples; // min samples per block
244 size_t mMaxSamples; // max samples per block
245
246 SampleBuffer mAppendBuffer {};
247 size_t mAppendBufferLen { 0 };
248 sampleFormat mAppendEffectiveFormat{ narrowestSampleFormat };
249
250 bool mErrorOpening{ false };
251
252 //
253 // Private methods
254 //
255
257
259 constSamplePtr buffer, sampleFormat format, size_t len, bool coalesce);
260
261 static void AppendBlock(SampleBlockFactory *pFactory, sampleFormat format,
262 BlockArray &blocks,
263 sampleCount &numSamples,
264 const SeqBlock &b);
265
266 // Accumulate NEW block files onto the end of a block array.
267 // Does not change this sequence. The intent is to use
268 // CommitChangesIfConsistent later.
269 static void Blockify(SampleBlockFactory &factory,
270 size_t maxSamples,
272 BlockArray &list,
273 sampleCount start,
274 constSamplePtr buffer,
275 size_t len);
276
277 bool Get(int b,
278 samplePtr buffer,
280 sampleCount start,
281 size_t len,
282 bool mayThrow) const;
283
284public:
285
286 //
287 // Public methods
288 //
289
290 int FindBlock(sampleCount pos) const;
291
292 static bool Read(samplePtr buffer, sampleFormat format,
293 const SeqBlock &b,
294 size_t blockRelativeStart, size_t len, bool mayThrow);
295
296 // This function throws if the track is messed up
297 // because of inconsistent block starts & lengths
298 void ConsistencyCheck (const wxChar *whereStr, bool mayThrow = true) const;
299
300 // This function prints information to stdout about the blocks in the
301 // tracks and indicates if there are inconsistencies.
302 static void DebugPrintf
303 (const BlockArray &block, sampleCount numSamples, wxString *dest);
304
305private:
307 (const BlockArray &block, size_t maxSamples, size_t from,
308 sampleCount numSamples, const wxChar *whereStr,
309 bool mayThrow = true);
310
311 // The next two are used in methods that give a strong guarantee.
312 // They either throw because final consistency check fails, or swap the
313 // changed contents into place.
314
315 void CommitChangesIfConsistent
316 (BlockArray &newBlock, sampleCount numSamples, const wxChar *whereStr);
317
318 void AppendBlocksIfConsistent
319 (BlockArray &additionalBlocks, bool replaceLast,
320 sampleCount numSamples, const wxChar *whereStr);
321
322};
323
324#endif // __AUDACITY_SEQUENCE__
325
int format
Definition: ExportPCM.cpp:53
gPrefs Read(wxT("/GUI/VerticalZooming"), &bVZoom, false)
std::shared_ptr< SampleBlockFactory > SampleBlockFactoryPtr
Definition: SampleBlock.h:29
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:55
const char * constSamplePtr
Definition: SampleFormat.h:56
std::vector< SeqBlock * > BlockPtrArray
Definition: Sequence.h:50
#define PROFILE_DLL_API
Definition: Sequence.h:58
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;})
std::vector< Attribute > AttributesList
Definition: XMLTagHandler.h:40
abstract base class with methods to produce SampleBlock objects
Definition: SampleBlock.h:114
Abstract class allows access to contents of a block of sound samples, serialization as XML,...
Definition: SampleBlock.h:45
Two sample formats, remembering format of original source and describing stored format.
Definition: SampleFormat.h:77
Data structure containing pointer to a sample block and a start time. Element of a BlockArray.
Definition: Sequence.h:28
sampleCount start
the sample in the global wavetrack that this block starts at.
Definition: Sequence.h:33
SampleBlockPtr sb
Definition: Sequence.h:31
SeqBlock()
Definition: Sequence.h:35
std::shared_ptr< SampleBlock > SampleBlockPtr
Definition: Sequence.h:30
SeqBlock(const SampleBlockPtr &sb_, sampleCount start_)
Definition: Sequence.h:39
SeqBlock Plus(sampleCount delta) const
Definition: Sequence.h:44
A WaveTrack contains WaveClip(s). A WaveClip contains a Sequence. A Sequence is primarily an interfac...
Definition: Sequence.h:61
bool GetErrorOpening()
Definition: Sequence.h:172
const SampleBlockFactoryPtr & GetFactory()
Definition: Sequence.h:161
size_t GetAppendBufferLen() const
Definition: Sequence.h:220
BlockArray mBlock
Definition: Sequence.h:237
const BlockArray & GetBlockArray() const
Definition: Sequence.h:218
SampleBlockFactoryPtr mpFactory
Definition: Sequence.h:235
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:229
sampleCount GetNumSamples() const
Definition: Sequence.h:91
constSamplePtr GetAppendBuffer() const
Definition: Sequence.h:221
size_t mMinSamples
Definition: Sequence.h:243
Sequence(const Sequence &)=delete
size_t mMaxSamples
Definition: Sequence.h:244
BlockArray & GetBlockArray()
Definition: Sequence.h:217
SampleFormats mSampleFormats
Definition: Sequence.h:238
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