From d5f344be4c6f73cca5aab0a3f374a15d999b590c Mon Sep 17 00:00:00 2001 From: Ling Hu Date: Tue, 14 Feb 2012 11:59:13 +1000 Subject: [PATCH] Update audioengine overview doc & reference doc Change-Id: If1061b3dc113f4354d741c536d63cbe36e7a65eb Reviewed-by: Michael Goddard --- doc/src/audioengineoverview.qdoc | 23 +++++++---- .../qdeclarative_attenuationmodel_p.cpp | 16 ++++---- .../qdeclarative_audiocategory_p.cpp | 16 ++++---- .../qdeclarative_audioengine_p.cpp | 24 +++++------ .../qdeclarative_audiolistener_p.cpp | 14 +++---- .../qdeclarative_audiosample_p.cpp | 16 ++++---- .../qdeclarative_playvariation_p.cpp | 14 +++---- .../audioengine/qdeclarative_sound_p.cpp | 40 +++++++++---------- .../qdeclarative_soundinstance_p.cpp | 38 +++++++++--------- 9 files changed, 104 insertions(+), 97 deletions(-) diff --git a/doc/src/audioengineoverview.qdoc b/doc/src/audioengineoverview.qdoc index aa988f49..bc979f6c 100644 --- a/doc/src/audioengineoverview.qdoc +++ b/doc/src/audioengineoverview.qdoc @@ -28,14 +28,21 @@ /*! \page audioengineoverview.html \title QtAudioEngine Overview -\brief 3D Positional Audio +\brief 3D positional audio playback and content management \section1 QtAudioEngine features Qt Multimedia includes the \c QtAudioEngine QML module for -providing 3D positional audio. +providing 3D positional audio playback and content management. -These element can be accessed through importing the +QtAudioEngine enables developers to organize wave files into discrete \l Sound with different +\l {PlayVariation}{play variations}, group sound controls by \l {AudioCategory} categories and +define \l {AttenuationModelLinear}{attenuation models} and various 3d audio settings all in one +place. Playback of \l {SoundInstance}{sound instances} can be conveniently activated by in-app +events and managed by QtAudioEngine or controlled by explicitly defining a \l SoundInstance elment +for easier qml bindings. + +QtAudioEngine elements can be accessed through importing the \bold{QtAudioEngine 1.0} module. \qml @@ -43,7 +50,7 @@ import QtQuick 2.0 import QtAudioEngine 1.0 AudioEngine { -// ... +//... \endqml \section1 Examples @@ -59,12 +66,12 @@ AudioEngine { \o \l AudioEngine \o \l AudioSample \o \l AudioCategory - \o \l Sound - \o \l SoundInstance - \o \l PlayVariation - \o \l AudioListener \o \l AttenuationModelLinear \o \l AttenuationModelInverse + \o \l Sound + \o \l PlayVariation + \o \l AudioListener + \o \l SoundInstance \endlist diff --git a/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp b/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp index 0f359e12..1b7e33e2 100644 --- a/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp +++ b/src/imports/audioengine/qdeclarative_attenuationmodel_p.cpp @@ -94,7 +94,7 @@ void QDeclarativeAttenuationModel::setName(const QString& name) \since 5.0 \brief The AttenuationModelLinear element allows you to define a linear attenuation curve for Sound element. - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary @@ -140,7 +140,7 @@ void QDeclarativeAttenuationModel::setName(const QString& name) */ /*! - \qmlproperty string AttenuationModelLinear::name + \qmlproperty string QtAudioEngine1::AttenuationModelLinear::name This property holds the name of AttenuationModelLinear, must be unique among all attenuation models and only defined once. @@ -162,7 +162,7 @@ void QDeclarativeAttenuationModelLinear::componentComplete() } /*! - \qmlproperty real AttenuationModelLinear::start + \qmlproperty real QtAudioEngine1::AttenuationModelLinear::start This property holds the start distance. There will be no attenuation if the distance from sound to listener is within this range. @@ -187,7 +187,7 @@ void QDeclarativeAttenuationModelLinear::setStartDistance(qreal startDist) } /*! - \qmlproperty real AttenuationModelLinear::end + \qmlproperty real QtAudioEngine1::AttenuationModelLinear::end This property holds the end distance. There will be no sound hearable if the distance from sound to listener is larger than this. @@ -279,14 +279,14 @@ qreal QDeclarativeAttenuationModelLinear::calculateGain(const QVector3D &listene */ /*! - \qmlproperty string AttenuationModelInverse::name + \qmlproperty string QtAudioEngine1::AttenuationModelInverse::name This property holds the name of AttenuationModelInverse, must be unique among all attenuation models and only defined once. */ /*! - \qmlproperty real AttenuationModelInverse::start + \qmlproperty real QtAudioEngine1::AttenuationModelInverse::start This property holds the start distance. There will be no attenuation if the distance from sound to listener is within this range. @@ -294,7 +294,7 @@ qreal QDeclarativeAttenuationModelLinear::calculateGain(const QVector3D &listene */ /*! - \qmlproperty real AttenuationModelInverse::end + \qmlproperty real QtAudioEngine1::AttenuationModelInverse::end This property holds the end distance. There will be no further attenuation if the distance from sound to listener is larger than this. @@ -302,7 +302,7 @@ qreal QDeclarativeAttenuationModelLinear::calculateGain(const QVector3D &listene */ /*! - \qmlproperty real AttenuationModelInverse::rolloff + \qmlproperty real QtAudioEngine1::AttenuationModelInverse::rolloff This property holds the rolloff factor. The bigger the value is, the faster the sound attenuates. The default value is 1. diff --git a/src/imports/audioengine/qdeclarative_audiocategory_p.cpp b/src/imports/audioengine/qdeclarative_audiocategory_p.cpp index 7b56daf5..29a445aa 100644 --- a/src/imports/audioengine/qdeclarative_audiocategory_p.cpp +++ b/src/imports/audioengine/qdeclarative_audiocategory_p.cpp @@ -50,15 +50,15 @@ QT_USE_NAMESPACE \qmlclass AudioCategory QDeclarativeAudioCategory \since 5.0 \brief The AudioCategory element allows you to control all active sound instances by group - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary This element is part of the \bold{QtAudioEngine 1.0} module. - AudioCategory element can be accessed through AudioEngine::categories with its unique name and - must be defined inside AudioEngine. + AudioCategory element can be accessed through QtAudioEngine1::AudioEngine::categories with its + unique name and must be defined inside AudioEngine. \qml import QtQuick 2.0 @@ -137,7 +137,7 @@ void QDeclarativeAudioCategory::componentComplete() } /*! - \qmlproperty real AudioCategory::volume + \qmlproperty real QtAudioEngine1::AudioCategory::volume This property holds the volume of the category and will modulate all audio output from the element which belongs to this category. @@ -159,7 +159,7 @@ void QDeclarativeAudioCategory::setVolume(qreal volume) } /*! - \qmlproperty string AudioCategory::name + \qmlproperty string QtAudioEngine1::AudioCategory::name This property holds the name of AudioCategory. The name must be unique among all categories and only defined once. @@ -179,7 +179,7 @@ QString QDeclarativeAudioCategory::name() const } /*! - \qmlmethod AudioCategory::stop() + \qmlmethod QtAudioEngine1::AudioCategory::stop() Stops all active sound instances which belong to this category. */ @@ -189,7 +189,7 @@ void QDeclarativeAudioCategory::stop() } /*! - \qmlmethod AudioCategory::pause() + \qmlmethod QtAudioEngine1::AudioCategory::pause() Pauses all active sound instances which belong to this category. */ @@ -199,7 +199,7 @@ void QDeclarativeAudioCategory::pause() } /*! - \qmlmethod AudioCategory::pause() + \qmlmethod QtAudioEngine1::AudioCategory::pause() Resumes all active sound instances from paused state which belong to this category. */ diff --git a/src/imports/audioengine/qdeclarative_audioengine_p.cpp b/src/imports/audioengine/qdeclarative_audioengine_p.cpp index 11870d53..1424c690 100644 --- a/src/imports/audioengine/qdeclarative_audioengine_p.cpp +++ b/src/imports/audioengine/qdeclarative_audioengine_p.cpp @@ -59,7 +59,7 @@ QT_USE_NAMESPACE \qmlclass AudioEngine QDeclarativeAudioEngine \since 5.0 \brief The AudioEngine element allows you to organize all your 3d audio content in one place. - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary @@ -194,7 +194,7 @@ void QDeclarativeAudioEngine::releaseManagedDeclarativeSoundInstance(QDeclarativ } /*! - \qmlproperty int AudioEngine::liveInstances + \qmlproperty int QtAudioEngine1::AudioEngine::liveInstances This property indicates how many live sound instances there are at the moment. */ @@ -407,7 +407,7 @@ QDeclarativeListProperty QDeclarativeAudioEngine::bank() } /*! - \qmlproperty map AudioEngine::categories + \qmlproperty map QtAudioEngine1::AudioEngine::categories Container of all AudioCategory elements. */ @@ -417,7 +417,7 @@ QObject* QDeclarativeAudioEngine::categories() } /*! - \qmlproperty map AudioEngine::samples + \qmlproperty map QtAudioEngine1::AudioEngine::samples Container of all AudioSample elements. */ @@ -427,7 +427,7 @@ QObject* QDeclarativeAudioEngine::samples() } /*! - \qmlproperty map AudioEngine::sounds + \qmlproperty map QtAudioEngine1::AudioEngine::sounds Container of all Sound elements. */ @@ -437,7 +437,7 @@ QObject* QDeclarativeAudioEngine::sounds() } /*! - \qmlproperty AudioListener AudioEngine::listener + \qmlproperty QtAudioEngine1::AudioListener QtAudioEngine1::AudioEngine::listener This property holds the listener object. You can change various properties to affect the 3D positioning of sounds. @@ -450,7 +450,7 @@ QDeclarativeAudioListener* QDeclarativeAudioEngine::listener() const } /*! - \qmlproperty real AudioEngine::dopplerFactor + \qmlproperty real QtAudioEngine1::AudioEngine::dopplerFactor This property holds a simple scaling for the effect of doppler shift. */ @@ -465,7 +465,7 @@ void QDeclarativeAudioEngine::setDopplerFactor(qreal dopplerFactor) } /*! - \qmlproperty real AudioEngine::speedOfSound + \qmlproperty real QtAudioEngine1::AudioEngine::speedOfSound This property holds the reference value of the sound speed which will be used in doppler shift calculation. @@ -481,7 +481,7 @@ void QDeclarativeAudioEngine::setSpeedOfSound(qreal speedOfSound) } /*! - \qmlproperty real AudioEngine::loading + \qmlproperty real QtAudioEngine1::AudioEngine::loading This property indicates if the audio engine is loading any audio sample at the moment. This may be useful if you specified the preloaded property in AudioSample and would like to show a loading screen @@ -501,19 +501,19 @@ void QDeclarativeAudioEngine::handleLoadingChanged() } /*! - \qmlsignal AudioEngine::onLiveInstancesChanged() + \qmlsignal QtAudioEngine1::AudioEngine::onLiveInstancesChanged() This handler is called when \l liveInstances is changed */ /*! - \qmlsignal AudioEngine::onLoadingChanged() + \qmlsignal QtAudioEngine1::AudioEngine::onLoadingChanged() This handler is called when \l loading is changed */ /*! - \qmlsignal AudioEngine::finishedLoading() + \qmlsignal QtAudioEngine1::AudioEngine::finishedLoading() This handler is called when \l loading is finished */ diff --git a/src/imports/audioengine/qdeclarative_audiolistener_p.cpp b/src/imports/audioengine/qdeclarative_audiolistener_p.cpp index 274e4891..96fcce25 100644 --- a/src/imports/audioengine/qdeclarative_audiolistener_p.cpp +++ b/src/imports/audioengine/qdeclarative_audiolistener_p.cpp @@ -51,7 +51,7 @@ QT_USE_NAMESPACE \qmlclass AudioListener QDeclarativeAudioListener \since 5.0 \brief The AudioListener element allows you to control global listener parameters. - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary @@ -154,7 +154,7 @@ QDeclarativeAudioListener::~QDeclarativeAudioListener() } /*! - \qmlproperty AudioEngine AudioListener::engine + \qmlproperty QtAudioEngine1::AudioEngine QtAudioEngine1::AudioListener::engine This property holds the reference to AudioEngine, must be set only once. */ @@ -170,7 +170,7 @@ void QDeclarativeAudioListener::setEngine(QDeclarativeAudioEngine *engine) } /*! - \qmlproperty vector3d AudioListener::position + \qmlproperty vector3d QtAudioEngine1::AudioListener::position This property holds the 3d position of the listener. */ @@ -189,7 +189,7 @@ void QDeclarativeAudioListener::setPosition(const QVector3D &position) } /*! - \qmlproperty vector3d AudioListener::direction + \qmlproperty vector3d QtAudioEngine1::AudioListener::direction This property holds the normalized 3d direction vector of the listener. */ @@ -208,7 +208,7 @@ void QDeclarativeAudioListener::setDirection(const QVector3D &direction) } /*! - \qmlproperty vector3d AudioListener::velocity + \qmlproperty vector3d QtAudioEngine1::AudioListener::velocity This property holds the 3d velocity vector of the listener. */ @@ -227,7 +227,7 @@ void QDeclarativeAudioListener::setVelocity(const QVector3D &velocity) } /*! - \qmlproperty vector3d AudioListener::up + \qmlproperty vector3d QtAudioEngine1::AudioListener::up This property holds the normalized 3d up vector of the listener. */ @@ -246,7 +246,7 @@ void QDeclarativeAudioListener::setUp(const QVector3D &up) } /*! - \qmlproperty real AudioListener::gain + \qmlproperty real QtAudioEngine1::AudioListener::gain This property will modulate all audio output from audio engine elements. */ diff --git a/src/imports/audioengine/qdeclarative_audiosample_p.cpp b/src/imports/audioengine/qdeclarative_audiosample_p.cpp index b731b5dc..83c81852 100644 --- a/src/imports/audioengine/qdeclarative_audiosample_p.cpp +++ b/src/imports/audioengine/qdeclarative_audiosample_p.cpp @@ -53,15 +53,15 @@ QT_USE_NAMESPACE \qmlclass AudioSample QDeclarativeAudioSample \since 5.0 \brief The AudioSample element allows you to load audio samples, mostly wav file. - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary This element is part of the \bold{QtAudioEngine 1.0} module. - AudioSample element can be accessed through AudioEngine::samples with its unique name and must - be defined inside AudioEngine. + AudioSample element can be accessed through QtAudioEngine1::AudioEngine::samples with its unique + name and must be defined inside AudioEngine. \qml import QtQuick 2.0 @@ -133,7 +133,7 @@ bool QDeclarativeAudioSample::isStreaming() const } /*! - \qmlproperty bool AudioSample::preloaded + \qmlproperty bool QtAudioEngine1::AudioSample::preloaded This property holds indicates whether this sample needs to be preloaded or not. If true, the audio engine will start loading the sample file immediately when the app started, @@ -146,7 +146,7 @@ bool QDeclarativeAudioSample::isPreloaded() const } /*! - \qmlproperty bool AudioSample::isLoaded + \qmlproperty bool QtAudioEngine1::AudioSample::isLoaded This property holds indicates whether this sample has been loaded into memory or not. */ @@ -158,7 +158,7 @@ bool QDeclarativeAudioSample::isLoaded() const } /*! - \qmlproperty AudioSample::load() + \qmlproperty QtAudioEngine1::AudioSample::load() Starts loading the sample into memory if not loaded. */ @@ -192,7 +192,7 @@ void QDeclarativeAudioSample::setStreaming(bool streaming) } /*! - \qmlproperty string AudioSample::name + \qmlproperty string QtAudioEngine1::AudioSample::name This property holds the name of AudioSample, must be unique among all samples and only defined once. @@ -236,7 +236,7 @@ QSoundBuffer* QDeclarativeAudioSample::soundBuffer() const } /*! - \qmlsignal AudioSample::onLoadedChanged() + \qmlsignal QtAudioEngine1::AudioSample::onLoadedChanged() This handler is called when \l loaded is changed */ diff --git a/src/imports/audioengine/qdeclarative_playvariation_p.cpp b/src/imports/audioengine/qdeclarative_playvariation_p.cpp index 4aab0231..edf2a87e 100644 --- a/src/imports/audioengine/qdeclarative_playvariation_p.cpp +++ b/src/imports/audioengine/qdeclarative_playvariation_p.cpp @@ -55,7 +55,7 @@ QT_USE_NAMESPACE So each time the playback of the same sound can be a slightly different even with the same AudioSample. - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary @@ -142,7 +142,7 @@ void QDeclarativePlayVariation::componentComplete() } /*! - \qmlproperty string PlayVariation::sample + \qmlproperty string QtAudioEngine1::PlayVariation::sample This property specifies which \l AudioSample this variation will use. */ @@ -161,7 +161,7 @@ void QDeclarativePlayVariation::setSample(const QString& sample) } /*! - \qmlproperty bool PlayVariation::looping + \qmlproperty bool QtAudioEngine1::PlayVariation::looping This property indicates whether the playback will be looped or not. */ @@ -180,7 +180,7 @@ void QDeclarativePlayVariation::setLooping(bool looping) } /*! - \qmlproperty real PlayVariation::maxGain + \qmlproperty real QtAudioEngine1::PlayVariation::maxGain This property specifies the maximum gain adjustment that can be applied in any playback. */ @@ -203,7 +203,7 @@ void QDeclarativePlayVariation::setMaxGain(qreal maxGain) } /*! - \qmlproperty real PlayVariation::minGain + \qmlproperty real QtAudioEngine1::PlayVariation::minGain This property specifies the minimum gain adjustment that can be applied in any playback. */ @@ -226,7 +226,7 @@ void QDeclarativePlayVariation::setMinGain(qreal minGain) } /*! - \qmlproperty real PlayVariation::maxPitch + \qmlproperty real QtAudioEngine1::PlayVariation::maxPitch This property specifies the maximum pitch adjustment that can be applied in any playback. */ @@ -249,7 +249,7 @@ void QDeclarativePlayVariation::setMaxPitch(qreal maxPitch) } /*! - \qmlproperty real PlayVariation::minPitch + \qmlproperty real QtAudioEngine1::PlayVariation::minPitch This property specifies the minimum pitch adjustment that can be applied in any playback. */ diff --git a/src/imports/audioengine/qdeclarative_sound_p.cpp b/src/imports/audioengine/qdeclarative_sound_p.cpp index 12d4f84d..81b3ec8e 100644 --- a/src/imports/audioengine/qdeclarative_sound_p.cpp +++ b/src/imports/audioengine/qdeclarative_sound_p.cpp @@ -142,15 +142,15 @@ void QDeclarativeSoundCone::componentComplete() \since 5.0 \brief The Sound element allows you to define a variety of samples and parameters to be used for SoundInstance. - \inmodule QtMultimedia + \inqmlmodule QtAudioEngine 1 \ingroup multimedia_audioengine \inherits Item \preliminary This element is part of the \bold{QtAudioEngine 1.0} module. - Sound element can be accessed through AudioEngine::sounds with its unique name and must be - defined inside AudioEngine. + Sound element can be accessed through QtAudioEngine1::AudioEngine::sounds with its unique name + and must be defined inside AudioEngine. \qml import QtQuick 2.0 @@ -227,7 +227,7 @@ void QDeclarativeSound::componentComplete() } /*! - \qmlproperty enueration Sound::playType + \qmlproperty enueration QtAudioEngine1::Sound::playType This property holds the playType. It can be one of: @@ -253,7 +253,7 @@ void QDeclarativeSound::setPlayType(PlayType playType) } /*! - \qmlproperty string Sound::category + \qmlproperty string QtAudioEngine1::Sound::category This property specifies which AudioCategory this sound belongs to. */ @@ -272,7 +272,7 @@ void QDeclarativeSound::setCategory(const QString& category) } /*! - \qmlproperty string Sound::name + \qmlproperty string QtAudioEngine1::Sound::name This property holds the name of Sound, must be unique among all sounds and only defined once. @@ -292,7 +292,7 @@ void QDeclarativeSound::setName(const QString& name) } /*! - \qmlproperty string Sound::attenuationModel + \qmlproperty string QtAudioEngine1::Sound::attenuationModel This property specifies which attenuation model this sound will apply. */ @@ -381,7 +381,7 @@ void QDeclarativeSound::appendFunction(QDeclarativeListProperty