OLD | NEW |
| (Empty) |
1 /* | |
2 * Copyright (c) 2011 The WebRTC project authors. All Rights Reserved. | |
3 * | |
4 * Use of this source code is governed by a BSD-style license | |
5 * that can be found in the LICENSE file in the root of the source | |
6 * tree. An additional intellectual property rights grant can be found | |
7 * in the file PATENTS. All contributing project authors may | |
8 * be found in the AUTHORS file in the root of the source tree. | |
9 */ | |
10 | |
11 /* | |
12 * video_processing.h | |
13 * This header file contains the API required for the video | |
14 * processing module class. | |
15 */ | |
16 | |
17 | |
18 #ifndef WEBRTC_MODULES_INTERFACE_VIDEO_PROCESSING_H | |
19 #define WEBRTC_MODULES_INTERFACE_VIDEO_PROCESSING_H | |
20 | |
21 #include "webrtc/modules/include/module.h" | |
22 #include "webrtc/modules/include/module_common_types.h" | |
23 #include "webrtc/modules/video_processing/main/interface/video_processing_define
s.h" | |
24 #include "webrtc/video_frame.h" | |
25 | |
26 /** | |
27 The module is largely intended to process video streams, except functionality | |
28 provided by static functions which operate independent of previous frames. It | |
29 is recommended, but not required that a unique instance be used for each | |
30 concurrently processed stream. Similarly, it is recommended to call Reset() | |
31 before switching to a new stream, but this is not absolutely required. | |
32 | |
33 The module provides basic thread safety by permitting only a single function | |
34 to execute concurrently. | |
35 */ | |
36 | |
37 namespace webrtc { | |
38 | |
39 class VideoProcessingModule : public Module { | |
40 public: | |
41 /** | |
42 Structure to hold frame statistics. Populate it with GetFrameStats(). | |
43 */ | |
44 struct FrameStats { | |
45 FrameStats() : | |
46 mean(0), | |
47 sum(0), | |
48 num_pixels(0), | |
49 subSamplWidth(0), | |
50 subSamplHeight(0) { | |
51 memset(hist, 0, sizeof(hist)); | |
52 } | |
53 | |
54 uint32_t hist[256]; // FRame histogram. | |
55 uint32_t mean; // Frame Mean value. | |
56 uint32_t sum; // Sum of frame. | |
57 uint32_t num_pixels; // Number of pixels. | |
58 uint8_t subSamplWidth; // Subsampling rate of width in powers of 2. | |
59 uint8_t subSamplHeight; // Subsampling rate of height in powers of 2. | |
60 }; | |
61 | |
62 /** | |
63 Specifies the warning types returned by BrightnessDetection(). | |
64 */ | |
65 enum BrightnessWarning { | |
66 kNoWarning, // Frame has acceptable brightness. | |
67 kDarkWarning, // Frame is too dark. | |
68 kBrightWarning // Frame is too bright. | |
69 }; | |
70 | |
71 /* | |
72 Creates a VPM object. | |
73 | |
74 \param[in] id | |
75 Unique identifier of this object. | |
76 | |
77 \return Pointer to a VPM object. | |
78 */ | |
79 static VideoProcessingModule* Create(); | |
80 | |
81 /** | |
82 Destroys a VPM object. | |
83 | |
84 \param[in] module | |
85 Pointer to the VPM object to destroy. | |
86 */ | |
87 static void Destroy(VideoProcessingModule* module); | |
88 | |
89 /** | |
90 Not supported. | |
91 */ | |
92 int64_t TimeUntilNextProcess() override { return -1; } | |
93 | |
94 /** | |
95 Not supported. | |
96 */ | |
97 int32_t Process() override { return -1; } | |
98 | |
99 /** | |
100 Resets all processing components to their initial states. This should be | |
101 called whenever a new video stream is started. | |
102 */ | |
103 virtual void Reset() = 0; | |
104 | |
105 /** | |
106 Retrieves statistics for the input frame. This function must be used to | |
107 prepare a FrameStats struct for use in certain VPM functions. | |
108 | |
109 \param[out] stats | |
110 The frame statistics will be stored here on return. | |
111 | |
112 \param[in] frame | |
113 Reference to the video frame. | |
114 | |
115 \return 0 on success, -1 on failure. | |
116 */ | |
117 static int32_t GetFrameStats(FrameStats* stats, const VideoFrame& frame); | |
118 | |
119 /** | |
120 Checks the validity of a FrameStats struct. Currently, valid implies only | |
121 that is had changed from its initialized state. | |
122 | |
123 \param[in] stats | |
124 Frame statistics. | |
125 | |
126 \return True on valid stats, false on invalid stats. | |
127 */ | |
128 static bool ValidFrameStats(const FrameStats& stats); | |
129 | |
130 /** | |
131 Returns a FrameStats struct to its intialized state. | |
132 | |
133 \param[in,out] stats | |
134 Frame statistics. | |
135 */ | |
136 static void ClearFrameStats(FrameStats* stats); | |
137 | |
138 /** | |
139 Increases/decreases the luminance value. | |
140 | |
141 \param[in,out] frame | |
142 Pointer to the video frame. | |
143 | |
144 \param[in] delta | |
145 The amount to change the chrominance value of every single pixel. | |
146 Can be < 0 also. | |
147 | |
148 \return 0 on success, -1 on failure. | |
149 */ | |
150 static int32_t Brighten(VideoFrame* frame, int delta); | |
151 | |
152 /** | |
153 Detects and removes camera flicker from a video stream. Every frame from | |
154 the stream must be passed in. A frame will only be altered if flicker has | |
155 been detected. Has a fixed-point implementation. | |
156 | |
157 \param[in,out] frame | |
158 Pointer to the video frame. | |
159 | |
160 \param[in,out] stats | |
161 Frame statistics provided by GetFrameStats(). On return the stats will | |
162 be reset to zero if the frame was altered. Call GetFrameStats() again | |
163 if the statistics for the altered frame are required. | |
164 | |
165 \return 0 on success, -1 on failure. | |
166 */ | |
167 virtual int32_t Deflickering(VideoFrame* frame, FrameStats* stats) = 0; | |
168 | |
169 /** | |
170 Detects if a video frame is excessively bright or dark. Returns a | |
171 warning if this is the case. Multiple frames should be passed in before | |
172 expecting a warning. Has a floating-point implementation. | |
173 | |
174 \param[in] frame | |
175 Pointer to the video frame. | |
176 | |
177 \param[in] stats | |
178 Frame statistics provided by GetFrameStats(). | |
179 | |
180 \return A member of BrightnessWarning on success, -1 on error | |
181 */ | |
182 virtual int32_t BrightnessDetection(const VideoFrame& frame, | |
183 const FrameStats& stats) = 0; | |
184 | |
185 /** | |
186 The following functions refer to the pre-processor unit within VPM. The | |
187 pre-processor perfoms spatial/temporal decimation and content analysis on | |
188 the frames prior to encoding. | |
189 */ | |
190 | |
191 /** | |
192 Enable/disable temporal decimation | |
193 | |
194 \param[in] enable when true, temporal decimation is enabled | |
195 */ | |
196 virtual void EnableTemporalDecimation(bool enable) = 0; | |
197 | |
198 /** | |
199 Set target resolution | |
200 | |
201 \param[in] width | |
202 Target width | |
203 | |
204 \param[in] height | |
205 Target height | |
206 | |
207 \param[in] frame_rate | |
208 Target frame_rate | |
209 | |
210 \return VPM_OK on success, a negative value on error (see error codes) | |
211 | |
212 */ | |
213 virtual int32_t SetTargetResolution(uint32_t width, | |
214 uint32_t height, | |
215 uint32_t frame_rate) = 0; | |
216 | |
217 virtual void SetTargetFramerate(int frame_rate) {} | |
218 | |
219 /** | |
220 Get decimated(target) frame rate | |
221 */ | |
222 virtual uint32_t Decimatedframe_rate() = 0; | |
223 | |
224 /** | |
225 Get decimated(target) frame width | |
226 */ | |
227 virtual uint32_t DecimatedWidth() const = 0; | |
228 | |
229 /** | |
230 Get decimated(target) frame height | |
231 */ | |
232 virtual uint32_t DecimatedHeight() const = 0 ; | |
233 | |
234 /** | |
235 Set the spatial resampling settings of the VPM: The resampler may either be | |
236 disabled or one of the following: | |
237 scaling to a close to target dimension followed by crop/pad | |
238 | |
239 \param[in] resampling_mode | |
240 Set resampling mode (a member of VideoFrameResampling) | |
241 */ | |
242 virtual void SetInputFrameResampleMode(VideoFrameResampling | |
243 resampling_mode) = 0; | |
244 | |
245 /** | |
246 Get Processed (decimated) frame | |
247 | |
248 \param[in] frame pointer to the video frame. | |
249 \param[in] processed_frame pointer (double) to the processed frame. If no | |
250 processing is required, processed_frame will be NULL. | |
251 | |
252 \return VPM_OK on success, a negative value on error (see error codes) | |
253 */ | |
254 virtual int32_t PreprocessFrame(const VideoFrame& frame, | |
255 VideoFrame** processed_frame) = 0; | |
256 | |
257 /** | |
258 Return content metrics for the last processed frame | |
259 */ | |
260 virtual VideoContentMetrics* ContentMetrics() const = 0 ; | |
261 | |
262 /** | |
263 Enable content analysis | |
264 */ | |
265 virtual void EnableContentAnalysis(bool enable) = 0; | |
266 }; | |
267 | |
268 } // namespace webrtc | |
269 | |
270 #endif // WEBRTC_MODULES_INTERFACE_VIDEO_PROCESSING_H | |
OLD | NEW |