FFmpeg  4.3.1
video_enc_params.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 #ifndef AVUTIL_VIDEO_ENC_PARAMS_H
20 #define AVUTIL_VIDEO_ENC_PARAMS_H
21 
22 #include <stddef.h>
23 #include <stdint.h>
24 
25 #include "libavutil/avassert.h"
26 #include "libavutil/frame.h"
27 
30  /**
31  * VP9 stores:
32  * - per-frame base (luma AC) quantizer index, exported as AVVideoEncParams.qp
33  * - deltas for luma DC, chroma AC and chroma DC, exported in the
34  * corresponding entries in AVVideoEncParams.delta_qp
35  * - per-segment delta, exported as for each block as AVVideoBlockParams.delta_qp
36  *
37  * To compute the resulting quantizer index for a block:
38  * - for luma AC, add the base qp and the per-block delta_qp, saturating to
39  * unsigned 8-bit.
40  * - for luma DC and chroma AC/DC, add the corresponding
41  * AVVideoBlockParams.delta_qp to the luma AC index, again saturating to
42  * unsigned 8-bit.
43  */
45 
46  /**
47  * H.264 stores:
48  * - in PPS (per-picture):
49  * * initial QP_Y (luma) value, exported as AVVideoEncParams.qp
50  * * delta(s) for chroma QP values (same for both, or each separately),
51  * exported as in the corresponding entries in AVVideoEncParams.delta_qp
52  * - per-slice QP delta, not exported directly, added to the per-MB value
53  * - per-MB delta; not exported directly; the final per-MB quantizer
54  * parameter - QP_Y - minus the value in AVVideoEncParams.qp is exported
55  * as AVVideoBlockParams.qp_delta.
56  */
58 };
59 
60 /**
61  * Video encoding parameters for a given frame. This struct is allocated along
62  * with an optional array of per-block AVVideoBlockParams descriptors.
63  * Must be allocated with av_video_enc_params_alloc().
64  */
65 typedef struct AVVideoEncParams {
66  /**
67  * Number of blocks in the array.
68  *
69  * May be 0, in which case no per-block information is present. In this case
70  * the values of blocks_offset / block_size are unspecified and should not
71  * be accessed.
72  */
73  unsigned int nb_blocks;
74  /**
75  * Offset in bytes from the beginning of this structure at which the array
76  * of blocks starts.
77  */
78  size_t blocks_offset;
79  /*
80  * Size of each block in bytes. May not match sizeof(AVVideoBlockParams).
81  */
82  size_t block_size;
83 
84  /**
85  * Type of the parameters (the codec they are used with).
86  */
88 
89  /**
90  * Base quantisation parameter for the frame. The final quantiser for a
91  * given block in a given plane is obtained from this value, possibly
92  * combined with {@code delta_qp} and the per-block delta in a manner
93  * documented for each type.
94  */
95  int32_t qp;
96 
97  /**
98  * Quantisation parameter offset from the base (per-frame) qp for a given
99  * plane (first index) and AC/DC coefficients (second index).
100  */
101  int32_t delta_qp[4][2];
103 
104 /**
105  * Data structure for storing block-level encoding information.
106  * It is allocated as a part of AVVideoEncParams and should be retrieved with
107  * av_video_enc_params_block().
108  *
109  * sizeof(AVVideoBlockParams) is not a part of the ABI and new fields may be
110  * added to it.
111  */
112 typedef struct AVVideoBlockParams {
113  /**
114  * Distance in luma pixels from the top-left corner of the visible frame
115  * to the top-left corner of the block.
116  * Can be negative if top/right padding is present on the coded frame.
117  */
118  int src_x, src_y;
119  /**
120  * Width and height of the block in luma pixels.
121  */
122  int w, h;
123 
124  /**
125  * Difference between this block's final quantization parameter and the
126  * corresponding per-frame value.
127  */
128  int32_t delta_qp;
130 
131 /*
132  * Get the block at the specified {@code idx}. Must be between 0 and nb_blocks.
133  */
136 {
137  av_assert0(idx < par->nb_blocks);
138  return (AVVideoBlockParams *)((uint8_t *)par + par->blocks_offset +
139  idx * par->block_size);
140 }
141 
142 /**
143  * Allocates memory for AVVideoEncParams of the given type, plus an array of
144  * {@code nb_blocks} AVVideoBlockParams and initializes the variables. Can be
145  * freed with a normal av_free() call.
146  *
147  * @param out_size if non-NULL, the size in bytes of the resulting data array is
148  * written here.
149  */
151  unsigned int nb_blocks, size_t *out_size);
152 
153 /**
154  * Allocates memory for AVEncodeInfoFrame plus an array of
155  * {@code nb_blocks} AVEncodeInfoBlock in the given AVFrame {@code frame}
156  * as AVFrameSideData of type AV_FRAME_DATA_ENCODE_INFO
157  * and initializes the variables.
158  */
161  unsigned int nb_blocks);
162 
163 #endif /* AVUTIL_VIDEO_ENC_PARAMS_H */
#define av_always_inline
Definition: attributes.h:45
simple assert() macros that are a bit more flexible than ISO C assert().
#define av_assert0(cond)
assert() equivalent, that is always enabled.
Definition: avassert.h:37
static AVFrame * frame
reference-counted frame API
This structure describes decoded (raw) audio or video data.
Definition: frame.h:300
Data structure for storing block-level encoding information.
int src_x
Distance in luma pixels from the top-left corner of the visible frame to the top-left corner of the b...
int w
Width and height of the block in luma pixels.
int32_t delta_qp
Difference between this block's final quantization parameter and the corresponding per-frame value.
Video encoding parameters for a given frame.
int32_t delta_qp[4][2]
Quantisation parameter offset from the base (per-frame) qp for a given plane (first index) and AC/DC ...
enum AVVideoEncParamsType type
Type of the parameters (the codec they are used with).
unsigned int nb_blocks
Number of blocks in the array.
int32_t qp
Base quantisation parameter for the frame.
size_t blocks_offset
Offset in bytes from the beginning of this structure at which the array of blocks starts.
AVVideoEncParams * av_video_enc_params_create_side_data(AVFrame *frame, enum AVVideoEncParamsType type, unsigned int nb_blocks)
Allocates memory for AVEncodeInfoFrame plus an array of.
static av_always_inline AVVideoBlockParams * av_video_enc_params_block(AVVideoEncParams *par, unsigned int idx)
AVVideoEncParams * av_video_enc_params_alloc(enum AVVideoEncParamsType type, unsigned int nb_blocks, size_t *out_size)
Allocates memory for AVVideoEncParams of the given type, plus an array of.
AVVideoEncParamsType
@ AV_VIDEO_ENC_PARAMS_NONE
@ AV_VIDEO_ENC_PARAMS_VP9
VP9 stores:
@ AV_VIDEO_ENC_PARAMS_H264
H.264 stores: