va/va_enc_vp9.h

   1 /*
   2  * Copyright (c) 2007-2015 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_vp9.h
  27  * \brief VP9 encoding API
  28  *
  29  * This file contains the \ref api_enc_vp9 "VP9 encoding API".
  30  *
  31  */
  32
  33 #ifndef VA_ENC_VP9_H
  34 #define VA_ENC_VP9_H
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /**
  41  * \defgroup api_enc_vp9 VP9 encoding API
  42  *
  43  * @{
  44  */
  45
  46 /**
  47  * \brief VP9 Encoding Status Data Buffer Structure
  48  *
  49  * This structure is used to convey status data from encoder to application.
  50  * Driver allocates VACodedBufferVP9Status as a private data buffer.
  51  * Driver encapsulates the status buffer with a VACodedBufferSegment,
  52  * and sets VACodedBufferSegment.status to be VA_CODED_BUF_STATUS_CODEC_SPECIFIC.
  53  * And driver associates status data segment to the bit stream buffer segment
  54  * by setting VACodedBufferSegment.next of coded_buf (bit stream) to the private
  55  * buffer segment of status data.
  56  * Application accesses it by calling VAMapBuffer() with VAEncCodedBufferType.
  57  */
  58 typedef struct  _VACodedBufferVP9Status
  59 {
  60     /** Final quantization index used (yac), determined by BRC.
  61      *  Application is providing quantization index deltas
  62      *  ydc(0), y2dc(1), y2ac(2), uvdc(3), uvac(4) that are applied to all segments
  63      *  and segmentation qi deltas, they will not be changed by BRC.
  64      */
  65     uint16_t    base_qp_index;
  66
  67     /** Final loopfilter levels for the frame, if segmentation is disabled only
  68      *  index 0 is used.
  69      *  If loop_filter_level is 0, it indicates loop filter is disabled.
  70      */
  71     uint8_t     loop_filter_level;
  72
  73     /**
  74      * Long term reference frame indication from BRC.  BRC recommends the
  75      * current frame that is being queried is a good candidate for a long
  76      * term reference.
  77      */
  78     uint8_t     long_term_indication;
  79
  80     /* suggested next frame width */
  81     uint16_t    next_frame_width;
  82
  83     /* suggested next frame height */
  84     uint16_t    next_frame_height;
  85
  86     /** \brief Reserved bytes for future use, must be zero */
  87     uint32_t                va_reserved[VA_PADDING_LOW];
  88 } VACodedBufferVP9Status;
  89
  90 /**
  91  * \brief VP9 Encoding Sequence Parameter Buffer Structure
  92  *
  93  * This structure conveys sequence level parameters.
  94  *
  95  */
  96 typedef struct  _VAEncSequenceParameterBufferVP9
  97 {
  98     /** \brief Frame size note:
  99      *  Picture resolution may change frame by frame.
 100      *  Application needs to allocate surfaces and frame buffers based on
 101      *  max frame resolution in case resolution changes for later frames.
 102      *  The source and recon surfaces allocated should be 64x64(SB) aligned
 103      *  on both horizontal and vertical directions.
 104      *  But buffers on the surfaces need to be aligned to CU boundaries.
 105      */
 106     /* maximum frame width in pixels for the whole sequence */
 107     uint32_t    max_frame_width;
 108
 109     /* maximum frame height in pixels for the whole sequence */
 110     uint32_t    max_frame_height;
 111
 112     /* auto keyframe placement, non-zero means enable auto keyframe placement */
 113     uint32_t    kf_auto;
 114
 115     /* keyframe minimum interval */
 116     uint32_t    kf_min_dist;
 117
 118     /* keyframe maximum interval */
 119     uint32_t    kf_max_dist;
 120
 121
 122     /* RC related fields. RC modes are set with VAConfigAttribRateControl */
 123     /* For VP9, CBR implies HRD conformance and VBR implies no HRD conformance */
 124
 125     /**
 126      * Initial bitrate set for this sequence in CBR or VBR modes.
 127      *
 128      * This field represents the initial bitrate value for this
 129      * sequence if CBR or VBR mode is used, i.e. if the encoder
 130      * pipeline was created with a #VAConfigAttribRateControl
 131      * attribute set to either \ref VA_RC_CBR or \ref VA_RC_VBR.
 132      *
 133      * The bitrate can be modified later on through
 134      * #VAEncMiscParameterRateControl buffers.
 135      */
 136     uint32_t    bits_per_second;
 137
 138     /* Period between key frames */
 139     uint32_t    intra_period;
 140
 141     /** \brief Reserved bytes for future use, must be zero */
 142     uint32_t                va_reserved[VA_PADDING_LOW];
 143 } VAEncSequenceParameterBufferVP9;
 144
 145
 146 /**
 147  * \brief VP9 Encoding Picture Parameter Buffer Structure
 148  *
 149  * This structure conveys picture level parameters.
 150  *
 151  */
 152 typedef struct  _VAEncPictureParameterBufferVP9
 153 {
 154     /** VP9 encoder may support dynamic scaling function.
 155      *  If enabled (enable_dynamic_scaling is set), application may request
 156      *  GPU encodes picture with a different resolution from the raw source.
 157      *  GPU should handle the scaling process of source and
 158      *  all reference frames.
 159      */
 160     /* raw source frame width in pixels */
 161     uint32_t    frame_width_src;
 162     /* raw source frame height in pixels */
 163     uint32_t    frame_height_src;
 164
 165     /* to be encoded frame width in pixels */
 166     uint32_t    frame_width_dst;
 167     /* to be encoded frame height in pixels */
 168     uint32_t    frame_height_dst;
 169
 170     /* surface to store reconstructed frame, not used for enc only case */
 171     VASurfaceID reconstructed_frame;
 172
 173     /** \brief reference frame buffers
 174      *  Each entry of the array specifies the surface index of the picture
 175      *  that is referred by current picture or will be referred by any future
 176      *  picture. The valid entries take value from 0 to 127, inclusive.
 177      *  Non-valid entries, those do not point to pictures which are referred
 178      *  by current picture or future pictures, should take value 0xFF.
 179      *  Other values are not allowed.
 180      *
 181      *  Application should update this array based on the refreshing
 182      *  information expected.
 183      */
 184     VASurfaceID reference_frames[8];
 185
 186           /* buffer to store coded data */
 187     VABufferID  coded_buf;
 188
 189     union {
 190         struct {
 191             /* force this frame to be a keyframe */
 192             uint32_t    force_kf                       : 1;
 193
 194             /** \brief Indiates which frames to be used as reference.
 195              *  (Ref_frame_ctrl & 0x01) ? 1: last frame as reference frame, 0: not.
 196              *  (Ref_frame_ctrl & 0x02) ? 1: golden frame as reference frame, 0: not.
 197              *  (Ref_frame_ctrl & 0x04) ? 1: alt frame as reference frame, 0: not.
 198              *  L0 is for forward prediction.
 199              *  L1 is for backward prediction.
 200              */
 201             uint32_t    ref_frame_ctrl_l0              : 3;
 202             uint32_t    ref_frame_ctrl_l1              : 3;
 203
 204             /** \brief Last Reference Frame index
 205              *  Specifies the index to RefFrameList[] which points to the LAST
 206              *  reference frame. It corresponds to active_ref_idx[0] in VP9 code.
 207              */
 208             uint32_t    ref_last_idx                   : 3;
 209
 210             /** \brief Specifies the Sign Bias of the LAST reference frame.
 211              *  It corresponds to ref_frame_sign_bias[LAST_FRAME] in VP9 code.
 212              */
 213             uint32_t    ref_last_sign_bias             : 1;
 214
 215             /** \brief GOLDEN Reference Frame index
 216              *  Specifies the index to RefFrameList[] which points to the Golden
 217              *  reference frame. It corresponds to active_ref_idx[1] in VP9 code.
 218              */
 219             uint32_t    ref_gf_idx                     : 3;
 220
 221             /** \brief Specifies the Sign Bias of the GOLDEN reference frame.
 222              *  It corresponds to ref_frame_sign_bias[GOLDEN_FRAME] in VP9 code.
 223              */
 224             uint32_t    ref_gf_sign_bias               : 1;
 225
 226             /** \brief Alternate Reference Frame index
 227              *  Specifies the index to RefFrameList[] which points to the Alternate
 228              *  reference frame. It corresponds to active_ref_idx[2] in VP9 code.
 229              */
 230             uint32_t    ref_arf_idx                    : 3;
 231
 232             /** \brief Specifies the Sign Bias of the ALTERNATE reference frame.
 233              *  It corresponds to ref_frame_sign_bias[ALTREF_FRAME] in VP9 code.
 234              */
 235             uint32_t    ref_arf_sign_bias              : 1;
 236
 237             /* The temporal id the frame belongs to */
 238             uint32_t    temporal_id                    : 8;
 239
 240             uint32_t    reserved                       : 5;
 241         } bits;
 242         uint32_t value;
 243     } ref_flags;
 244
 245     union {
 246         struct {
 247             /**
 248              * Indicates if the current frame is a key frame or not.
 249              * Corresponds to the same VP9 syntax element in frame tag.
 250              */
 251             uint32_t    frame_type                     : 1;
 252
 253             /** \brief show_frame
 254              *  0: current frame is not for display
 255                    *  1: current frame is for display
 256              */
 257             uint32_t    show_frame                     : 1;
 258
 259             /**
 260              * The following fields correspond to the same VP9 syntax elements
 261              * in the frame header.
 262              */
 263             uint32_t    error_resilient_mode           : 1;
 264
 265             /** \brief Indicate intra-only for inter pictures.
 266              *  Must be 0 for key frames.
 267              *  0: inter frame use both intra and inter blocks
 268              *  1: inter frame use only intra blocks.
 269              */
 270             uint32_t    intra_only                     : 1;
 271
 272             /** \brief Indicate high precision mode for Motion Vector prediction
 273              *  0: normal mode
 274              *  1: high precision mode
 275              */
 276             uint32_t    allow_high_precision_mv        : 1;
 277
 278             /** \brief Motion Compensation Filter type
 279              *  0: eight-tap  (only this mode is supported now.)
 280              *  1: eight-tap-smooth
 281              *  2: eight-tap-sharp
 282              *  3: bilinear
 283              *  4: switchable
 284              */
 285             uint32_t    mcomp_filter_type              : 3;
 286             uint32_t    frame_parallel_decoding_mode   : 1;
 287             uint32_t    reset_frame_context            : 2;
 288             uint32_t    refresh_frame_context          : 1;
 289             uint32_t    frame_context_idx              : 2;
 290             uint32_t    segmentation_enabled           : 1;
 291
 292             /* corresponds to variable temporal_update in VP9 code.
 293              * Indicates whether Segment ID is from bitstream or from previous
 294              * frame.
 295              * 0: Segment ID from bitstream
 296              * 1: Segment ID from previous frame
 297              */
 298             uint32_t    segmentation_temporal_update   : 1;
 299
 300             /* corresponds to variable update_mb_segmentation_map in VP9 code.
 301              * Indicates how hardware determines segmentation ID
 302              * 0: intra block - segment id is 0;
 303              *    inter block - segment id from previous frame
 304              * 1: intra block - segment id from bitstream (app or GPU decides)
 305              *    inter block - depends on segmentation_temporal_update
 306              */
 307             uint32_t    segmentation_update_map        : 1;
 308
 309             /** \brief Specifies if the picture is coded in lossless mode.
 310              *
 311              *  lossless_mode = base_qindex == 0 && y_dc_delta_q == 0  \
 312              *                  && uv_dc_delta_q == 0 && uv_ac_delta_q == 0;
 313              *  Where base_qindex, y_dc_delta_q, uv_dc_delta_q and uv_ac_delta_q
 314              *  are all variables in VP9 code.
 315              *
 316              *  When enabled, tx_mode needs to be set to 4x4 only and all
 317              *  tu_size in CU record set to 4x4 for entire frame.
 318              *  Software also has to program such that final_qindex=0 and
 319              *  final_filter_level=0 following the Quant Scale and
 320              *  Filter Level Table in Segmentation State section.
 321              *  Hardware forces Hadamard Tx when this bit is set.
 322              *  When lossless_mode is on, BRC has to be turned off.
 323              *  0: normal mode
 324              *  1: lossless mode
 325              */
 326             uint32_t    lossless_mode                  : 1;
 327
 328             /** \brief MV prediction mode. Corresponds to VP9 variable with same name.
 329              *  comp_prediction_mode = 0:               single prediction ony,
 330              *  comp_prediction_mode = 1:               compound prediction,
 331              *  comp_prediction_mode = 2:               hybrid prediction
 332              *
 333              *  Not mandatory. App may suggest the setting based on power or
 334              *  performance. Kernal may use it as a guildline and decide the proper
 335              *  setting on its own.
 336              */
 337             uint32_t    comp_prediction_mode           : 2;
 338
 339             /** \brief Indicate how segmentation is specified
 340              *  0   application specifies segmentation partitioning and
 341              *      relevant parameters.
 342              *  1   GPU may decide on segmentation. If application already
 343              *      provides segmentation information, GPU may choose to
 344              *      honor it and further split into more levels if possible.
 345              */
 346             uint32_t    auto_segmentation              : 1;
 347
 348             /** \brief Indicate super frame syntax should be inserted
 349              *  0   current frame is not encapsulated in super frame structure
 350              *  1   current fame is to be encapsulated in super frame structure.
 351              *      super frame index syntax will be inserted by encoder at
 352              *      the end of current frame.
 353              */
 354             uint32_t    super_frame_flag               : 1;
 355
 356             uint32_t    reserved                       : 10;
 357         } bits;
 358         uint32_t    value;
 359     } pic_flags;
 360
 361     /** \brief indicate which frames in DPB should be refreshed.
 362      *  same syntax and semantic as in VP9 code.
 363      */
 364     uint8_t     refresh_frame_flags;
 365
 366     /** \brief Base Q index in the VP9 term.
 367      *  Added with per segment delta Q index to get Q index of Luma AC.
 368      */
 369     uint8_t     luma_ac_qindex;
 370
 371     /**
 372      *  Q index delta from base Q index in the VP9 term for Luma DC.
 373      */
 374     int8_t      luma_dc_qindex_delta;
 375
 376     /**
 377      *  Q index delta from base Q index in the VP9 term for Chroma AC.
 378      */
 379     int8_t      chroma_ac_qindex_delta;
 380
 381     /**
 382      *  Q index delta from base Q index in the VP9 term for Chroma DC.
 383      */
 384     int8_t      chroma_dc_qindex_delta;
 385
 386     /** \brief filter level
 387      *  Corresponds to the same VP9 syntax element in frame header.
 388      */
 389     uint8_t     filter_level;
 390
 391     /**
 392      * Controls the deblocking filter sensitivity.
 393      * Corresponds to the same VP9 syntax element in frame header.
 394      */
 395     uint8_t     sharpness_level;
 396
 397     /** \brief Loop filter level reference delta values.
 398      *  Contains a list of 4 delta values for reference frame based block-level
 399      *  loop filter adjustment.
 400      *  If no update, set to 0.
 401      *  value range [-63..63]
 402      */
 403     int8_t      ref_lf_delta[4];
 404
 405     /** \brief Loop filter level mode delta values.
 406      *  Contains a list of 4 delta values for coding mode based MB-level loop
 407      *  filter adjustment.
 408      *  If no update, set to 0.
 409      *  value range [-63..63]
 410      */
 411     int8_t      mode_lf_delta[2];
 412
 413     /**
 414      *  Offset from starting position of output bitstream in bits where
 415      *  ref_lf_delta[] should be inserted. This offset should cover any metadata
 416      *  ahead of uncompressed header in inserted bit stream buffer (the offset
 417      *  should be same as that for final output bitstream buffer).
 418      *
 419      *  In BRC mode, always insert ref_lf_delta[] (This implies uncompressed
 420      *  header should have mode_ref_delta_enabled=1 and mode_ref_delta_update=1).
 421      */
 422     uint16_t    bit_offset_ref_lf_delta;
 423
 424     /**
 425      *  Offset from starting position of output bitstream in bits where
 426      *  mode_lf_delta[] should be inserted.
 427      *
 428      *  In BRC mode, always insert mode_lf_delta[] (This implies uncompressed
 429      *  header should have mode_ref_delta_enabled=1 and mode_ref_delta_update=1).
 430      */
 431     uint16_t    bit_offset_mode_lf_delta;
 432
 433     /**
 434      *  Offset from starting position of output bitstream in bits where (loop)
 435      *  filter_level should be inserted.
 436      */
 437     uint16_t    bit_offset_lf_level;
 438
 439     /**
 440      *  Offset from starting position of output bitstream in bits where
 441      *  Base Qindex should be inserted.
 442      */
 443     uint16_t    bit_offset_qindex;
 444
 445     /**
 446      *  Offset from starting position of output bitstream in bits where
 447      *  First Partition Size should be inserted.
 448      */
 449     uint16_t    bit_offset_first_partition_size;
 450
 451     /**
 452      *  Offset from starting position of output bitstream in bits where
 453      *  segmentation_enabled is located in bitstream. When auto_segmentation
 454      *  is enabled, GPU uses this offset to locate and update the
 455      *  segmentation related information.
 456      */
 457     uint16_t    bit_offset_segmentation;
 458
 459     /** \brief length in bit of segmentation portion from the location
 460      *  in bit stream where segmentation_enabled syntax is coded.
 461      *  When auto_segmentation is enabled, GPU uses this bit size to locate
 462      *  and update the information after segmentation.
 463      */
 464     uint16_t    bit_size_segmentation;
 465
 466
 467     /** \brief log2 of number of tile rows
 468      *  Corresponds to the same VP9 syntax element in frame header.
 469      *  value range [0..2]
 470      */
 471     uint8_t     log2_tile_rows;
 472
 473     /** \brief log2 of number of tile columns
 474      *  Corresponds to the same VP9 syntax element in frame header.
 475      *  value range [0..5]
 476      */
 477     uint8_t     log2_tile_columns;
 478
 479     /** \brief indicate frame-skip happens
 480      *  Application may choose to drop/skip one or mulitple encoded frames or
 481      *  to-be-encoded frame due to various reasons such as insufficient
 482      *  bandwidth.
 483      *  Application uses the following three flags to inform GPU about frame-skip.
 484      *
 485      *  value range of skip_frame_flag: [0..2]
 486      *      0 - encode as normal, no skip;
 487      *      1 - one or more frames were skipped by application prior to the
 488      *          current frame. Encode the current frame as normal. The driver
 489      *          will pass the number_skip_frames and skip_frames_size
 490      *          to bit rate control for adjustment.
 491      *      2 - the current frame is to be skipped. Do not encode it but encrypt
 492      *          the packed header contents. This is for the secure encoding case
 493      *          where application generates a frame of all skipped blocks.
 494      *          The packed header will contain the skipped frame.
 495      */
 496     uint8_t     skip_frame_flag;
 497
 498     /** \brief The number of frames skipped prior to the current frame.
 499      *  It includes only the skipped frames that were not counted before,
 500      *  and does not include the frame with skip_frame_flag == 2.
 501      *  Valid when skip_frame_flag = 1.
 502      */
 503     uint8_t     number_skip_frames;
 504
 505     /** \brief When skip_frame_flag = 1, the size of the skipped frames in bits.
 506      *  It includes only the skipped frames that were not counted before,
 507      *  and does not include the frame size with skip_frame_flag = 2.
 508      *  When skip_frame_flag = 2, it is the size of the current skipped frame
 509      *  that is to be encrypted.
 510      */
 511     uint32_t    skip_frames_size;
 512
 513     /** \brief Reserved bytes for future use, must be zero */
 514     uint32_t    va_reserved[VA_PADDING_MEDIUM];
 515 } VAEncPictureParameterBufferVP9;
 516
 517
 518 /**
 519  * \brief Per segment parameters
 520  */
 521 typedef struct _VAEncSegParamVP9
 522 {
 523     union {
 524         struct {
 525             /** \brief Indicates if per segment reference frame indicator is enabled.
 526              *  Corresponding to variable feature_enabled when
 527              *  j == SEG_LVL_REF_FRAME in function setup_segmentation() VP9 code.
 528              */
 529             uint8_t     segment_reference_enabled       : 1;
 530
 531             /** \brief Specifies per segment reference indication.
 532              *  0: reserved
 533              *  1: Last ref
 534              *  2: golden
 535              *  3: altref
 536              *  Value can be derived from variable data when
 537              *  j == SEG_LVL_REF_FRAME in function setup_segmentation() VP9 code.
 538              *  value range: [0..3]
 539              */
 540             uint8_t     segment_reference               : 2;
 541
 542             /** \brief Indicates if per segment skip mode is enabled.
 543              *  Corresponding to variable feature_enabled when
 544              *  j == SEG_LVL_SKIP in function setup_segmentation() VP9 code.
 545              */
 546             uint8_t     segment_reference_skipped       : 1;
 547
 548             uint8_t     reserved                        : 4;
 549
 550         } bits;
 551         uint8_t value;
 552     } seg_flags;
 553
 554     /** \brief Specifies per segment Loop Filter Delta.
 555      *  Must be 0 when segmentation_enabled == 0.
 556      *  value range: [-63..63]
 557      */
 558     int8_t      segment_lf_level_delta;
 559
 560     /** \brief Specifies per segment QIndex Delta.
 561      *  Must be 0 when segmentation_enabled == 0.
 562      *  value range: [-255..255]
 563      */
 564     int16_t     segment_qindex_delta;
 565
 566     /** \brief Reserved bytes for future use, must be zero */
 567     uint32_t                va_reserved[VA_PADDING_LOW];
 568 } VAEncSegParamVP9;
 569
 570 /**
 571  *  Structure to convey all segment related information.
 572  *  If segmentation is disabled, this data structure is still required.
 573  *  In this case, only seg_data[0] contains valid data.
 574  *  This buffer is sent once per frame.
 575  *
 576  *  The buffer is created with VABufferType VAQMatrixBufferType.
 577  *
 578  */
 579 typedef struct _VAEncMiscParameterTypeVP9PerSegmantParam
 580 {
 581     /**
 582      *  Parameters for 8 segments.
 583      */
 584     VAEncSegParamVP9    seg_data[8];
 585
 586     /** \brief Reserved bytes for future use, must be zero */
 587     uint32_t                va_reserved[VA_PADDING_LOW];
 588 } VAEncMiscParameterTypeVP9PerSegmantParam;
 589
 590
 591 /**
 592  * \brief VP9 Block Segmentation ID Buffer
 593  *
 594  * The application provides a buffer of VAEncMacroblockMapBufferType containing
 595  * the initial segmentation id for each 8x8 block, one byte each, in raster scan order.
 596  * Rate control may reassign it.  For example, a 640x480 video, the buffer has 4800 entries.
 597  * The value of each entry should be in the range [0..7], inclusive.
 598  * If segmentation is not enabled, the application does not need to provide it.
 599  */
 600
 601
 602 /**@}*/
 603
 604 #ifdef __cplusplus
 605 }
 606 #endif
 607
 608 #endif /* VA_ENC_VP9_H */