1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qaudiobuffer.h"
5
6#include <QObject>
7#include <QDebug>
8
9QT_BEGIN_NAMESPACE
10
11class QAudioBufferPrivate : public QSharedData
12{
13public:
14 QAudioBufferPrivate(const QAudioFormat &f, const QByteArray &d, qint64 start)
15 : format(f), data(d), startTime(start)
16 {
17 }
18
19 QAudioFormat format;
20 QByteArray data;
21 qint64 startTime;
22};
23
24QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QAudioBufferPrivate);
25
26/*!
27 \class QAbstractAudioBuffer
28 \internal
29*/
30
31/*!
32 \class QAudioBuffer
33 \inmodule QtMultimedia
34 \ingroup multimedia
35 \ingroup multimedia_audio
36 \brief The QAudioBuffer class represents a collection of audio samples with a specific format
37 and sample rate.
38
39 QAudioBuffer is used by the QAudioDecoder class to hand decoded audio data over to the
40 application. An audio buffer contains data in a certain QAudioFormat that can be queried using
41 format(). It is also tagged with timing and duration information.
42
43 To access the data stored inside the buffer, use the data() or constData() methods.
44
45 Audio buffers are explicitly shared, in most cases, you should call detach() before
46 modifying the data.
47*/
48
49/*!
50 Create a new, empty, invalid buffer.
51 */
52QAudioBuffer::QAudioBuffer() noexcept = default;
53
54/*!
55 Creates a new audio buffer from \a other. Audio buffers are explicitly shared,
56 you should call detach() on the buffer to make a copy that can then be modified.
57 */
58QAudioBuffer::QAudioBuffer(const QAudioBuffer &other) noexcept = default;
59
60/*!
61 Creates a new audio buffer from the supplied \a data, in the
62 given \a format. The format will determine how the number
63 and sizes of the samples are interpreted from the \a data.
64
65 If the supplied \a data is not an integer multiple of the
66 calculated frame size, the excess data will not be used.
67
68 This audio buffer will copy the contents of \a data.
69
70 \a startTime (in microseconds) indicates when this buffer
71 starts in the stream.
72 If this buffer is not part of a stream, set it to -1.
73 */
74QAudioBuffer::QAudioBuffer(const QByteArray &data, const QAudioFormat &format, qint64 startTime)
75{
76 if (!format.isValid() || !data.size())
77 return;
78 d = new QAudioBufferPrivate(format, data, startTime);
79}
80
81/*!
82 Creates a new audio buffer with space for \a numFrames frames of
83 the given \a format. The individual samples will be initialized
84 to the default for the format.
85
86 \a startTime (in microseconds) indicates when this buffer
87 starts in the stream.
88 If this buffer is not part of a stream, set it to -1.
89 */
90QAudioBuffer::QAudioBuffer(int numFrames, const QAudioFormat &format, qint64 startTime)
91{
92 if (!format.isValid() || !numFrames)
93 return;
94
95 QByteArray data(format.bytesForFrames(frameCount: numFrames), '\0');
96 d = new QAudioBufferPrivate(format, data, startTime);
97}
98
99/*!
100 \fn QAudioBuffer::QAudioBuffer(QAudioBuffer &&other)
101
102 Constructs a QAudioBuffer by moving from \a other.
103*/
104
105/*!
106 \fn void QAudioBuffer::swap(QAudioBuffer &other) noexcept
107
108 Swaps the audio buffer with \a other.
109*/
110
111/*!
112 \fn QAudioBuffer &QAudioBuffer::operator=(QAudioBuffer &&other)
113
114 Moves \a other into this QAudioBuffer.
115*/
116
117/*!
118 Assigns the \a other buffer to this.
119 */
120QAudioBuffer &QAudioBuffer::operator=(const QAudioBuffer &other) = default;
121
122/*!
123 Destroys this audio buffer.
124 */
125QAudioBuffer::~QAudioBuffer() = default;
126
127/*! \fn bool QAudioBuffer::isValid() const noexcept
128
129 Returns true if this is a valid buffer. A valid buffer
130 has more than zero frames in it and a valid format.
131 */
132
133/*!
134 Detaches this audio buffers from other copies that might share data with it.
135*/
136void QAudioBuffer::detach()
137{
138 if (!d)
139 return;
140 d = new QAudioBufferPrivate(*d);
141}
142
143/*!
144 Returns the \l {QAudioFormat}{format} of this buffer.
145
146 Several properties of this format influence how
147 the \l duration() or \l byteCount() are calculated
148 from the \l frameCount().
149 */
150QAudioFormat QAudioBuffer::format() const noexcept
151{
152 if (!d)
153 return QAudioFormat();
154 return d->format;
155}
156
157/*!
158 Returns the number of complete audio frames in this buffer.
159
160 An audio frame is an interleaved set of one sample per channel
161 for the same instant in time.
162*/
163qsizetype QAudioBuffer::frameCount() const noexcept
164{
165 if (!d)
166 return 0;
167 return d->format.framesForBytes(byteCount: d->data.size());
168}
169
170/*!
171 Returns the number of samples in this buffer.
172
173 If the format of this buffer has multiple channels,
174 then this count includes all channels. This means
175 that a stereo buffer with 1000 samples in total will
176 have 500 left samples and 500 right samples (interleaved),
177 and this function will return 1000.
178
179 \sa frameCount()
180*/
181qsizetype QAudioBuffer::sampleCount() const noexcept
182{
183 return frameCount() * format().channelCount();
184}
185
186/*!
187 Returns the size of this buffer, in bytes.
188 */
189qsizetype QAudioBuffer::byteCount() const noexcept
190{
191 return d ? d->data.size() : 0;
192}
193
194/*!
195 Returns the duration of audio in this buffer, in microseconds.
196
197 This depends on the \l format(), and the \l frameCount().
198*/
199qint64 QAudioBuffer::duration() const noexcept
200{
201 return format().durationForFrames(frameCount: frameCount());
202}
203
204/*!
205 Returns the time in a stream that this buffer starts at (in microseconds).
206
207 If this buffer is not part of a stream, this will return -1.
208 */
209qint64 QAudioBuffer::startTime() const noexcept
210{
211 if (!d)
212 return -1;
213 return d->startTime;
214}
215
216/*!
217 Returns a pointer to this buffer's data. You can only read it.
218
219 This method is preferred over the const version of \l data() to
220 prevent unnecessary copying.
221
222 There is also a templatized version of this constData() function that
223 allows you to retrieve a specific type of read-only pointer to
224 the data. Note that there is no checking done on the format of
225 the audio buffer - this is simply a convenience function.
226
227 \code
228 // With a 16bit sample buffer:
229 const quint16 *data = buffer->constData<quint16>();
230 \endcode
231
232*/
233const void *QAudioBuffer::constData() const noexcept
234{
235 if (!d)
236 return nullptr;
237 return d->data.constData();
238}
239
240/*!
241 Returns a pointer to this buffer's data. You can only read it.
242
243 You should use the \l constData() function rather than this
244 to prevent accidental deep copying.
245
246 There is also a templatized version of this data() function that
247 allows you to retrieve a specific type of read-only pointer to
248 the data. Note that there is no checking done on the format of
249 the audio buffer - this is simply a convenience function.
250
251 \code
252 // With a 16bit sample const buffer:
253 const quint16 *data = buffer->data<quint16>();
254 \endcode
255*/
256const void *QAudioBuffer::data() const noexcept
257{
258 if (!d)
259 return nullptr;
260 return d->data.constData();
261}
262
263/*
264 Template data/constData functions caused override problems with qdoc,
265 so moved their docs into the non template versions.
266*/
267
268/*!
269 Returns a pointer to this buffer's data. You can modify the
270 data through the returned pointer.
271
272 Since QAudioBuffer objects are explicitly shared, you should usually
273 call detach() before modifying the data through this function.
274
275 There is also a templatized version of data() allows you to retrieve
276 a specific type of pointer to the data. Note that there is no
277 checking done on the format of the audio buffer - this is
278 simply a convenience function.
279
280 \code
281 // With a 16bit sample buffer:
282 quint16 *data = buffer->data<quint16>(); // May cause deep copy
283 \endcode
284*/
285void *QAudioBuffer::data()
286{
287 if (!d)
288 return nullptr;
289 return d->data.data();
290}
291
292/*!
293 \typedef QAudioBuffer::S16S
294
295 This is a predefined specialization for a signed stereo 16 bit sample. Each
296 channel is a \e {signed short}.
297*/
298
299/*!
300 \typedef QAudioBuffer::U8M
301
302 This is a predefined specialization for an unsigned 8 bit mono sample.
303*/
304/*!
305 \typedef QAudioBuffer::S16M
306 This is a predefined specialization for a signed 16 bit mono sample.
307i*/
308/*!
309 \typedef QAudioBuffer::S32M
310 This is a predefined specialization for a signed 32 bit mono sample.
311*/
312/*!
313 \typedef QAudioBuffer::F32M
314 This is a predefined specialization for a 32 bit float mono sample.
315*/
316/*!
317 \typedef QAudioBuffer::U8S
318 This is a predifined specialization for an unsiged 8 bit stereo sample.
319*/
320/*!
321 \typedef QAudioBuffer::S32S
322 This is a predifined specialization for a siged 32 bit stereo sample.
323*/
324/*!
325 \typedef QAudioBuffer::F32S
326 This is a predifined specialization for a 32 bit float stereo sample.
327*/
328QT_END_NAMESPACE
329

source code of qtmultimedia/src/multimedia/audio/qaudiobuffer.cpp