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_rate_control.h
25 *
26 * @brief
27 *  This file contains function declarations of api functions for h264 rate
28 *  control
29 *
30 * @author
31 *  ittiam
32 *
33 * @remarks
34 *  None
35 *
36 *******************************************************************************
37 */
38 
39 #ifndef IH264E_RATE_CONTROL_H_
40 #define IH264E_RATE_CONTROL_H_
41 
42 /*****************************************************************************/
43 /* Function Declarations                                                     */
44 /*****************************************************************************/
45 
46 /**
47 *******************************************************************************
48 *
49 * @brief
50 *  This function initializes rate control context and variables
51 *
52 * @par Description
53 *  This function initializes rate control type, source and target frame rate,
54 *  average and peak bitrate, intra-inter frame interval and initial
55 *  quantization parameter
56 *
57 * @param[in] pv_rc_api
58 *  Handle to rate control api
59 *
60 * @param[in] pv_frame_time
61 *  Handle to frame time context
62 *
63 * @param[in] pv_time_stamp
64 *  Handle to time stamp context
65 *
66 * @param[in] pv_pd_frm_rate
67 *  Handle to pull down frame time context
68 *
69 * @param[in] u4_max_frm_rate
70 *  Maximum frame rate
71 *
72 * @param[in] u4_src_frm_rate
73 *  Source frame rate
74 *
75 * @param[in] u4_tgt_frm_rate
76 *  Target frame rate
77 *
78 * @param[in] e_rate_control_type
79 *  Rate control type
80 *
81 * @param[in] u4_avg_bit_rate
82 *  Average bit rate
83 *
84 * @param[in] u4_peak_bit_rate
85 *  Peak bit rate
86 *
87 * @param[in] u4_max_delay
88 *  Maximum delay between frames
89 *
90 * @param[in] u4_intra_frame_interval
91 *  Intra frame interval
92 *
93 * @param[in] i4_inter_frm_int
94 *  Inter frame interval
95 *
96 * @param[in] pu1_init_qp
97 *  Initial qp
98 *
99 * @param[in] i4_max_inter_frm_int
100 *  Maximum inter frame interval
101 *
102 * @param[in] pu1_min_max_qp
103 *  Array of min/max qp
104 *
105 * @param[in] u1_profile_level
106 *  Encoder profile level
107 *
108 * @returns none
109 *
110 * @remarks
111 *
112 *******************************************************************************
113 */
114 void ih264e_rc_init(void *pv_rc_api,
115                     void *pv_frame_time,
116                     void *pv_time_stamp,
117                     void *pv_pd_frm_rate,
118                     UWORD32 u4_max_frm_rate,
119                     UWORD32 u4_src_frm_rate,
120                     UWORD32 u4_tgt_frm_rate,
121                     rc_type_e e_rate_control_type,
122                     UWORD32 u4_avg_bit_rate,
123                     UWORD32 u4_peak_bit_rate,
124                     UWORD32 u4_max_delay,
125                     UWORD32 u4_intra_frame_interval,
126                     WORD32  i4_inter_frm_int,
127                     UWORD8 *pu1_init_qp,
128                     WORD32 i4_max_inter_frm_int,
129                     UWORD8 *pu1_min_max_qp,
130                     UWORD8 u1_profile_level);
131 
132 /**
133 *******************************************************************************
134 *
135 * @brief Function to get picture details
136 *
137 * @par   Description
138 *  This function returns the Picture type(I/P/B)
139 *
140 * @param[in] pv_rc_api
141 *  Handle to Rate control api
142 *
143 * @returns
144 *  Picture type
145 *
146 * @remarks none
147 *
148 *******************************************************************************
149 */
150 picture_type_e ih264e_rc_get_picture_details(void *pv_rc_api,
151                                              WORD32 *pi4_pic_id,
152                                              WORD32 *pi4_pic_disp_order_no);
153 
154 
155 /**
156 *******************************************************************************
157 *
158 * @brief  Function to set frame rate inside RC.
159 *
160 * @par Description
161 *  This function is called before encoding the current frame and gets the qp
162 *  for the current frame from rate control module
163 *
164 * @param[in] ps_rate_control_api
165 *  Handle to rate control api
166 *
167 * @param[in] ps_pd_frm_rate
168 *  Handle to pull down frm rate context
169 *
170 * @param[in] ps_time_stamp
171 *  Handle to time stamp context
172 *
173 * @param[in] ps_frame_time
174 *  Handle to frame time context
175 *
176 * @returns
177 *  Skip or encode the current frame
178 *
179 * @remarks
180 *
181 *******************************************************************************
182 */
183 WORD32 ih264e_update_rc_framerates(void *ps_rate_control_api,
184                          void *ps_pd_frm_rate,
185                          void *ps_time_stamp,
186                          void *ps_frame_time
187                          );
188 
189 /**
190 *******************************************************************************
191 *
192 * @brief Function to update mb info for rate control context
193 *
194 * @par   Description
195 *  After encoding a mb, information such as mb type, qp used, mb distortion
196 *  resulted in encoding the block and so on needs to be preserved for modelling
197 *  RC. This is preserved via this function call.
198 *
199 * @param[in] ps_frame_info
200 *  Handle Frame info context
201 *
202 * @param[in] ps_proc
203 *  Process context
204 *
205 * @returns
206 *
207 * @remarks
208 *
209 *******************************************************************************
210 */
211 void ih264e_update_rc_mb_info(frame_info_t *ps_frame_info, void *pv_proc);
212 
213 /**
214 *******************************************************************************
215 *
216 * @brief Function to get rate control buffer status
217 *
218 * @par Description
219 *  This function is used to get buffer status(underflow/overflow) by rate
220 *  control module
221 *
222 * @param[in] pv_rc_api
223 *  Handle to rate control api context
224 *
225 * @param[in] i4_total_frame_bits
226 *  Total frame bits
227 *
228 * @param[in] u1_pic_type
229 *  Picture type
230 *
231 * @param[in] pi4_num_bits_to_prevent_vbv_underflow
232 *  Number of bits to prevent underflow
233 *
234 * @param[out] pu1_is_enc_buf_overflow
235 *  Buffer overflow indication flag
236 *
237 * @param[out] pu1_is_enc_buf_underflow
238 *  Buffer underflow indication flag
239 *
240 * @returns
241 *
242 * @remarks
243 *
244 *******************************************************************************
245 */
246 void ih264e_rc_get_buffer_status(void *pv_rc_api,
247                                  WORD32 i4_total_frame_bits,
248                                  picture_type_e e_pic_type,
249                                  WORD32 *pi4_num_bits_to_prevent_vbv_underflow,
250                                  UWORD8 *pu1_is_enc_buf_overflow,
251                                  UWORD8 *pu1_is_enc_buf_underflow);
252 
253 /**
254 *******************************************************************************
255 *
256 * @brief Function to update rate control module after encoding
257 *
258 * @par Description
259 *  This function is used to update the rate control module after the current
260 *  frame encoding is done with details such as bits consumed, SAD for I/P/B,
261 *  intra cost ,mb type and other
262 *
263 * @param[in] ps_rate_control_api
264 *  Handle to rate control api context
265 *
266 * @param[in] ps_frame_info
267 *  Handle to frame info context
268 *
269 * @param[in] ps_pd_frm_rate
270 *  Handle to pull down frame rate context
271 *
272 * @param[in] ps_time_stamp
273 *  Handle to time stamp context
274 *
275 * @param[in] ps_frame_time
276 *  Handle to frame time context
277 *
278 * @param[in] i4_total_mb_in_frame
279 *  Total mb in frame
280 *
281 * @param[in] pe_vop_coding_type
282 *  Picture coding type
283 *
284 * @param[in] i4_is_first_frame
285 *  Is first frame
286 *
287 * @param[in] pi4_is_post_encode_skip
288 *  Post encoding skip flag
289 *
290 * @param[in] u1_frame_qp
291 *  Frame qp
292 *
293 * @param[in] pi4_num_intra_in_prev_frame
294 *  Number of intra mbs in previous frame
295 *
296 * @param[in] pi4_avg_activity
297 *  Average activity
298 *
299 * @returns
300 *
301 * @remarks
302 *
303 *******************************************************************************
304 */
305 WORD32 ih264e_rc_post_enc(void *ps_rate_control_api,
306                          frame_info_t *ps_frame_info,
307                          void *ps_pd_frm_rate,
308                          void *ps_time_stamp,
309                          void *ps_frame_time,
310                          WORD32 i4_total_mb_in_frame,
311                          picture_type_e *pe_vop_coding_type,
312                          WORD32 i4_is_first_frame,
313                          WORD32 *pi4_is_post_encode_skip,
314                          UWORD8 u1_frame_qp,
315                          WORD32 *pi4_num_intra_in_prev_frame,
316                          WORD32 *pi4_avg_activity);
317 
318 /**
319 *******************************************************************************
320 *
321 * @brief Function to update bits consumed info to rate control context
322 *
323 * @par Description
324 *  Function to update bits consume info to rate control context
325 *
326 * @param[in] ps_frame_info
327 *  Frame info context
328 *
329 * @param[in] ps_entropy
330 *  Entropy context
331 *
332 * @returns
333 *  total bits consumed by the frame
334 *
335 * @remarks
336 *
337 *******************************************************************************
338 */
339 void ih264e_update_rc_bits_info(frame_info_t *ps_frame_info, void *pv_entropy);
340 
341 #endif /* IH264E_RATE_CONTROL_H */
342 
343