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
28 enum AVVideoEncParamsType {
29 AV_VIDEO_ENC_PARAMS_NONE = -1,
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 */
44 AV_VIDEO_ENC_PARAMS_VP9,
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 */
57 AV_VIDEO_ENC_PARAMS_H264,
58
59 /*
60 * MPEG-2-compatible quantizer.
61 *
62 * Summing the frame-level qp with the per-block delta_qp gives the
63 * resulting quantizer for the block.
64 */
65 AV_VIDEO_ENC_PARAMS_MPEG2,
66 };
67
68 /**
69 * Video encoding parameters for a given frame. This struct is allocated along
70 * with an optional array of per-block AVVideoBlockParams descriptors.
71 * Must be allocated with av_video_enc_params_alloc().
72 */
73 typedef struct AVVideoEncParams {
74 /**
75 * Number of blocks in the array.
76 *
77 * May be 0, in which case no per-block information is present. In this case
78 * the values of blocks_offset / block_size are unspecified and should not
79 * be accessed.
80 */
81 unsigned int nb_blocks;
82 /**
83 * Offset in bytes from the beginning of this structure at which the array
84 * of blocks starts.
85 */
86 size_t blocks_offset;
87 /*
88 * Size of each block in bytes. May not match sizeof(AVVideoBlockParams).
89 */
90 size_t block_size;
91
92 /**
93 * Type of the parameters (the codec they are used with).
94 */
95 enum AVVideoEncParamsType type;
96
97 /**
98 * Base quantisation parameter for the frame. The final quantiser for a
99 * given block in a given plane is obtained from this value, possibly
100 * combined with {@code delta_qp} and the per-block delta in a manner
101 * documented for each type.
102 */
103 int32_t qp;
104
105 /**
106 * Quantisation parameter offset from the base (per-frame) qp for a given
107 * plane (first index) and AC/DC coefficients (second index).
108 */
109 int32_t delta_qp[4][2];
110 } AVVideoEncParams;
111
112 /**
113 * Data structure for storing block-level encoding information.
114 * It is allocated as a part of AVVideoEncParams and should be retrieved with
115 * av_video_enc_params_block().
116 *
117 * sizeof(AVVideoBlockParams) is not a part of the ABI and new fields may be
118 * added to it.
119 */
120 typedef struct AVVideoBlockParams {
121 /**
122 * Distance in luma pixels from the top-left corner of the visible frame
123 * to the top-left corner of the block.
124 * Can be negative if top/right padding is present on the coded frame.
125 */
126 int src_x, src_y;
127 /**
128 * Width and height of the block in luma pixels.
129 */
130 int w, h;
131
132 /**
133 * Difference between this block's final quantization parameter and the
134 * corresponding per-frame value.
135 */
136 int32_t delta_qp;
137 } AVVideoBlockParams;
138
139 /*
140 * Get the block at the specified {@code idx}. Must be between 0 and nb_blocks.
141 */
142 static av_always_inline AVVideoBlockParams*
av_video_enc_params_block(AVVideoEncParams * par,unsigned int idx)143 av_video_enc_params_block(AVVideoEncParams *par, unsigned int idx)
144 {
145 av_assert0(idx < par->nb_blocks);
146 return (AVVideoBlockParams *)((uint8_t *)par + par->blocks_offset +
147 idx * par->block_size);
148 }
149
150 /**
151 * Allocates memory for AVVideoEncParams of the given type, plus an array of
152 * {@code nb_blocks} AVVideoBlockParams and initializes the variables. Can be
153 * freed with a normal av_free() call.
154 *
155 * @param out_size if non-NULL, the size in bytes of the resulting data array is
156 * written here.
157 */
158 AVVideoEncParams *av_video_enc_params_alloc(enum AVVideoEncParamsType type,
159 unsigned int nb_blocks, size_t *out_size);
160
161 /**
162 * Allocates memory for AVEncodeInfoFrame plus an array of
163 * {@code nb_blocks} AVEncodeInfoBlock in the given AVFrame {@code frame}
164 * as AVFrameSideData of type AV_FRAME_DATA_VIDEO_ENC_PARAMS
165 * and initializes the variables.
166 */
167 AVVideoEncParams*
168 av_video_enc_params_create_side_data(AVFrame *frame, enum AVVideoEncParamsType type,
169 unsigned int nb_blocks);
170
171 #endif /* AVUTIL_VIDEO_ENC_PARAMS_H */
172