1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtSensors module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qrotationsensor.h"
41#include "qrotationsensor_p.h"
42
43QT_BEGIN_NAMESPACE
44
45IMPLEMENT_READING(QRotationReading)
46
47/*!
48 \class QRotationReading
49 \ingroup sensors_reading
50 \inmodule QtSensors
51 \since 5.1
52
53 \brief The QRotationReading class represents one reading from the
54 rotation sensor.
55
56 \section2 QRotationReading Units
57
58 The rotation reading contains 3 angles, measured in degrees that define
59 the orientation of the device in three-dimensional space. These angles
60 are similar to yaw, pitch and roll but are defined using only right hand
61 rotation with axes as defined by the right hand cartesian coordinate system.
62
63 \image sensors-rotation.jpg
64
65 The three angles are applied to the device in the following order.
66
67 \list
68 \li Right-handed rotation z (-180, 180]. Starting from the y-axis and
69 incrementing in the counter-clockwise direction.
70 \li Right-handed rotation x [-90, 90]. Starting from the new
71 (once-rotated) y-axis and incrementing towards the z-axis.
72 \li Right-handed rotation y (-180, 180]. Starting from the new
73 (twice-rotated) z-axis and incrementing towards the x-axis.
74 \endlist
75
76 Here is a visualization showing the order in which angles are applied.
77
78 \image sensors-rotation-anim.gif
79
80 The 0 point for the z angle is defined as a fixed, external entity and
81 is device-specific. While magnetic North is typically used as this
82 reference point it may not be. Do not attempt to compare values
83 for the z angle between devices or even on the same device if it has
84 moved a significant distance.
85
86 If the device cannot detect a fixed, external entity the z angle will
87 always be 0 and the QRotationSensor::hasZ property will be set to false.
88
89 The 0 point for the x and y angles are defined as when the x and y axes
90 of the device are oriented towards the horizon. Here is an example of
91 how the x value will change with device movement.
92
93 \image sensors-rotation2.jpg
94
95 Here is an example of how the y value will change with device movement.
96
97 \image sensors-rotation3.jpg
98
99 Note that when x is 90 or -90, values for z and y achieve rotation around
100 the same axis (due to the order of operations). In this case the y
101 rotation will be 0.
102*/
103
104/*!
105 \property QRotationReading::x
106 \brief the rotation around the x axis.
107
108 Measured as degrees.
109 \sa {QRotationReading Units}
110*/
111
112qreal QRotationReading::x() const
113{
114 return d->x;
115}
116
117/*!
118 \property QRotationReading::y
119 \brief the rotation around the y axis.
120
121 Measured as degrees.
122 \sa {QRotationReading Units}
123*/
124
125qreal QRotationReading::y() const
126{
127 return d->y;
128}
129
130/*!
131 \property QRotationReading::z
132 \brief the rotation around the z axis.
133
134 Measured as degrees.
135 \sa {QRotationReading Units}
136*/
137
138qreal QRotationReading::z() const
139{
140 return d->z;
141}
142
143/*!
144 \brief Sets the rotation from three euler angles.
145
146 This is to be called from the backend.
147
148 The angles are measured in degrees. The order of the rotations matters, as first the \a z rotation
149 is applied, then the \a x rotation and finally the \a y rotation.
150
151 \since 5.0
152 */
153void QRotationReading::setFromEuler(qreal x, qreal y, qreal z)
154{
155 d->x = x;
156 d->y = y;
157 d->z = z;
158}
159
160// =====================================================================
161
162/*!
163 \class QRotationFilter
164 \ingroup sensors_filter
165 \inmodule QtSensors
166 \since 5.1
167
168 \brief The QRotationFilter class is a convenience wrapper around QSensorFilter.
169
170 The only difference is that the filter() method features a pointer to QRotationReading
171 instead of QSensorReading.
172*/
173
174/*!
175 \fn QRotationFilter::filter(QRotationReading *reading)
176
177 Called when \a reading changes. Returns false to prevent the reading from propagating.
178
179 \sa QSensorFilter::filter()
180*/
181
182bool QRotationFilter::filter(QSensorReading *reading)
183{
184 return filter(reading: static_cast<QRotationReading*>(reading));
185}
186
187char const * const QRotationSensor::type("QRotationSensor");
188
189/*!
190 \class QRotationSensor
191 \ingroup sensors_type
192 \inmodule QtSensors
193 \since 5.1
194
195 \brief The QRotationSensor class is a convenience wrapper around QSensor.
196
197 The only behavioural difference is that this class sets the type properly.
198
199 This class also features a reading() function that returns a QRotationReading instead of a QSensorReading.
200
201 For details about how the sensor works, see \l QRotationReading.
202
203 \sa QRotationReading
204*/
205
206/*!
207 Construct the sensor as a child of \a parent.
208*/
209QRotationSensor::QRotationSensor(QObject *parent)
210 : QSensor(QRotationSensor::type, *new QRotationSensorPrivate, parent)
211{
212}
213
214/*!
215 Destroy the sensor. Stops the sensor if it has not already been stopped.
216*/
217QRotationSensor::~QRotationSensor()
218{
219}
220
221/*!
222 \fn QRotationSensor::reading() const
223
224 Returns the reading class for this sensor.
225
226 \sa QSensor::reading()
227*/
228
229QRotationReading *QRotationSensor::reading() const
230{
231 return static_cast<QRotationReading*>(QSensor::reading());
232}
233
234/*!
235 \property QRotationSensor::hasZ
236 \brief a value indicating if the z angle is available.
237
238 Returns true if z is available.
239 Returns false if z is not available.
240*/
241
242bool QRotationSensor::hasZ() const
243{
244 Q_D(const QRotationSensor);
245 return (d->hasZ);
246}
247
248/*!
249 \since 5.1
250
251 Sets whether the z angle is available to \a hasZ. This is to be called from the
252 backend. By default the hasZ property is true, so a backend only has to
253 call this if its rotation sensor can not report z angles.
254*/
255void QRotationSensor::setHasZ(bool hasZ)
256{
257 Q_D(QRotationSensor);
258 if (d->hasZ != hasZ) {
259 d->hasZ = hasZ;
260 emit hasZChanged(hasZ);
261 }
262}
263
264QT_END_NAMESPACE
265
266#include "moc_qrotationsensor.cpp"
267

source code of qtsensors/src/sensors/qrotationsensor.cpp