dom/camera/ICameraControl.h

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #ifndef DOM_CAMERA_ICAMERACONTROL_H
   6 #define DOM_CAMERA_ICAMERACONTROL_H
   7
   8 #include "nsCOMPtr.h"
   9 #include "nsString.h"
  10 #include "nsAutoPtr.h"
  11 #include "nsISupportsImpl.h"
  12 #include "base/basictypes.h"
  13
  14 struct DeviceStorageFileDescriptor;
  15
  16 class nsIFile;
  17
  18 namespace mozilla {
  19
  20 class CameraControlListener;
  21
  22 // XXXmikeh - In some future patch this should move into the ICameraControl
  23 //  class as well, and the names updated to the 'k'-style;
  24 //  e.g. kParamPreviewSize, etc.
  25 enum {
  26   // current settings
  27   CAMERA_PARAM_PREVIEWSIZE,
  28   CAMERA_PARAM_PREVIEWFORMAT,
  29   CAMERA_PARAM_PREVIEWFRAMERATE,
  30   CAMERA_PARAM_VIDEOSIZE,
  31   CAMERA_PARAM_PICTURE_SIZE,
  32   CAMERA_PARAM_PICTURE_FILEFORMAT,
  33   CAMERA_PARAM_PICTURE_ROTATION,
  34   CAMERA_PARAM_PICTURE_LOCATION,
  35   CAMERA_PARAM_PICTURE_DATETIME,
  36   CAMERA_PARAM_PICTURE_QUALITY,
  37   CAMERA_PARAM_EFFECT,
  38   CAMERA_PARAM_WHITEBALANCE,
  39   CAMERA_PARAM_SCENEMODE,
  40   CAMERA_PARAM_FLASHMODE,
  41   CAMERA_PARAM_FOCUSMODE,
  42   CAMERA_PARAM_ZOOM,
  43   CAMERA_PARAM_METERINGAREAS,
  44   CAMERA_PARAM_FOCUSAREAS,
  45   CAMERA_PARAM_FOCALLENGTH,
  46   CAMERA_PARAM_FOCUSDISTANCENEAR,
  47   CAMERA_PARAM_FOCUSDISTANCEOPTIMUM,
  48   CAMERA_PARAM_FOCUSDISTANCEFAR,
  49   CAMERA_PARAM_EXPOSURECOMPENSATION,
  50   CAMERA_PARAM_THUMBNAILSIZE,
  51   CAMERA_PARAM_THUMBNAILQUALITY,
  52   CAMERA_PARAM_SENSORANGLE,
  53   CAMERA_PARAM_ISOMODE,
  54   CAMERA_PARAM_LUMINANCE,
  55   CAMERA_PARAM_SCENEMODE_HDR_RETURNNORMALPICTURE,
  56   CAMERA_PARAM_RECORDINGHINT,
  57   CAMERA_PARAM_PREFERRED_PREVIEWSIZE_FOR_VIDEO,
  58   CAMERA_PARAM_METERINGMODE,
  59
  60   // supported features
  61   CAMERA_PARAM_SUPPORTED_PREVIEWSIZES,
  62   CAMERA_PARAM_SUPPORTED_PICTURESIZES,
  63   CAMERA_PARAM_SUPPORTED_VIDEOSIZES,
  64   CAMERA_PARAM_SUPPORTED_PICTUREFORMATS,
  65   CAMERA_PARAM_SUPPORTED_WHITEBALANCES,
  66   CAMERA_PARAM_SUPPORTED_SCENEMODES,
  67   CAMERA_PARAM_SUPPORTED_EFFECTS,
  68   CAMERA_PARAM_SUPPORTED_FLASHMODES,
  69   CAMERA_PARAM_SUPPORTED_FOCUSMODES,
  70   CAMERA_PARAM_SUPPORTED_MAXFOCUSAREAS,
  71   CAMERA_PARAM_SUPPORTED_MAXMETERINGAREAS,
  72   CAMERA_PARAM_SUPPORTED_MINEXPOSURECOMPENSATION,
  73   CAMERA_PARAM_SUPPORTED_MAXEXPOSURECOMPENSATION,
  74   CAMERA_PARAM_SUPPORTED_EXPOSURECOMPENSATIONSTEP,
  75   CAMERA_PARAM_SUPPORTED_ZOOM,
  76   CAMERA_PARAM_SUPPORTED_ZOOMRATIOS,
  77   CAMERA_PARAM_SUPPORTED_MAXDETECTEDFACES,
  78   CAMERA_PARAM_SUPPORTED_JPEG_THUMBNAIL_SIZES,
  79   CAMERA_PARAM_SUPPORTED_ISOMODES,
  80   CAMERA_PARAM_SUPPORTED_METERINGMODES
  81 };
  82
  83 class ICameraControl
  84 {
  85 public:
  86   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(ICameraControl)
  87
  88   // Returns the number of cameras supported by the system.
  89   //
  90   // Return values:
  91   //  - NS_OK on success;
  92   //  - NS_ERROR_FAILURE if the camera count cannot be retrieved.
  93   static nsresult GetNumberOfCameras(int32_t& aDeviceCount);
  94
  95   // Gets the (possibly-meaningful) name of a particular camera.
  96   //
  97   // Return values:
  98   //  - NS_OK on success;
  99   //  - NS_ERROR_INVALID_ARG if 'aDeviceNum' is not a valid camera number;
 100   //  - NS_ERROR_NOT_AVAILABLE if 'aDeviceNum' is valid but the camera name
 101   //      could still not be retrieved.
 102   static nsresult GetCameraName(uint32_t aDeviceNum, nsCString& aDeviceName);
 103
 104   // Returns a list of names of all cameras supported by the system.
 105   //
 106   // Return values:
 107   //  - NS_OK on success, even if no camera names are returned (in which
 108   //      case 'aList' will be empty);
 109   //  - NS_ERROR_NOT_AVAILABLE if the list of cameras cannot be retrieved.
 110   static nsresult GetListOfCameras(nsTArray<nsString>& aList);
 111
 112   enum Mode {
 113     kUnspecifiedMode,
 114     kPictureMode,
 115     kVideoMode,
 116   };
 117
 118   struct Size {
 119     uint32_t  width;
 120     uint32_t  height;
 121   };
 122
 123   struct Region {
 124     int32_t   top;
 125     int32_t   left;
 126     int32_t   bottom;
 127     int32_t   right;
 128     uint32_t  weight;
 129   };
 130
 131   struct Position {
 132     double    latitude;
 133     double    longitude;
 134     double    altitude;
 135     double    timestamp;
 136   };
 137
 138   struct StartRecordingOptions {
 139     uint32_t  rotation;
 140     uint64_t  maxFileSizeBytes;
 141     uint64_t  maxVideoLengthMs;
 142     bool      autoEnableLowLightTorch;
 143   };
 144
 145   struct Configuration {
 146     Mode      mMode;
 147     Size      mPreviewSize;
 148     Size      mPictureSize;
 149     nsString  mRecorderProfile;
 150   };
 151
 152   struct Point {
 153     int32_t   x;
 154     int32_t   y;
 155   };
 156
 157   struct Face {
 158     uint32_t  id;
 159     uint32_t  score;
 160     Region    bound;
 161     bool      hasLeftEye;
 162     Point     leftEye;
 163     bool      hasRightEye;
 164     Point     rightEye;
 165     bool      hasMouth;
 166     Point     mouth;
 167   };
 168
 169   class RecorderProfile
 170   {
 171   public:
 172     class Video
 173     {
 174     public:
 175       Video() { }
 176       virtual ~Video() { }
 177
 178       const nsString& GetCodec() const    { return mCodec; }
 179       const Size& GetSize() const         { return mSize; }
 180       uint32_t GetBitsPerSecond() const   { return mBitsPerSecond; }
 181       uint32_t GetFramesPerSecond() const { return mFramesPerSecond; }
 182
 183     protected:
 184       nsString  mCodec;
 185       Size      mSize;
 186       uint32_t  mBitsPerSecond;
 187       uint32_t  mFramesPerSecond;
 188
 189     private:
 190       DISALLOW_EVIL_CONSTRUCTORS(Video);
 191     };
 192
 193     class Audio
 194     {
 195     public:
 196       Audio() { }
 197       virtual ~Audio() { }
 198
 199       const nsString& GetCodec() const    { return mCodec; }
 200
 201       uint32_t GetChannels() const        { return mChannels; }
 202       uint32_t GetBitsPerSecond() const   { return mBitsPerSecond; }
 203       uint32_t GetSamplesPerSecond() const { return mSamplesPerSecond; }
 204
 205     protected:
 206       nsString  mCodec;
 207       uint32_t  mChannels;
 208       uint32_t  mBitsPerSecond;
 209       uint32_t  mSamplesPerSecond;
 210
 211     private:
 212       DISALLOW_EVIL_CONSTRUCTORS(Audio);
 213     };
 214
 215     NS_INLINE_DECL_THREADSAFE_REFCOUNTING(RecorderProfile)
 216
 217     RecorderProfile()
 218     { }
 219
 220     const nsString& GetName() const       { return mName; }
 221     const nsString& GetContainer() const  { return mContainer; }
 222     const nsString& GetMimeType() const   { return mMimeType; }
 223
 224     virtual const Video& GetVideo() const = 0;
 225     virtual const Audio& GetAudio() const = 0;
 226
 227   protected:
 228     virtual ~RecorderProfile() { }
 229
 230     nsString    mName;
 231     nsString    mContainer;
 232     nsString    mMimeType;
 233
 234   private:
 235     DISALLOW_EVIL_CONSTRUCTORS(RecorderProfile);
 236   };
 237
 238   static already_AddRefed<ICameraControl> Create(uint32_t aCameraId);
 239
 240   virtual void AddListener(CameraControlListener* aListener) = 0;
 241   virtual void RemoveListener(CameraControlListener* aListener) = 0;
 242
 243   // Camera control methods.
 244   //
 245   // Return values:
 246   //  - NS_OK on success (if the method requires an asynchronous process,
 247   //      this value indicates that the process has begun successfully);
 248   //  - NS_ERROR_INVALID_ARG if one or more arguments is invalid;
 249   //  - NS_ERROR_FAILURE if an asynchronous method could not be dispatched.
 250   virtual nsresult Start(const Configuration* aInitialConfig = nullptr) = 0;
 251   virtual nsresult Stop() = 0;
 252   virtual nsresult SetConfiguration(const Configuration& aConfig) = 0;
 253   virtual nsresult StartPreview() = 0;
 254   virtual nsresult StopPreview() = 0;
 255   virtual nsresult AutoFocus() = 0;
 256   virtual nsresult TakePicture() = 0;
 257   virtual nsresult StartRecording(DeviceStorageFileDescriptor* aFileDescriptor,
 258                                   const StartRecordingOptions* aOptions = nullptr) = 0;
 259   virtual nsresult StopRecording() = 0;
 260   virtual nsresult PauseRecording() = 0;
 261   virtual nsresult ResumeRecording() = 0;
 262   virtual nsresult StartFaceDetection() = 0;
 263   virtual nsresult StopFaceDetection() = 0;
 264   virtual nsresult ResumeContinuousFocus() = 0;
 265
 266   // Camera parameter getters and setters. 'aKey' must be one of the
 267   // CAMERA_PARAM_* values enumerated above.
 268   //
 269   // Return values:
 270   //  - NS_OK on success;
 271   //  - NS_ERROR_INVALID_ARG if 'aValue' contains an invalid value;
 272   //  - NS_ERROR_NOT_IMPLEMENTED if 'aKey' is invalid;
 273   //  - NS_ERROR_NOT_AVAILABLE if the getter fails to retrieve a valid value,
 274   //      or if a setter fails because it requires one or more values that
 275   //      could not be retrieved;
 276   //  - NS_ERROR_FAILURE on unexpected internal failures.
 277   virtual nsresult Set(uint32_t aKey, const nsAString& aValue) = 0;
 278   virtual nsresult Get(uint32_t aKey, nsAString& aValue) = 0;
 279   virtual nsresult Set(uint32_t aKey, double aValue) = 0;
 280   virtual nsresult Get(uint32_t aKey, double& aValue) = 0;
 281   virtual nsresult Set(uint32_t aKey, int32_t aValue) = 0;
 282   virtual nsresult Get(uint32_t aKey, int32_t& aValue) = 0;
 283   virtual nsresult Set(uint32_t aKey, int64_t aValue) = 0;
 284   virtual nsresult Get(uint32_t aKey, int64_t& aValue) = 0;
 285   virtual nsresult Set(uint32_t aKey, bool aValue) = 0;
 286   virtual nsresult Get(uint32_t aKey, bool& aValue) = 0;
 287   virtual nsresult Set(uint32_t aKey, const Size& aValue) = 0;
 288   virtual nsresult Get(uint32_t aKey, Size& aValue) = 0;
 289   virtual nsresult Set(uint32_t aKey, const nsTArray<Region>& aRegions) = 0;
 290   virtual nsresult Get(uint32_t aKey, nsTArray<Region>& aRegions) = 0;
 291
 292   virtual nsresult SetLocation(const Position& aLocation) = 0;
 293
 294   virtual nsresult Get(uint32_t aKey, nsTArray<Size>& aSizes) = 0;
 295   virtual nsresult Get(uint32_t aKey, nsTArray<nsString>& aValues) = 0;
 296   virtual nsresult Get(uint32_t aKey, nsTArray<double>& aValues) = 0;
 297
 298   virtual nsresult GetRecorderProfiles(nsTArray<nsString>& aProfiles) = 0;
 299   virtual RecorderProfile* GetProfileInfo(const nsAString& aProfile) = 0;
 300
 301 protected:
 302   virtual ~ICameraControl() { }
 303
 304   friend class ICameraControlParameterSetAutoEnter;
 305
 306   virtual void BeginBatchParameterSet() = 0;
 307   virtual void EndBatchParameterSet() = 0;
 308 };
 309
 310 // Helper class to make it easy to update a batch of camera parameters;
 311 // the parameters are applied atomically when this object goes out of
 312 // scope.
 313 class ICameraControlParameterSetAutoEnter
 314 {
 315 public:
 316   explicit ICameraControlParameterSetAutoEnter(ICameraControl* aCameraControl)
 317     : mCameraControl(aCameraControl)
 318   {
 319     mCameraControl->BeginBatchParameterSet();
 320   }
 321   virtual ~ICameraControlParameterSetAutoEnter()
 322   {
 323     mCameraControl->EndBatchParameterSet();
 324   }
 325
 326 protected:
 327   nsRefPtr<ICameraControl> mCameraControl;
 328 };
 329
 330 } // namespace mozilla
 331
 332 #endif // DOM_CAMERA_ICAMERACONTROL_H