From 8484b0ff9c40fe70cdfc17bf74b0a5be93d674de Mon Sep 17 00:00:00 2001 From: Michael Goddard Date: Tue, 10 Apr 2012 20:19:34 +1000 Subject: Fix a number of doc errors and warnings. * Document a few missing classes/functions/methods * Fix a number of QML snippets that wouldn't work as standalone snippets * Add files to .pro so they show up in Creator.. Still the mysterious lack of controls dir documentation persists :/ Change-Id: I57162371a4d966e4db5bdb1b71d1baf9c0ca57c3 Reviewed-by: Jonas Rabbe --- src/multimedia/audio/qaudio.cpp | 8 +- src/multimedia/audio/qaudiobuffer.cpp | 158 ++++++++++++++++++++++++++++++- src/multimedia/audio/qaudiodecoder_p.cpp | 20 ++-- 3 files changed, 170 insertions(+), 16 deletions(-) (limited to 'src/multimedia/audio') diff --git a/src/multimedia/audio/qaudio.cpp b/src/multimedia/audio/qaudio.cpp index f89783f46..4a516a0ac 100644 --- a/src/multimedia/audio/qaudio.cpp +++ b/src/multimedia/audio/qaudio.cpp @@ -62,7 +62,7 @@ public: } -/* +/*! \namespace QAudio \brief The QAudio namespace contains enums used by the audio classes. \inmodule QtMultimedia @@ -70,7 +70,7 @@ public: \ingroup multimedia_audio */ -/* +/*! \enum QAudio::Error \value NoError No errors have occurred @@ -80,7 +80,7 @@ public: \value FatalError A non-recoverable error has occurred, the audio device is not usable at this time. */ -/* +/*! \enum QAudio::State \value ActiveState Audio data is being processed, this state is set after start() is called @@ -92,7 +92,7 @@ public: is set after start() is called and while no audio data is available to be processed. */ -/* +/*! \enum QAudio::Mode \value AudioOutput audio output device diff --git a/src/multimedia/audio/qaudiobuffer.cpp b/src/multimedia/audio/qaudiobuffer.cpp index 7161e44d4..bde04501f 100644 --- a/src/multimedia/audio/qaudiobuffer.cpp +++ b/src/multimedia/audio/qaudiobuffer.cpp @@ -371,7 +371,18 @@ qint64 QAudioBuffer::startTime() const This method is preferred over the const version of \l data() to prevent unnecessary copying. - */ + + There is also a templatized version of this constData() function that + allows you to retrieve a specific type of read-only pointer to + the data. Note that there is no checking done on the format of + the audio buffer - this is simply a convenience function. + + \code + // With a 16bit sample buffer: + const quint16 *data = buffer->constData(); + \endcode + +*/ const void* QAudioBuffer::constData() const { if (!isValid()) @@ -384,7 +395,17 @@ const void* QAudioBuffer::constData() const You should use the \l constData() function rather than this to prevent accidental deep copying. - */ + + There is also a templatized version of this data() function that + allows you to retrieve a specific type of read-only pointer to + the data. Note that there is no checking done on the format of + the audio buffer - this is simply a convenience function. + + \code + // With a 16bit sample const buffer: + const quint16 *data = buffer->data(); + \endcode +*/ const void* QAudioBuffer::data() const { if (!isValid()) @@ -392,6 +413,12 @@ const void* QAudioBuffer::data() const return d->mProvider->constData(); } + +/* + Template data/constData functions caused override problems with qdoc, + so moved their docs into the non template versions. +*/ + /*! Returns a pointer to this buffer's data. You can modify the data through the returned pointer. @@ -407,7 +434,17 @@ const void* QAudioBuffer::data() const change both buffer instances. Calling \l data() on either instance will again cause a deep copy to be made, which may invalidate the pointers returned from this function previously. - */ + + There is also a templatized version of data() allows you to retrieve + a specific type of pointer to the data. Note that there is no + checking done on the format of the audio buffer - this is + simply a convenience function. + + \code + // With a 16bit sample buffer: + quint16 *data = buffer->data(); // May cause deep copy + \endcode +*/ void *QAudioBuffer::data() { if (!isValid()) @@ -447,4 +484,119 @@ void *QAudioBuffer::data() return 0; } +// Template helper classes worth documenting + +/*! + \class QAudioBuffer::StereoSampleDefault + \internal + + Just a trait class for the default value. +*/ + +/*! + \class QAudioBuffer::StereoSample + \brief The StereoSample class provides a simple wrapper for a stereo audio sample. + \inmodule QtMultimedia + \ingroup multimedia + \ingroup multimedia_audio + + This templatized structure lets you treat a block of individual samples as an + interleaved stereo stream. This is most useful when used with the templatized + \l {QAudioBuffer::data()}{data()} functions of QAudioBuffer. Generally the data + is accessed as a pointer, so no copying should occur. + + There are some predefined instantiations of this template for working with common + stereo sample depths in a convenient way. + + This structure has \e left and \e right members for accessing individual channel data. + + For example: + \code + // Assuming 'buffer' is an unsigned 16 bit stereo buffer.. + QAudioBuffer::S16U *sample = buffer->data(); + for (int i=0; i < buffer->sampleCount() / 2; i++) { + qSwap(sample[i].left, sample[i].right); + } + \endcode + + \sa QAudioBuffer::S8U, QAudioBuffer::S8S, QAudioBuffer::S16S, QAudioBuffer::S16U, QAudioBuffer::S32F +*/ + +/*! + \fn QAudioBuffer::StereoSample::StereoSample() + + Constructs a new sample with the "silent" value for this + sample format (0 for signed formats and floats, 0x8* for unsigned formats). +*/ + +/*! + \fn QAudioBuffer::StereoSample::StereoSample(T leftSample, T rightSample) + + Constructs a new sample with the supplied \a leftSample and \a rightSample values. +*/ + +/*! + \fn QAudioBuffer::StereoSample::operator=(const StereoSample &other) + + Assigns \a other to this sample. + */ + + +/*! + \fn QAudioBuffer::StereoSample::average() const + + Returns the arithmetic average of the left and right samples. + */ + +/*! \fn QAudioBuffer::StereoSample::clear() + + Sets the values of this sample to the "silent" value. +*/ + +/*! + \variable QAudioBuffer::StereoSample::left + \brief the left sample +*/ + +/*! + \variable QAudioBuffer::StereoSample::right + \brief the right sample +*/ + +/*! + \typedef QAudioBuffer::S8U + \relates QAudioBuffer::StereoSample + + This is a predefined specialization for an unsigned stereo 8 bit sample. Each + channel is an \e {unsigned char}. +*/ +/*! + \typedef QAudioBuffer::S8S + \relates QAudioBuffer::StereoSample + + This is a predefined specialization for a signed stereo 8 bit sample. Each + channel is a \e {signed char}. +*/ +/*! + \typedef QAudioBuffer::S16U + \relates QAudioBuffer::StereoSample + + This is a predefined specialization for an unsigned stereo 16 bit sample. Each + channel is an \e {unsigned short}. +*/ +/*! + \typedef QAudioBuffer::S16S + \relates QAudioBuffer::StereoSample + + This is a predefined specialization for a signed stereo 16 bit sample. Each + channel is a \e {signed short}. +*/ +/*! + \typedef QAudioBuffer::S32F + \relates QAudioBuffer::StereoSample + + This is a predefined specialization for an 32 bit float sample. Each + channel is a \e float. +*/ + QT_END_NAMESPACE diff --git a/src/multimedia/audio/qaudiodecoder_p.cpp b/src/multimedia/audio/qaudiodecoder_p.cpp index 8776215ca..b0d57ee8f 100644 --- a/src/multimedia/audio/qaudiodecoder_p.cpp +++ b/src/multimedia/audio/qaudiodecoder_p.cpp @@ -69,7 +69,7 @@ QT_BEGIN_NAMESPACE directly to audio hardware, and playlists and network and streaming based media is not supported. - \sa QAudioBuffer, QAudioDecoder + \sa QAudioBuffer */ namespace @@ -130,7 +130,7 @@ void QAudioDecoderPrivate::_q_error(int error, const QString &errorString) /*! Construct an QAudioDecoder instance - parented to \a parent and with \a flags. + parented to \a parent. */ QAudioDecoder::QAudioDecoder(QObject *parent) : QMediaObject(*new QAudioDecoderPrivate, @@ -204,7 +204,7 @@ QString QAudioDecoder::errorString() const Alternatively, if you wish to block until enough data has been decoded, you can call read() at any time to block until a buffer is ready. - \sa read(), bufferSize() + \sa read() */ void QAudioDecoder::start() { @@ -267,7 +267,7 @@ void QAudioDecoder::setSourceFilename(const QString &fileName) /*! Returns the current source QIODevice, if one was set. - If \l setSourceFilename was called, this will be 0. + If \l setSourceFilename() was called, this will be 0. */ QIODevice *QAudioDecoder::sourceDevice() const { @@ -299,7 +299,7 @@ void QAudioDecoder::setSourceDevice(QIODevice *device) Any buffers returned should have this format. - \sa setAudioFormat, audioFormatChanged + \sa setAudioFormat(), formatChanged() */ QAudioFormat QAudioDecoder::audioFormat() const { @@ -366,6 +366,8 @@ QtMultimedia::SupportEstimate QAudioDecoder::hasSupport(const QString &mimeType, } /*! + \fn QAudioDecoder::bufferAvailable() const + Returns true if a buffer is available to be read, and false otherwise. If there is no buffer available, calling the \l read() function may block until a buffer is available or @@ -471,7 +473,7 @@ QAudioBuffer QAudioDecoder::read() const Signals that the current audio format of the decoder has changed to \a format. - \sa audioFormat(), setAudioFormat + \sa audioFormat(), setAudioFormat() */ /*! @@ -498,7 +500,7 @@ QAudioBuffer QAudioDecoder::read() const Signals that the decoding has finished successfully. If decoding fails, error signal is emitted instead. - \sa start(), stop(), error + \sa start(), stop(), error() */ /*! @@ -506,7 +508,7 @@ QAudioBuffer QAudioDecoder::read() const Signals that the current \a position of the decoder has changed. - \sa durationChanged + \sa durationChanged() */ /*! @@ -514,7 +516,7 @@ QAudioBuffer QAudioDecoder::read() const Signals that the estimated \a duration of the decoded data has changed. - \sa positionChanged + \sa positionChanged() */ -- cgit v1.2.3