content: /*
   * Copyright (C) 2016 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.hardware;
  
  import android.annotation.IntDef;
  
  import java.lang.annotation.Retention;
  import java.lang.annotation.RetentionPolicy;
  
  /**
   * This class represents a {@link android.hardware.Sensor Sensor} additional information frame,
   * which is reported through listener callback {@link
   * android.hardware.SensorEventCallback#onSensorAdditionalInfo onSensorAdditionalInfo}.
   *
   * @see SensorManager
   * @see SensorEventCallback
   * @see Sensor
   *
   */
  
  public class SensorAdditionalInfo {
  
      /**
       * The sensor that generated this event. See
       * {@link android.hardware.SensorManager SensorManager} for details.
       */
      public final Sensor sensor;
  
      /**
       * Type of this additional info frame.
       */
      public final int type;
  
      /**
       * Sequence number of frame for a certain type.
       */
      public final int serial;
  
      /**
       * Additional info payload data represented in float values. Depending on the type of
       * information, this may be null.
       */
      public final float[] floatValues;
  
      /**
       * Additional info payload data represented in int values. Depending on the type of information,
       * this may be null.
       */
      public final int[] intValues;
  
      /**
       * Typical values of additional infomation type. The set of values is subject to extension in
       * newer versions and vendors have the freedom of define their own custom values.
       *
       * @hide
       */
      @IntDef(prefix = { "TYPE_" }, value = {
              TYPE_FRAME_BEGIN,
              TYPE_FRAME_END,
              TYPE_UNTRACKED_DELAY,
              TYPE_INTERNAL_TEMPERATURE,
              TYPE_VEC3_CALIBRATION,
              TYPE_SENSOR_PLACEMENT,
              TYPE_SAMPLING
      })
      @Retention(RetentionPolicy.SOURCE)
      public @interface AdditionalInfoType {}
  
      /**
       * Mark the beginning of a set of additional info frames.
       */
      public static final int TYPE_FRAME_BEGIN = 0;
  
      /**
       * Mark the end of a set of additional info frames.
       */
      public static final int TYPE_FRAME_END = 1;
  
      /**
       * Untracked delay. Delays that are introduced by data processing, such as filtering, which is
       * not taken into account by sensor timestamps.
       *
       * Payload:
       *     floatValues[0]: delay estimation in seconds
       *     floatValues[1]: delay estimation standard deviation
       */
      public static final int TYPE_UNTRACKED_DELAY = 0x10000;
  
      /**
       * Internal temperature. Sensor hardware device internal temperature.
       *
       * Payload:
       *     floatValues[0]: internal temperature in Celsius.
       */
      public static final int TYPE_INTERNAL_TEMPERATURE = 0x10001;
  
      /**
       * Vector calibration parameter. Calibration applied to a sensor with 3 elements vector output,
       * such as accelerometer, gyro, etc.
       *
       * Payload:
       *     floatValues[0..11]: First 3 rows of a homogeneous matrix in row major order that captures
       *     any linear transformation, including rotation, scaling, shear, shift.
       */
      public static final int TYPE_VEC3_CALIBRATION = 0x10002;
  
      /**
       * Sensor placement.
       *
       * Provides the orientation and location of the sensor element in terms of the
       * Android coordinate system. This data is given as a 3x4 matrix consisting of a 3x3 rotation
       * matrix (R) concatenated with a 3x1 location vector (t). The rotation matrix provides the
       * orientation of the Android device coordinate frame relative to the local coordinate frame of
       * the sensor. Note that assuming the axes conventions of the sensor are the same as Android,
       * this is the inverse of the matrix applied to raw samples read from the sensor to convert them
       * into the Android representation. The location vector represents the translation from the
       * origin of the Android sensor coordinate system to the geometric center of the sensor,
       * specified in millimeters (mm).
       * <p>
       * <b>Payload</b>:
       *     <code>floatValues[0..11]</code>: 3x4 matrix in row major order [R; t]
       * </p>
       * <p>
       * <b>Example</b>:
       *     This raw buffer: <code>{0, 1, 0, 0, -1, 0, 0, 10, 0, 0, 1, -2.5}</code><br>
       *     Corresponds to this 3x4 matrix:
       *     <table>
       *      <thead>
       *       <tr><td colspan="3">Orientation</td><td>Location</tr>
       *      </thead>
       *      <tbody>
       *       <tr><td>0</td><td>1</td><td>0</td><td>0</td></tr>
       *       <tr><td>-1</td><td>0</td><td>0</td><td>10</td></tr>
       *       <tr><td>0</td><td>0</td><td>1</td><td>-2.5</td></tr>
       *      </tbody>
       *     </table>
       *     The sensor is oriented such that:
       *     <ul>
       *        <li>The device X axis corresponds to the sensor's local -Y axis
       *        <li>The device Y axis corresponds to the sensor's local X axis
       *        <li>The device Z axis and sensor's local Z axis are equivalent
       *     </ul>
       *     In other words, if viewing the origin of the Android coordinate system from the positive
       *     Z direction, the device coordinate frame is to be rotated 90° counter-clockwise about the
       *     Z axis to align with the sensor's local coordinate frame. Equivalently, a vector in the
       *     Android coordinate frame may be multiplied with R to rotate it 90° clockwise (270°
       *     counter-clockwise), yielding its representation in the sensor's coordinate frame.
       *     Relative to the origin of the Android coordinate system, the physical center of the
       *     sensor is located 10mm in the positive Y direction, and 2.5mm in the negative Z
       *     direction.
       * </p>
       */
      public static final int TYPE_SENSOR_PLACEMENT = 0x10003;
  
      /**
       * Sampling parameter. Describes the raw sample period and estimated jitter of sample time in
       * terms of standard deviation.
       *
       * Payload:
       *     floatValues[0]: raw sample period in seconds.
       *     floatValues[1]: standard deviation of sampling period.
       */
      public static final int TYPE_SAMPLING = 0x10004;
  
      /**
       * Local geo-magnetic Field.
       *
       * Additional into to sensor hardware.  Local geomagnetic field information based on
       * device geo location. This type is primarily for for magnetic field calibration and rotation
       * vector sensor fusion.
       *
       * float[3]: strength (uT), declination and inclination angle (rad).
       * @hide
       */
      public static final int TYPE_LOCAL_GEOMAGNETIC_FIELD = 0x30000;
  
      /**
       * Local gravity acceleration strength.
       *
       * Additional info to sensor hardware for accelerometer calibration.
       *
       * float: gravitational acceleration norm in m/s^2.
       * @hide
       */
      public static final int TYPE_LOCAL_GRAVITY = 0x30001;
  
      /**
       * Device dock state.
       *
       * Additional info to sensor hardware indicating dock states of device.
       *
       * int32_t: dock state following definition of {@link android.content.Intent#EXTRA_DOCK_STATE}.
       *          Undefined values are ignored.
       * @hide
       */
      public static final int TYPE_DOCK_STATE = 0x30002;
  
      /**
       * High performance mode.
       *
       * Additional info to sensor hardware. Device is able to use up more power and take more
       * resources to improve throughput and latency in high performance mode. One possible use case
       * is virtual reality, when sensor latency need to be carefully controlled.
       *
       * int32_t: 1 or 0, denoting device is in or out of high performance mode, respectively.
       *          Other values are ignored.
       * @hide
       */
      public static final int TYPE_HIGH_PERFORMANCE_MODE = 0x30003;
  
      /**
       * Magnetic field calibration hint.
       *
       * Additional info to sensor hardware. Device is notified when manually triggered magnetic field
       * calibration procedure is started or stopped. The calibration procedure is assumed timed out
       * after 1 minute from start, even if an explicit stop is not received.
       *
       * int32_t: 1 for calibration start, 0 for stop, other values are ignored.
       * @hide
       */
      public static final int TYPE_MAGNETIC_FIELD_CALIBRATION = 0x30004;
  
      /**
       * Custom sensor info: array of float values interpreted by sensor based on the type
       * Any type between TYPE_CUSTOM_INFO <= info_type < TYPE_DEBUG_INFO may be
       * used to send custom sensor info.
       * @hide
       */
      public static final int TYPE_CUSTOM_INFO = 0x10000000;
      /** @hide */
      public static final int TYPE_DEBUG_INFO  = 0x40000000;
  
      SensorAdditionalInfo(
              Sensor aSensor, int aType, int aSerial, int[] aIntValues, float[] aFloatValues) {
          sensor = aSensor;
          type = aType;
          serial = aSerial;
          intValues = aIntValues;
          floatValues = aFloatValues;
      }
  
      /** @hide */
      public static SensorAdditionalInfo createLocalGeomagneticField(
              float strength, float declination, float inclination) {
          if (strength < 10 || strength > 100 // much beyond extreme values on earth
                  || declination < 0 || declination > Math.PI
                  || inclination < -Math.PI / 2 || inclination > Math.PI / 2) {
              throw new IllegalArgumentException("Geomagnetic field info out of range");
          }
  
          return new SensorAdditionalInfo(
                  null, TYPE_LOCAL_GEOMAGNETIC_FIELD, 0,
                  null, new float[] { strength, declination, inclination});
      }
      /** @hide */
      public static SensorAdditionalInfo createCustomInfo(Sensor aSensor, int type, float[] data) {
          if (type < TYPE_CUSTOM_INFO || type >= TYPE_DEBUG_INFO || aSensor == null) {
              throw new IllegalArgumentException(
                      "invalid parameter(s): type: " + type + "; sensor: " + aSensor);
          }
  
          return new SensorAdditionalInfo(aSensor, type, 0, null, data);
      }
  }
  