From 79ac7ce92c9651ce420a427f786f35af97dd8491 Mon Sep 17 00:00:00 2001 From: Miikka Heikkinen Date: Mon, 7 Oct 2013 13:50:23 +0300 Subject: Improve documentation on data handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change-Id: Ie1acb5b12eeb9b59815b7482042edc8adc0250d8 Reviewed-by: Tomi Korpipää --- .../doc/src/qtdatavisualization.qdoc | 76 +++++++++++++++++++++- 1 file changed, 74 insertions(+), 2 deletions(-) (limited to 'src/datavisualization/doc/src/qtdatavisualization.qdoc') diff --git a/src/datavisualization/doc/src/qtdatavisualization.qdoc b/src/datavisualization/doc/src/qtdatavisualization.qdoc index ba158d27..7c4bcd2e 100644 --- a/src/datavisualization/doc/src/qtdatavisualization.qdoc +++ b/src/datavisualization/doc/src/qtdatavisualization.qdoc @@ -98,11 +98,83 @@ \section1 Data proxies - TODO + The data users wish to visualize comes in many formats, all of which cannot obviously be + directly supported. Therefore Qt Data Visualization implements data proxies into which + user can feed their data in a known format. Each visualization type has a basic proxy type, + which takes data in a format suitable for that visualization. + For example, the basic proxy for Q3DBars is QBarDataProxy, which stores rows of QBarDataItem + objects. Each QBarDataItem stores a single bar value. Additional typedefs are provided for + QBarDataArray and QBarDataRow containers. + + This code snipped shows how to use basic proxy when your data is stored in some hypothetical + \c myData object: + + \snippet doc_src_qtdatavisualization.cpp 10 + + \note The graph objects can own more than one data proxy, but only one proxy can be + active at a time. If you need to switch back and forth between two different sets of data, + it may be more efficient to store each set in different proxy and just change the active + proxy, rather than reset the data in one proxy every time you need to switch. \section1 Item models and data mapping - TODO + For common use cases, Qt Data Visualization offers specialized proxies. One such case is having + data in an item model (QAbstractItemModel subclass), which is a common way to store data in + Qt applications. Each of the visualization types offers a special proxy and a corresponding mapping + class for this purpose, e.g. QItemModelBarDataProxy and QItemModelBarDataMapping for Q3DBars. + These proxies are simple to use - just give them a pointer to the item model containing the + data and the mapping object containing rules how to map the data into format the basic proxy can + digest. + + Mapping objects work with item model roles. Each data item in the model can have different + values for different roles. For example, with QItemModelBarDataMapping you can specify which + role is used to determine which row the item belongs to, which role does the same for columns, + and which role specifies the value of the item. When the proxy resolves the data from the model, + it uses these mappings to generate the rows and columns of the bar graph. + + Depending on the visualization type, mapping classes may support other functionality as well, + such as QItemModelBarDataMapping optionally mapping QAbstractItemModel rows and columns directly + into bar graph rows and columns. See individual mapping classes for more information and examples + how to use them: QItemModelBarDataMapping, QItemModelScatterDataMapping, and + QItemModelSurfaceDataMapping. + + \section1 Other custom proxies + + QHeightMapSurfaceDataProxy is a specialized proxy for generating a surface graph from a + heightmap image. See QHeightMapSurfaceDataProxy documentation for more information. + + The \l{Rainfall Example}{Rainfall} example shows how a custom proxy can be created. It defines + a custom data set based on variant lists and an extension of the basic proxy to resolve that + data with an associated mapper. + + \section1 Dealing with real-time data + + When you have a data set that updates rapidly, it is important to handle data properly to + ensure good performance. Since memory allocation is a costly operation, always use + QList::reserve() and QVector::resize() where possible to avoid reallocations when constructing + the array to give to the proxy. If you need to change the entire data set for each frame, + it is in most cases best to re-use the existing array - especially if the array dimensions do not + change. If you need to add, insert, remove, or change several rows or items for each frame, it + is always more efficient to do it with one method call instead of multiple calls affecting + a single row or item each. For example, adding ten rows with a single QBarDataProxy::addRows() call + is much more efficient than ten separate QBarDataProxy::addRow() calls. + + Bars renderer is optimized to access only data that is within data window and thus should not + suffer noticeable slowdown even if more data is continually added to the proxy. + + Due to the unsorted nature of the scatter data, any change in the data window ranges requires + all data points to be checked for visibility, which can cause increasing slowdown if data is + continually added to the proxy. + + Surface data, while on item level similar to scatter data, is already assigned into rows and + columns, so the surface renderer can do some optimization by making assumption that the data in + rows and columns is sorted along their respective axes, but it is nowhere near as efficient + as in bars case. Surface rendering can suffer significant slowdown if the data size grows unchecked. + + For the best performance with the scatter and surface graphs, only keep the data you need in the + proxy. + + \note Data handling is not yet fully optimized in the technology preview version. */ /*! -- cgit v1.2.3