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 | |
9 | QT_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 | */ |
80 | Q3DSurface::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 | */ |
98 | Q3DSurface::~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 | */ |
109 | void 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 | */ |
119 | void 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 | */ |
129 | QList<QSurface3DSeries *> Q3DSurface::seriesList() const |
130 | { |
131 | return dptrc()->m_shared->surfaceSeriesList(); |
132 | } |
133 | |
134 | Q3DSurfacePrivate *Q3DSurface::dptr() |
135 | { |
136 | return static_cast<Q3DSurfacePrivate *>(d_ptr.data()); |
137 | } |
138 | |
139 | const 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 | */ |
162 | void Q3DSurface::setAxisX(QValue3DAxis *axis) |
163 | { |
164 | dptr()->m_shared->setAxisX(axis); |
165 | } |
166 | |
167 | QValue3DAxis *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 | */ |
190 | void Q3DSurface::setAxisY(QValue3DAxis *axis) |
191 | { |
192 | dptr()->m_shared->setAxisY(axis); |
193 | } |
194 | |
195 | QValue3DAxis *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 | */ |
218 | void Q3DSurface::setAxisZ(QValue3DAxis *axis) |
219 | { |
220 | dptr()->m_shared->setAxisZ(axis); |
221 | } |
222 | |
223 | QValue3DAxis *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 | */ |
236 | QSurface3DSeries *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 | */ |
259 | void Q3DSurface::setFlipHorizontalGrid(bool flip) |
260 | { |
261 | dptr()->m_shared->setFlipHorizontalGrid(flip); |
262 | } |
263 | |
264 | bool 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 | */ |
276 | void 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 | */ |
289 | void 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 | */ |
299 | QList<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 | |
311 | Q3DSurfacePrivate::Q3DSurfacePrivate(Q3DSurface *q) |
312 | : QAbstract3DGraphPrivate(q), |
313 | m_shared(0) |
314 | { |
315 | } |
316 | |
317 | Q3DSurfacePrivate::~Q3DSurfacePrivate() |
318 | { |
319 | } |
320 | |
321 | void Q3DSurfacePrivate::handleAxisXChanged(QAbstract3DAxis *axis) |
322 | { |
323 | emit qptr()->axisXChanged(axis: static_cast<QValue3DAxis *>(axis)); |
324 | } |
325 | |
326 | void Q3DSurfacePrivate::handleAxisYChanged(QAbstract3DAxis *axis) |
327 | { |
328 | emit qptr()->axisYChanged(axis: static_cast<QValue3DAxis *>(axis)); |
329 | } |
330 | |
331 | void Q3DSurfacePrivate::handleAxisZChanged(QAbstract3DAxis *axis) |
332 | { |
333 | emit qptr()->axisZChanged(axis: static_cast<QValue3DAxis *>(axis)); |
334 | } |
335 | |
336 | Q3DSurface *Q3DSurfacePrivate::qptr() |
337 | { |
338 | return static_cast<Q3DSurface *>(q_ptr); |
339 | } |
340 | |
341 | QT_END_NAMESPACE |
342 | |