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/common_video/interface/i420_video_frame.h"
22#include "webrtc/modules/interface/module.h"
23#include "webrtc/modules/interface/module_common_types.h"
24#include "webrtc/modules/video_processing/main/interface/video_processing_defines.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
37namespace webrtc {
38
39class 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(int32_t id);
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  virtual int32_t TimeUntilNextProcess() OVERRIDE { return -1; }
93
94  /**
95     Not supported.
96  */
97  virtual 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,
118                               const I420VideoFrame& frame);
119
120  /**
121     Checks the validity of a FrameStats struct. Currently, valid implies only
122     that is had changed from its initialized state.
123
124     \param[in] stats
125         Frame statistics.
126
127     \return True on valid stats, false on invalid stats.
128  */
129  static bool ValidFrameStats(const FrameStats& stats);
130
131  /**
132     Returns a FrameStats struct to its intialized state.
133
134     \param[in,out] stats
135         Frame statistics.
136  */
137  static void ClearFrameStats(FrameStats* stats);
138
139  /**
140     Enhances the color of an image through a constant mapping. Only the
141     chrominance is altered. Has a fixed-point implementation.
142
143     \param[in,out] frame
144         Pointer to the video frame.
145  */
146  static int32_t ColorEnhancement(I420VideoFrame* frame);
147
148  /**
149     Increases/decreases the luminance value.
150
151     \param[in,out] frame
152         Pointer to the video frame.
153
154    \param[in] delta
155         The amount to change the chrominance value of every single pixel.
156         Can be < 0 also.
157
158     \return 0 on success, -1 on failure.
159  */
160  static int32_t Brighten(I420VideoFrame* frame, int delta);
161
162  /**
163     Detects and removes camera flicker from a video stream. Every frame from
164     the stream must be passed in. A frame will only be altered if flicker has
165     been detected. Has a fixed-point implementation.
166
167     \param[in,out] frame
168         Pointer to the video frame.
169
170     \param[in,out] stats
171         Frame statistics provided by GetFrameStats(). On return the stats will
172         be reset to zero if the frame was altered. Call GetFrameStats() again
173         if the statistics for the altered frame are required.
174
175     \return 0 on success, -1 on failure.
176  */
177  virtual int32_t Deflickering(I420VideoFrame* frame, FrameStats* stats) = 0;
178
179  /**
180     Detects if a video frame is excessively bright or dark. Returns a
181     warning if this is the case. Multiple frames should be passed in before
182     expecting a warning. Has a floating-point implementation.
183
184     \param[in] frame
185         Pointer to the video frame.
186
187     \param[in] stats
188         Frame statistics provided by GetFrameStats().
189
190     \return A member of BrightnessWarning on success, -1 on error
191  */
192  virtual int32_t BrightnessDetection(const I420VideoFrame& frame,
193                                      const FrameStats& stats) = 0;
194
195  /**
196  The following functions refer to the pre-processor unit within VPM. The
197  pre-processor perfoms spatial/temporal decimation and content analysis on
198  the frames prior to encoding.
199  */
200
201  /**
202  Enable/disable temporal decimation
203
204  \param[in] enable when true, temporal decimation is enabled
205  */
206  virtual void EnableTemporalDecimation(bool enable) = 0;
207
208  /**
209 Set target resolution
210
211 \param[in] width
212 Target width
213
214 \param[in] height
215 Target height
216
217  \param[in] frame_rate
218  Target frame_rate
219
220  \return VPM_OK on success, a negative value on error (see error codes)
221
222  */
223  virtual int32_t SetTargetResolution(uint32_t width,
224                                      uint32_t height,
225                                      uint32_t frame_rate) = 0;
226
227  /**
228  Get decimated(target) frame rate
229  */
230  virtual uint32_t Decimatedframe_rate() = 0;
231
232  /**
233  Get decimated(target) frame width
234  */
235  virtual uint32_t DecimatedWidth() const = 0;
236
237  /**
238  Get decimated(target) frame height
239  */
240  virtual uint32_t DecimatedHeight() const = 0 ;
241
242  /**
243  Set the spatial resampling settings of the VPM: The resampler may either be
244  disabled or one of the following:
245  scaling to a close to target dimension followed by crop/pad
246
247  \param[in] resampling_mode
248  Set resampling mode (a member of VideoFrameResampling)
249  */
250  virtual void SetInputFrameResampleMode(VideoFrameResampling
251                                         resampling_mode) = 0;
252
253  /**
254  Get Processed (decimated) frame
255
256  \param[in] frame pointer to the video frame.
257  \param[in] processed_frame pointer (double) to the processed frame. If no
258             processing is required, processed_frame will be NULL.
259
260  \return VPM_OK on success, a negative value on error (see error codes)
261  */
262  virtual int32_t PreprocessFrame(const I420VideoFrame& frame,
263                                  I420VideoFrame** processed_frame) = 0;
264
265  /**
266  Return content metrics for the last processed frame
267  */
268  virtual VideoContentMetrics* ContentMetrics() const = 0 ;
269
270  /**
271  Enable content analysis
272  */
273  virtual void EnableContentAnalysis(bool enable) = 0;
274};
275
276}  // namespace webrtc
277
278#endif  // WEBRTC_MODULES_INTERFACE_VIDEO_PROCESSING_H
279