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     unsigned int frame_width;
  55     /* frame height in pixels */
  56     unsigned int frame_height;
  57     /* horizontal scale */
  58     unsigned int frame_width_scale;
  59     /* vertical scale */
  60     unsigned int frame_height_scale;
  61
  62     /* whether to enable error resilience features */
  63     unsigned int error_resilient;
  64     /* auto keyframe placement, non-zero means enable auto keyframe placement */
  65     unsigned int kf_auto;
  66     /* keyframe minimum interval */
  67     unsigned int kf_min_dist;
  68     /* keyframe maximum interval */
  69     unsigned int 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     unsigned int bits_per_second;
  87     /* Period between I frames. */
  88     unsigned int 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 } VAEncSequenceParameterBufferVP8;
  97
  98
  99 /**
 100  * \brief VP8 Encoding Picture Parameter Buffer Structure
 101  *
 102  * This structure conveys picture level parameters.
 103  *
 104  */
 105 typedef struct  _VAEncPictureParameterBufferVP8
 106 {
 107     /* surface to store reconstructed frame  */
 108     VASurfaceID reconstructed_frame;
 109
 110     /*
 111      * surfaces to store reference frames in non auto reference mode
 112      * VA_INVALID_SURFACE can be used to denote an invalid reference frame.
 113      */
 114     VASurfaceID ref_last_frame;
 115     VASurfaceID ref_gf_frame;
 116     VASurfaceID ref_arf_frame;
 117
 118     /* buffer to store coded data */
 119     VABufferID coded_buf;
 120
 121     union {
 122         struct {
 123             /* force this frame to be a keyframe */
 124             unsigned int force_kf                       : 1;
 125             /* don't reference the last frame */
 126             unsigned int no_ref_last                    : 1;
 127             /* don't reference the golden frame */
 128             unsigned int no_ref_gf                      : 1;
 129             /* don't reference the alternate reference frame */
 130             unsigned int no_ref_arf                     : 1;
 131             unsigned int reserved                       : 28;
 132         } bits;
 133         unsigned int value;
 134     } ref_flags;
 135
 136     union {
 137         struct {
 138             /* version */
 139             unsigned int frame_type                     : 1;
 140             unsigned int version                        : 3;
 141             /* show_frame */
 142             unsigned int show_frame                     : 1;
 143             /* color_space */
 144             unsigned int color_space                    : 1;
 145             /*  0: bicubic, 1: bilinear, other: none */
 146             unsigned int recon_filter_type              : 2;
 147             /*  0: no loop fitler, 1: simple loop filter */
 148             unsigned int loop_filter_type               : 2;
 149             /* 0: disabled, 1: normal, 2: simple */
 150             unsigned int auto_partitions                : 1;
 151             /* same as log2_nbr_of_dct_partitions in frame header syntax */
 152             unsigned int num_token_partitions           : 2;
 153
 154             /**
 155              * The following fields correspond to the same VP8 syntax elements
 156              * in the frame header.
 157              */
 158             /**
 159              * 0: clamping of reconstruction pixels is disabled,
 160              * 1: clamping enabled.
 161              */
 162             unsigned int clamping_type                  : 1;
 163             /* indicate segmentation is enabled for the current frame. */
 164             unsigned int segmentation_enabled           : 1;
 165             /**
 166              * Determines if the MB segmentation map is updated in the current
 167              * frame.
 168              */
 169             unsigned int update_mb_segmentation_map     : 1;
 170             /**
 171              * Indicates if the segment feature data is updated in the current
 172              * frame.
 173              */
 174             unsigned int update_segment_feature_data    : 1;
 175             /**
 176              * indicates if the MB level loop filter adjustment is enabled for
 177              * the current frame (0 off, 1 on).
 178              */
 179             unsigned int loop_filter_adj_enable         : 1;
 180             /**
 181              * Determines whether updated token probabilities are used only for
 182              * this frame or until further update.
 183              * It may be used by application to enable error resilient mode.
 184              * In this mode probability updates are allowed only at Key Frames.
 185              */
 186             unsigned int refresh_entropy_probs          : 1;
 187             /**
 188              * Determines if the current decoded frame refreshes the golden frame.
 189              */
 190             unsigned int refresh_golden_frame           : 1;
 191             /**
 192              * Determines if the current decoded frame refreshes the alternate
 193              * reference frame.
 194              */
 195             unsigned int refresh_alternate_frame        : 1;
 196             /**
 197              * Determines if the current decoded frame refreshes the last frame
 198              * reference buffer.
 199              */
 200             unsigned int refresh_last                   : 1;
 201             /**
 202              * Determines if the golden reference is replaced by another reference.
 203              */
 204             unsigned int copy_buffer_to_golden          : 2;
 205             /**
 206              * Determines if the alternate reference is replaced by another reference.
 207              */
 208             unsigned int copy_buffer_to_alternate       : 2;
 209             /**
 210              * Controls the sign of motion vectors when the golden frame is referenced.
 211              */
 212             unsigned int sign_bias_golden               : 1;
 213             /**
 214              * Controls the sign of motion vectors when the alternate frame is
 215              * referenced.
 216              */
 217             unsigned int sign_bias_alternate            : 1;
 218             /**
 219              * Enables or disables the skipping of macroblocks containing no
 220              * non-zero coefficients.
 221              */
 222             unsigned int mb_no_coeff_skip               : 1;
 223             /**
 224              * Enforces unconditional per-MB loop filter delta update setting frame
 225              * header flags mode_ref_lf_delta_update, all mb_mode_delta_update_flag[4],
 226              * and all ref_frame_delta_update_flag[4] to 1.
 227              * Since loop filter deltas are not automatically refreshed to default
 228              * values at key frames, dropped frame with delta update may prevent
 229              * correct decoding from the next key frame.
 230              * Encoder application is advised to set this flag to 1 at key frames.
 231              */
 232             unsigned int forced_lf_adjustment           : 1;
 233             unsigned int reserved                       : 2;
 234         } bits;
 235         unsigned int value;
 236     } pic_flags;
 237
 238     /**
 239      * Contains a list of 4 loop filter level values (updated value if applicable)
 240      * controlling the deblocking filter strength. Each entry represents a segment.
 241      * When segmentation is disabled, use entry 0.
 242      * When loop_filter_level is 0, loop filter shall be disabled.
 243      */
 244     char loop_filter_level[4];
 245
 246     /**
 247      * Contains a list of 4 delta values for reference frame based MB-level
 248      * loop filter adjustment.
 249      * If no update, then set to 0.
 250      */
 251     char ref_lf_delta[4];
 252
 253     /**
 254      * Contains a list of 4 delta values for coding mode based MB-level loop
 255      * filter adjustment.
 256      * If no update, then set to 0.
 257      */
 258     char mode_lf_delta[4];
 259
 260     /**
 261      * Controls the deblocking filter sensitivity.
 262      * Corresponds to the same VP8 syntax element in frame header.
 263      */
 264     unsigned char sharpness_level;
 265
 266     /**
 267      * Application supplied maximum clamp value for Qindex used in quantization.
 268      * Qindex will not be allowed to exceed this value.
 269      * It has a valid range [0..127] inclusive.
 270      */
 271     unsigned char clamp_qindex_high;
 272
 273     /**
 274      * Application supplied minimum clamp value for Qindex used in quantization.
 275      * Qindex will not be allowed to be lower than this value.
 276      * It has a valid range [0..127] inclusive.
 277      * Condition clamp_qindex_low <= clamp_qindex_high must be guaranteed,
 278      * otherwise they are ignored.
 279      */
 280     unsigned char clamp_qindex_low;
 281
 282 } VAEncPictureParameterBufferVP8;
 283
 284
 285 /**
 286  * \brief VP8 MB Segmentation ID Buffer
 287  *
 288  * application provides buffer containing the initial segmentation id for each
 289  * MB, in raster scan order. Rate control may reassign it.
 290  * For an 640x480 video, the buffer has 1200 entries.
 291  * the value of each entry should be in the range [0..3], inclusive.
 292  * If segmentation is not enabled, application does not need to provide it.
 293  */
 294 typedef struct _VAEncMBMapBufferVP8
 295 {
 296     /**
 297      * number of MBs in the frame.
 298      * It is also the number of entries of mb_segment_id[];
 299      */
 300     unsigned int num_mbs;
 301     /**
 302      * per MB Segmentation ID Buffer
 303      */
 304     unsigned char *mb_segment_id;
 305 } VAEncMBMapBufferVP8;
 306
 307
 308 /**
 309  * \brief VP8 Quantization Matrix Buffer Structure
 310  *
 311  * Contains quantization index for yac(0-3) for each segment and quantization
 312  * index deltas, ydc(0), y2dc(1), y2ac(2), uvdc(3), uvac(4) that are applied
 313  * to all segments.  When segmentation is disabled, only quantization_index[0]
 314  * will be used. This structure is sent once per frame.
 315  */
 316 typedef struct _VAQMatrixBufferVP8
 317 {
 318     unsigned short quantization_index[4];
 319     short quantization_index_delta[5];
 320 } VAQMatrixBufferVP8;
 321
 322
 323
 324 /**@}*/
 325
 326 #ifdef __cplusplus
 327 }
 328 #endif
 329
 330 #endif /* VA_ENC_VP8_H */