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