1 /******************************************************************************
2  *
3  * Copyright (C) 2015 The Android Open Source Project
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at:
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  *****************************************************************************
18  * Originally developed and contributed by Ittiam Systems Pvt. Ltd, Bangalore
19 */
20 
21 /**
22 *******************************************************************************
23 * @file
24 *  ih264e_utils.h
25 *
26 * @brief
27 *  Contains declarations of miscellaneous utility functions used by the encoder
28 *
29 * @author
30 *  Harish
31 *
32 * @par List of Functions:
33 *  -ih264e_input_queue_update()
34 *  -ih264e_get_min_level()
35 *  -ih264e_get_lvl_idx()
36 *  -ih264e_get_dpb_size()
37 *  -ih264e_get_total_pic_buf_size()
38 *  -ih264e_get_pic_mv_bank_size()
39 *  -ih264e_pic_buf_mgr_add_bufs()
40 *  -ih264e_mv_buf_mgr_add_bufs()
41 *  -ih264e_init_quant_params()
42 *  -ih264e_init_air_map()
43 *  -ih264e_codec_init()
44 *  -ih264e_pic_init()
45 *
46 * @remarks
47 *  None
48 *
49 *******************************************************************************
50 */
51 
52 #ifndef IH264E_UTILS_H_
53 #define IH264E_UTILS_H_
54 
55 /**
56  *******************************************************************************
57  *
58  * @brief
59  *  Queues the current buffer, gets back a another buffer for encoding with corrent
60  *  picture type
61  *
62  * @par Description:
63  *
64  * @param[in] ps_codec
65  *   Pointer to codec descriptor
66  *
67  * @param[in] ps_ive_ip
68  *   Current input buffer to the encoder
69  *
70  * @param[out] ps_inp
71  *   Buffer to be encoded in the current pass
72  *
73  * @returns
74  *   Flag indicating if we have a pre-enc skip or not
75  *
76  * @remarks
77  *
78  *******************************************************************************
79  */
80 WORD32 ih264e_input_queue_update(codec_t *ps_codec,
81                                  ive_video_encode_ip_t *ps_ive_ip,
82                                  inp_buf_t *ps_enc_buff);
83 
84 /**
85 *******************************************************************************
86 *
87 * @brief
88 *  Used to get minimum level index for a given picture size
89 *
90 * @par Description:
91 *  Gets the minimum level index and then gets corresponding level.
92 *  Also used to ignore invalid levels like 2.3, 3.3 etc
93 *
94 * @param[in] wd
95 *  Width
96 *
97 * @param[in] ht
98 *  Height
99 *
100 * @returns  Level index for a given level
101 *
102 * @remarks
103 *
104 *******************************************************************************
105 */
106 WORD32 ih264e_get_min_level(WORD32 wd, WORD32 ht);
107 
108 /**
109 *******************************************************************************
110 *
111 * @brief
112 *  Used to get level index for a given level
113 *
114 * @par Description:
115 *  Converts from level_idc (which is multiplied by 30) to an index that can be
116 *  used as a lookup. Also used to ignore invalid levels like 2.2 , 3.2 etc
117 *
118 * @param[in] level
119 *  Level of the stream
120 *
121 * @returns  Level index for a given level
122 *
123 * @remarks
124 *
125 *******************************************************************************
126 */
127 WORD32 ih264e_get_lvl_idx(WORD32 level);
128 
129 /**
130 *******************************************************************************
131 *
132 * @brief returns maximum number of pictures allowed in dpb for a given level
133 *
134 * @par Description:
135 *  For given width, height and level, number of pictures allowed in decoder
136 *  picture buffer is computed as per Annex A.3.1
137 *
138 * @param[in] level
139 *  level of the bit-stream
140 *
141 * @param[in] pic_size
142 *  width * height
143 *
144 * @returns  Number of buffers in DPB
145 *
146 * @remarks
147 *  From annexure A.3.1 of H264 specification,
148 *  max_dec_frame_buffering <= MaxDpbSize, where MaxDpbSize is equal to
149 *  Min( 1024 * MaxDPB / ( PicWidthInMbs * FrameHeightInMbs * 384 ), 16 ) and
150 *  MaxDPB is given in Table A-1 in units of 1024 bytes. However the MaxDPB size
151 *  presented in the look up table gas_ih264_lvl_tbl is in units of 512
152 *  bytes. Hence the expression is modified accordingly.
153 *
154 *******************************************************************************
155 */
156 WORD32 ih264e_get_dpb_size(WORD32 level, WORD32 pic_size);
157 
158 /**
159 *******************************************************************************
160 *
161 * @brief
162 *  Used to get reference picture buffer size for a given level and
163 *  and padding used
164 *
165 * @par Description:
166 *  Used to get reference picture buffer size for a given level and padding used
167 *  Each picture is padded on all four sides
168 *
169 * @param[in] pic_size
170 *  Number of luma samples (Width * Height)
171 *
172 * @param[in] level
173 *  Level
174 *
175 * @param[in] horz_pad
176 *  Total padding used in horizontal direction
177 *
178 * @param[in] vert_pad
179 *  Total padding used in vertical direction
180 *
181 * @returns  Total picture buffer size
182 *
183 * @remarks
184 *
185 *
186 *******************************************************************************
187 */
188 WORD32 ih264e_get_total_pic_buf_size(WORD32 pic_size, WORD32 level,
189                                      WORD32 horz_pad, WORD32 vert_pad,
190                                      WORD32 num_ref_frames,
191                                      WORD32 num_reorder_frames);
192 
193 /**
194 *******************************************************************************
195 *
196 * @brief Returns MV bank buffer size for a given number of luma samples
197 *
198 * @par Description:
199 *  For given number of luma samples  one MV bank size is computed.
200 *  Each MV bank includes pu_map and enc_pu_t for all the min PUs(4x4) in a picture
201 *
202 * @param[in] num_luma_samples
203 *  Max number of luma pixels in the frame
204 *
205 * @returns  Total MV Bank size
206 *
207 * @remarks
208 *
209 *
210 *******************************************************************************
211 */
212 WORD32 ih264e_get_pic_mv_bank_size(WORD32 num_luma_samples);
213 
214 /**
215 *******************************************************************************
216 *
217 * @brief
218 *  Function to initialize ps_pic_buf structs add pic buffers to
219 *  buffer manager in case of non-shared mode
220 *
221 * @par Description:
222 *  Function to initialize ps_pic_buf structs add pic buffers to
223 *  buffer manager in case of non-shared mode
224 *  To be called once per stream or for every reset
225 *
226 * @param[in] ps_codec
227 *  Pointer to codec context
228 *
229 * @returns  error status
230 *
231 * @remarks
232 *
233 *
234 *******************************************************************************
235 */
236 IH264E_ERROR_T ih264e_pic_buf_mgr_add_bufs(codec_t *ps_codec);
237 
238 /**
239 *******************************************************************************
240 *
241 * @brief Function to add buffers to MV Bank buffer manager
242 *
243 * @par Description:
244 *  Function to add buffers to MV Bank buffer manager.  To be called once per
245 *  stream or for every reset
246 *
247 * @param[in] ps_codec
248 *  Pointer to codec context
249 *
250 * @returns  error status
251 *
252 * @remarks
253 *
254 *******************************************************************************
255 */
256 IH264E_ERROR_T ih264e_mv_buf_mgr_add_bufs(codec_t *ps_codec);
257 
258 /**
259 *******************************************************************************
260 *
261 * @brief Function to initialize quant params structure
262 *
263 * @par Description:
264 *  The forward quantization modules depends on qp/6, qp mod 6, forward scale
265 *  matrix, forward threshold matrix, weight list. The inverse quantization
266 *  modules depends on qp/6, qp mod 6, inverse scale matrix, weight list.
267 *  These params are initialized in this function.
268 *
269 * @param[in] ps_proc
270 *  pointer to process context
271 *
272 * @param[in] qp
273 *  quantization parameter
274 *
275 * @returns none
276 *
277 * @remarks
278 *
279 *******************************************************************************
280 */
281 void ih264e_init_quant_params(process_ctxt_t *ps_proc, int qp);
282 
283 /**
284 *******************************************************************************
285 *
286 * @brief
287 *  Initialize AIR mb frame Map
288 *
289 * @par Description:
290 *  Initialize AIR mb frame map
291 *  MB frame map indicates which frame an Mb should be coded as intra according to AIR
292 *
293 * @param[in] ps_codec
294 *  Pointer to codec context
295 *
296 * @returns  error_status
297 *
298 * @remarks
299 *
300 *
301 *******************************************************************************
302 */
303 IH264E_ERROR_T ih264e_init_air_map(codec_t *ps_codec);
304 
305 /**
306 *******************************************************************************
307 *
308 * @brief
309 *  Codec level initializations
310 *
311 * @par Description:
312 *  Initializes the codec with parameters that needs to be set before encoding
313 *  first frame
314 *
315 * @param[in] ps_codec
316 *  Pointer to codec context
317 *
318 * @param[in] ps_inp_buf
319 *  Pointer to input buffer context
320 *
321 * @returns  error_status
322 *
323 * @remarks
324 *
325 *
326 *******************************************************************************
327 */
328 IH264E_ERROR_T ih264e_codec_init(codec_t *ps_codec);
329 
330 /**
331 *******************************************************************************
332 *
333 * @brief
334 *  Picture level initializations
335 *
336 * @par Description:
337 *  Before beginning to encode the frame, the current function initializes all
338 *  the ctxts (proc, entropy, me, ...) basing on the input configured params.
339 *  It locates space for storing recon in the encoder picture buffer set, fetches
340 *  reference frame from encoder picture buffer set. Calls RC pre-enc to get
341 *  qp and pic type for the current frame. Queues proc jobs so that
342 *  the other threads can begin encoding. In brief, this function sets up the
343 *  tone for the entire encoder.
344 *
345 * @param[in] ps_codec
346 *  Pointer to codec context
347 *
348 * @param[in] ps_inp_buf
349 *  Pointer to input buffer context
350 *
351 * @returns  error_status
352 *
353 * @remarks
354 *
355 *
356 *******************************************************************************
357 */
358 IH264E_ERROR_T ih264e_pic_init(codec_t *ps_codec, inp_buf_t *ps_inp_buf);
359 
360 #endif /* IH264E_UTILS_H_ */
361