va/va_enc_vp8.h

   1 /*
   2  * Copyright (c) 2007-2012 Intel Corporation. All Rights Reserved.
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the
   6  * "Software"), to deal in the Software without restriction, including
   7  * without limitation the rights to use, copy, modify, merge, publish,
   8  * distribute, sub license, and/or sell copies of the Software, and to
   9  * permit persons to whom the Software is furnished to do so, subject to
  10  * the following conditions:
  11  *
  12  * The above copyright notice and this permission notice (including the
  13  * next paragraph) shall be included in all copies or substantial portions
  14  * of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
  19  * IN NO EVENT SHALL INTEL AND/OR ITS SUPPLIERS BE LIABLE FOR
  20  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  21  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  22  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 /**
  26  * \file va_enc_vp8.h
  27  * \brief VP8 encoding API
  28  *
  29  * This file contains the \ref api_enc_vp8 "VP8 encoding API".
  30  */
  31
  32 #ifndef VA_ENC_VP8_H
  33 #define VA_ENC_VP8_H
  34
  35 #ifdef __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 /**
  40  * \defgroup api_enc_vp8 VP8 encoding API
  41  *
  42  * @{
  43  */
  44
  45 /**
  46  * \brief VP8 Encoding Sequence Parameter Buffer Structure
  47  *
  48  * This structure conveys sequence level parameters.
  49  *
  50  */
  51 typedef struct  _VAEncSequenceParameterBufferVP8
  52 {
  53     /* frame width in pixels */
  54     uint32_t frame_width;
  55     /* frame height in pixels */
  56     uint32_t frame_height;
  57     /* horizontal scale */
  58     uint32_t frame_width_scale;
  59     /* vertical scale */
  60     uint32_t frame_height_scale;
  61
  62     /* whether to enable error resilience features */
  63     uint32_t error_resilient;
  64     /* auto keyframe placement, non-zero means enable auto keyframe placement */
  65     uint32_t kf_auto;
  66     /* keyframe minimum interval */
  67     uint32_t kf_min_dist;
  68     /* keyframe maximum interval */
  69     uint32_t kf_max_dist;
  70
  71
  72     /* RC related fields. RC modes are set with VAConfigAttribRateControl */
  73     /* For VP8, CBR implies HRD conformance and VBR implies no HRD conformance */
  74
  75     /**
  76      * Initial bitrate set for this sequence in CBR or VBR modes.
  77      *
  78      * This field represents the initial bitrate value for this
  79      * sequence if CBR or VBR mode is used, i.e. if the encoder
  80      * pipeline was created with a #VAConfigAttribRateControl
  81      * attribute set to either \ref VA_RC_CBR or \ref VA_RC_VBR.
  82      *
  83      * The bitrate can be modified later on through
  84      * #VAEncMiscParameterRateControl buffers.
  85      */
  86     uint32_t bits_per_second;
  87     /* Period between I frames. */
  88     uint32_t intra_period;
  89
  90     /* reference and reconstructed frame buffers
  91      * Used for driver auto reference management when configured through
  92      * VAConfigAttribEncAutoReference.
  93      */
  94     VASurfaceID reference_frames[4];
  95
  96     /** \brief Reserved bytes for future use, must be zero */
  97     uint32_t                va_reserved[VA_PADDING_LOW];
  98 } VAEncSequenceParameterBufferVP8;
  99
 100
 101 /**
 102  * \brief VP8 Encoding Picture Parameter Buffer Structure
 103  *
 104  * This structure conveys picture level parameters.
 105  *
 106  */
 107 typedef struct  _VAEncPictureParameterBufferVP8
 108 {
 109     /* surface to store reconstructed frame  */
 110     VASurfaceID reconstructed_frame;
 111
 112     /*
 113      * surfaces to store reference frames in non auto reference mode
 114      * VA_INVALID_SURFACE can be used to denote an invalid reference frame.
 115      */
 116     VASurfaceID ref_last_frame;
 117     VASurfaceID ref_gf_frame;
 118     VASurfaceID ref_arf_frame;
 119
 120     /* buffer to store coded data */
 121     VABufferID coded_buf;
 122
 123     union {
 124         struct {
 125             /* force this frame to be a keyframe */
 126             uint32_t force_kf                       : 1;
 127             /* don't reference the last frame */
 128             uint32_t no_ref_last                    : 1;
 129             /* don't reference the golden frame */
 130             uint32_t no_ref_gf                      : 1;
 131             /* don't reference the alternate reference frame */
 132             uint32_t no_ref_arf                     : 1;
 133             /* The temporal id the frame belongs to. */
 134             uint32_t temporal_id                    : 8;
 135             /**
 136             *  following two flags indicate the reference order
 137             *  LastRef is specified by 01b;
 138             *  GoldRef is specified by 10b;
 139             *  AltRef  is specified by 11b;
 140             *  first_ref specifies the reference frame which is searched first.
 141             *  second_ref specifies the reference frame which is searched second
 142             *  if there is.
 143             */
 144             uint32_t first_ref                      : 2;
 145             uint32_t second_ref                     : 2;
 146             /** \brief Reserved for future use, must be zero */
 147             uint32_t reserved                       : 16;
 148         } bits;
 149         uint32_t value;
 150     } ref_flags;
 151
 152     union {
 153         struct {
 154             /* version */
 155             uint32_t frame_type                     : 1;
 156             uint32_t version                        : 3;
 157             /* show_frame */
 158             uint32_t show_frame                     : 1;
 159             /* color_space */
 160             uint32_t color_space                    : 1;
 161             /*  0: bicubic, 1: bilinear, other: none */
 162             uint32_t recon_filter_type              : 2;
 163             /*  0: no loop fitler, 1: simple loop filter */
 164             uint32_t loop_filter_type               : 2;
 165             /* 0: disabled, 1: normal, 2: simple */
 166             uint32_t auto_partitions                : 1;
 167             /* same as log2_nbr_of_dct_partitions in frame header syntax */
 168             uint32_t num_token_partitions           : 2;
 169
 170             /**
 171              * The following fields correspond to the same VP8 syntax elements
 172              * in the frame header.
 173              */
 174             /**
 175              * 0: clamping of reconstruction pixels is disabled,
 176              * 1: clamping enabled.
 177              */
 178             uint32_t clamping_type                  : 1;
 179             /* indicate segmentation is enabled for the current frame. */
 180             uint32_t segmentation_enabled           : 1;
 181             /**
 182              * Determines if the MB segmentation map is updated in the current
 183              * frame.
 184              */
 185             uint32_t update_mb_segmentation_map     : 1;
 186             /**
 187              * Indicates if the segment feature data is updated in the current
 188              * frame.
 189              */
 190             uint32_t update_segment_feature_data    : 1;
 191             /**
 192              * indicates if the MB level loop filter adjustment is enabled for
 193              * the current frame (0 off, 1 on).
 194              */
 195             uint32_t loop_filter_adj_enable         : 1;
 196             /**
 197              * Determines whether updated token probabilities are used only for
 198              * this frame or until further update.
 199              * It may be used by application to enable error resilient mode.
 200              * In this mode probability updates are allowed only at Key Frames.
 201              */
 202             uint32_t refresh_entropy_probs          : 1;
 203             /**
 204              * Determines if the current decoded frame refreshes the golden frame.
 205              */
 206             uint32_t refresh_golden_frame           : 1;
 207             /**
 208              * Determines if the current decoded frame refreshes the alternate
 209              * reference frame.
 210              */
 211             uint32_t refresh_alternate_frame        : 1;
 212             /**
 213              * Determines if the current decoded frame refreshes the last frame
 214              * reference buffer.
 215              */
 216             uint32_t refresh_last                   : 1;
 217             /**
 218              * Determines if the golden reference is replaced by another reference.
 219              */
 220             uint32_t copy_buffer_to_golden          : 2;
 221             /**
 222              * Determines if the alternate reference is replaced by another reference.
 223              */
 224             uint32_t copy_buffer_to_alternate       : 2;
 225             /**
 226              * Controls the sign of motion vectors when the golden frame is referenced.
 227              */
 228             uint32_t sign_bias_golden               : 1;
 229             /**
 230              * Controls the sign of motion vectors when the alternate frame is
 231              * referenced.
 232              */
 233             uint32_t sign_bias_alternate            : 1;
 234             /**
 235              * Enables or disables the skipping of macroblocks containing no
 236              * non-zero coefficients.
 237              */
 238             uint32_t mb_no_coeff_skip               : 1;
 239             /**
 240              * Enforces unconditional per-MB loop filter delta update setting frame
 241              * header flags mode_ref_lf_delta_update, all mb_mode_delta_update_flag[4],
 242              * and all ref_frame_delta_update_flag[4] to 1.
 243              * Since loop filter deltas are not automatically refreshed to default
 244              * values at key frames, dropped frame with delta update may prevent
 245              * correct decoding from the next key frame.
 246              * Encoder application is advised to set this flag to 1 at key frames.
 247              */
 248             uint32_t forced_lf_adjustment           : 1;
 249             uint32_t reserved                       : 2;
 250         } bits;
 251         uint32_t value;
 252     } pic_flags;
 253
 254     /**
 255      * Contains a list of 4 loop filter level values (updated value if applicable)
 256      * controlling the deblocking filter strength. Each entry represents a segment.
 257      * When segmentation is disabled, use entry 0.
 258      * When loop_filter_level is 0, loop filter shall be disabled.
 259      */
 260     int8_t loop_filter_level[4];
 261
 262     /**
 263      * Contains a list of 4 delta values for reference frame based MB-level
 264      * loop filter adjustment.
 265      * If no update, then set to 0.
 266      */
 267     int8_t ref_lf_delta[4];
 268
 269     /**
 270      * Contains a list of 4 delta values for coding mode based MB-level loop
 271      * filter adjustment.
 272      * If no update, then set to 0.
 273      */
 274     int8_t mode_lf_delta[4];
 275
 276     /**
 277      * Controls the deblocking filter sensitivity.
 278      * Corresponds to the same VP8 syntax element in frame header.
 279      */
 280     uint8_t sharpness_level;
 281
 282     /**
 283      * Application supplied maximum clamp value for Qindex used in quantization.
 284      * Qindex will not be allowed to exceed this value.
 285      * It has a valid range [0..127] inclusive.
 286      */
 287     uint8_t clamp_qindex_high;
 288
 289     /**
 290      * Application supplied minimum clamp value for Qindex used in quantization.
 291      * Qindex will not be allowed to be lower than this value.
 292      * It has a valid range [0..127] inclusive.
 293      * Condition clamp_qindex_low <= clamp_qindex_high must be guaranteed,
 294      * otherwise they are ignored.
 295      */
 296     uint8_t clamp_qindex_low;
 297
 298     /** \brief Reserved bytes for future use, must be zero */
 299     uint32_t                va_reserved[VA_PADDING_LOW];
 300 } VAEncPictureParameterBufferVP8;
 301
 302
 303 /**
 304  * \brief VP8 MB Segmentation ID Buffer
 305  *
 306  * application provides buffer containing the initial segmentation id for each
 307  * MB, in raster scan order. Rate control may reassign it.
 308  * For an 640x480 video, the buffer has 1200 entries.
 309  * the value of each entry should be in the range [0..3], inclusive.
 310  * If segmentation is not enabled, application does not need to provide it.
 311  */
 312 typedef struct _VAEncMBMapBufferVP8
 313 {
 314     /**
 315      * number of MBs in the frame.
 316      * It is also the number of entries of mb_segment_id[];
 317      */
 318     uint32_t num_mbs;
 319     /**
 320      * per MB Segmentation ID Buffer
 321      */
 322     uint8_t *mb_segment_id;
 323
 324     /** \brief Reserved bytes for future use, must be zero */
 325     uint32_t                va_reserved[VA_PADDING_LOW];
 326 } VAEncMBMapBufferVP8;
 327
 328
 329 /**
 330  * \brief VP8 Quantization Matrix Buffer Structure
 331  *
 332  * Contains quantization index for yac(0-3) for each segment and quantization
 333  * index deltas, ydc(0), y2dc(1), y2ac(2), uvdc(3), uvac(4) that are applied
 334  * to all segments.  When segmentation is disabled, only quantization_index[0]
 335  * will be used. This structure is sent once per frame.
 336  */
 337 typedef struct _VAQMatrixBufferVP8
 338 {
 339     uint16_t quantization_index[4];
 340     int16_t quantization_index_delta[5];
 341
 342     /** \brief Reserved bytes for future use, must be zero */
 343     uint32_t                va_reserved[VA_PADDING_LOW];
 344 } VAQMatrixBufferVP8;
 345
 346
 347
 348 /**@}*/
 349
 350 #ifdef __cplusplus
 351 }
 352 #endif
 353
 354 #endif /* VA_ENC_VP8_H */