8 files changed, 412 insertions, 0 deletions
diff --git a/examples/audiolevels/audiolevels.cpp b/examples/audiolevels/audiolevels.cpp
new file mode 100644
index 00000000..e1788936
--- /dev/null
+++ b/examples/audiolevels/audiolevels.cpp
@@ -0,0 +1,78 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#include "audiolevelsiodevice.h"
+#include "audiolevels.h"
+
+#include <QtDataVisualization/qbardataproxy.h>
+#include <QtDataVisualization/q3dvalueaxis.h>
+#include <QtDataVisualization/q3dscene.h>
+#include <QtDataVisualization/q3dcamera.h>
+
+#include <QAudioDeviceInfo>
+#include <QAudioInput>
+
+QT_DATAVISUALIZATION_USE_NAMESPACE
+
+AudioLevels::AudioLevels(Q3DBars *graph, QObject *parent)
+    : QObject(parent),
+      m_graph(graph),
+      m_device(0),
+      m_audioInput(0)
+{
+    // Set up the graph
+    m_graph->setBarThickness(0.5);
+    m_graph->setBarSpacing(QSizeF(0.0, 1.0));
+    m_graph->setGridVisible(false);
+    m_graph->setBackgroundVisible(false);
+    m_graph->valueAxis()->setRange(0.0, 2.0);
+    m_graph->setShadowQuality(QDataVis::ShadowQualityNone);
+    m_graph->scene()->activeCamera()->setCameraPosition(-20.0, 10.0, 20);
+    m_graph->setTheme(QDataVis::ThemeIsabelle);
+    m_graph->setBarType(QDataVis::MeshStyleBars);
+
+    //! [0]
+    QAudioFormat formatAudio;
+    formatAudio.setSampleRate(8000);
+    formatAudio.setChannelCount(1);
+    formatAudio.setSampleSize(8);
+    formatAudio.setCodec("audio/pcm");
+    formatAudio.setByteOrder(QAudioFormat::LittleEndian);
+    formatAudio.setSampleType(QAudioFormat::UnSignedInt);
+
+    QAudioDeviceInfo inputDevices = QAudioDeviceInfo::defaultInputDevice();
+    m_audioInput = new QAudioInput(inputDevices, formatAudio, this);
+#ifdef Q_OS_MAC
+    // Mac seems to wait for entire buffer to fill before calling writeData, so use smaller buffer
+    m_audioInput->setBufferSize(256);
+#else
+    m_audioInput->setBufferSize(1024);
+#endif
+
+    m_device = new AudioLevelsIODevice(m_graph->activeDataProxy(), this);
+    m_device->open(QIODevice::WriteOnly);
+
+    m_audioInput->start(m_device);
+    //! [0]
+}
+
+AudioLevels::~AudioLevels()
+{
+    m_audioInput->stop();
+    m_device->close();
+}
diff --git a/examples/audiolevels/audiolevels.h b/examples/audiolevels/audiolevels.h
new file mode 100644
index 00000000..db1d8936
--- /dev/null
+++ b/examples/audiolevels/audiolevels.h
@@ -0,0 +1,45 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#ifndef AUDIOLEVELS_H
+#define AUDIOLEVELS_H
+
+#include <QtDataVisualization/q3dbars.h>
+
+QT_DATAVISUALIZATION_USE_NAMESPACE
+
+class AudioLevelsIODevice;
+class QAudioInput;
+
+class AudioLevels : public QObject
+{
+    Q_OBJECT
+
+public:
+    AudioLevels(Q3DBars *graph, QObject *parent = 0);
+    ~AudioLevels();
+
+private:
+    //! [0]
+    Q3DBars *m_graph;
+    AudioLevelsIODevice *m_device;
+    QAudioInput *m_audioInput;
+    //! [0]
+};
+
+#endif
diff --git a/examples/audiolevels/audiolevels.pro b/examples/audiolevels/audiolevels.pro
new file mode 100644
index 00000000..7df4379b
--- /dev/null
+++ b/examples/audiolevels/audiolevels.pro
@@ -0,0 +1,20 @@
+!include( ../examples.pri ) {
+    error( "Couldn't find the examples.pri file!" )
+}
+
+TARGET = audiolevels
+
+QT += multimedia
+
+SOURCES += main.cpp \
+           audiolevels.cpp \
+           audiolevelsiodevice.cpp
+
+HEADERS += audiolevels.h \
+           audiolevelsiodevice.h
+
+INSTALLS += target
+
+OTHER_FILES += doc/src/* \
+               doc/images/*
+
diff --git a/examples/audiolevels/audiolevelsiodevice.cpp b/examples/audiolevels/audiolevelsiodevice.cpp
new file mode 100644
index 00000000..11cba5aa
--- /dev/null
+++ b/examples/audiolevels/audiolevelsiodevice.cpp
@@ -0,0 +1,102 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#include "audiolevelsiodevice.h"
+#include <QDebug>
+
+QT_DATAVISUALIZATION_USE_NAMESPACE
+
+//! [1]
+static const int resolution = 8;
+static const int rowSize = 800;
+static const int rowCount = 7; // Must be odd number
+static const int middleRow = rowCount / 2;
+//! [1]
+
+AudioLevelsIODevice::AudioLevelsIODevice(QBarDataProxy *proxy, QObject *parent)
+    : QIODevice(parent),
+      m_proxy(proxy),
+      m_array(new QBarDataArray)
+{
+    // We reuse the existing array for maximum performance, so construct the array here
+    //! [0]
+    m_array->reserve(rowCount);
+    for (int i = 0; i < rowCount; i++)
+        m_array->append(new QBarDataRow(rowSize));
+    //! [0]
+
+    qDebug() << "Total of" << (rowSize * rowCount) << "items in the array.";
+}
+
+// Implementation required for this pure virtual function
+qint64 AudioLevelsIODevice::readData(char *data, qint64 maxSize)
+{
+    Q_UNUSED(data)
+    Q_UNUSED(maxSize)
+    return -1;
+}
+
+//! [2]
+qint64 AudioLevelsIODevice::writeData(const char *data, qint64 maxSize)
+{
+    // The amount of new data available.
+    int newDataSize = maxSize / resolution;
+
+    // If we get more data than array size, we need to adjust the start index for new data.
+    int newDataStartIndex = qMax(0, (newDataSize - rowSize));
+
+    // Move the old data ahead in the rows (only do first half of rows + middle one now).
+    // If the amount of new data was larger than row size, skip copying.
+    if (!newDataStartIndex) {
+        for (int i = 0; i <= middleRow; i++) {
+            QBarDataItem *srcPos = m_array->at(i)->data();
+            QBarDataItem *dstPos = srcPos + newDataSize;
+            memmove(dstPos, srcPos, (rowSize - newDataSize) * sizeof(QBarDataItem));
+        }
+    }
+
+    // Insert data in reverse order, so that newest data is always at the front of the row.
+    int index = 0;
+    for (int i = newDataSize - 1; i >= newDataStartIndex; i--) {
+        // Add 0.01 to the value to avoid gaps in the graph (i.e. zero height bars).
+        qreal value = qreal(quint8(data[resolution * i]) - 128) / 2.0 + 0.01;
+        (*m_array->at(middleRow))[index].setValue(value);
+        // Insert a fractional value into front half of the rows.
+        for (int j = 1; j <= middleRow; j++) {
+            qreal fractionalValue = value / qreal(j + 1);
+            (*m_array->at(middleRow - j))[index].setValue(fractionalValue);
+        }
+        index++;
+    }
+
+    // Copy the front half of rows to the back half for symmetry.
+    index = 0;
+    for (int i = rowCount - 1; i > middleRow; i--) {
+        QBarDataItem *srcPos = m_array->at(index++)->data();
+        QBarDataItem *dstPos = m_array->at(i)->data();
+        memcpy(dstPos, srcPos, rowSize * sizeof(QBarDataItem));
+    }
+
+    // Reset the proxy array now that data has been updated to trigger a redraw.
+    m_proxy->resetArray(m_array);
+
+    return maxSize;
+}
+//! [2]
+
+
diff --git a/examples/audiolevels/audiolevelsiodevice.h b/examples/audiolevels/audiolevelsiodevice.h
new file mode 100644
index 00000000..8d665fe8
--- /dev/null
+++ b/examples/audiolevels/audiolevelsiodevice.h
@@ -0,0 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#ifndef AUDIOLEVELSIODEVICE_H
+#define AUDIOLEVELSIODEVICE_H
+
+#include <QtDataVisualization/qbardataproxy.h>
+#include <QIODevice>
+
+QT_DATAVISUALIZATION_USE_NAMESPACE
+
+class AudioLevelsIODevice : public QIODevice
+{
+    Q_OBJECT
+public:
+    explicit AudioLevelsIODevice(QBarDataProxy *proxy, QObject *parent = 0);
+
+protected:
+    qint64 readData(char *data, qint64 maxSize);
+    qint64 writeData(const char *data, qint64 maxSize);
+
+private:
+    //! [0]
+    QBarDataProxy *m_proxy;
+    QBarDataArray *m_array;
+    //! [0]
+};
+
+#endif
diff --git a/examples/audiolevels/doc/images/audiolevels-example.png b/examples/audiolevels/doc/images/audiolevels-example.png
new file mode 100644
index 00000000..47c982d9
--- /dev/null
+++ b/examples/audiolevels/doc/images/audiolevels-example.png
diff --git a/examples/audiolevels/doc/src/audiolevels.qdoc b/examples/audiolevels/doc/src/audiolevels.qdoc
new file mode 100644
index 00000000..3d392487
--- /dev/null
+++ b/examples/audiolevels/doc/src/audiolevels.qdoc
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+/*!
+    \example audiolevels
+    \title Audiolevels Example
+    \ingroup qtdatavisualization_examples
+    \brief Simple application showing real time audio data.
+
+    The audiolevels example shows how feed real-time dynamic data to a graph using Q3DBars.
+
+    This example reads the audio levels from a microphone and displays those levels
+    in a bar graph. To increase the load for demonstration purposes, and to make the
+    graph little fancier, slightly modified data is used to fill multiple rows.
+
+    \image audiolevels-example.png
+
+    The interesting stuff happens in AudioLevels and AudioLevelsIODevice classes, so we
+    concentrate on those and skip explaining the basic Q3DBars functionality - for that see
+    \l{Bars Example}.
+
+    AudioLevelsIODevice subclasses QIODevice and is given as input device for QAudioInput
+    class, so it receives microphone data.
+
+    In the header file for QAudioInput class we declare necessary members:
+
+    \snippet ../examples/audiolevels/audiolevels.h 0
+
+    And initialize the microphone listening in the source:
+
+    \snippet ../examples/audiolevels/audiolevels.cpp 0
+
+    In the header file for AudioLevelsIODevice class we store pointers to the data proxy and
+    also the data array we give to the proxy, because we reuse the same array to keep memory
+    reallocations to the minimum:
+
+    \snippet ../examples/audiolevels/audiolevelsiodevice.h 0
+
+    In the source file we define some static constants to define size of the data array and
+    the middle row index, as well as the resolution of the visualization. You may need to adjust
+    these values to get decent performance in low-end devices:
+
+    \snippet ../examples/audiolevels/audiolevelsiodevice.cpp 1
+
+    The \c resolution constant indicates the sample rate, e.g. value 8 means every eighth
+    byte from audio input is visualized. This is necessary to make the data readable, as it would
+    otherwise make the graph scroll too fast.
+
+    In the AudioLevelsIODevice class constructor we initialize the data array:
+
+    \snippet ../examples/audiolevels/audiolevelsiodevice.cpp 0
+
+    The AudioLevelsIODevice::writeData function is called whenever there is new audio data
+    available to be visualized. There we move the old data along the rows and insert new
+    data in the beginning of the rows:
+
+    \snippet ../examples/audiolevels/audiolevelsiodevice.cpp 2
+
+    We use a couple of techniques here to improve performance. First off, we reuse
+    the existing data array, as this allows us to avoid any extra memory allocations in our
+    application code. This also means the data array dimensions do not change, which further
+    improves efficiency in the bar graph renderer.
+    Secondly, since the rows are QVectors of QBarDataItems, which do not allocate any data that needs
+    deletion, we can utilize memmove and memcpy functions to quickly move and copy data around.
+
+    \note In the future versions of Qt Data Visualization, QBarDataItem might get extended so that
+    it does allocate some memory to store other optional bar properties besides the value.
+    In use cases where those optional properties are used, using memmove and memcpy would lead to
+    memory leaks, so use them with care.
+*/
diff --git a/examples/audiolevels/main.cpp b/examples/audiolevels/main.cpp
new file mode 100644
index 00000000..9d16610c
--- /dev/null
+++ b/examples/audiolevels/main.cpp
@@ -0,0 +1,38 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc
+** All rights reserved.
+** For any questions to Digia, please use contact form at http://qt.digia.com
+**
+** This file is part of the QtDataVisualization module.
+**
+** Licensees holding valid Qt Enterprise licenses may use this file in
+** accordance with the Qt Enterprise License Agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.
+**
+** If you have questions regarding the use of this file, please use
+** contact form at http://qt.digia.com
+**
+****************************************************************************/
+
+#include "audiolevels.h"
+
+#include <QGuiApplication>
+#include <QAudio>
+
+using namespace QtDataVisualization;
+
+int main(int argc, char *argv[])
+{
+    QGuiApplication app(argc, argv);
+
+    Q3DBars window;
+    window.resize(1024, 768);
+    window.setTitle("Qt Data Visualization - Microphone audio levels visualizer");
+    window.show();
+
+    AudioLevels audioLevels(&window);
+
+    return app.exec();
+}