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

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