ih264e_time_stamp.h revision 8d3d303c7942ced6a987a52db8977d768dc3605f 
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 */
49typedef 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
73typedef 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 */
88typedef 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
119typedef 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*/
152void 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*/
185UWORD8 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*/
218void 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*/
245void 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*/
272WORD32 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*/
301WORD32 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*/
326WORD32 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*/
346WORD32 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*/
366WORD32 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*/
386WORD32 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*/
406WORD32 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*/
426WORD32 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*/
449void 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*/
472void 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*/
495void 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