src/media/video/capture/video_capture_device.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // VideoCaptureDevice is the abstract base class for realizing video capture
   6 // device support in Chromium. It provides the interface for OS dependent
   7 // implementations.
   8 // The class is created and functions are invoked on a thread owned by
   9 // VideoCaptureManager. Capturing is done on other threads, depending on the OS
  10 // specific implementation.
  11
  12 #ifndef MEDIA_VIDEO_CAPTURE_VIDEO_CAPTURE_DEVICE_H_
  13 #define MEDIA_VIDEO_CAPTURE_VIDEO_CAPTURE_DEVICE_H_
  14
  15 #include <list>
  16 #include <string>
  17
  18 #include "base/logging.h"
  19 #include "base/memory/ref_counted.h"
  20 #include "base/memory/scoped_ptr.h"
  21 #include "base/single_thread_task_runner.h"
  22 #include "base/time/time.h"
  23 #include "media/base/media_export.h"
  24 #include "media/base/video_frame.h"
  25 #include "media/video/capture/video_capture_types.h"
  26
  27 namespace media {
  28
  29 class MEDIA_EXPORT VideoCaptureDevice {
  30  public:
  31   // Represents a capture device name and ID.
  32   // You should not create an instance of this class directly by e.g. setting
  33   // various properties directly.  Instead use
  34   // VideoCaptureDevice::GetDeviceNames to do this for you and if you need to
  35   // cache your own copy of a name, you can do so via the copy constructor.
  36   // The reason for this is that a device name might contain platform specific
  37   // settings that are relevant only to the platform specific implementation of
  38   // VideoCaptureDevice::Create.
  39   class MEDIA_EXPORT Name {
  40    public:
  41     Name();
  42     Name(const std::string& name, const std::string& id);
  43
  44 #if defined(OS_WIN)
  45     // Windows targets Capture Api type: it can only be set on construction.
  46     enum CaptureApiType {
  47       MEDIA_FOUNDATION,
  48       DIRECT_SHOW,
  49       API_TYPE_UNKNOWN
  50     };
  51 #endif
  52 #if defined(OS_MACOSX)
  53     // Mac targets Capture Api type: it can only be set on construction.
  54     enum CaptureApiType {
  55       AVFOUNDATION,
  56       QTKIT,
  57       API_TYPE_UNKNOWN
  58     };
  59     // For AVFoundation Api, identify devices that are built-in or USB.
  60     enum TransportType {
  61       USB_OR_BUILT_IN,
  62       OTHER_TRANSPORT
  63     };
  64 #endif
  65 #if defined(OS_WIN) || defined(OS_MACOSX)
  66     Name(const std::string& name,
  67          const std::string& id,
  68          const CaptureApiType api_type);
  69 #endif
  70 #if defined(OS_MACOSX)
  71     Name(const std::string& name,
  72          const std::string& id,
  73          const CaptureApiType api_type,
  74          const TransportType transport_type);
  75 #endif
  76     ~Name();
  77
  78     // Friendly name of a device
  79     const std::string& name() const { return device_name_; }
  80
  81     // Unique name of a device. Even if there are multiple devices with the same
  82     // friendly name connected to the computer this will be unique.
  83     const std::string& id() const { return unique_id_; }
  84
  85     // The unique hardware model identifier of the capture device. Returns
  86     // "[vid]:[pid]" when a USB device is detected, otherwise "".
  87     // The implementation of this method is platform-dependent.
  88     const std::string GetModel() const;
  89
  90     // Friendly name of a device, plus the model identifier in parentheses.
  91     const std::string GetNameAndModel() const;
  92
  93     // These operators are needed due to storing the name in an STL container.
  94     // In the shared build, all methods from the STL container will be exported
  95     // so even though they're not used, they're still depended upon.
  96     bool operator==(const Name& other) const {
  97       return other.id() == unique_id_;
  98     }
  99     bool operator<(const Name& other) const {
 100       return unique_id_ < other.id();
 101     }
 102
 103 #if defined(OS_WIN) || defined(OS_MACOSX)
 104     CaptureApiType capture_api_type() const {
 105       return capture_api_class_.capture_api_type();
 106     }
 107 #endif
 108 #if defined(OS_MACOSX)
 109     TransportType transport_type() const {
 110       return transport_type_;
 111     }
 112     bool is_blacklisted() const {
 113       return is_blacklisted_;
 114     }
 115     void set_is_blacklisted(bool is_blacklisted) {
 116       is_blacklisted_ = is_blacklisted;
 117     }
 118 #endif  // if defined(OS_WIN)
 119
 120    private:
 121     std::string device_name_;
 122     std::string unique_id_;
 123 #if defined(OS_WIN) || defined(OS_MACOSX)
 124     // This class wraps the CaptureApiType to give it a by default value if not
 125     // initialized.
 126     class CaptureApiClass {
 127      public:
 128       CaptureApiClass(): capture_api_type_(API_TYPE_UNKNOWN) {}
 129       CaptureApiClass(const CaptureApiType api_type)
 130           : capture_api_type_(api_type) {}
 131       CaptureApiType capture_api_type() const {
 132         DCHECK_NE(capture_api_type_, API_TYPE_UNKNOWN);
 133         return capture_api_type_;
 134       }
 135      private:
 136       CaptureApiType capture_api_type_;
 137     };
 138
 139     CaptureApiClass capture_api_class_;
 140 #endif
 141 #if defined(OS_MACOSX)
 142     TransportType transport_type_;
 143     // Flag used to mark blacklisted devices for QTKit Api.
 144     bool is_blacklisted_;
 145 #endif
 146     // Allow generated copy constructor and assignment.
 147   };
 148
 149   // Manages a list of Name entries.
 150   typedef std::list<Name> Names;
 151
 152   class MEDIA_EXPORT Client {
 153    public:
 154     // Memory buffer returned by Client::ReserveOutputBuffer().
 155     class Buffer : public base::RefCountedThreadSafe<Buffer> {
 156      public:
 157       int id() const { return id_; }
 158       void* data() const { return data_; }
 159       size_t size() const { return size_; }
 160
 161      protected:
 162       friend class base::RefCountedThreadSafe<Buffer>;
 163
 164       Buffer(int id, void* data, size_t size)
 165           : id_(id), data_(data), size_(size) {}
 166       virtual ~Buffer() {}
 167
 168       const int id_;
 169       void* const data_;
 170       const size_t size_;
 171     };
 172
 173     virtual ~Client() {}
 174
 175     // Reserve an output buffer into which contents can be captured directly.
 176     // The returned Buffer will always be allocated with a memory size suitable
 177     // for holding a packed video frame with pixels of |format| format, of
 178     // |dimensions| frame dimensions. It is permissible for |dimensions| to be
 179     // zero; in which case the returned Buffer does not guarantee memory
 180     // backing, but functions as a reservation for external input for the
 181     // purposes of buffer throttling.
 182     //
 183     // The output buffer stays reserved for use until the Buffer object is
 184     // destroyed.
 185     virtual scoped_refptr<Buffer> ReserveOutputBuffer(
 186         media::VideoFrame::Format format,
 187         const gfx::Size& dimensions) = 0;
 188
 189     // Captured a new video frame, data for which is pointed to by |data|.
 190     //
 191     // The format of the frame is described by |frame_format|, and is assumed to
 192     // be tightly packed. This method will try to reserve an output buffer and
 193     // copy from |data| into the output buffer. If no output buffer is
 194     // available, the frame will be silently dropped.
 195     virtual void OnIncomingCapturedData(const uint8* data,
 196                                         int length,
 197                                         const VideoCaptureFormat& frame_format,
 198                                         int rotation,  // Clockwise.
 199                                         base::TimeTicks timestamp) = 0;
 200
 201     // Captured a new video frame, held in |frame|.
 202     //
 203     // As the frame is backed by a reservation returned by
 204     // ReserveOutputBuffer(), delivery is guaranteed and will require no
 205     // additional copies in the browser process.
 206     virtual void OnIncomingCapturedVideoFrame(
 207         const scoped_refptr<Buffer>& buffer,
 208         const VideoCaptureFormat& buffer_format,
 209         const scoped_refptr<media::VideoFrame>& frame,
 210         base::TimeTicks timestamp) = 0;
 211
 212     // An error has occurred that cannot be handled and VideoCaptureDevice must
 213     // be StopAndDeAllocate()-ed. |reason| is a text description of the error.
 214     virtual void OnError(const std::string& reason) = 0;
 215
 216     // VideoCaptureDevice requests the |message| to be logged.
 217     virtual void OnLog(const std::string& message) {}
 218   };
 219
 220   // Creates a VideoCaptureDevice object.
 221   // Return NULL if the hardware is not available.
 222   static VideoCaptureDevice* Create(
 223       scoped_refptr<base::SingleThreadTaskRunner> ui_task_runner,
 224       const Name& device_name);
 225   virtual ~VideoCaptureDevice();
 226
 227   // Gets the names of all video capture devices connected to this computer.
 228   static void GetDeviceNames(Names* device_names);
 229
 230   // Gets the supported formats of a particular device attached to the system.
 231   // This method should be called before allocating or starting a device. In
 232   // case format enumeration is not supported, or there was a problem, the
 233   // formats array will be empty.
 234   static void GetDeviceSupportedFormats(const Name& device,
 235                                         VideoCaptureFormats* supported_formats);
 236
 237   // Prepares the camera for use. After this function has been called no other
 238   // applications can use the camera. StopAndDeAllocate() must be called before
 239   // the object is deleted.
 240   virtual void AllocateAndStart(const VideoCaptureParams& params,
 241                                 scoped_ptr<Client> client) = 0;
 242
 243   // Deallocates the camera, possibly asynchronously.
 244   //
 245   // This call requires the device to do the following things, eventually: put
 246   // camera hardware into a state where other applications could use it, free
 247   // the memory associated with capture, and delete the |client| pointer passed
 248   // into AllocateAndStart.
 249   //
 250   // If deallocation is done asynchronously, then the device implementation must
 251   // ensure that a subsequent AllocateAndStart() operation targeting the same ID
 252   // would be sequenced through the same task runner, so that deallocation
 253   // happens first.
 254   virtual void StopAndDeAllocate() = 0;
 255
 256   // Gets the power line frequency from the current system time zone if this is
 257   // defined, otherwise returns 0.
 258   int GetPowerLineFrequencyForLocation() const;
 259
 260  protected:
 261   static const int kPowerLine50Hz = 50;
 262   static const int kPowerLine60Hz = 60;
 263 };
 264
 265 }  // namespace media
 266
 267 #endif  // MEDIA_VIDEO_CAPTURE_VIDEO_CAPTURE_DEVICE_H_