Audacity 3.2.0
SampleFormat.h
Go to the documentation of this file.
1/**********************************************************************
2
3 Audacity: A Digital Audio Editor
4
5 @file SampleFormat.h
6
7 Dominic Mazzoni
8
9**********************************************************************/
10
11#ifndef __AUDACITY_SAMPLE_FORMAT__
12#define __AUDACITY_SAMPLE_FORMAT__
13
14#include "MemoryX.h"
15#include <cstdlib>
16
17//
18// Definitions / Meta-Information
19//
20
21enum DitherType : unsigned;
24
25// ----------------------------------------------------------------------------
26// Supported sample formats
27// ----------------------------------------------------------------------------
29
30enum class sampleFormat : unsigned {
31 int16Sample = 0x00020001,
32 int24Sample = 0x00040001,
33 floatSample = 0x0004000F,
34
38};
39
40// C++20 using enum sampleFormat;
46
47// ----------------------------------------------------------------------------
48// Provide the number of bytes a specific sample will take
49// ----------------------------------------------------------------------------
50#define SAMPLE_SIZE(SampleFormat) (static_cast<unsigned>(SampleFormat) >> 16)
51
52// ----------------------------------------------------------------------------
53// Generic pointer to sample data
54// ----------------------------------------------------------------------------
55using samplePtr = char *;
56using constSamplePtr = const char *;
57
58// Used to determine how to fill in empty areas of audio.
59typedef enum {
61 fillTwo = 2
63
65#define SAMPLE_SIZE_DISK(SampleFormat) (((SampleFormat) == int24Sample) ? \
66 size_t{ 3 } : SAMPLE_SIZE(SampleFormat) )
67
70
72
77class SampleFormats final {
78public:
81 sampleFormat effective,
82 sampleFormat stored
83 )
84 : m_Effective{ std::min( effective, stored ) }
85 , m_Stored{ stored }
86 {}
87
89 sampleFormat Stored() const { return m_Stored; }
90
92
97 {
98 if (effective > m_Effective)
99 m_Effective = std::min(effective, m_Stored);
100 }
101
102private:
105};
106
107//
108// Allocating/Freeing Samples
109//
110
112
113public:
115 : mPtr(0)
116 {}
118 : mPtr((samplePtr)malloc(count * SAMPLE_SIZE(format)))
119 {}
121 {
122 Free();
123 }
125 {
126 mPtr = other.mPtr;
127 other.mPtr = nullptr;
128 }
130 {
131 auto ptr = other.mPtr;
132 other.mPtr = nullptr;
133 mPtr = ptr;
134 return *this;
135 }
136
137 // WARNING! May not preserve contents.
139 {
140 Free();
141 mPtr = (samplePtr)malloc(count * SAMPLE_SIZE(format));
142 return *this;
143 }
144
145
146 void Free()
147 {
148 free(mPtr);
149 mPtr = 0;
150 }
151
152 samplePtr ptr() const { return mPtr; }
153
154
155private:
157};
158
160{
161public:
163 : SampleBuffer()
164 , mCount(0)
165 {}
166
168 : SampleBuffer(count, format)
169 , mCount(count)
170 {}
171
173 {
174 if (!ptr() || mCount < count) {
175 Allocate(count, format);
176 mCount = count;
177 }
178 return *this;
179 }
180
181 void Free()
182 {
184 mCount = 0;
185 }
186
187 using SampleBuffer::ptr;
188
189private:
190 size_t mCount;
191};
192
193//
194// Copying, Converting and Clearing Samples
195//
196
197MATH_API
199
208 float *dst, size_t len, size_t srcStride = 1, size_t dstStride = 1);
209
210MATH_API
212
217void CopySamples(constSamplePtr src, sampleFormat srcFormat,
218 samplePtr dst, sampleFormat dstFormat, size_t len,
219 DitherType ditherType = gHighQualityDither,
220 unsigned int srcStride=1, unsigned int dstStride=1);
221
222MATH_API
224 size_t start, size_t len);
225
226MATH_API
228 int start, int len);
229
230//
231// This must be called on startup and everytime NEW ditherers
232// are set in preferences.
233//
234
235MATH_API
236void InitDitherers();
237
238// These are so commonly done for processing samples in floating point form in memory,
239// let's have abbreviations.
243
244#endif
int min(int a, int b)
DitherType
These ditherers are currently available:
Definition: Dither.h:19
int format
Definition: ExportPCM.cpp:53
constexpr sampleFormat int16Sample
Definition: SampleFormat.h:41
MATH_API DitherType gHighQualityDither
Definition: SampleFormat.h:23
MATH_API void InitDitherers()
MATH_API void ReverseSamples(samplePtr buffer, sampleFormat format, int start, int len)
MATH_API TranslatableString GetSampleFormatStr(sampleFormat format)
constexpr sampleFormat floatSample
Definition: SampleFormat.h:43
constexpr sampleFormat int24Sample
Definition: SampleFormat.h:42
MATH_API void ClearSamples(samplePtr buffer, sampleFormat format, size_t start, size_t len)
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
MATH_API DitherType gLowQualityDither
These global variables are assigned at application startup or after change of preferences.
#define SAMPLE_SIZE(SampleFormat)
Definition: SampleFormat.h:50
MATH_API void SamplesToFloats(constSamplePtr src, sampleFormat srcFormat, float *dst, size_t len, size_t srcStride=1, size_t dstStride=1)
Copy samples from any format into the widest format, which is 32 bit float, with no dithering.
const char * constSamplePtr
Definition: SampleFormat.h:56
MATH_API void CopySamples(constSamplePtr src, sampleFormat srcFormat, samplePtr dst, sampleFormat dstFormat, size_t len, DitherType ditherType=gHighQualityDither, unsigned int srcStride=1, unsigned int dstStride=1)
Copy samples from any format to any other format; apply dithering only if narrowing the format.
constexpr sampleFormat widestSampleFormat
Definition: SampleFormat.h:45
fillFormat
Definition: SampleFormat.h:59
@ fillZero
Definition: SampleFormat.h:60
@ fillTwo
Definition: SampleFormat.h:61
constexpr sampleFormat narrowestSampleFormat
Definition: SampleFormat.h:44
GrowableSampleBuffer & Resize(size_t count, sampleFormat format)
Definition: SampleFormat.h:172
samplePtr ptr() const
Definition: SampleFormat.h:152
GrowableSampleBuffer(size_t count, sampleFormat format)
Definition: SampleFormat.h:167
SampleBuffer & Allocate(size_t count, sampleFormat format)
Definition: SampleFormat.h:138
SampleBuffer(size_t count, sampleFormat format)
Definition: SampleFormat.h:117
SampleBuffer(SampleBuffer &&other)
Definition: SampleFormat.h:124
SampleBuffer & operator=(SampleBuffer &&other)
Definition: SampleFormat.h:129
samplePtr ptr() const
Definition: SampleFormat.h:152
samplePtr mPtr
Definition: SampleFormat.h:156
Two sample formats, remembering format of original source and describing stored format.
Definition: SampleFormat.h:77
sampleFormat m_Stored
Definition: SampleFormat.h:104
SampleFormats(sampleFormat effective, sampleFormat stored)
Definition: SampleFormat.h:80
sampleFormat m_Effective
Definition: SampleFormat.h:103
void UpdateEffective(sampleFormat effective)
Update the effective format, for insertion of more samples into the sequence.
Definition: SampleFormat.h:96
sampleFormat Stored() const
Definition: SampleFormat.h:89
sampleFormat Effective() const
Definition: SampleFormat.h:88
Holds a msgid for the translation catalog; may also bind format arguments.
STL namespace.