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_time_stamp.h
25 *
26 * @brief
27 *  This file contains function declarations used for managing input and output
28 *  frame time stamps
29 *
30 * @author
31 *  ittiam
32 *
33 * @remarks
34 *  None
35 *
36 *******************************************************************************
37 */
38 
39 #ifndef IH264E_TIME_STAMP_H_
40 #define IH264E_TIME_STAMP_H_
41 
42 /*****************************************************************************/
43 /* Structures                                                                */
44 /*****************************************************************************/
45 
46 /**
47  * Parameters for Src/Tgt frames that are encoded
48  */
49 typedef struct frame_time_t
50 {
51     /* common time base(=LCM) between source and target frame rate (in ticks)*/
52     WORD32 common_time_base;
53 
54     /* number of ticks between two source frames */
55     UWORD32 u4_src_frm_time_incr;
56 
57     /* number of ticks between two target frames */
58     UWORD32 u4_tgt_frm_time_incr;
59 
60     /* Source frame time - measured as modulo of common time base
61      and incremented by src_frm_time_incr */
62     UWORD32 u4_src_frm_time;
63 
64     /* Target frame time - measured as modulo of common time base
65      and incremented by tgt_frm_time_incr */
66     UWORD32 u4_tgt_frm_time;
67 
68     /* Number of frames not to be skipped while maintaining
69      tgt_frm_rate due to delta_time_stamp  */
70     UWORD32 u4_num_frms_dont_skip;
71 }frame_time_t;
72 
73 typedef struct frame_time_t *frame_time_handle;
74 
75 /**
76  *  Parameters that go in the bitstream based on tgt_frm_rate
77  *   1) Initialize the vop_time_incr_res with the max_frame_rate (in frames per 1000 bits)
78  *      - To represent all kinds of frame rates
79  *   2) Decide the vop_time_incr based on the source frame rate
80  *      - The decoder would like to know which source frame is encoded i.e. the source time
81  *    id of the target frame encoded and there by adjusting its time of delay
82  *   3) vop_time increments every source frame and whenever a frame is encoded (target frame),
83  *      the encoder queries the vop time of the source frame and sends it in the bit stream.
84  *   4) Since the Source frame skip logic is taken care by the frame_time module, whenever the
85  *      encoder queries the time stamp module (which gets updated outside the encoder) the
86  *      time stamp module would have the source time
87  */
88 typedef struct time_stamp_t
89 {
90     /*vop_time_incr_res is a integer that indicates
91      the number of evenly spaced subintervals, called ticks,
92      within one modulo time. */
93     UWORD32 u4_vop_time_incr_res;
94 
95     /* number of bits to represent vop_time_incr_res */
96     UWORD32 u4_vop_time_incr_range;
97 
98     /* The number of ticks elapsed between two source vops */
99     UWORD32 u4_vop_time_incr;
100 
101     /* incremented by vop_time_incr for every source frame.
102      Represents the time offset after a modulo_time_base = 1 is sent
103      in bit stream*/
104     UWORD32 u4_vop_time;
105 
106     /* A temporary buffer to copy of vop time and modulo time base
107      is stored since update is called before query (get time stamp) and
108      so these extra variables cur_tgt_vop_time,  */
109     UWORD32 u4_cur_tgt_vop_time;
110 
111     UWORD32 u4_prev_tgt_vop_time;
112 
113     /* This variable is set to 1 if we scale max frame rate by a factor of 2.
114      For mpeg4 standard, we just have 16bits and we can't accommodate more than 60000 as frame rate.
115      So we scale it and work with it */
116     WORD32 is_max_frame_rate_scaled;
117 } time_stamp_t;
118 
119 typedef struct time_stamp_t *time_stamp_handle;
120 
121 /*****************************************************************************/
122 /* Extern function declarations                                              */
123 /*****************************************************************************/
124 
125 /**
126 *******************************************************************************
127 *
128 * @brief
129 *  Function to init frame time context
130 *
131 * @par Description
132 *  Frame time structure stores the time of the source and the target frames to
133 *  be encoded. Based on the time we decide whether or not to encode the source
134 *  frame
135 *
136 * @param[in] ps_frame_time
137 *  Pointer Frame time context
138 *
139 * @param[in] u4_src_frm_rate
140 *  Source frame rate
141 *
142 * @param[in] u4_tgt_frm_rate
143 *  Target frame rate
144 *
145 * @returns
146 *  none
147 *
148 * @remarks
149 *
150 *******************************************************************************
151 */
152 void ih264e_init_frame_time(frame_time_t *ps_frame_time,
153                             UWORD32 u4_src_frm_rate,
154                             UWORD32 u4_tgt_frm_rate);
155 
156 /**
157 *******************************************************************************
158 *
159 * @brief
160 *  Function to check if frame can be skipped
161 *
162 * @par Description
163 *  Based on the source and target frame time and the delta time stamp
164 *  we decide whether to code the source or not.
165 *  This is based on the assumption
166 *  that the source frame rate is greater that target frame rate.
167 *  Updates the time_stamp structure
168 *
169 * @param[in] ps_frame_time
170 *  Handle to frame time context
171 *
172 * @param[in] u4_delta_time_stamp
173 *  Time stamp difference between frames
174 *
175 * @param[out] pu4_frm_not_skipped_for_dts
176 *  Flag to indicate if frame is already skipped by application
177 *
178 * @returns
179 *  Flag to skip frame
180 *
181 * @remarks
182 *
183 *******************************************************************************
184 */
185 UWORD8 ih264e_should_src_be_skipped(frame_time_t *ps_frame_time,
186                                     UWORD32 u4_delta_time_stamp,
187                                     UWORD32 *pu4_frm_not_skipped_for_dts);
188 
189 /**
190 *******************************************************************************
191 *
192 * @brief
193 *  Function to initialize time stamp context
194 *
195 * @par Description
196 *  Time stamp structure stores the time stamp data that
197 *  needs to be sent in to the header of MPEG4. Based on the
198 *  max target frame rate the vop_time increment resolution is set
199 *  so as to support all the frame rates below max frame rate.
200 *  A support till the third decimal point is assumed.
201 *
202 * @param[in] ps_time_stamp
203 *  Pointer to time stamp structure
204 *
205 * @param[in] u4_max_frm_rate
206 *  Maximum frame rate
207 *
208 * @param[in] u4_src_frm_rate
209 *  Source frame rate
210 *
211 * @returns
212 *  none
213 *
214 * @remarks
215 *
216 *******************************************************************************
217 */
218 void ih264e_init_time_stamp(time_stamp_handle time_stamp,
219                             UWORD32 max_frm_rate,
220                             UWORD32 src_frm_rate);
221 
222 /**
223 *******************************************************************************
224 *
225 * @brief Function to update time stamp context
226 *
227 * @par Description
228 *  Vop time is incremented by increment value. When vop time goes
229 *  more than the vop time resolution set the modulo time base to
230 *  1 and reduce the vop time by vop time resolution so that the
231 *  excess value is present in vop time and get accumulated over time
232 *  so that the corresponding frame rate is achieved at a average of
233 *  1000 seconds
234 *
235 * @param[in] ps_time_stamp
236 *  Pointer to time stamp structure
237 *
238 * @returns
239 *  none
240 *
241 * @remarks
242 *
243 *******************************************************************************
244 */
245 void ih264e_update_time_stamp(time_stamp_handle time_stamp);
246 
247 /**
248 *******************************************************************************
249 *
250 * @brief
251 *  Function to init frame time memtabs
252 *
253 * @par Description
254 *  Function to init frame time memtabs
255 *
256 * @param[in] pps_frame_time
257 *  Pointer to frame time contexts
258 *
259 * @param[in] ps_memtab
260 *  Pointer to memtab
261 *
262 * @param[in] e_func_type
263 *  Function type (get memtabs/init memtabs)
264 *
265 * @returns
266 *  none
267 *
268 * @remarks
269 *
270 *******************************************************************************
271 */
272 WORD32 ih264e_frame_time_get_init_free_memtab(frame_time_handle *pps_frame_time,
273                                               itt_memtab_t *ps_memtab,
274                                               ITT_FUNC_TYPE_E e_func_type);
275 
276 /**
277 *******************************************************************************
278 *
279 * @brief
280 *  Function to initialize time stamp memtabs
281 *
282 * @par Description
283 *  Function to initialize time stamp memtabs
284 *
285 * @param[in] pps_time_stamp
286 *  Pointer to time stamp context
287 *
288 * @param[in] ps_memtab
289 *  Pointer to memtab
290 *
291 * @param[in] e_func_type
292 *  Funcion type (Get memtab/ init memtab)
293 *
294 * @returns
295 *   number of memtabs used
296 *
297 * @remarks
298 *
299 *******************************************************************************
300 */
301 WORD32 ih264e_time_stamp_get_init_free_memtab(time_stamp_handle *pps_time_stamp,
302                                               itt_memtab_t *ps_memtab,
303                                               ITT_FUNC_TYPE_E e_func_type);
304 
305 /****************************************************************************
306                        Run-Time Modifying functions
307 ****************************************************************************/
308 /**
309 *******************************************************************************
310 *
311 * @brief Function to get source frame rate
312 *
313 * @par Description
314 *  Function to get source frame rate
315 *
316 * @param[in] ps_frame_time
317 *  Pointer to frame time context
318 *
319 * @returns
320 *  source frame rate
321 *
322 * @remarks
323 *
324 *******************************************************************************
325 */
326 WORD32 ih264e_frame_time_get_src_frame_rate(frame_time_t *ps_frame_time);
327 
328 /**
329 *******************************************************************************
330 *
331 * @brief Function to get target frame rate
332 *
333 * @par Description
334 *  Function to get target frame rate
335 *
336 * @param[in] ps_frame_time
337 *  Pointer to frame time context
338 *
339 * @returns
340 *   target frame rate
341 *
342 * @remarks
343 *
344 *******************************************************************************
345 */
346 WORD32 ih264e_frame_time_get_tgt_frame_rate(frame_time_t *ps_frame_time);
347 
348 /**
349 *******************************************************************************
350 *
351 * @brief Function to get source time increment
352 *
353 * @par Description
354 *  Function to get source time increment
355 *
356 * @param[in] ps_frame_time
357 *  Pointer to frame time context
358 *
359 * @returns
360 *  source time increment
361 *
362 * @remarks
363 *
364 *******************************************************************************
365 */
366 WORD32 ih264e_frame_time_get_src_ticks(frame_time_t *ps_frame_time);
367 
368 /**
369 *******************************************************************************
370 *
371 * @brief Function to get target time increment
372 *
373 * @par Description
374 *  Function to get target time increment
375 *
376 * @param[in] ps_frame_time
377 *  Pointer to frame time context
378 *
379 * @returns
380 *  target time increment
381 *
382 * @remarks
383 *
384 *******************************************************************************
385 */
386 WORD32 ih264e_frame_time_get_tgt_ticks(frame_time_t *ps_frame_time);
387 
388 /**
389 *******************************************************************************
390 *
391 * @brief Function to get src frame time
392 *
393 * @par Description
394 *  Function to get src frame time
395 *
396 * @param[in] ps_frame_time
397 *  Pointer to frame time context
398 *
399 * @returns
400 *  src frame time
401 *
402 * @remarks
403 *
404 *******************************************************************************
405 */
406 WORD32 ih264e_frame_time_get_src_time(frame_time_t *frame_time);
407 
408 /**
409 *******************************************************************************
410 *
411 * @brief Function to get tgt frame time
412 *
413 * @par Description
414 *  Function to get tgt frame time
415 *
416 * @param[in] ps_frame_time
417 *  Pointer to frame time context
418 *
419 * @returns
420 *  tgt frame time
421 *
422 * @remarks
423 *
424 *******************************************************************************
425 */
426 WORD32 ih264e_frame_time_get_tgt_time(frame_time_t *frame_time);
427 
428 /**
429 *******************************************************************************
430 *
431 * @brief Function to update source frame time with a new source frame rate
432 *
433 * @par Description
434 *  Function to update source frame time with a new source frame rate
435 *
436 * @param[in] ps_frame_time
437 *  Pointer to frame time context
438 *
439 * @param[in] src_frm_rate
440 *  source frame rate
441 *
442 * @returns
443 *  None
444 *
445 * @remarks
446 *
447 *******************************************************************************
448 */
449 void ih264e_frame_time_update_src_frame_rate(frame_time_t *ps_frame_time, WORD32 src_frm_rate);
450 
451 /**
452 *******************************************************************************
453 *
454 * @brief Function to update target frame time with a new source frame rate
455 *
456 * @par Description
457 *  Function to update target frame time with a new source frame rate
458 *
459 * @param[in] ps_frame_time
460 *  Pointer to frame time context
461 *
462 * @param[in] tgt_frm_rate
463 *  target frame rate
464 *
465 * @returns
466 *  None
467 *
468 * @remarks
469 *
470 *******************************************************************************
471 */
472 void ih264e_frame_time_update_tgt_frame_rate(frame_time_t *ps_frame_time, WORD32 tgt_frm_rate);
473 
474 /**
475 *******************************************************************************
476 *
477 * @brief Function to update target frame time with a new source frame rate
478 *
479 * @par Description
480 *  When the frame rate changes the time increment is modified by appropriate ticks
481 *
482 * @param[in] ps_time_stamp
483 *  Pointer to time stamp structure
484 *
485 * @param[in] src_frm_rate
486 *  source frame rate
487 *
488 * @returns
489 *  None
490 *
491 * @remarks
492 *
493 *******************************************************************************
494 */
495 void ih264_time_stamp_update_frame_rate(time_stamp_t *ps_time_stamp, UWORD32 src_frm_rate);
496 
497 #endif /*IH264E_TIME_STAMP_H_*/
498 
499