2 * Copyright (c) 2007-2011 Intel Corporation. All Rights Reserved.
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:
12 * The above copyright notice and this permission notice (including the
13 * next paragraph) shall be included in all copies or substantial portions
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.
27 * \brief The H.264 encoding API
29 * This file contains the \ref api_enc_h264 "H.264 encoding API".
40 * \defgroup api_enc_h264 H.264 encoding API
48 * Those flags flags are meant to signal when a picture marks the end
49 * of a sequence, a stream, or even both at once.
54 * \brief Marks the last picture in the sequence.
56 * i.e. the driver appends \c end_of_seq() NAL unit to the encoded frame.
58 #define H264_LAST_PICTURE_EOSEQ 0x01
60 * \brief Marks the last picture in the stream.
62 * i.e. the driver appends \c end_of_stream() NAL unit to the encoded frame.
64 #define H264_LAST_PICTURE_EOSTREAM 0x02
68 * \brief Packed header types specific to H.264 encoding.
70 * Types of packed headers generally used for H.264 encoding. Each
71 * associated packed header data buffer shall contain the start code
72 * prefix 0x000001 followed by the complete NAL unit, thus also
73 * including the \c nal_unit_type.
77 * \brief Packed Supplemental Enhancement Information (SEI).
79 * The corresponding packed header data buffer shall contain the
80 * complete sei_rbsp() syntax element, thus including several
81 * sei_message() elements if necessary.
83 * Note: packed \c nal_unit_type shall be equal to 6.
85 VAEncPackedHeaderH264_SEI = (VAEncPackedHeaderMiscMask | 1),
86 } VAEncPackedHeaderTypeH264;
89 * \brief Sequence parameter for H.264 encoding in main & high profiles.
91 * This structure holds information for \c seq_parameter_set_data() as
92 * defined by the H.264 specification.
94 * If packed sequence headers mode is used, i.e. if the encoding
95 * pipeline was configured with the #VA_ENC_PACKED_HEADER_SEQUENCE
96 * flag, then the driver expects two more buffers to be provided to
97 * the same \c vaRenderPicture() as this buffer:
98 * - a #VAEncPackedHeaderParameterBuffer with type set to
99 * VAEncPackedHeaderType::VAEncPackedHeaderSequence ;
100 * - a #VAEncPackedHeaderDataBuffer which holds the actual packed
103 * If \c seq_scaling_matrix_present_flag is set to \c 1, then a
104 * #VAIQMatrixBufferH264 buffer shall also be provided within the same
105 * \c vaRenderPicture() call as this sequence parameter buffer.
107 typedef struct _VAEncSequenceParameterBufferH264 {
108 /** \brief Same as the H.264 bitstream syntax element. */
109 unsigned char seq_parameter_set_id;
110 /** \brief XXX: implied by VA config. */
111 unsigned char profile_idc;
112 /** \brief Same as the H.264 bitstream syntax element. */
113 unsigned char level_idc;
114 /** \brief Period between I frames. */
115 unsigned int intra_period;
116 /** \brief Period between I/P frames. */
117 unsigned int ip_period;
119 * \brief Initial bitrate set for this sequence in CBR or VBR modes.
121 * This field represents the initial bitrate value for this
122 * sequence if CBR or VBR mode is used, i.e. if the encoder
123 * pipeline was created with a #VAConfigAttribRateControl
124 * attribute set to either \ref VA_RC_CBR or \ref VA_RC_VBR.
126 * The bitrate can be modified later on through
127 * #VAEncMiscParameterRateControl buffers.
129 unsigned int bits_per_second;
130 /** \brief Same as the H.264 bitstream syntax element. */
131 unsigned int max_num_ref_frames;
132 /** \brief Picture width in macroblocks. */
133 unsigned short picture_width_in_mbs;
134 /** \brief Picture height in macroblocks. */
135 unsigned short picture_height_in_mbs;
139 /** \brief Same as the H.264 bitstream syntax element. */
140 unsigned int chroma_format_idc : 2;
141 /** \brief Same as the H.264 bitstream syntax element. */
142 unsigned int frame_mbs_only_flag : 1;
143 /** \brief Same as the H.264 bitstream syntax element. */
144 unsigned int mb_adaptive_frame_field_flag : 1;
145 /** \brief Same as the H.264 bitstream syntax element. */
146 unsigned int seq_scaling_matrix_present_flag : 1;
147 /** \brief Same as the H.264 bitstream syntax element. */
148 unsigned int direct_8x8_inference_flag : 1;
149 /** \brief Same as the H.264 bitstream syntax element. */
150 unsigned int log2_max_frame_num_minus4 : 4;
151 /** \brief Same as the H.264 bitstream syntax element. */
152 unsigned int pic_order_cnt_type : 2;
153 /** \brief Same as the H.264 bitstream syntax element. */
154 unsigned int log2_max_pic_order_cnt_lsb_minus4 : 4;
155 /** \brief Same as the H.264 bitstream syntax element. */
156 unsigned int delta_pic_order_always_zero_flag : 1;
161 /** \brief Same as the H.264 bitstream syntax element. */
162 unsigned char bit_depth_luma_minus8;
163 /** \brief Same as the H.264 bitstream syntax element. */
164 unsigned char bit_depth_chroma_minus8;
166 /** if pic_order_cnt_type == 1 */
168 /** \brief Same as the H.264 bitstream syntax element. */
169 unsigned char num_ref_frames_in_pic_order_cnt_cycle;
170 /** \brief Same as the H.264 bitstream syntax element. */
171 int offset_for_non_ref_pic;
172 /** \brief Same as the H.264 bitstream syntax element. */
173 int offset_for_top_to_bottom_field;
174 /** \brief Same as the H.264 bitstream syntax element. */
175 int offset_for_ref_frame[256];
178 /** @name Cropping (optional) */
180 /** \brief Same as the H.264 bitstream syntax element. */
181 unsigned char frame_cropping_flag;
182 /** \brief Same as the H.264 bitstream syntax element. */
183 unsigned int frame_crop_left_offset;
184 /** \brief Same as the H.264 bitstream syntax element. */
185 unsigned int frame_crop_right_offset;
186 /** \brief Same as the H.264 bitstream syntax element. */
187 unsigned int frame_crop_top_offset;
188 /** \brief Same as the H.264 bitstream syntax element. */
189 unsigned int frame_crop_bottom_offset;
192 /** @name VUI parameters (optional) */
194 /** \brief Same as the H.264 bitstream syntax element. */
195 unsigned char vui_parameters_present_flag;
198 /** \brief Same as the H.264 bitstream syntax element. */
199 unsigned int timing_info_present_flag : 1;
200 /** \brief Same as the H.264 bitstream syntax element. */
201 unsigned int bitstream_restriction_flag : 1;
202 /** \brief Range: 0 to 16, inclusive. */
203 unsigned int log2_max_mv_length_horizontal : 5;
204 /** \brief Range: 0 to 16, inclusive. */
205 unsigned int log2_max_mv_length_vertical : 5;
209 /** \brief Same as the H.264 bitstream syntax element. */
210 unsigned int num_units_in_tick;
211 /** \brief Same as the H.264 bitstream syntax element. */
212 unsigned int time_scale;
214 } VAEncSequenceParameterBufferH264;
217 * \brief Picture parameter for H.264 encoding in main & high profiles.
219 * This structure holds information for \c pic_parameter_set_rbsp() as
220 * defined by the H.264 specification.
222 * If packed picture headers mode is used, i.e. if the encoding
223 * pipeline was configured with the #VA_ENC_PACKED_HEADER_PICTURE
224 * flag, then the driver expects two more buffers to be provided to
225 * the same \c vaRenderPicture() as this buffer:
226 * - a #VAEncPackedHeaderParameterBuffer with type set to
227 * VAEncPackedHeaderType::VAEncPackedHeaderPicture ;
228 * - a #VAEncPackedHeaderDataBuffer which holds the actual packed
231 * If \c pic_scaling_matrix_present_flag is set to \c 1, then a
232 * #VAIQMatrixBufferH264 buffer shall also be provided within the same
233 * \c vaRenderPicture() call as this picture parameter buffer.
235 typedef struct _VAEncPictureParameterBufferH264 {
236 /** \brief Information about the picture to be encoded. */
237 VAPictureH264 CurrPic;
238 /** \brief Decoded Picture Buffer (DPB).
239 * XXX: is this really used?
241 VAPictureH264 ReferenceFrames[16];
243 * \brief Output encoded bitstream.
245 * \ref coded_buf has type #VAEncCodedBufferType. It should be
246 * large enough to hold the compressed NAL slice and possibly SPS
249 VABufferID coded_buf;
251 /** \brief The picture parameter set referred to in the slice header. */
252 unsigned char pic_parameter_set_id;
253 /** \brief The active sequence parameter set. Range: 0 to 31, inclusive. */
254 unsigned char seq_parameter_set_id;
257 * \brief OR'd flags describing whether the picture is the last one or not.
259 * This fields holds 0 if the picture to be encoded is not the last
260 * one in the stream or sequence. Otherwise, it is a combination of
261 * \ref H264_LAST_PICTURE_EOSEQ or \ref H264_LAST_PICTURE_EOSTREAM.
263 unsigned char last_picture;
265 /** \brief The picture identifier.
266 * Range: 0 to \f$2^{log2\_max\_frame\_num\_minus4 + 4} - 1\f$, inclusive.
268 unsigned short frame_num; /* (0..65535) */
270 /** \brief \c pic_init_qp_minus26 + 26. */
271 unsigned char pic_init_qp;
272 /** \brief Maximum reference index for reference picture list 0.
273 * Range: 0 to 31, inclusive.
275 unsigned char num_ref_idx_l0_active_minus1;
276 /** \brief Maximum reference index for reference picture list 1.
277 * Range: 0 to 31, inclusive.
279 unsigned char num_ref_idx_l1_active_minus1;
281 /** \brief Range: -12 to 12, inclusive. */
282 signed char chroma_qp_index_offset;
283 /** \brief Range: -12 to 12, inclusive. */
284 signed char second_chroma_qp_index_offset;
288 /** \brief Is picture an IDR picture? */
289 unsigned int idr_pic_flag : 1;
290 /** \brief Is picture a reference picture? */
291 unsigned int reference_pic_flag : 2;
292 /** \brief Selects CAVLC (0) or CABAC (1) entropy coding mode. */
293 unsigned int entropy_coding_mode_flag : 1;
294 /** \brief Is weighted prediction applied to P slices? */
295 unsigned int weighted_pred_flag : 1;
296 /** \brief Range: 0 to 2, inclusive. */
297 unsigned int weighted_bipred_idc : 2;
298 /** \brief Same as the H.264 bitstream syntax element. */
299 unsigned int constrained_intra_pred_flag : 1;
300 /** \brief Same as the H.264 bitstream syntax element. */
301 unsigned int transform_8x8_mode_flag : 1;
302 /** \brief Same as the H.264 bitstream syntax element. */
303 unsigned int deblocking_filter_control_present_flag : 1;
304 /** \brief Same as the H.264 bitstream syntax element. */
305 unsigned int redundant_pic_cnt_present_flag : 1;
306 /** \brief Same as the H.264 bitstream syntax element. */
307 unsigned int pic_order_present_flag : 1;
308 /** \brief Same as the H.264 bitstream syntax element. */
309 unsigned int pic_scaling_matrix_present_flag : 1;
313 } VAEncPictureParameterBufferH264;
316 * \brief Slice parameter for H.264 encoding in main & high profiles.
318 * This structure holds information for \c
319 * slice_layer_without_partitioning_rbsp() as defined by the H.264
322 * If packed slice headers mode is used, i.e. if the encoding
323 * pipeline was configured with the #VA_ENC_PACKED_HEADER_SLICE
324 * flag, then the driver expects two more buffers to be provided to
325 * the same \c vaRenderPicture() as this buffer:
326 * - a #VAEncPackedHeaderParameterBuffer with type set to
327 * VAEncPackedHeaderType::VAEncPackedHeaderSlice ;
328 * - a #VAEncPackedHeaderDataBuffer which holds the actual packed
331 * If per-macroblock encoder configuration is needed, \c macroblock_info
332 * references a buffer of type #VAEncMacroblockParameterBufferH264. This
333 * buffer is not passed to vaRenderPicture(). i.e. it is not destroyed
334 * by subsequent calls to vaRenderPicture() and then can be re-used
335 * without re-allocating the whole buffer.
337 typedef struct _VAEncSliceParameterBufferH264 {
338 /** \brief Starting MB address for this slice. */
339 unsigned int macroblock_address;
341 * \brief Per-MB encoder configuration buffer, or \c VA_INVALID_ID.
343 * If per-MB encoder configuration is needed, then \ref macroblock_info
344 * references a buffer of type #VAEncMacroblockParameterBufferH264
345 * (\c VAEncMacroblockParameterBufferType). Otherwise, buffer id
346 * is set to \c VA_INVALID_ID and per-MB configuration is derived
347 * from this slice parameter.
349 * The \c macroblock_info buffer must hold \ref num_macroblocks
352 VABufferID macroblock_info;
353 /** \brief Number of macroblocks in this slice. */
354 unsigned int num_macroblocks;
355 /** \brief Slice type.
356 * Range: 0..2, 5..7, i.e. no switching slices.
358 unsigned char slice_type;
359 /** \brief Same as the H.264 bitstream syntax element. */
360 unsigned char pic_parameter_set_id;
361 /** \brief Same as the H.264 bitstream syntax element. */
362 unsigned short idr_pic_id;
364 /** @name If pic_order_cnt_type == 0 */
366 /** \brief The picture order count modulo MaxPicOrderCntLsb. */
367 unsigned short pic_order_cnt_lsb;
368 /** \brief Valid if \c pic_order_present_flag and this is a bottom field. */
369 int delta_pic_order_cnt_bottom;
371 /** @name If pic_order_cnt_type == 1 && !delta_pic_order_always_zero_flag */
373 /** \brief [0]: top, [1]: bottom. */
374 int delta_pic_order_cnt[2];
377 /** @name If slice_type == B */
379 unsigned char direct_spatial_mv_pred_flag;
382 /** @name If slice_type == P */
384 /** \brief Specifies if
385 * \ref _VAEncPictureParameterBufferH264::num_ref_idx_l0_active_minus1 or
386 * \ref _VAEncPictureParameterBufferH264::num_ref_idx_l1_active_minus1 are
387 * overriden by the values for this slice.
389 unsigned char num_ref_idx_active_override_flag;
390 /** \brief Maximum reference index for reference picture list 0.
391 * Range: 0 to 31, inclusive.
393 unsigned char num_ref_idx_l0_active_minus1;
394 /** \brief Maximum reference index for reference picture list 1.
395 * Range: 0 to 31, inclusive.
397 unsigned char num_ref_idx_l1_active_minus1;
398 /** \brief XXX: is this really used? */
399 VAPictureH264 RefPicList0[32];
400 /** \brief XXX: is this really used? */
401 VAPictureH264 RefPicList1[32];
404 /** @name ref_pic_list_modification() */
406 /** \brief Same as the H.264 bitstream syntax element. */
407 unsigned char ref_pic_list_modification_flag_l0;
408 /** \brief Same as the H.264 bitstream syntax element. */
409 unsigned char ref_pic_list_modification_flag_l1;
410 /** \brief Same as the H.264 bitstream syntax element. */
411 unsigned char modification_of_pic_nums_idc_l0[32];
412 /** \brief Same as the H.264 bitstream syntax element. */
413 unsigned char modification_of_pic_nums_idc_l1[32];
414 /** \brief List 0 values for each \c modification_of_pic_nums_idc_l0. */
416 * - If \c modification_of_pic_nums_idc == 0 or 1:
417 * - \c modification_of_pic_nums_value is \c abs_diff_pic_num_minus1
418 * - If \c modification_of_pic_nums_idc == 2:
419 * - \c modification_of_pic_nums_value is \c long_term_pic_num
421 unsigned int modification_of_pic_nums_value_l0[32];
422 /** \brief Same as \c modification_of_pic_nums_value_l0 but for list 1. */
423 unsigned int modification_of_pic_nums_value_l1[32];
426 /** @name pred_weight_table() */
428 /** \brief Same as the H.264 bitstream syntax element. */
429 unsigned char luma_log2_weight_denom;
430 /** \brief Same as the H.264 bitstream syntax element. */
431 unsigned char chroma_log2_weight_denom;
432 /** \brief Same as the H.264 bitstream syntax element. */
433 unsigned char luma_weight_l0_flag;
434 /** \brief Same as the H.264 bitstream syntax element. */
435 signed short luma_weight_l0[32];
436 /** \brief Same as the H.264 bitstream syntax element. */
437 signed short luma_offset_l0[32];
438 /** \brief Same as the H.264 bitstream syntax element. */
439 unsigned char chroma_weight_l0_flag;
440 /** \brief Same as the H.264 bitstream syntax element. */
441 signed short chroma_weight_l0[32][2];
442 /** \brief Same as the H.264 bitstream syntax element. */
443 signed short chroma_offset_l0[32][2];
444 /** \brief Same as the H.264 bitstream syntax element. */
445 unsigned char luma_weight_l1_flag;
446 /** \brief Same as the H.264 bitstream syntax element. */
447 signed short luma_weight_l1[32];
448 /** \brief Same as the H.264 bitstream syntax element. */
449 signed short luma_offset_l1[32];
450 /** \brief Same as the H.264 bitstream syntax element. */
451 unsigned char chroma_weight_l1_flag;
452 /** \brief Same as the H.264 bitstream syntax element. */
453 signed short chroma_weight_l1[32][2];
454 /** \brief Same as the H.264 bitstream syntax element. */
455 signed short chroma_offset_l1[32][2];
458 /** @name dec_ref_pic_marking() */
460 /** \brief Same as the H.264 bitstream syntax element. */
461 unsigned char no_output_of_prior_pics_flag;
462 /** \brief Same as the H.264 bitstream syntax element. */
463 unsigned char long_term_reference_flag;
464 /** \brief Same as the H.264 bitstream syntax element. */
465 unsigned char adaptive_ref_pic_marking_mode_flag;
466 /** \brief Same as the \c memory_management_control_operation syntax element. */
467 unsigned char mmco[32];
469 * \brief Values for each \c memory_management_control_operation.
472 * - \c mmco_value[0] is \c difference_of_pic_nums_minus1
473 * - \c mmco_value[1] is not used
475 * - \c mmco_value[0] is \c long_term_pic_num
476 * - \c mmco_value[1] is not used
478 * - \c mmco_value[0] is \c difference_of_pic_nums_minus1
479 * - \c mmco_value[1] is \c long_term_frame_idx
481 * - \c mmco_value[0] is \c max_long_term_frame_idx_plus1
482 * - \c mmco_value[1] is not used
484 * - \c mmco_value[0] is \c long_term_frame_idx
485 * - \c mmco_value[1] is not used
487 unsigned int mmco_value[32][2];
490 /** \brief Range: 0 to 2, inclusive. */
491 unsigned char cabac_init_idc;
492 /** \brief Same as the H.264 bitstream syntax element. */
493 signed char slice_qp_delta;
494 /** @name If deblocking_filter_control_present_flag */
496 /** \brief Range: 0 to 2, inclusive. */
497 unsigned char disable_deblocking_filter_idc;
498 /** \brief Same as the H.264 bitstream syntax element. */
499 signed char slice_alpha_c0_offset_div2;
500 /** \brief Same as the H.264 bitstream syntax element. */
501 signed char slice_beta_offset_div2;
503 } VAEncSliceParameterBufferH264;
506 * @name Macroblock neighbour availability bits
508 * \anchor api_enc_h264_mb_pred_avail_bits
509 * Definitions for macroblock neighbour availability bits used in
510 * intra prediction mode (non MBAFF only).
514 /** \brief References macroblock in the top-left corner. */
515 #define VA_MB_PRED_AVAIL_TOP_LEFT (1 << 2)
516 /** \brief References macroblock above the current macroblock. */
517 #define VA_MB_PRED_AVAIL_TOP (1 << 4)
518 /** \brief References macroblock in the top-right corner. */
519 #define VA_MB_PRED_AVAIL_TOP_RIGHT (1 << 3)
520 /** \brief References macroblock on the left of the current macroblock. */
521 #define VA_MB_PRED_AVAIL_LEFT (1 << 6)
525 * \brief Macroblock parameter for H.264 encoding in main & high profiles.
527 * This structure holds per-macroblock information. The buffer must be
528 * allocated with as many elements (macroblocks) as necessary to fit
529 * the slice to be encoded. Besides, the per-macroblock records must
530 * be written in a strict raster order and with no gap. i.e. every
531 * macroblock, regardless of its type, shall have an entry.
533 typedef struct _VAEncMacroblockParameterBufferH264 {
535 * \brief Quantization parameter.
537 * Requested quantization parameter. Range: 0 to 51, inclusive.
538 * If \ref qp is set to 0xff, then the actual value is derived
539 * from the slice-level value: \c pic_init_qp + \c slice_qp_delta.
544 /** @name Data for intra macroblock */
549 * \brief Flag specified to override MB neighbour
550 * availability bits from VME stage.
552 * This flag specifies that macroblock neighbour
553 * availability bits from the VME stage are overriden
554 * by the \ref pred_avail_flags hereunder.
556 unsigned int pred_avail_override_flag : 1;
558 * \brief Bitwise representation of which macroblocks
559 * are available for intra prediction.
561 * If the slice is intra-coded, this field represents
562 * the macroblocks available for intra prediction.
563 * See \ref api_enc_h264_mb_pred_avail_bits
564 * "macroblock neighbour availability" bit definitions.
566 unsigned int pred_avail_flags : 8;
572 /** @name Data for inter macroblock */
581 } VAEncMacroblockParameterBufferH264;
589 #endif /* VA_ENC_H264_H */