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 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(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() { return -1; } 93 94 /** 95 Not supported. 96 */ 97 virtual int32_t Process() { 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 Denoises a video frame. Every frame from the stream should be passed in. 181 Has a fixed-point implementation. 182 183 \param[in,out] frame 184 Pointer to the video frame. 185 186 \return The number of modified pixels on success, -1 on failure. 187 */ 188 virtual int32_t Denoising(I420VideoFrame* frame) = 0; 189 190 /** 191 Detects if a video frame is excessively bright or dark. Returns a 192 warning if this is the case. Multiple frames should be passed in before 193 expecting a warning. Has a floating-point implementation. 194 195 \param[in] frame 196 Pointer to the video frame. 197 198 \param[in] stats 199 Frame statistics provided by GetFrameStats(). 200 201 \return A member of BrightnessWarning on success, -1 on error 202 */ 203 virtual int32_t BrightnessDetection(const I420VideoFrame& frame, 204 const FrameStats& stats) = 0; 205 206 /** 207 The following functions refer to the pre-processor unit within VPM. The 208 pre-processor perfoms spatial/temporal decimation and content analysis on 209 the frames prior to encoding. 210 */ 211 212 /** 213 Enable/disable temporal decimation 214 215 \param[in] enable when true, temporal decimation is enabled 216 */ 217 virtual void EnableTemporalDecimation(bool enable) = 0; 218 219 /** 220 Set target resolution 221 222 \param[in] width 223 Target width 224 225 \param[in] height 226 Target height 227 228 \param[in] frame_rate 229 Target frame_rate 230 231 \return VPM_OK on success, a negative value on error (see error codes) 232 233 */ 234 virtual int32_t SetTargetResolution(uint32_t width, 235 uint32_t height, 236 uint32_t frame_rate) = 0; 237 238 /** 239 Get decimated(target) frame rate 240 */ 241 virtual uint32_t Decimatedframe_rate() = 0; 242 243 /** 244 Get decimated(target) frame width 245 */ 246 virtual uint32_t DecimatedWidth() const = 0; 247 248 /** 249 Get decimated(target) frame height 250 */ 251 virtual uint32_t DecimatedHeight() const = 0 ; 252 253 /** 254 Set the spatial resampling settings of the VPM: The resampler may either be 255 disabled or one of the following: 256 scaling to a close to target dimension followed by crop/pad 257 258 \param[in] resampling_mode 259 Set resampling mode (a member of VideoFrameResampling) 260 */ 261 virtual void SetInputFrameResampleMode(VideoFrameResampling 262 resampling_mode) = 0; 263 264 /** 265 Get Processed (decimated) frame 266 267 \param[in] frame pointer to the video frame. 268 \param[in] processed_frame pointer (double) to the processed frame. If no 269 processing is required, processed_frame will be NULL. 270 271 \return VPM_OK on success, a negative value on error (see error codes) 272 */ 273 virtual int32_t PreprocessFrame(const I420VideoFrame& frame, 274 I420VideoFrame** processed_frame) = 0; 275 276 /** 277 Return content metrics for the last processed frame 278 */ 279 virtual VideoContentMetrics* ContentMetrics() const = 0 ; 280 281 /** 282 Enable content analysis 283 */ 284 virtual void EnableContentAnalysis(bool enable) = 0; 285 }; 286 287 } // namespace webrtc 288 289 #endif // WEBRTC_MODULES_INTERFACE_VIDEO_PROCESSING_H 290
