1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 /** 19 * @file pvmf_sync_util.h 20 * @brief Utility class to synchronize processing of media data to a specified clock. 21 */ 22 23 #ifndef PVMF_SYNC_UTIL_H_INCLUDED 24 #define PVMF_SYNC_UTIL_H_INCLUDED 25 26 #ifndef OSCL_BASE_H_INCLUDED 27 #include "oscl_base.h" 28 #endif 29 30 #ifndef PVMF_MEDIA_CLOCK_H_INCLUDED 31 #include "pvmf_media_clock.h" 32 #endif 33 34 35 36 37 38 #ifndef PVLOGGER_H_INCLUDED 39 #include "pvlogger.h" 40 #endif 41 #ifndef PVMF_TIMESTAMP_H_INCLUDED 42 #include "pvmf_timestamp.h" 43 #endif 44 #ifndef PVMF_RETURN_CODES_H_INCLUDED 45 #include "pvmf_return_codes.h" 46 #endif 47 48 const int32 DEFAULT_EARLY_MARGIN = 10; 49 const int32 DEFAULT_LATE_MARGIN = 50; 50 51 typedef enum 52 { 53 PVMF_SYNC_EARLY = 0, /**< Timestamp is earlier than the current clock by more than the early margin.*/ 54 PVMF_SYNC_ON_TIME, /**< Timestamp is on time with regards to current clock. */ 55 PVMF_SYNC_LATE, /**< Timestamp is later than the current clock by more than the late margin. */ 56 PVMF_SYNC_SKIPPED, /**< Timestamp falls within the range of skipped media data timestamps. */ 57 PVMF_SYNC_SKIPPED_RENDER,/**< same as PVMF_SYNC_SKIPPED, but we want to render skipped data */ 58 PVMF_SYNC_SKIP_COMPLETE /**< Timestamp is the first media data timestamp after the skipped range. */ 59 } PvmfSyncStatus; 60 61 /** 62 * Utility class to synchronize media data to a specified clock. PvmfSyncUtil checks the timestamp 63 * of incoming data against the specified clock, and decide whether to drop the data if it arrived 64 * too late, or schedule the data to be processed at a later time that is synchronized to the 65 * specified clock. 66 */ 67 class PvmfSyncUtil 68 { 69 public: 70 /** Constructor */ 71 OSCL_IMPORT_REF PvmfSyncUtil(); 72 73 /** Destructor */ 74 ~PvmfSyncUtil() {} 75 76 /** 77 * Configure the criteria to determine whether media data is early or late. 78 * 79 * Media data is considered early if it has a timestamp earlier than the current time of the clock by 80 * the early margin. The media data will be scheduled to be processed at the later time that is 81 * synchronized to the clock. Media data is considered late if it has a timestamp later than the 82 * current time of the clock by the late margin and will be dropped. 83 * 84 * @param aEarlyMargin Early margin in milliseconds. 85 * @param aLateMargin Late margin in milliseconds. 86 * @return Completion status 87 */ 88 OSCL_IMPORT_REF PVMFStatus SetMargins(int32 aEarlyMargin, int32 aLateMargin); 89 90 /** 91 * Synchronize the timestamp of media data with the clock. 92 * 93 * The provided timestamp is checked against the clock and the utility determines whether the timestamp 94 * is considered early, on-time or late. If the timestamp is earlier than the current time on the clock 95 * by more than the early margin, it is considered early, and this API will return the number of 96 * milliseconds to the time to process the data. If the timestamp is later than the current time on the 97 * clock by more than the late margin, it is considered late and this API will return -1 to indicate 98 * the data should be dropped. Otherwise the timestamp is considered on-time and this API will return 0. 99 * 100 * @param aDataTimestamp Timestamp of media data in milliseconds. 101 * @param aDuration Duration of the media data in milliseconds. 102 * @param aMillisecondsEarly If return status is PVMF_SYNC_EARLY, the number of milliseconds to the 103 * time to process the data is saved to this parameter 104 * If return is PVMF_SYNC_LATE, the amount by which the frame was late is returned. 105 * If return is PVMF_SYNC_SKIPPED, the delta from the frame TS to the skip mark is returned. 106 * @return Synchronization status. 107 */ 108 OSCL_IMPORT_REF PvmfSyncStatus SyncMediaData(PVMFTimestamp aDataTimestamp, uint32 aDuration, uint32& aMillisecondsEarly); 109 110 /** 111 * Skip processing media data until a specified timestamp 112 * 113 * Media data with timestamp before the specified resume timestamp will be skipped. Default 114 * behaviour is to drop all skipped data, where SyncMediaData API will return -1 for all timestamps 115 * before the resume time. If aRenderSkippedData is set to true, SyncMediaData API will return 116 * 0 for all timestamps before the resume time to indicate forced rendering of all skipped data. 117 * 118 * @param aResumeTimestamp Timestamp at which normal evaluation of timestamp against the clock will resume. 119 * @param aRenderSkippedData When set to true, SyncMediaData API will return 0 for all timestamps 120 * before the resume time. 121 * @return Completion status. 122 */ 123 OSCL_IMPORT_REF PVMFStatus SkipMediaData(PVMFTimestamp aResumeTimestamp, bool aRenderSkippedData = false); 124 125 /** 126 * Cancel a SkipMediaData that is in progress. If no SkipMediaData 127 * is in progress, ignore the command. 128 * 129 */ 130 OSCL_IMPORT_REF void CancelSkipMediaData(); 131 132 /** 133 * A query for whether a skip is in progress 134 */ 135 bool IsSkipping() 136 { 137 return iSkipMediaData; 138 } 139 140 private: 141 friend class PvmfSyncUtilDataQueue; 142 /** 143 * Sets the clock to which media data is synchronized. 144 * 145 * @param aClock Clock object to which media data is synchronized. 146 * @return Completion status. 147 */ 148 OSCL_IMPORT_REF PVMFStatus SetClock(PVMFMediaClock* aClock); 149 OSCL_IMPORT_REF PVMFStatus SetFrameStepClock(PVMFMediaClock* aClock); 150 151 152 private: 153 154 PVMFMediaClock* iClock; 155 PVMFMediaClock* iFrameStepClock; 156 int32 iEarlyMargin; 157 int32 iLateMargin; 158 159 // Repositioning 160 bool iSkipMediaData; 161 PVMFTimestamp iResumeTimestamp; 162 bool iRenderSkippedData; 163 164 PVLogger* iLogger; 165 166 }; 167 168 #endif // PVMF_SYNC_UTIL_H_INCLUDED 169 170 171 172 173 174
