src/third_party/webrtc/modules/video_processing/main/interface/video_processing.h

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