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

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