Moved doc under src to fall in-line with the new modular structure

Change-Id: Ia2933baa1f0eaf82b5c2a626cb3661ee087049e3
Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>

1 files changed, 153 insertions, 0 deletions

diff --git a/src/multimedia/doc/src/audiooverview.qdoc b/src/multimedia/doc/src/audiooverview.qdoc
new file mode 100644
index 000000000..916174d8c
--- /dev/null
+++ b/src/multimedia/doc/src/audiooverview.qdoc
@@ -0,0 +1,153 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page audiooverview.html
+\title Audio Overview
+\brief Audio playback, recording and processing
+
+\section1 Audio Features
+
+Qt Multimedia offers a range of audio classes, covering both low and
+high level approaches to audio input, output and processing.  In
+addition to traditional audio usage, the \l {Positional Audio}{Qt AudioEngine}
+QML types offer high level 3D positional audio for QML applications.
+See that documentation for more information.
+
+\section1 Audio Implementation Details
+
+\section2 Playing Compressed Audio
+For playing media or audio files that are not simple, uncompressed audio, you can
+use the \l QMediaPlayer C++ class, or the \l {Audio} and \l {MediaPlayer} QML types.
+The QMediaPlayer class and associated QML types are also capable of playing
+\l{multimedia-playing-video}{video}, if required.  The compressed audio formats supported does depend
+on the operating system environment, and also what media plugins the user
+may have installed.
+
+Here is how you play a local file using C++:
+
+    \snippet doc/src/snippets/multimedia-snippets/media.cpp Local playback
+
+You can also put files (even remote URLs) into a playlist:
+    \snippet doc/src/snippets/multimedia-snippets/media.cpp Audio playlist
+
+\section2 Recording Audio to a File
+For recording audio to a file, the \l {QAudioRecorder} class allows you
+to compress audio data from an input device and record it.
+
+    \snippet doc/src/snippets/multimedia-snippets/media.cpp Audio recorder
+
+\section2 Low Latency Sound Effects
+
+In addition to the raw access to sound devices described above, the QSoundEffect class (and
+\l {SoundEffect} QML type) offers a slightly higher level way to play
+sounds.  These classes allow you to specify a WAV format file which can
+then be played with low latency when necessary.  Both QSoundEffect and
+SoundEffect have essentially the same API.
+
+You can adjust the number of \l {QSoundEffect::loopCount()}{loops} a sound effect is played, as well as
+the \l {QSoundEffect::setVolume()}{volume} (or \l {QSoundEffect::setMuted()}{muting}) of the effect.
+
+For older, Qt 4.x based applications \l QSound is also available.  Applications
+are recommended to use QSoundEffect where possible.
+
+\section2 Monitoring Audio Data During Playback or Recording
+
+The \l QAudioProbe class allows you to monitor audio data being played or
+recorded in the higher level classes like \l QMediaPlayer, \l QCamera and
+\l QAudioRecorder.  After creating your high level class, you can simply
+set the source of the probe to your class, and receive audio buffers as they
+are processed.  This is useful for several audio processing tasks, particularly
+for visualization or adjusting gain.  You cannot modify the buffers, and
+they may arrive at a slightly different time than the media pipeline
+processes them.
+
+Here's an example of installing a probe during recording:
+    \snippet doc/src/snippets/multimedia-snippets/media.cpp Audio probe
+
+\section2 Low Level Audio Playback and Recording
+Qt Multimedia offers classes for raw access to audio input and output
+facilities, allowing applications to receive raw data from devices like
+microphones, and to write raw data to speakers or other devices.  Generally
+these classes do not do any audio decoding, or other processing, but they
+can support different types of raw audio data.
+
+The QAudioOutput class offers raw audio data output, while QAudioInput
+offers raw audio data input.  Both classes have adjustable buffers and
+latency, so they are suitable for both low latency use cases (like games
+or VOIP) and high latency (like music playback).  The available hardware
+determines what audio outputs and inputs are available.
+
+\section3 Push and Pull
+The low level audio classes can operate in two modes - \c push and \c pull.
+In \c pull mode, the audio device is started by giving it a QIODevice.  For
+an output device, the QAudioOutput class will pull data from the QIODevice
+(using \l QIODevice::read()) when more audio data is required.  Conversely,
+for \c pull mode with QAudioInput, when audio data is available then the
+data will be written directly to the QIODevice.
+
+In \c push mode, the audio device provides a QIODevice instance that
+can be written or read to as needed.  Typically this results in simpler
+code but more buffering, which may affect latency.
+
+\section2 Decoding Compressed Audio to Memory
+In some cases you may want to decode a compressed audio file and do further
+processing yourself (like mix multiple samples, or some custom digital signal
+processing algorithms).  Qt Multimedia 5.0 offers a preliminary API for this
+case - the \l QAudioDecoder class.  QAudioDecoder supports decoding local files
+or from a QIODevice instances.
+
+Here's an example of decoding a local file:
+
+    \snippet doc/src/snippets/multimedia-snippets/audio.cpp Local audio decoding
+
+Note:  This API is preliminary at this time - the API may change or be
+removed before the final 5.0 release.
+
+\section1 Examples
+
+There are both C++ and QML examples available.
+
+\section2 C++ Examples
+
+\annotatedlist audio_examples
+
+\section2 QML Examples
+
+[TBD]
+
+\section1 Reference Documentation
+
+\section2 C++ Classes
+
+\annotatedlist multimedia_audio
+
+\section2 QML Types
+
+\annotatedlist multimedia_audio_qml
+
+*/