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.
5 // VideoCaptureController is the glue between a VideoCaptureDevice and all
6 // VideoCaptureHosts that have connected to it. A controller exists on behalf of
7 // one (and only one) VideoCaptureDevice; both are owned by the
8 // VideoCaptureManager.
10 // The VideoCaptureController is responsible for:
12 // * Allocating and keeping track of shared memory buffers, and filling them
13 // with I420 video frames for IPC communication between VideoCaptureHost (in
14 // the browser process) and VideoCaptureMessageFilter (in the renderer
16 // * Broadcasting the events from a single VideoCaptureDevice, fanning them
17 // out to multiple clients.
18 // * Keeping track of the clients on behalf of the VideoCaptureManager, making
19 // it possible for the Manager to delete the Controller and its Device when
20 // there are no clients left.
22 // A helper class, VCC::VideoCaptureDeviceClient, is responsible for:
24 // * Conveying events from the device thread (where VideoCaptureDevices live)
25 // the IO thread (where the VideoCaptureController lives).
26 // * Performing some image transformations on the output of the Device;
27 // specifically, colorspace conversion and rotation.
29 // Interactions between VideoCaptureController and other classes:
31 // * VideoCaptureController indirectly observes a VideoCaptureDevice
32 // by means of its proxy, VideoCaptureDeviceClient, which implements
33 // the VideoCaptureDevice::Client interface. The proxy forwards
34 // observed events to the VideoCaptureController on the IO thread.
35 // * A VideoCaptureController interacts with its clients (VideoCaptureHosts)
36 // via the VideoCaptureControllerEventHandler interface.
37 // * Conversely, a VideoCaptureControllerEventHandler (typically,
38 // VideoCaptureHost) will interact directly with VideoCaptureController to
39 // return leased buffers by means of the ReturnBuffer() public method of
41 // * VideoCaptureManager (which owns the VCC) interacts directly with
42 // VideoCaptureController through its public methods, to add and remove
45 // VideoCaptureController is not thread safe and operates on the IO thread only.
47 #ifndef CONTENT_BROWSER_RENDERER_HOST_MEDIA_VIDEO_CAPTURE_CONTROLLER_H_
48 #define CONTENT_BROWSER_RENDERER_HOST_MEDIA_VIDEO_CAPTURE_CONTROLLER_H_
52 #include "base/compiler_specific.h"
53 #include "base/memory/ref_counted.h"
54 #include "base/memory/scoped_ptr.h"
55 #include "base/memory/weak_ptr.h"
56 #include "base/process/process.h"
57 #include "content/browser/renderer_host/media/video_capture_buffer_pool.h"
58 #include "content/browser/renderer_host/media/video_capture_controller_event_handler.h"
59 #include "content/common/content_export.h"
60 #include "content/common/media/video_capture.h"
61 #include "media/video/capture/video_capture_device.h"
62 #include "media/video/capture/video_capture_types.h"
65 class VideoCaptureBufferPool;
67 class CONTENT_EXPORT VideoCaptureController {
69 // |max_buffers| is the maximum number of video frame buffers in-flight at any
70 // one time. This value should be based on the logical capacity of the
71 // capture pipeline, and not on hardware performance. For example, tab
72 // capture requires more buffers than webcam capture because the pipeline is
73 // longer (it includes read-backs pending in the GPU pipeline).
74 explicit VideoCaptureController(int max_buffers);
75 virtual ~VideoCaptureController();
77 base::WeakPtr<VideoCaptureController> GetWeakPtr();
79 // Return a new VideoCaptureDeviceClient to forward capture events to this
81 scoped_ptr<media::VideoCaptureDevice::Client> NewDeviceClient();
83 // Start video capturing and try to use the resolution specified in |params|.
84 // Buffers will be shared to the client as necessary. The client will continue
85 // to receive frames from the device until RemoveClient() is called.
86 void AddClient(const VideoCaptureControllerID& id,
87 VideoCaptureControllerEventHandler* event_handler,
88 base::ProcessHandle render_process,
89 media::VideoCaptureSessionId session_id,
90 const media::VideoCaptureParams& params);
92 // Stop video capture. This will take back all buffers held by by
93 // |event_handler|, and |event_handler| shouldn't use those buffers any more.
94 // Returns the session_id of the stopped client, or
95 // kInvalidMediaCaptureSessionId if the indicated client was not registered.
96 int RemoveClient(const VideoCaptureControllerID& id,
97 VideoCaptureControllerEventHandler* event_handler);
99 // Pause or resume the video capture for specified client.
100 void PauseOrResumeClient(const VideoCaptureControllerID& id,
101 VideoCaptureControllerEventHandler* event_handler,
104 int GetClientCount() const;
106 // Return the number of clients that aren't paused.
107 int GetActiveClientCount() const;
109 // API called directly by VideoCaptureManager in case the device is
110 // prematurely closed.
111 void StopSession(int session_id);
113 // Return a buffer with id |buffer_id| previously given in
114 // VideoCaptureControllerEventHandler::OnBufferReady. In the case that the
115 // buffer was backed by a texture, |sync_point| will be waited on before
116 // destroying or recycling the texture, to synchronize with texture users in
117 // the renderer process.
118 void ReturnBuffer(const VideoCaptureControllerID& id,
119 VideoCaptureControllerEventHandler* event_handler,
123 const media::VideoCaptureFormat& GetVideoCaptureFormat() const;
126 class VideoCaptureDeviceClient;
128 struct ControllerClient;
129 typedef std::list<ControllerClient*> ControllerClients;
131 // Worker functions on IO thread. Called by the VideoCaptureDeviceClient.
132 void DoIncomingCapturedVideoFrameOnIOThread(
133 const scoped_refptr<media::VideoCaptureDevice::Client::Buffer>& buffer,
134 const media::VideoCaptureFormat& format,
135 const scoped_refptr<media::VideoFrame>& frame,
136 base::TimeTicks timestamp);
137 void DoErrorOnIOThread();
138 void DoDeviceStoppedOnIOThread();
139 void DoBufferDestroyedOnIOThread(int buffer_id_to_drop);
141 // Find a client of |id| and |handler| in |clients|.
142 ControllerClient* FindClient(
143 const VideoCaptureControllerID& id,
144 VideoCaptureControllerEventHandler* handler,
145 const ControllerClients& clients);
147 // Find a client of |session_id| in |clients|.
148 ControllerClient* FindClient(
150 const ControllerClients& clients);
152 // The pool of shared-memory buffers used for capturing.
153 const scoped_refptr<VideoCaptureBufferPool> buffer_pool_;
155 // All clients served by this controller.
156 ControllerClients controller_clients_;
158 // Takes on only the states 'STARTED' and 'ERROR'. 'ERROR' is an absorbing
159 // state which stops the flow of data to clients.
160 VideoCaptureState state_;
162 // True if the controller has received a video frame from the device.
163 bool frame_received_;
165 media::VideoCaptureFormat video_capture_format_;
167 base::WeakPtrFactory<VideoCaptureController> weak_ptr_factory_;
169 DISALLOW_COPY_AND_ASSIGN(VideoCaptureController);
172 } // namespace content
174 #endif // CONTENT_BROWSER_RENDERER_HOST_MEDIA_VIDEO_CAPTURE_CONTROLLER_H_