granicus.if.org Git - libvpx/blob - vpx/vp8.h

   1 /*
   2  *  Copyright (c) 2010 The WebM 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 /*!\defgroup vp8 VP8
  13  * \ingroup codecs
  14  * VP8 is vpx's newest video compression algorithm that uses motion
  15  * compensated prediction, Discrete Cosine Transform (DCT) coding of the
  16  * prediction error signal and context dependent entropy coding techniques
  17  * based on arithmetic principles. It features:
  18  *  - YUV 4:2:0 image format
  19  *  - Macro-block based coding (16x16 luma plus two 8x8 chroma)
  20  *  - 1/4 (1/8) pixel accuracy motion compensated prediction
  21  *  - 4x4 DCT transform
  22  *  - 128 level linear quantizer
  23  *  - In loop deblocking filter
  24  *  - Context-based entropy coding
  25  *
  26  * @{
  27  */
  28 /*!\file
  29  * \brief Provides controls common to both the VP8 encoder and decoder.
  30  */
  31 #ifndef VP8_H
  32 #define VP8_H
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /*!\brief Control functions
  39  *
  40  * The set of macros define the control functions of VP8 interface
  41  */
  42 enum vp8_com_control_id {
  43   VP8_SET_REFERENCE           = 1,    /**< pass in an external frame into decoder to be used as reference frame */
  44   VP8_COPY_REFERENCE          = 2,    /**< get a copy of reference frame from the decoder */
  45   VP8_SET_POSTPROC            = 3,    /**< set the decoder's post processing settings  */
  46   VP8_SET_DBG_COLOR_REF_FRAME = 4,    /**< set the reference frames to color for each macroblock */
  47   VP8_SET_DBG_COLOR_MB_MODES  = 5,    /**< set which macro block modes to color */
  48   VP8_SET_DBG_COLOR_B_MODES   = 6,    /**< set which blocks modes to color */
  49   VP8_SET_DBG_DISPLAY_MV      = 7,    /**< set which motion vector modes to draw */
  50
  51   /* TODO(jkoleszar): The encoder incorrectly reuses some of these values (5+)
  52    * for its control ids. These should be migrated to something like the
  53    * VP8_DECODER_CTRL_ID_START range next time we're ready to break the ABI.
  54    */
  55   VP9_GET_REFERENCE           = 128,  /**< get a pointer to a reference frame */
  56   VP8_COMMON_CTRL_ID_MAX,
  57   VP8_DECODER_CTRL_ID_START   = 256
  58 };
  59
  60 /*!\brief post process flags
  61  *
  62  * The set of macros define VP8 decoder post processing flags
  63  */
  64 enum vp8_postproc_level {
  65   VP8_NOFILTERING             = 0,
  66   VP8_DEBLOCK                 = 1 << 0,
  67   VP8_DEMACROBLOCK            = 1 << 1,
  68   VP8_ADDNOISE                = 1 << 2,
  69   VP8_DEBUG_TXT_FRAME_INFO    = 1 << 3, /**< print frame information */
  70   VP8_DEBUG_TXT_MBLK_MODES    = 1 << 4, /**< print macro block modes over each macro block */
  71   VP8_DEBUG_TXT_DC_DIFF       = 1 << 5, /**< print dc diff for each macro block */
  72   VP8_DEBUG_TXT_RATE_INFO     = 1 << 6, /**< print video rate info (encoder only) */
  73   VP8_MFQE                    = 1 << 10
  74 };
  75
  76 /*!\brief post process flags
  77  *
  78  * This define a structure that describe the post processing settings. For
  79  * the best objective measure (using the PSNR metric) set post_proc_flag
  80  * to VP8_DEBLOCK and deblocking_level to 1.
  81  */
  82
  83 typedef struct vp8_postproc_cfg {
  84   int post_proc_flag;         /**< the types of post processing to be done, should be combination of "vp8_postproc_level" */
  85   int deblocking_level;       /**< the strength of deblocking, valid range [0, 16] */
  86   int noise_level;            /**< the strength of additive noise, valid range [0, 16] */
  87 } vp8_postproc_cfg_t;
  88
  89 /*!\brief reference frame type
  90  *
  91  * The set of macros define the type of VP8 reference frames
  92  */
  93 typedef enum vpx_ref_frame_type {
  94   VP8_LAST_FRAME = 1,
  95   VP8_GOLD_FRAME = 2,
  96   VP8_ALTR_FRAME = 4
  97 } vpx_ref_frame_type_t;
  98
  99 /*!\brief reference frame data struct
 100  *
 101  * define the data struct to access vp8 reference frames
 102  */
 103
 104 typedef struct vpx_ref_frame {
 105   vpx_ref_frame_type_t  frame_type;   /**< which reference frame */
 106   vpx_image_t           img;          /**< reference frame data in image format */
 107 } vpx_ref_frame_t;
 108
 109 typedef struct vp9_ref_frame {
 110   int idx; /**< frame index to get (input) */
 111   vpx_image_t  img; /**< img structure to populate (output) */
 112 } vp9_ref_frame_t;
 113
 114 /*!\brief vp8 decoder control function parameter type
 115  *
 116  * defines the data type for each of VP8 decoder control function requires
 117  */
 118
 119 VPX_CTRL_USE_TYPE(VP8_SET_REFERENCE,           vpx_ref_frame_t *)
 120 VPX_CTRL_USE_TYPE(VP8_COPY_REFERENCE,          vpx_ref_frame_t *)
 121 VPX_CTRL_USE_TYPE(VP8_SET_POSTPROC,            vp8_postproc_cfg_t *)
 122 VPX_CTRL_USE_TYPE(VP8_SET_DBG_COLOR_REF_FRAME, int)
 123 VPX_CTRL_USE_TYPE(VP8_SET_DBG_COLOR_MB_MODES,  int)
 124 VPX_CTRL_USE_TYPE(VP8_SET_DBG_COLOR_B_MODES,   int)
 125 VPX_CTRL_USE_TYPE(VP8_SET_DBG_DISPLAY_MV,      int)
 126 VPX_CTRL_USE_TYPE(VP9_GET_REFERENCE,           vp9_ref_frame_t *)
 127
 128
 129 /*! @} - end defgroup vp8 */
 130
 131 #ifdef __cplusplus
 132 }  // extern "C"
 133 #endif
 134
 135 #endif