dali/devel-api/adaptor-framework/tilt-sensor.h

   1 #ifndef __DALI_TILT_SENSOR_H__
   2 #define __DALI_TILT_SENSOR_H__
   3
   4 /*
   5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/public-api/object/base-handle.h>
  23 #include <dali/public-api/signals/dali-signal.h>
  24
  25 namespace Dali
  26 {
  27
  28 namespace Internal DALI_INTERNAL
  29 {
  30 namespace Adaptor
  31 {
  32 class TiltSensor;
  33 }
  34 }
  35
  36 /**
  37  * TiltSensor provides pitch & roll values when the device is tilted.
  38  * The basic usage is shown below:
  39  *
  40  * @code
  41  *
  42  *  void Example()
  43  *  {
  44  *    TiltSensor sensor = TiltSensor::Get();
  45  *
  46  *    // Try to start the tilt sensor
  47  *    if ( sensor.Start() )
  48  *    {
  49  *      // Query the current values
  50  *      std::cout << "Roll = " << sensor.GetRoll() << ", Pitch = " << sensor.GetPitch() << std::endl;
  51  *
  52  *      // Get notifications when the device is tilted
  53  *      sensor.TiltedSignal().Connect( &OnTilted );
  54  *    }
  55  *  }
  56  *
  57  *  void OnTilted( const TiltSensor& sensor )
  58  *  {
  59  *    // Query the new values
  60  *    std::cout << "Roll = " << sensor.GetRoll() << ", Pitch = " << sensor.GetPitch() << std::endl;
  61  *  }
  62  *
  63  * @endcode
  64  *
  65  * While the tilt sensor is started, it will periodically poll for the latest pitch & roll values.
  66  * For performance & power-saving, applications should disable this polling when no longer needed:
  67  *
  68  * @code
  69  *
  70  *  void EndExample()
  71  *  {
  72  *    // Stop the sensor when no longer needed
  73  *    TiltSensor::Get().Stop();
  74  *  }
  75  *
  76  * @endcode
  77  */
  78 class DALI_IMPORT_API TiltSensor : public BaseHandle
  79 {
  80 public:
  81
  82   typedef Signal< void (const TiltSensor&) > TiltedSignalType;
  83
  84   static const float DEFAULT_UPDATE_FREQUENCY; // 60 hertz
  85
  86   /**
  87    * Create an uninitialized handle.
  88    * This can be initialized by calling TiltSensor::Get().
  89    */
  90   TiltSensor();
  91
  92   /**
  93    * Create an initialized handle to the TiltSensor.
  94    * @return A handle to a newly allocated Dali resource.
  95    */
  96   static TiltSensor Get();
  97
  98   /**
  99    * @brief Destructor
 100    *
 101    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 102    */
 103   ~TiltSensor();
 104
 105   /**
 106    * Attempt to start the tilt-sensor. This will fail if the underlying sensor hardware is powered-down,
 107    * typically this occurs when the device is set to "sleep" mode.
 108    * @return True if the tilt-sensor is started.
 109    */
 110   bool Start();
 111
 112   /**
 113    * Stop the tilt-sensor.
 114    */
 115   void Stop();
 116
 117   /**
 118    * Query whether the tilt-sensor is started.
 119    * The sensor may be disabled automatically; typically this occurs when the device is set to "sleep" mode.
 120    * @return True if the tilt-sensor is started.
 121    */
 122   bool IsStarted() const;
 123
 124   /**
 125    * Query the roll value. This is in the range -1 to 1.
 126    * When the device is lying face-up on a flat surface, this method will return a value close to zero.
 127    * A value close to 1 indicates that the right-side of the device is pointing upwards.
 128    * A value close to -1 indicates that the right-side of the device is pointing downwards.
 129    * @pre The tilt-sensor is started.
 130    * @return The roll value.
 131    */
 132   float GetRoll() const;
 133
 134   /**
 135    * Query the pitch value. This is in the range -1 to 1.
 136    * When the device is lying face-up on a flat surface, this method will return a value close to zero.
 137    * A value close to 1 indicates that the top of the device is pointing upwards.
 138    * A value close to -1 indicates that the top of the device is pointing downwards.
 139    * @pre The tilt-sensor is started.
 140    * @return The pitch value.
 141    */
 142   float GetPitch() const;
 143
 144   /**
 145    * Retrieve the rotation of the device.
 146    * When the device is lying face-up on a flat surface, the rotation angle will be approximately zero.
 147    * The roll & pitch of the device is considered to be a rotation around the Y and X axes respectively.
 148    * @pre The tilt-sensor is started.
 149    * @return The rotation in quaternion format.
 150    */
 151   Quaternion GetRotation() const;
 152
 153   /**
 154    * This signal will be emitted when the device is tilted, if the tilt-sensor is started.
 155    * The frequency of the signals can be controlled using SetUpdateFrequency().
 156    * @return The signal to connect to.
 157    *
 158    * @note The signal name is "tilted" if using BaseHandle::ConnectSignal()
 159    */
 160   TiltedSignalType& TiltedSignal();
 161
 162   /**
 163    * Set the sensor update frequency.
 164    * The default is TiltSensor::DEFAULT_UPDATE_FREQUENCY.
 165    * @param[in] frequencyHertz The frequency in hertz.
 166    */
 167   void SetUpdateFrequency( float frequencyHertz );
 168
 169   /**
 170    * Query the sensor update frequency.
 171    * @return The frequency in hertz.
 172    */
 173   float GetUpdateFrequency() const;
 174
 175   /**
 176    * Set the threshold value for rotation in Radians, above which TiltedSignal should be emitted.
 177    * The default is 0.0f in Radians (i.e) it will be emitted always at the frequency set.
 178    * Example tiltSensor.SetRotationThreshold( Radian(Degree(10) ) // A rotation threshold of 10 degrees
 179    * @param[in] rotationThreshold The threshold value for rotation.
 180    */
 181   void SetRotationThreshold( Radian rotationThreshold );
 182
 183   /**
 184    * Query the rotation threshold above which TiltedSignal will be emitted.
 185    * @return The rotation degree threshold in Radians.
 186    */
 187   Radian GetRotationThreshold() const;
 188
 189 public: // Not intended for application developers
 190
 191   /**
 192    * This constructor is used by TiltSensor::Get().
 193    * @param[in] sensor A pointer to the tilt sensor.
 194    */
 195   explicit DALI_INTERNAL TiltSensor( Internal::Adaptor::TiltSensor* sensor );
 196 };
 197
 198 } // namespace Dali
 199
 200 #endif // __DALI_TILT_SENSOR_H__