dsfml.window.sensor source code

1 /*
2  * DSFML - The Simple and Fast Multimedia Library for D
3  *
4  * Copyright (c) 2013 - 2018 Jeremy DeHaan (dehaan.jeremiah@gmail.com)
5  *
6  * This software is provided 'as-is', without any express or implied warranty.
7  * In no event will the authors be held liable for any damages arising from the
8  * use of this software.
9  *
10  * Permission is granted to anyone to use this software for any purpose,
11  * including commercial applications, and to alter it and redistribute it
12  * freely, subject to the following restrictions:
13  *
14  * 1. The origin of this software must not be misrepresented; you must not claim
15  * that you wrote the original software. If you use this software in a product,
16  * an acknowledgment in the product documentation would be appreciated but is
17  * not required.
18  *
19  * 2. Altered source versions must be plainly marked as such, and must not be
20  * misrepresented as being the original software.
21  *
22  * 3. This notice may not be removed or altered from any source distribution
23  *
24  *
25  * DSFML is based on SFML (Copyright Laurent Gomila)
26  */
27 
28 /**
29  * $(U Sensor) provides an interface to the state of the various sensors that a
30  * device provides. It only contains static functions, so it's not meant to be
31  * instantiated.
32  *
33  * This class allows users to query the sensors values at any time and directly,
34  * without having to deal with a window and its events. Compared to the
35  * SensorChanged event, Sensor can retrieve the state of a sensor at any time
36  * (you don't need to store and update its current value on your side).
37  *
38  * Depending on the OS and hardware of the device (phone, tablet, ...), some
39  * sensor types may not be available. You should always check the availability
40  * of a sensor before trying to read it, with the `Sensor.isAvailable` function.
41  *
42  * You may wonder why some sensor types look so similar, for example
43  * Accelerometer and Gravity / UserAcceleration. The first one is the raw
44  * measurement of the acceleration, and takes into account both the earth
45  * gravity and the user movement. The others are more precise: they provide
46  * these components separately, which is usually more useful. In fact they are
47  * not direct sensors, they are computed internally based on the raw
48  * acceleration and other sensors. This is exactly the same for Gyroscope vs
49  * Orientation.
50  *
51  * Because sensors consume a non-negligible amount of current, they are all
52  * disabled by default. You must call `Sensor.setEnabled` for each sensor in
53  * which you are interested.
54  *
55  * Example:
56  * ---
57  * if (Sensor.isAvailable(Sensor.Type.Gravity))
58  * {
59  *     // gravity sensor is available
60  * }
61  *
62  * // enable the gravity sensor
63  * Sensor.setEnabled(Sensor.Type.Gravity, true);
64  *
65  * // get the current value of gravity
66  * Vector3f gravity = Sensor.getValue(Sensor.Type.Gravity);
67  * ---
68  */
69 module dsfml.window.sensor;
70 
71 import dsfml.system.vector3;
72 
73 /**
74  * Give access to the real-time state of the sensors.
75  */
76 final abstract class Sensor
77 {
78     /// Sensor type
79     enum Type
80     {
81         /// Measures the raw acceleration (m/s²)
82         Accelerometer,
83         /// Measures the raw rotation rates (°/s)
84         Gyroscope,
85         /// Measures the ambient magnetic field (micro-teslas)
86         Magnetometer,
87         /**
88          * Measures the direction and intensity of gravity, independent of
89          * device acceleration (m/s²)
90          */
91         Gravity,
92         /**
93          * Measures the direction and intensity of device cceleration,
94          * independent of the gravity (m/s²)
95          */
96         UserAcceleration,
97         /// Measures the absolute 3D orientation (°)
98         Orientation,
99         /// Keep last - the total number of sensor types
100         Count
101     }
102 
103     /**
104     * Check if a sensor is available on the underlying platform.
105     *
106     * Params:
107     *	sensor = Sensor to check
108     *
109     * Returns: true if the sensor is available, false otherwise.
110     */
111     static bool isAvailable (Type sensor)
112     {
113         return sfSensor_isAvailable(sensor);
114     }
115 
116     /**
117     * Enable or disable a sensor.
118     *
119     * All sensors are disabled by default, to avoid consuming too much battery
120     * power. Once a sensor is enabled, it starts sending events of the
121     * corresponding type.
122     *
123     * This function does nothing if the sensor is unavailable.
124     *
125     * Params:
126     *   sensor = Sensor to enable
127     *   enabled = true to enable, false to disable
128     */
129     static void setEnabled (Type sensor, bool enabled)
130     {
131         sfSensor_setEnabled(sensor, enabled);
132     }
133 
134     /**
135     * Get the current sensor value.
136     *
137     * Params:
138     *   sensor = Sensor to read
139     *
140     * Returns: The current sensor value.
141     */
142     static Vector3f getValue (Type sensor)
143     {
144         Vector3f getValue;
145         sfSensor_getValue(sensor, &getValue.x, &getValue.y, &getValue.z);
146 
147         return getValue;
148     }
149 }
150 
151 private extern(C)
152 {
153     //Check if a sensor is available
154     bool sfSensor_isAvailable (int sensor);
155 
156     //Enable or disable a given sensor
157     void sfSensor_setEnabled (int sensor, bool enabled);
158 
159     //Set the current value of teh sensor
160     void sfSensor_getValue (int sensor, float* x, float* y, float* z);
161 }