summaryrefslogtreecommitdiffstats
path: root/src/multimedia
diff options
context:
space:
mode:
authorKurt Korbatits <kurt.korbatits@nokia.com>2010-02-23 00:24:22 (GMT)
committerKurt Korbatits <kurt.korbatits@nokia.com>2010-02-23 00:24:22 (GMT)
commitf91f64ee2d0caa86b004bf3653f286116681fa3d (patch)
tree27d0def384d10ec2f7a1b6fc10efc0ab502802b5 /src/multimedia
parentec3dc06b5fbf7ef37e0836992f6d7a3fd49c5891 (diff)
downloadQt-f91f64ee2d0caa86b004bf3653f286116681fa3d.zip
Qt-f91f64ee2d0caa86b004bf3653f286116681fa3d.tar.gz
Qt-f91f64ee2d0caa86b004bf3653f286116681fa3d.tar.bz2
Updates to low-level audio documentation.
Detail state changes and error states in QAudioInput and QAudioOutput documentation. Reviewed-by: Derick Hawcroft
Diffstat (limited to 'src/multimedia')
-rw-r--r--src/multimedia/audio/qaudioinput.cpp74
-rw-r--r--src/multimedia/audio/qaudiooutput.cpp78
2 files changed, 66 insertions, 86 deletions
diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index 45cafc1..fd892dd 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -190,18 +190,18 @@ QAudioInput::~QAudioInput()
Passing a QIODevice allows the data to be transfered without any extra code.
All that is required is to open the QIODevice.
+ If able to successfully get audio data from the systems audio device the
+ state() is set to either QAudio::ActiveState or QAudio::IdleState,
+ error() is set to QAudio::NoError and the stateChanged() signal is emitted.
+
+ If a problem occurs during this process the error() is set to QAudio::OpenError,
+ state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
+
\sa QIODevice
*/
void QAudioInput::start(QIODevice* device)
{
- /*
- -If currently not StoppedState, stop
- -If previous start was push mode, delete internal QIODevice.
- -open audio input.
- If ok, NoError and ActiveState, else OpenError and StoppedState.
- -emit stateChanged()
- */
d->start(device);
}
@@ -210,19 +210,18 @@ void QAudioInput::start(QIODevice* device)
transfer. This QIODevice can be used to read() audio data
directly.
+ If able to access the systems audio device the state() is set to
+ QAudio::IdleState, error() is set to QAudio::NoError
+ and the stateChanged() signal is emitted.
+
+ If a problem occurs during this process the error() is set to QAudio::OpenError,
+ state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
+
\sa QIODevice
*/
QIODevice* QAudioInput::start()
{
- /*
- -If currently not StoppedState, stop
- -If no internal QIODevice, create one.
- -open audio input.
- -If ok, NoError and IdleState, else OpenError and StoppedState
- -emit stateChanged()
- -return internal QIODevice
- */
return d->start(0);
}
@@ -236,17 +235,14 @@ QAudioFormat QAudioInput::format() const
}
/*!
- Stops the audio input.
+ Stops the audio input, detaching from the system resource.
+
+ Sets error() to QAudio::NoError, state() to QAudio::StoppedState and
+ emit stateChanged() signal.
*/
void QAudioInput::stop()
{
- /*
- -If StoppedState, return
- -set to StoppedState
- -detach from audio device
- -emit stateChanged()
- */
d->stop();
}
@@ -256,42 +252,32 @@ void QAudioInput::stop()
void QAudioInput::reset()
{
- /*
- -drop all buffered audio, set buffers to zero.
- -call stop()
- */
d->reset();
}
/*!
Stops processing audio data, preserving buffered audio data.
+
+ Sets error() to QAudio::NoError, state() to QAudio::SuspendedState and
+ emit stateChanged() signal.
*/
void QAudioInput::suspend()
{
- /*
- -If not ActiveState|IdleState, return
- -stop processing audio, saving all buffered audio data
- -set NoError and SuspendedState
- -emit stateChanged()
- */
d->suspend();
}
/*!
Resumes processing audio data after a suspend().
+
+ Sets error() to QAudio::NoError.
+ Sets state() to QAudio::ActiveState if you previously called start(QIODevice*).
+ Sets state() to QAudio::IdleState if you previously called start().
+ emits stateChanged() signal.
*/
void QAudioInput::resume()
{
- /*
- -If SuspendedState, return
- -resume audio
- -(PULL MODE): set ActiveState, NoError
- -(PUSH MODE): set IdleState, NoError
- -kick start audio if needed
- -emit stateChanged()
- */
d->resume();
}
@@ -327,6 +313,9 @@ int QAudioInput::bufferSize() const
/*!
Returns the amount of audio data available to read in bytes.
+
+ NOTE: returned value is only valid while in QAudio::ActiveState or QAudio::IdleState
+ state, otherwise returns zero.
*/
int QAudioInput::bytesReady() const
@@ -352,7 +341,10 @@ int QAudioInput::periodSize() const
/*!
Sets the interval for notify() signal to be emitted.
This is based on the \a ms of audio data processed
- not on actual real-time. The resolution of the timer is platform specific.
+ not on actual real-time.
+ The minimum resolution of the timer is platform specific and values
+ should be checked with notifyInterval() to confirm actual value
+ being used.
*/
void QAudioInput::setNotifyInterval(int ms)
diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp
index afd8a84..b0b5244 100644
--- a/src/multimedia/audio/qaudiooutput.cpp
+++ b/src/multimedia/audio/qaudiooutput.cpp
@@ -202,18 +202,18 @@ QAudioFormat QAudioOutput::format() const
Passing a QIODevice allows the data to be transfered without any extra code.
All that is required is to open the QIODevice.
+ If able to successfully output audio data to the systems audio device the
+ state() is set to QAudio::ActiveState, error() is set to QAudio::NoError
+ and the stateChanged() signal is emitted.
+
+ If a problem occurs during this process the error() is set to QAudio::OpenError,
+ state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
+
\sa QIODevice
*/
void QAudioOutput::start(QIODevice* device)
{
- /*
- -If currently not StoppedState, stop.
- -If previous start was push mode, delete internal QIODevice.
- -open audio output.
- -If ok, NoError and ActiveState, else OpenError and StoppedState
- -emit stateChanged()
- */
d->start(device);
}
@@ -221,34 +221,30 @@ void QAudioOutput::start(QIODevice* device)
Returns a pointer to the QIODevice being used to handle the data
transfer. This QIODevice can be used to write() audio data directly.
+ If able to access the systems audio device the state() is set to
+ QAudio::IdleState, error() is set to QAudio::NoError
+ and the stateChanged() signal is emitted.
+
+ If a problem occurs during this process the error() is set to QAudio::OpenError,
+ state() is set to QAudio::StoppedState and stateChanged() signal is emitted.
+
\sa QIODevice
*/
QIODevice* QAudioOutput::start()
{
- /*
- -If currently not StoppedState, stop.
- -If no internal QIODevice, create one.
- -open audio output.
- -If ok, NoError and IdleState, else OpenError and StoppedState
- -emit stateChanged()
- -return internal QIODevice
- */
return d->start(0);
}
/*!
- Stops the audio output.
+ Stops the audio output, detaching from the system resource.
+
+ Sets error() to QAudio::NoError, state() to QAudio::StoppedState and
+ emit stateChanged() signal.
*/
void QAudioOutput::stop()
{
- /*
- -If StoppedState, return
- -set to StoppedState
- -detach from audio device
- -emit stateChanged()
- */
d->stop();
}
@@ -258,55 +254,44 @@ void QAudioOutput::stop()
void QAudioOutput::reset()
{
- /*
- -drop all buffered audio, set buffers to zero.
- -call stop()
- */
d->reset();
}
/*!
Stops processing audio data, preserving buffered audio data.
+
+ Sets error() to QAudio::NoError, state() to QAudio::SuspendedState and
+ emit stateChanged() signal.
*/
void QAudioOutput::suspend()
{
- /*
- -If not ActiveState|IdleState, return
- -stop processing audio, saving all buffered audio data
- -set NoError and SuspendedState
- -emit stateChanged()
- */
d->suspend();
}
/*!
Resumes processing audio data after a suspend().
+
+ Sets error() to QAudio::NoError.
+ Sets state() to QAudio::ActiveState if you previously called start(QIODevice*).
+ Sets state() to QAudio::IdleState if you previously called start().
+ emits stateChanged() signal.
*/
void QAudioOutput::resume()
{
- /*
- -If SuspendedState, return
- -resume audio
- -(PULL MODE): set ActiveState, NoError
- -(PUSH MODE): set IdleState, NoError
- -kick start audio if needed
- -emit stateChanged()
- */
d->resume();
}
/*!
Returns the free space available in bytes in the audio buffer.
+
+ NOTE: returned value is only valid while in QAudio::ActiveState or QAudio::IdleState
+ state, otherwise returns zero.
*/
int QAudioOutput::bytesFree() const
{
- /*
- -If not ActiveState|IdleState, return 0
- -return space available in audio buffer in bytes
- */
return d->bytesFree();
}
@@ -353,7 +338,10 @@ int QAudioOutput::bufferSize() const
/*!
Sets the interval for notify() signal to be emitted.
This is based on the \a ms of audio data processed
- not on actual real-time. The resolution of the timer is platform specific.
+ not on actual real-time.
+ The minimum resolution of the timer is platform specific and values
+ should be checked with notifyInterval() to confirm actual value
+ being used.
*/
void QAudioOutput::setNotifyInterval(int ms)