1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only
3
4#undef QT_NO_FOREACH // this file contains unported legacy Q_FOREACH uses
5
6#include "q3dsurface.h"
7#include "q3dsurface_p.h"
8
9QT_BEGIN_NAMESPACE
10
11/*!
12 * \class Q3DSurface
13 * \inmodule QtDataVisualization
14 * \brief The Q3DSurface class provides methods for rendering 3D surface plots.
15 * \since QtDataVisualization 1.0
16 *
17 * This class enables developers to render 3D surface plots and to view them by rotating the scene
18 * freely. The visual properties of the surface such as draw mode and shading can be controlled
19 * via QSurface3DSeries.
20 *
21 * The Q3DSurface supports selection by showing a highlighted ball on the data point where the user has clicked
22 * with left mouse button (when default input handler is in use) or selected via QSurface3DSeries.
23 * The selection pointer is accompanied with a label which in default case shows the value of the
24 * data point and the coordinates of the point.
25 *
26 * The value range and the label format shown on the axis can be controlled through QValue3DAxis.
27 *
28 * To rotate the graph, hold down the right mouse button and move the mouse. Zooming is done using mouse
29 * wheel. Both assume the default input handler is in use.
30 *
31 * If no axes are set explicitly to Q3DSurface, temporary default axes with no labels are created.
32 * These default axes can be modified via axis accessors, but as soon any axis is set explicitly
33 * for the orientation, the default axis for that orientation is destroyed.
34 *
35 * \section1 How to construct a minimal Q3DSurface graph
36 *
37 * First, construct Q3DSurface. Since we are running the graph as top level window
38 * in this example, we need to clear the \c Qt::FramelessWindowHint flag, which gets set by
39 * default:
40 *
41 * \snippet doc_src_q3dsurface_construction.cpp 0
42 *
43 * Now Q3DSurface is ready to receive data to be rendered. Create data elements to receive values:
44 *
45 * \snippet doc_src_q3dsurface_construction.cpp 1
46 *
47 * First feed the data to the row elements and then add their pointers to the data element:
48 *
49 * \snippet doc_src_q3dsurface_construction.cpp 2
50 *
51 * Create a new series and set data to it:
52 *
53 * \snippet doc_src_q3dsurface_construction.cpp 3
54 *
55 * Finally you will need to set it visible:
56 *
57 * \snippet doc_src_q3dsurface_construction.cpp 4
58 *
59 * The complete code needed to create and display this graph is:
60 *
61 * \snippet doc_src_q3dsurface_construction.cpp 5
62 *
63 * And this is what those few lines of code produce:
64 *
65 * \image q3dsurface-minimal.png
66 *
67 * The scene can be rotated, zoomed into, and a surface point can be selected to view its position,
68 * but no other interaction is included in this minimal code example.
69 * You can learn more by familiarizing yourself with the examples provided,
70 * like the \l{Surface Graph}.
71 *
72 *
73 * \sa Q3DBars, Q3DScatter, {Qt Data Visualization C++ Classes}
74 */
75
76/*!
77 * Constructs a new 3D surface graph with optional \a parent window
78 * and surface \a format.
79 */
80Q3DSurface::Q3DSurface(const QSurfaceFormat *format, QWindow *parent)
81 : QAbstract3DGraph(new Q3DSurfacePrivate(this), format, parent)
82{
83 if (!dptr()->m_initialized)
84 return;
85
86 dptr()->m_shared = new Surface3DController(geometry());
87 d_ptr->setVisualController(dptr()->m_shared);
88 dptr()->m_shared->initializeOpenGL();
89 QObject::connect(sender: dptr()->m_shared, signal: &Surface3DController::selectedSeriesChanged,
90 context: this, slot: &Q3DSurface::selectedSeriesChanged);
91 QObject::connect(sender: dptr()->m_shared, signal: &Surface3DController::flipHorizontalGridChanged,
92 context: this, slot: &Q3DSurface::flipHorizontalGridChanged);
93}
94
95/*!
96 * Destroys the 3D surface graph.
97 */
98Q3DSurface::~Q3DSurface()
99{
100}
101
102/*!
103 * Adds the \a series to the graph. A graph can contain multiple series, but has only one set of
104 * axes. If the newly added series has specified a selected item, it will be highlighted and
105 * any existing selection will be cleared. Only one added series can have an active selection.
106 *
107 * \sa QAbstract3DGraph::hasSeries()
108 */
109void Q3DSurface::addSeries(QSurface3DSeries *series)
110{
111 dptr()->m_shared->addSeries(series);
112}
113
114/*!
115 * Removes the \a series from the graph.
116 *
117 * \sa QAbstract3DGraph::hasSeries()
118 */
119void Q3DSurface::removeSeries(QSurface3DSeries *series)
120{
121 dptr()->m_shared->removeSeries(series);
122}
123
124/*!
125 * Returns the list of series added to this graph.
126 *
127 * \sa QAbstract3DGraph::hasSeries()
128 */
129QList<QSurface3DSeries *> Q3DSurface::seriesList() const
130{
131 return dptrc()->m_shared->surfaceSeriesList();
132}
133
134Q3DSurfacePrivate *Q3DSurface::dptr()
135{
136 return static_cast<Q3DSurfacePrivate *>(d_ptr.data());
137}
138
139const Q3DSurfacePrivate *Q3DSurface::dptrc() const
140{
141 return static_cast<const Q3DSurfacePrivate *>(d_ptr.data());
142}
143
144/*!
145 * \property Q3DSurface::axisX
146 *
147 * \brief The active x-axis.
148 */
149
150/*!
151 * Sets \a axis as the active x-axis. Implicitly calls addAxis() to transfer the
152 * ownership of the axis to this graph.
153 *
154 * If \a axis is null, a temporary default axis with no labels and an
155 * automatically adjusting range is created.
156 *
157 * This temporary axis is destroyed if another axis is set explicitly to the
158 * same orientation.
159 *
160 * \sa addAxis(), releaseAxis()
161 */
162void Q3DSurface::setAxisX(QValue3DAxis *axis)
163{
164 dptr()->m_shared->setAxisX(axis);
165}
166
167QValue3DAxis *Q3DSurface::axisX() const
168{
169 return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisX());
170}
171
172/*!
173 * \property Q3DSurface::axisY
174 *
175 * \brief The active y-axis.
176 */
177
178/*!
179 * Sets \a axis as the active y-axis. Implicitly calls addAxis() to transfer the
180 * ownership of the axis to this graph.
181 *
182 * If \a axis is null, a temporary default axis with no labels and an
183 * automatically adjusting range is created.
184 *
185 * This temporary axis is destroyed if another axis is set explicitly to the
186 * same orientation.
187 *
188 * \sa addAxis(), releaseAxis()
189 */
190void Q3DSurface::setAxisY(QValue3DAxis *axis)
191{
192 dptr()->m_shared->setAxisY(axis);
193}
194
195QValue3DAxis *Q3DSurface::axisY() const
196{
197 return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisY());
198}
199
200/*!
201 * \property Q3DSurface::axisZ
202 *
203 * \brief The active z-axis.
204 */
205
206/*!
207 * Sets \a axis as the active z-axis. Implicitly calls addAxis() to transfer the
208 * ownership of the axis to this graph.
209 *
210 * If \a axis is null, a temporary default axis with no labels and an
211 * automatically adjusting range is created.
212 *
213 * This temporary axis is destroyed if another axis is set explicitly to the
214 * same orientation.
215 *
216 * \sa addAxis(), releaseAxis()
217 */
218void Q3DSurface::setAxisZ(QValue3DAxis *axis)
219{
220 dptr()->m_shared->setAxisZ(axis);
221}
222
223QValue3DAxis *Q3DSurface::axisZ() const
224{
225 return static_cast<QValue3DAxis *>(dptrc()->m_shared->axisZ());
226}
227
228/*!
229 * \property Q3DSurface::selectedSeries
230 *
231 * \brief The selected series or null.
232 *
233 * If selectionMode has \c SelectionMultiSeries set, this
234 * property holds the series which owns the selected point.
235 */
236QSurface3DSeries *Q3DSurface::selectedSeries() const
237{
238 return dptrc()->m_shared->selectedSeries();
239}
240
241/*!
242 * \property Q3DSurface::flipHorizontalGrid
243 * \since QtDataVisualization 1.2
244 *
245 * \brief Whether the horizontal axis grid is displayed on top of the graph
246 * rather than on the bottom.
247 *
248 * In some use cases the horizontal axis grid is mostly covered by the surface, so it can be more
249 * useful to display the horizontal axis grid on top of the graph rather than on the bottom.
250 * A typical use case for this is showing 2D spectrograms using orthoGraphic projection with
251 * a top-down viewpoint.
252 *
253 * If \c{false}, the horizontal axis grid and labels are drawn on the horizontal background
254 * of the graph.
255 * If \c{true}, the horizontal axis grid and labels are drawn on the opposite side of the graph
256 * from the horizontal background.
257 * Defaults to \c{false}.
258 */
259void Q3DSurface::setFlipHorizontalGrid(bool flip)
260{
261 dptr()->m_shared->setFlipHorizontalGrid(flip);
262}
263
264bool Q3DSurface::flipHorizontalGrid() const
265{
266 return dptrc()->m_shared->flipHorizontalGrid();
267}
268
269/*!
270 * Adds \a axis to the graph. The axes added via addAxis are not yet taken to use,
271 * addAxis is simply used to give the ownership of the \a axis to the graph.
272 * The \a axis must not be null or added to another graph.
273 *
274 * \sa releaseAxis(), setAxisX(), setAxisY(), setAxisZ()
275 */
276void Q3DSurface::addAxis(QValue3DAxis *axis)
277{
278 dptr()->m_shared->addAxis(axis);
279}
280
281/*!
282 * Releases the ownership of the \a axis back to the caller, if it is added to this graph.
283 * If the released \a axis is in use, a new default axis will be created and set active.
284 *
285 * If the default axis is released and added back later, it behaves as any other axis would.
286 *
287 * \sa addAxis(), setAxisX(), setAxisY(), setAxisZ()
288 */
289void Q3DSurface::releaseAxis(QValue3DAxis *axis)
290{
291 dptr()->m_shared->releaseAxis(axis);
292}
293
294/*!
295 * Returns the list of all added axes.
296 *
297 * \sa addAxis()
298 */
299QList<QValue3DAxis *> Q3DSurface::axes() const
300{
301 QList<QAbstract3DAxis *> abstractAxes = dptrc()->m_shared->axes();
302 QList<QValue3DAxis *> retList;
303 foreach (QAbstract3DAxis *axis, abstractAxes)
304 retList.append(t: static_cast<QValue3DAxis *>(axis));
305
306 return retList;
307}
308
309// Q3DSurfacePrivate
310
311Q3DSurfacePrivate::Q3DSurfacePrivate(Q3DSurface *q)
312 : QAbstract3DGraphPrivate(q),
313 m_shared(0)
314{
315}
316
317Q3DSurfacePrivate::~Q3DSurfacePrivate()
318{
319}
320
321void Q3DSurfacePrivate::handleAxisXChanged(QAbstract3DAxis *axis)
322{
323 emit qptr()->axisXChanged(axis: static_cast<QValue3DAxis *>(axis));
324}
325
326void Q3DSurfacePrivate::handleAxisYChanged(QAbstract3DAxis *axis)
327{
328 emit qptr()->axisYChanged(axis: static_cast<QValue3DAxis *>(axis));
329}
330
331void Q3DSurfacePrivate::handleAxisZChanged(QAbstract3DAxis *axis)
332{
333 emit qptr()->axisZChanged(axis: static_cast<QValue3DAxis *>(axis));
334}
335
336Q3DSurface *Q3DSurfacePrivate::qptr()
337{
338 return static_cast<Q3DSurface *>(q_ptr);
339}
340
341QT_END_NAMESPACE
342

source code of qtdatavis3d/src/datavisualization/engine/q3dsurface.cpp