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() 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
