aom/aom.h

   1 /*
   2  * Copyright (c) 2016, Alliance for Open Media. All rights reserved
   3  *
   4  * This source code is subject to the terms of the BSD 2 Clause License and
   5  * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
   6  * was not distributed with this source code in the LICENSE file, you can
   7  * obtain it at www.aomedia.org/license/software. If the Alliance for Open
   8  * Media Patent License 1.0 was not distributed with this source code in the
   9  * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
  10  */
  11
  12 /*!\defgroup aom AOM
  13  * \ingroup codecs
  14  * AOM is aom'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 AOM encoder and decoder.
  30  */
  31 #ifndef AOM_AOM_H_
  32 #define AOM_AOM_H_
  33
  34 #include "./aom_codec.h"
  35 #include "./aom_image.h"
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /*!\brief Control functions
  42  *
  43  * The set of macros define the control functions of AOM interface
  44  */
  45 enum aom_com_control_id {
  46   /*!\brief pass in an external frame into decoder to be used as reference frame
  47    */
  48   AOM_SET_POSTPROC = 3, /**< set the decoder's post processing settings  */
  49   AOM_SET_DBG_COLOR_REF_FRAME =
  50       4, /**< set the reference frames to color for each macroblock */
  51   AOM_SET_DBG_COLOR_MB_MODES = 5, /**< set which macro block modes to color */
  52   AOM_SET_DBG_COLOR_B_MODES = 6,  /**< set which blocks modes to color */
  53   AOM_SET_DBG_DISPLAY_MV = 7,     /**< set which motion vector modes to draw */
  54
  55   /* TODO(jkoleszar): The encoder incorrectly reuses some of these values (5+)
  56    * for its control ids. These should be migrated to something like the
  57    * AOM_DECODER_CTRL_ID_START range next time we're ready to break the ABI.
  58    */
  59   AV1_GET_REFERENCE = 128, /**< get a pointer to a reference frame */
  60   AV1_SET_REFERENCE = 129, /**< write a frame into a reference buffer */
  61   AV1_COPY_REFERENCE =
  62       130, /**< get a copy of reference frame from the decoder */
  63   AOM_COMMON_CTRL_ID_MAX,
  64
  65   AV1_GET_NEW_FRAME_IMAGE = 192, /**< get a pointer to the new frame */
  66
  67   AOM_DECODER_CTRL_ID_START = 256
  68 };
  69
  70 /*!\brief post process flags
  71  *
  72  * The set of macros define AOM decoder post processing flags
  73  */
  74 enum aom_postproc_level {
  75   AOM_NOFILTERING = 0,
  76   AOM_DEBLOCK = 1 << 0,
  77   AOM_DEMACROBLOCK = 1 << 1,
  78   AOM_ADDNOISE = 1 << 2,
  79   AOM_DEBUG_TXT_FRAME_INFO = 1 << 3, /**< print frame information */
  80   AOM_DEBUG_TXT_MBLK_MODES =
  81       1 << 4, /**< print macro block modes over each macro block */
  82   AOM_DEBUG_TXT_DC_DIFF = 1 << 5,   /**< print dc diff for each macro block */
  83   AOM_DEBUG_TXT_RATE_INFO = 1 << 6, /**< print video rate info (encoder only) */
  84   AOM_MFQE = 1 << 10
  85 };
  86
  87 /*!\brief post process flags
  88  *
  89  * This define a structure that describe the post processing settings. For
  90  * the best objective measure (using the PSNR metric) set post_proc_flag
  91  * to AOM_DEBLOCK and deblocking_level to 1.
  92  */
  93
  94 typedef struct aom_postproc_cfg {
  95   /*!\brief the types of post processing to be done, should be combination of
  96    * "aom_postproc_level" */
  97   int post_proc_flag;
  98   int deblocking_level; /**< the strength of deblocking, valid range [0, 16] */
  99   int noise_level; /**< the strength of additive noise, valid range [0, 16] */
 100 } aom_postproc_cfg_t;
 101
 102 /*!\brief AV1 specific reference frame data struct
 103  *
 104  * Define the data struct to access av1 reference frames.
 105  */
 106 typedef struct av1_ref_frame {
 107   int idx;         /**< frame index to get (input) */
 108   aom_image_t img; /**< img structure to populate (output) */
 109 } av1_ref_frame_t;
 110
 111 /*!\cond */
 112 /*!\brief aom decoder control function parameter type
 113  *
 114  * defines the data type for each of AOM decoder control function requires
 115  */
 116 AOM_CTRL_USE_TYPE(AOM_SET_POSTPROC, aom_postproc_cfg_t *)
 117 #define AOM_CTRL_AOM_SET_POSTPROC
 118 AOM_CTRL_USE_TYPE(AOM_SET_DBG_COLOR_REF_FRAME, int)
 119 #define AOM_CTRL_AOM_SET_DBG_COLOR_REF_FRAME
 120 AOM_CTRL_USE_TYPE(AOM_SET_DBG_COLOR_MB_MODES, int)
 121 #define AOM_CTRL_AOM_SET_DBG_COLOR_MB_MODES
 122 AOM_CTRL_USE_TYPE(AOM_SET_DBG_COLOR_B_MODES, int)
 123 #define AOM_CTRL_AOM_SET_DBG_COLOR_B_MODES
 124 AOM_CTRL_USE_TYPE(AOM_SET_DBG_DISPLAY_MV, int)
 125 #define AOM_CTRL_AOM_SET_DBG_DISPLAY_MV
 126 AOM_CTRL_USE_TYPE(AV1_GET_REFERENCE, av1_ref_frame_t *)
 127 #define AOM_CTRL_AV1_GET_REFERENCE
 128 AOM_CTRL_USE_TYPE(AV1_SET_REFERENCE, av1_ref_frame_t *)
 129 #define AOM_CTRL_AV1_SET_REFERENCE
 130 AOM_CTRL_USE_TYPE(AV1_COPY_REFERENCE, av1_ref_frame_t *)
 131 #define AOM_CTRL_AV1_COPY_REFERENCE
 132 AOM_CTRL_USE_TYPE(AV1_GET_NEW_FRAME_IMAGE, aom_image_t *)
 133 #define AOM_CTRL_AV1_GET_NEW_FRAME_IMAGE
 134
 135 /*!\endcond */
 136 /*! @} - end defgroup aom */
 137
 138 #ifdef __cplusplus
 139 }  // extern "C"
 140 #endif
 141
 142 #endif  // AOM_AOM_H_