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
37extern "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 */
58typedef 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 */
95typedef 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 */
150typedef 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 */
518typedef 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 */
575typedef 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

source code of include/va/va_enc_vp9.h