/******************************************************************************
*
* Copyright (C) 2015 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
*****************************************************************************
* Originally developed and contributed by Ittiam Systems Pvt. Ltd, Bangalore
*/
/**
*******************************************************************************
* @file
* ih264e_time_stamp.h
*
* @brief
* This file contains function declarations used for managing input and output
* frame time stamps
*
* @author
* ittiam
*
* @remarks
* None
*
*******************************************************************************
*/
#ifndef IH264E_TIME_STAMP_H_
#define IH264E_TIME_STAMP_H_
/*****************************************************************************/
/* Structures */
/*****************************************************************************/
/**
* Parameters for Src/Tgt frames that are encoded
*/
typedef struct frame_time_t
{
/* common time base(=LCM) between source and target frame rate (in ticks)*/
WORD32 common_time_base;
/* number of ticks between two source frames */
UWORD32 u4_src_frm_time_incr;
/* number of ticks between two target frames */
UWORD32 u4_tgt_frm_time_incr;
/* Source frame time - measured as modulo of common time base
and incremented by src_frm_time_incr */
UWORD32 u4_src_frm_time;
/* Target frame time - measured as modulo of common time base
and incremented by tgt_frm_time_incr */
UWORD32 u4_tgt_frm_time;
/* Number of frames not to be skipped while maintaining
tgt_frm_rate due to delta_time_stamp */
UWORD32 u4_num_frms_dont_skip;
}frame_time_t;
typedef struct frame_time_t *frame_time_handle;
/**
* Parameters that go in the bitstream based on tgt_frm_rate
* 1) Initialize the vop_time_incr_res with the max_frame_rate (in frames per 1000 bits)
* - To represent all kinds of frame rates
* 2) Decide the vop_time_incr based on the source frame rate
* - The decoder would like to know which source frame is encoded i.e. the source time
* id of the target frame encoded and there by adjusting its time of delay
* 3) vop_time increments every source frame and whenever a frame is encoded (target frame),
* the encoder queries the vop time of the source frame and sends it in the bit stream.
* 4) Since the Source frame skip logic is taken care by the frame_time module, whenever the
* encoder queries the time stamp module (which gets updated outside the encoder) the
* time stamp module would have the source time
*/
typedef struct time_stamp_t
{
/*vop_time_incr_res is a integer that indicates
the number of evenly spaced subintervals, called ticks,
within one modulo time. */
UWORD32 u4_vop_time_incr_res;
/* number of bits to represent vop_time_incr_res */
UWORD32 u4_vop_time_incr_range;
/* The number of ticks elapsed between two source vops */
UWORD32 u4_vop_time_incr;
/* incremented by vop_time_incr for every source frame.
Represents the time offset after a modulo_time_base = 1 is sent
in bit stream*/
UWORD32 u4_vop_time;
/* A temporary buffer to copy of vop time and modulo time base
is stored since update is called before query (get time stamp) and
so these extra variables cur_tgt_vop_time, */
UWORD32 u4_cur_tgt_vop_time;
UWORD32 u4_prev_tgt_vop_time;
/* This variable is set to 1 if we scale max frame rate by a factor of 2.
For mpeg4 standard, we just have 16bits and we can't accommodate more than 60000 as frame rate.
So we scale it and work with it */
WORD32 is_max_frame_rate_scaled;
} time_stamp_t;
typedef struct time_stamp_t *time_stamp_handle;
/*****************************************************************************/
/* Extern function declarations */
/*****************************************************************************/
/**
*******************************************************************************
*
* @brief
* Function to init frame time context
*
* @par Description
* Frame time structure stores the time of the source and the target frames to
* be encoded. Based on the time we decide whether or not to encode the source
* frame
*
* @param[in] ps_frame_time
* Pointer Frame time context
*
* @param[in] u4_src_frm_rate
* Source frame rate
*
* @param[in] u4_tgt_frm_rate
* Target frame rate
*
* @returns
* none
*
* @remarks
*
*******************************************************************************
*/
void ih264e_init_frame_time(frame_time_t *ps_frame_time,
UWORD32 u4_src_frm_rate,
UWORD32 u4_tgt_frm_rate);
/**
*******************************************************************************
*
* @brief
* Function to check if frame can be skipped
*
* @par Description
* Based on the source and target frame time and the delta time stamp
* we decide whether to code the source or not.
* This is based on the assumption
* that the source frame rate is greater that target frame rate.
* Updates the time_stamp structure
*
* @param[in] ps_frame_time
* Handle to frame time context
*
* @param[in] u4_delta_time_stamp
* Time stamp difference between frames
*
* @param[out] pu4_frm_not_skipped_for_dts
* Flag to indicate if frame is already skipped by application
*
* @returns
* Flag to skip frame
*
* @remarks
*
*******************************************************************************
*/
UWORD8 ih264e_should_src_be_skipped(frame_time_t *ps_frame_time,
UWORD32 u4_delta_time_stamp,
UWORD32 *pu4_frm_not_skipped_for_dts);
/**
*******************************************************************************
*
* @brief
* Function to initialize time stamp context
*
* @par Description
* Time stamp structure stores the time stamp data that
* needs to be sent in to the header of MPEG4. Based on the
* max target frame rate the vop_time increment resolution is set
* so as to support all the frame rates below max frame rate.
* A support till the third decimal point is assumed.
*
* @param[in] ps_time_stamp
* Pointer to time stamp structure
*
* @param[in] u4_max_frm_rate
* Maximum frame rate
*
* @param[in] u4_src_frm_rate
* Source frame rate
*
* @returns
* none
*
* @remarks
*
*******************************************************************************
*/
void ih264e_init_time_stamp(time_stamp_handle time_stamp,
UWORD32 max_frm_rate,
UWORD32 src_frm_rate);
/**
*******************************************************************************
*
* @brief Function to update time stamp context
*
* @par Description
* Vop time is incremented by increment value. When vop time goes
* more than the vop time resolution set the modulo time base to
* 1 and reduce the vop time by vop time resolution so that the
* excess value is present in vop time and get accumulated over time
* so that the corresponding frame rate is achieved at a average of
* 1000 seconds
*
* @param[in] ps_time_stamp
* Pointer to time stamp structure
*
* @returns
* none
*
* @remarks
*
*******************************************************************************
*/
void ih264e_update_time_stamp(time_stamp_handle time_stamp);
/**
*******************************************************************************
*
* @brief
* Function to init frame time memtabs
*
* @par Description
* Function to init frame time memtabs
*
* @param[in] pps_frame_time
* Pointer to frame time contexts
*
* @param[in] ps_memtab
* Pointer to memtab
*
* @param[in] e_func_type
* Function type (get memtabs/init memtabs)
*
* @returns
* none
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_init_free_memtab(frame_time_handle *pps_frame_time,
itt_memtab_t *ps_memtab,
ITT_FUNC_TYPE_E e_func_type);
/**
*******************************************************************************
*
* @brief
* Function to initialize time stamp memtabs
*
* @par Description
* Function to initialize time stamp memtabs
*
* @param[in] pps_time_stamp
* Pointer to time stamp context
*
* @param[in] ps_memtab
* Pointer to memtab
*
* @param[in] e_func_type
* Funcion type (Get memtab/ init memtab)
*
* @returns
* number of memtabs used
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_time_stamp_get_init_free_memtab(time_stamp_handle *pps_time_stamp,
itt_memtab_t *ps_memtab,
ITT_FUNC_TYPE_E e_func_type);
/****************************************************************************
Run-Time Modifying functions
****************************************************************************/
/**
*******************************************************************************
*
* @brief Function to get source frame rate
*
* @par Description
* Function to get source frame rate
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @returns
* source frame rate
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_src_frame_rate(frame_time_t *ps_frame_time);
/**
*******************************************************************************
*
* @brief Function to get target frame rate
*
* @par Description
* Function to get target frame rate
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @returns
* target frame rate
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_tgt_frame_rate(frame_time_t *ps_frame_time);
/**
*******************************************************************************
*
* @brief Function to get source time increment
*
* @par Description
* Function to get source time increment
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @returns
* source time increment
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_src_ticks(frame_time_t *ps_frame_time);
/**
*******************************************************************************
*
* @brief Function to get target time increment
*
* @par Description
* Function to get target time increment
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @returns
* target time increment
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_tgt_ticks(frame_time_t *ps_frame_time);
/**
*******************************************************************************
*
* @brief Function to get src frame time
*
* @par Description
* Function to get src frame time
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @returns
* src frame time
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_src_time(frame_time_t *frame_time);
/**
*******************************************************************************
*
* @brief Function to get tgt frame time
*
* @par Description
* Function to get tgt frame time
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @returns
* tgt frame time
*
* @remarks
*
*******************************************************************************
*/
WORD32 ih264e_frame_time_get_tgt_time(frame_time_t *frame_time);
/**
*******************************************************************************
*
* @brief Function to update source frame time with a new source frame rate
*
* @par Description
* Function to update source frame time with a new source frame rate
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @param[in] src_frm_rate
* source frame rate
*
* @returns
* None
*
* @remarks
*
*******************************************************************************
*/
void ih264e_frame_time_update_src_frame_rate(frame_time_t *ps_frame_time, WORD32 src_frm_rate);
/**
*******************************************************************************
*
* @brief Function to update target frame time with a new source frame rate
*
* @par Description
* Function to update target frame time with a new source frame rate
*
* @param[in] ps_frame_time
* Pointer to frame time context
*
* @param[in] tgt_frm_rate
* target frame rate
*
* @returns
* None
*
* @remarks
*
*******************************************************************************
*/
void ih264e_frame_time_update_tgt_frame_rate(frame_time_t *ps_frame_time, WORD32 tgt_frm_rate);
/**
*******************************************************************************
*
* @brief Function to update target frame time with a new source frame rate
*
* @par Description
* When the frame rate changes the time increment is modified by appropriate ticks
*
* @param[in] ps_time_stamp
* Pointer to time stamp structure
*
* @param[in] src_frm_rate
* source frame rate
*
* @returns
* None
*
* @remarks
*
*******************************************************************************
*/
void ih264_time_stamp_update_frame_rate(time_stamp_t *ps_time_stamp, UWORD32 src_frm_rate);
#endif /*IH264E_TIME_STAMP_H_*/