dsfml.window.sensor source code

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