| OLD | NEW |
|---|
| (Empty) |
| 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_CAPTURE_VIDEO_VIDEO_CAPTURE_DEVICE_H_ | |
| 13 #define MEDIA_CAPTURE_VIDEO_VIDEO_CAPTURE_DEVICE_H_ | |
| 14 | |
| 15 #include <stddef.h> | |
| 16 #include <stdint.h> | |
| 17 | |
| 18 #include <list> | |
| 19 #include <memory> | |
| 20 #include <string> | |
| 21 | |
| 22 #include "base/callback.h" | |
| 23 #include "base/files/file.h" | |
| 24 #include "base/logging.h" | |
| 25 #include "base/memory/ref_counted.h" | |
| 26 #include "base/single_thread_task_runner.h" | |
| 27 #include "base/time/time.h" | |
| 28 #include "build/build_config.h" | |
| 29 #include "media/base/video_capture_types.h" | |
| 30 #include "media/base/video_frame.h" | |
| 31 #include "media/capture/capture_export.h" | |
| 32 #include "media/capture/video/scoped_result_callback.h" | |
| 33 #include "media/mojo/interfaces/image_capture.mojom.h" | |
| 34 #include "mojo/public/cpp/bindings/array.h" | |
| 35 #include "ui/gfx/gpu_memory_buffer.h" | |
| 36 | |
| 37 namespace tracked_objects { | |
| 38 class Location; | |
| 39 } // namespace tracked_objects | |
| 40 | |
| 41 namespace media { | |
| 42 | |
| 43 class CAPTURE_EXPORT VideoCaptureDevice { | |
| 44 public: | |
| 45 // Represents a capture device name and ID. | |
| 46 // You should not create an instance of this class directly by e.g. setting | |
| 47 // various properties directly. Instead use | |
| 48 // VideoCaptureDevice::GetDeviceNames to do this for you and if you need to | |
| 49 // cache your own copy of a name, you can do so via the copy constructor. | |
| 50 // The reason for this is that a device name might contain platform specific | |
| 51 // settings that are relevant only to the platform specific implementation of | |
| 52 // VideoCaptureDevice::Create. | |
| 53 class CAPTURE_EXPORT Name { | |
| 54 public: | |
| 55 Name(); | |
| 56 Name(const std::string& name, const std::string& id); | |
| 57 | |
| 58 #if defined(OS_LINUX) | |
| 59 // Linux/CrOS targets Capture Api type: it can only be set on construction. | |
| 60 enum CaptureApiType { | |
| 61 V4L2_SINGLE_PLANE, | |
| 62 API_TYPE_UNKNOWN | |
| 63 }; | |
| 64 #elif defined(OS_WIN) | |
| 65 // Windows targets Capture Api type: it can only be set on construction. | |
| 66 enum CaptureApiType { MEDIA_FOUNDATION, DIRECT_SHOW, API_TYPE_UNKNOWN }; | |
| 67 #elif defined(OS_MACOSX) | |
| 68 // Mac targets Capture Api type: it can only be set on construction. | |
| 69 enum CaptureApiType { AVFOUNDATION, DECKLINK, API_TYPE_UNKNOWN }; | |
| 70 // For AVFoundation Api, identify devices that are built-in or USB. | |
| 71 enum TransportType { USB_OR_BUILT_IN, OTHER_TRANSPORT }; | |
| 72 #elif defined(OS_ANDROID) | |
| 73 // Android targets Capture Api type: it can only be set on construction. | |
| 74 // Automatically generated enum to interface with Java world. | |
| 75 // | |
| 76 // A Java counterpart will be generated for this enum. | |
| 77 // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.media | |
| 78 enum CaptureApiType { | |
| 79 API1, | |
| 80 API2_LEGACY, | |
| 81 API2_FULL, | |
| 82 API2_LIMITED, | |
| 83 TANGO, | |
| 84 API_TYPE_UNKNOWN | |
| 85 }; | |
| 86 #endif | |
| 87 | |
| 88 #if defined(OS_WIN) || defined(OS_MACOSX) || defined(OS_LINUX) || \ | |
| 89 defined(OS_ANDROID) | |
| 90 Name(const std::string& name, | |
| 91 const std::string& id, | |
| 92 const CaptureApiType api_type); | |
| 93 #endif | |
| 94 #if defined(OS_MACOSX) | |
| 95 Name(const std::string& name, | |
| 96 const std::string& id, | |
| 97 const CaptureApiType api_type, | |
| 98 const TransportType transport_type); | |
| 99 #endif | |
| 100 Name(const Name& other); | |
| 101 ~Name(); | |
| 102 | |
| 103 // Friendly name of a device | |
| 104 const std::string& name() const { return device_name_; } | |
| 105 | |
| 106 // Unique name of a device. Even if there are multiple devices with the same | |
| 107 // friendly name connected to the computer this will be unique. | |
| 108 const std::string& id() const { return unique_id_; } | |
| 109 | |
| 110 // The unique hardware model identifier of the capture device. Returns | |
| 111 // "[vid]:[pid]" when a USB device is detected, otherwise "". | |
| 112 // The implementation of this method is platform-dependent. | |
| 113 const std::string GetModel() const; | |
| 114 | |
| 115 // Friendly name of a device, plus the model identifier in parentheses. | |
| 116 const std::string GetNameAndModel() const; | |
| 117 | |
| 118 // These operators are needed due to storing the name in an STL container. | |
| 119 // In the shared build, all methods from the STL container will be exported | |
| 120 // so even though they're not used, they're still depended upon. | |
| 121 bool operator==(const Name& other) const { | |
| 122 return other.id() == unique_id_; | |
| 123 } | |
| 124 bool operator<(const Name& other) const { return unique_id_ < other.id(); } | |
| 125 | |
| 126 #if defined(OS_WIN) || defined(OS_MACOSX) || defined(OS_LINUX) || \ | |
| 127 defined(OS_ANDROID) | |
| 128 CaptureApiType capture_api_type() const { | |
| 129 return capture_api_class_.capture_api_type(); | |
| 130 } | |
| 131 const char* GetCaptureApiTypeString() const; | |
| 132 #endif | |
| 133 #if defined(OS_WIN) | |
| 134 // Certain devices need an ID different from the |unique_id_| for | |
| 135 // capabilities retrieval. | |
| 136 const std::string& capabilities_id() const { return capabilities_id_; } | |
| 137 void set_capabilities_id(const std::string& id) { capabilities_id_ = id; } | |
| 138 #endif // if defined(OS_WIN) | |
| 139 #if defined(OS_MACOSX) | |
| 140 TransportType transport_type() const { return transport_type_; } | |
| 141 #endif // if defined(OS_MACOSX) | |
| 142 | |
| 143 private: | |
| 144 std::string device_name_; | |
| 145 std::string unique_id_; | |
| 146 #if defined(OS_WIN) || defined(OS_MACOSX) || defined(OS_LINUX) || \ | |
| 147 defined(OS_ANDROID) | |
| 148 // This class wraps the CaptureApiType to give it a by default value if not | |
| 149 // initialized. | |
| 150 class CaptureApiClass { | |
| 151 public: | |
| 152 CaptureApiClass() : capture_api_type_(API_TYPE_UNKNOWN) {} | |
| 153 CaptureApiClass(const CaptureApiType api_type) | |
| 154 : capture_api_type_(api_type) {} | |
| 155 CaptureApiType capture_api_type() const { | |
| 156 DCHECK_NE(capture_api_type_, API_TYPE_UNKNOWN); | |
| 157 return capture_api_type_; | |
| 158 } | |
| 159 | |
| 160 private: | |
| 161 CaptureApiType capture_api_type_; | |
| 162 }; | |
| 163 | |
| 164 CaptureApiClass capture_api_class_; | |
| 165 #endif | |
| 166 #if defined(OS_WIN) | |
| 167 // ID used for capabilities retrieval. By default is equal to |unique_id|. | |
| 168 std::string capabilities_id_; | |
| 169 #endif | |
| 170 #if defined(OS_MACOSX) | |
| 171 TransportType transport_type_; | |
| 172 #endif | |
| 173 // Allow generated copy constructor and assignment. | |
| 174 }; | |
| 175 | |
| 176 // Manages a list of Name entries. | |
| 177 typedef std::list<Name> Names; | |
| 178 | |
| 179 // Interface defining the methods that clients of VideoCapture must have. It | |
| 180 // is actually two-in-one: clients may implement OnIncomingCapturedData() or | |
| 181 // ReserveOutputBuffer() + OnIncomingCapturedVideoFrame(), or all of them. | |
| 182 // All clients must implement OnError(). | |
| 183 class CAPTURE_EXPORT Client { | |
| 184 public: | |
| 185 // Memory buffer returned by Client::ReserveOutputBuffer(). | |
| 186 class CAPTURE_EXPORT Buffer { | |
| 187 public: | |
| 188 virtual ~Buffer() = 0; | |
| 189 virtual int id() const = 0; | |
| 190 virtual gfx::Size dimensions() const = 0; | |
| 191 virtual size_t mapped_size() const = 0; | |
| 192 virtual void* data(int plane) = 0; | |
| 193 void* data() { return data(0); } | |
| 194 virtual ClientBuffer AsClientBuffer(int plane) = 0; | |
| 195 #if defined(OS_POSIX) && !(defined(OS_MACOSX) && !defined(OS_IOS)) | |
| 196 virtual base::FileDescriptor AsPlatformFile() = 0; | |
| 197 #endif | |
| 198 }; | |
| 199 | |
| 200 virtual ~Client() {} | |
| 201 | |
| 202 // Captured a new video frame, data for which is pointed to by |data|. | |
| 203 // | |
| 204 // The format of the frame is described by |frame_format|, and is assumed to | |
| 205 // be tightly packed. This method will try to reserve an output buffer and | |
| 206 // copy from |data| into the output buffer. If no output buffer is | |
| 207 // available, the frame will be silently dropped. |reference_time| is | |
| 208 // system clock time when we detect the capture happens, it is used for | |
| 209 // Audio/Video sync, not an exact presentation time for playout, because it | |
| 210 // could contain noise. |timestamp| measures the ideal time span between the | |
| 211 // first frame in the stream and the current frame; however, the time source | |
| 212 // is determined by the platform's device driver and is often not the system | |
| 213 // clock, or even has a drift with respect to system clock. | |
| 214 virtual void OnIncomingCapturedData(const uint8_t* data, | |
| 215 int length, | |
| 216 const VideoCaptureFormat& frame_format, | |
| 217 int clockwise_rotation, | |
| 218 base::TimeTicks reference_time, | |
| 219 base::TimeDelta timestamp) = 0; | |
| 220 | |
| 221 // Reserve an output buffer into which contents can be captured directly. | |
| 222 // The returned Buffer will always be allocated with a memory size suitable | |
| 223 // for holding a packed video frame with pixels of |format| format, of | |
| 224 // |dimensions| frame dimensions. It is permissible for |dimensions| to be | |
| 225 // zero; in which case the returned Buffer does not guarantee memory | |
| 226 // backing, but functions as a reservation for external input for the | |
| 227 // purposes of buffer throttling. | |
| 228 // | |
| 229 // The output buffer stays reserved and mapped for use until the Buffer | |
| 230 // object is destroyed or returned. | |
| 231 virtual std::unique_ptr<Buffer> ReserveOutputBuffer( | |
| 232 const gfx::Size& dimensions, | |
| 233 VideoPixelFormat format, | |
| 234 VideoPixelStorage storage) = 0; | |
| 235 | |
| 236 // Captured new video data, held in |frame| or |buffer|, respectively for | |
| 237 // OnIncomingCapturedVideoFrame() and OnIncomingCapturedBuffer(). | |
| 238 // | |
| 239 // In both cases, as the frame is backed by a reservation returned by | |
| 240 // ReserveOutputBuffer(), delivery is guaranteed and will require no | |
| 241 // additional copies in the browser process. | |
| 242 // See OnIncomingCapturedData for details of |reference_time| and | |
| 243 // |timestamp|. | |
| 244 virtual void OnIncomingCapturedBuffer( | |
| 245 std::unique_ptr<Buffer> buffer, | |
| 246 const VideoCaptureFormat& frame_format, | |
| 247 base::TimeTicks reference_time, | |
| 248 base::TimeDelta timestamp) = 0; | |
| 249 virtual void OnIncomingCapturedVideoFrame( | |
| 250 std::unique_ptr<Buffer> buffer, | |
| 251 const scoped_refptr<VideoFrame>& frame) = 0; | |
| 252 | |
| 253 // Attempts to reserve the same Buffer provided in the last call to one of | |
| 254 // the OnIncomingCapturedXXX() methods. This will fail if the content of the | |
| 255 // Buffer has not been preserved, or if the |dimensions|, |format|, or | |
| 256 // |storage| disagree with how it was reserved via ReserveOutputBuffer(). | |
| 257 // When this operation fails, nullptr will be returned. | |
| 258 virtual std::unique_ptr<Buffer> ResurrectLastOutputBuffer( | |
| 259 const gfx::Size& dimensions, | |
| 260 VideoPixelFormat format, | |
| 261 VideoPixelStorage storage) = 0; | |
| 262 | |
| 263 // An error has occurred that cannot be handled and VideoCaptureDevice must | |
| 264 // be StopAndDeAllocate()-ed. |reason| is a text description of the error. | |
| 265 virtual void OnError(const tracked_objects::Location& from_here, | |
| 266 const std::string& reason) = 0; | |
| 267 | |
| 268 // VideoCaptureDevice requests the |message| to be logged. | |
| 269 virtual void OnLog(const std::string& message) {} | |
| 270 | |
| 271 // Returns the current buffer pool utilization, in the range 0.0 (no buffers | |
| 272 // are in use by producers or consumers) to 1.0 (all buffers are in use). | |
| 273 virtual double GetBufferPoolUtilization() const = 0; | |
| 274 }; | |
| 275 | |
| 276 virtual ~VideoCaptureDevice(); | |
| 277 | |
| 278 // Prepares the video capturer for use. StopAndDeAllocate() must be called | |
| 279 // before the object is deleted. | |
| 280 virtual void AllocateAndStart(const VideoCaptureParams& params, | |
| 281 std::unique_ptr<Client> client) = 0; | |
| 282 | |
| 283 // In cases where the video capturer self-pauses (e.g., a screen capturer | |
| 284 // where the screen's content has not changed in a while), consumers may call | |
| 285 // this to request a "refresh frame" be delivered to the Client. This is used | |
| 286 // in a number of circumstances, such as: | |
| 287 // | |
| 288 // 1. An additional consumer of video frames is starting up and requires a | |
| 289 // first frame (as opposed to not receiving a frame for an indeterminate | |
| 290 // amount of time). | |
| 291 // 2. A few repeats of the same frame would allow a lossy video encoder to | |
| 292 // improve the video quality of unchanging content. | |
| 293 // | |
| 294 // The default implementation is a no-op. VideoCaptureDevice implementations | |
| 295 // are not required to honor this request, especially if they do not | |
| 296 // self-pause and/or if honoring the request would cause them to exceed their | |
| 297 // configured maximum frame rate. Any VideoCaptureDevice that does self-pause, | |
| 298 // however, should provide an implementation of this method that makes | |
| 299 // reasonable attempts to honor these requests. | |
| 300 virtual void RequestRefreshFrame() {} | |
| 301 | |
| 302 // Deallocates the video capturer, possibly asynchronously. | |
| 303 // | |
| 304 // This call requires the device to do the following things, eventually: put | |
| 305 // hardware into a state where other applications could use it, free the | |
| 306 // memory associated with capture, and delete the |client| pointer passed into | |
| 307 // AllocateAndStart. | |
| 308 // | |
| 309 // If deallocation is done asynchronously, then the device implementation must | |
| 310 // ensure that a subsequent AllocateAndStart() operation targeting the same ID | |
| 311 // would be sequenced through the same task runner, so that deallocation | |
| 312 // happens first. | |
| 313 virtual void StopAndDeAllocate() = 0; | |
| 314 | |
| 315 // Retrieve the photo capabilities of the device (e.g. zoom levels etc). | |
| 316 using GetPhotoCapabilitiesCallback = | |
| 317 ScopedResultCallback<base::Callback<void(mojom::PhotoCapabilitiesPtr)>>; | |
| 318 virtual void GetPhotoCapabilities(GetPhotoCapabilitiesCallback callback); | |
| 319 | |
| 320 using SetPhotoOptionsCallback = | |
| 321 ScopedResultCallback<base::Callback<void(bool)>>; | |
| 322 virtual void SetPhotoOptions(mojom::PhotoSettingsPtr settings, | |
| 323 SetPhotoOptionsCallback callback); | |
| 324 | |
| 325 // Asynchronously takes a photo, possibly reconfiguring the capture objects | |
| 326 // and/or interrupting the capture flow. Runs |callback| on the thread | |
| 327 // where TakePhoto() is called, if the photo was successfully taken. | |
| 328 using TakePhotoCallback = ScopedResultCallback< | |
| 329 base::Callback<void(mojo::String, mojo::Array<uint8_t>)>>; | |
| 330 virtual void TakePhoto(TakePhotoCallback callback); | |
| 331 | |
| 332 // Gets the power line frequency, either from the params if specified by the | |
| 333 // user or from the current system time zone. | |
| 334 PowerLineFrequency GetPowerLineFrequency( | |
| 335 const VideoCaptureParams& params) const; | |
| 336 | |
| 337 private: | |
| 338 // Gets the power line frequency from the current system time zone if this is | |
| 339 // defined, otherwise returns 0. | |
| 340 PowerLineFrequency GetPowerLineFrequencyForLocation() const; | |
| 341 }; | |
| 342 | |
| 343 } // namespace media | |
| 344 | |
| 345 #endif // MEDIA_CAPTURE_VIDEO_VIDEO_CAPTURE_DEVICE_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2143903003:
[WIP] Move media/capture to device/capture (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@master