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_data_queue.h 20 * @brief Utility class to synchronize processing of media msg to a specified clock. 21 */ 22 23 #ifndef PVMF_SYNC_UTIL_DATA_QUEUE_H_INCLUDED 24 #define PVMF_SYNC_UTIL_DATA_QUEUE_H_INCLUDED 25 26 #ifndef OSCL_BASE_H_INCLUDED 27 #include "oscl_base.h" 28 #endif 29 #ifndef OSCL_VECTOR_H_INCLUDED 30 #include "oscl_vector.h" 31 #endif 32 #ifndef OSCL_MEM_H_INCLUDED 33 #include "oscl_mem.h" 34 #endif 35 #ifndef OSCL_STRING_CONTAINERS_H_INCLUDED 36 #include "oscl_string_containers.h" 37 #endif 38 #ifndef PVLOGGER_H_INCLUDED 39 #include "pvlogger.h" 40 #endif 41 #ifndef PVMF_MEDIA_MSG_H_INCLUDED 42 #include "pvmf_media_msg.h" 43 #endif 44 #ifndef PVMF_MEDIA_DATA_H_INCLUDED 45 #include "pvmf_media_data.h" 46 #endif 47 #ifndef PVMF_MEDIA_CMD_H_INCLUDED 48 #include "pvmf_media_cmd.h" 49 #endif 50 #ifndef PVMF_SYNC_UTIL_H_INCLUDED 51 #include "pvmf_sync_util.h" 52 #endif 53 54 /** Default data queue reserve size */ 55 const int32 DEFAULT_QUEUE_RESERVE_SIZE = 10; 56 57 // Forward declaration 58 class PvmfSyncUtilDataQueue; 59 60 /** 61 * Observer class for PvmfSyncUtilDataQueue. User of PvmfSyncUtilDataQueue class must implement this observer 62 * interface to listen to events from the utility. 63 */ 64 class PvmfSyncUtilDataQueueObserver 65 { 66 public: 67 /** 68 * Notifies the observer to call PvmfSyncUtilDataQueue::DequeueMediaData at the specified 69 * time to retrieve the media msg and process it. 70 * 71 * @param aDataQueue Pointer to the PvmfSyncUtilDataQueue object to be processed at the specified time. 72 * @param aTimeMilliseconds Number of milliseconds to the time to process the media data. 73 */ 74 virtual void ScheduleProcessData(PvmfSyncUtilDataQueue* aDataQueue, uint32 aTimeMilliseconds) = 0; 75 76 /** 77 * Notifies the observer of completing SkipMediaData call. The first media data after the specified 78 * resume timestamp is at the head of the queue. 79 */ 80 virtual void SkipMediaDataComplete() = 0; 81 ~PvmfSyncUtilDataQueueObserver()82 virtual ~PvmfSyncUtilDataQueueObserver() {} 83 }; 84 85 /** 86 * Utility class to synchronize media message to a specified clock. PvmfSyncUtilDataQueue checks the timestamp 87 * of incoming message against the specified clock, and decide whether to drop the message if it arrived 88 * too late, or schedule the data to be processed at a later time that is synchronized to the 89 * specified clock. 90 */ 91 class PvmfSyncUtilDataQueue: public PVMFMediaClockObserver 92 { 93 public: 94 /** 95 * Constructor 96 * @param aObserver Observer to the utility 97 * @param name Optional name for this queue. If a name is provided, datapath 98 * logging will be enabled for the queue. 99 */ 100 OSCL_IMPORT_REF PvmfSyncUtilDataQueue(PvmfSyncUtilDataQueueObserver* aObserver, PvmfSyncUtil* aUtil, char*name = NULL); 101 102 /** Destructor */ 103 OSCL_IMPORT_REF virtual ~PvmfSyncUtilDataQueue() ; 104 105 /** 106 * Sets the reserve size of the media message queue. 107 * 108 * @param aReserveSize Number of media msg reserved on the data queue. 109 * @return PVMFErrNoMemory if there is a failure in reserving the necessary memory. Else PVMFSuccess. 110 */ 111 OSCL_IMPORT_REF PVMFStatus ReserveDataQueue(uint32 aReserveSize); 112 113 /** 114 * Queue incoming media message to be processed. 115 * 116 * Incoming media message will be added to the data queue and a PvmfSyncUtilDataQueueObserver::ScheduleProcessData 117 * call will be made to schedule the data to be processed when necessary. If the media message is 118 * determined to be late, the data will be dropped and will not be scheduled for processing. 119 * 120 * @param aMediaMsg Incoming media message to be queued and processed. 121 * @param aDropped Optional output parameter to hold the number of late frames dropped. 122 * @param aSkipped Optional output parameter to hold the number of frames skipped. 123 * @param aFront Optional input parameter, when set the data will go to the front of the queue 124 * rather than at the end. 125 * @return PVMFErrNoMemory if the incoming data cannot be added to the queue. PVMFFailure if the 126 * media message is late and is dropped. PVMFSuccess if the data is successfully scheduled 127 * to be processed at a later time that is synchronized to the clock. 128 */ 129 OSCL_IMPORT_REF PVMFStatus QueueMediaData(PVMFSharedMediaMsgPtr aMediaMsg, uint32*aDropped = NULL, uint32*aSkipped = NULL, bool aFront = false); 130 131 /** 132 * Retrieve media message to be processed. 133 * 134 * Returns the first queued media message if it has a timestamp that lies between the current time of 135 * the clock plus and minus the specified late and early margins. If it is too late to process 136 * the first queued media message, the data will be dropped and continue to the next media message. This 137 * continues until media message that is on time is found, or media message is scheduled to be processed 138 * later, or all queued media message are dropped. If it is too early to process the first queued 139 * media message, it will be rescheduled to be processed at a later time. 140 * 141 * @param aMediaMsg Output parameter to hold the retrieved media message if the method completed successfully. 142 * @param aDropped Optional output parameter to hold the number of late frames dropped. 143 * @param aSkipped Optional output parameter to hold the number of frames skipped. 144 * @return PVMFSuccess if there is media message for processing at the current time. PVMFPending if 145 * media message is rescheduled to be processed at a later time. PVMFFailure if there is no 146 * media message for processing at the current time. 147 */ 148 OSCL_IMPORT_REF PVMFStatus DequeueMediaData(PVMFSharedMediaMsgPtr& aMediaMsg, uint32* aDropped = NULL, uint32* aSkipped = NULL); 149 150 /** 151 * Skip processing media message until a specified timestamp 152 * 153 * Media message with timestamp before the specified resume timestamp will be skipped. Default 154 * behaviour is to drop all skipped message, but if aRenderSkippedData is set to true, DequeueMediaData 155 * will return all media message before the resume time forces rendering of all skipped message. This 156 * is an asynchronous method and the observer will be notified through SkipMediaDataComplete when 157 * the first media message after skipping is at the head of data queue. 158 * 159 * @param aResumeTimestamp Timestamp at which normal evaluation of timestamp against the clock will resume. 160 * @param aRenderSkippedData Force rendering of skipped message. 161 * @return PVMFPending if skipping has started and pending completion. 162 */ 163 OSCL_IMPORT_REF PVMFStatus SkipMediaData(PVMFTimestamp aResumeTimestamp, bool aRenderSkippedData = false); 164 165 /** 166 * Cancel a SkipMediaData that is in progress and do not make the SkipMediaDataComplete 167 * callback. If not SkipMediaData is in progress, ignore the command. 168 * 169 */ 170 OSCL_IMPORT_REF void CancelSkipMediaData(); 171 172 /** 173 * Clear buffered media message in data queue 174 * 175 * @return Completion status 176 */ 177 OSCL_IMPORT_REF PVMFStatus Clear(); 178 179 /** 180 * Set frame drop mode. Default is enabled (late frames are dropped). 181 * 182 */ 183 OSCL_IMPORT_REF void SetLateFrameDropMode(bool); 184 185 186 /** 187 * For direct access to the media message queue. 188 */ DataQueue()189 Oscl_Vector<PVMFSharedMediaMsgPtr, OsclMemAllocator> &DataQueue() 190 { 191 return iDataQueue; 192 } 193 194 /** 195 * For direct access to the synchronization function 196 */ 197 OSCL_IMPORT_REF PVMFStatus SynchronizeData(uint32* , uint32*); 198 199 200 /** 201 * To enable datapath logging on this queue 202 */ 203 OSCL_IMPORT_REF void SetName(const char*); 204 205 OSCL_IMPORT_REF PVMFStatus SetClock(PVMFMediaClock*); 206 OSCL_IMPORT_REF PVMFStatus SetClockForFrameStep(PVMFMediaClock*); 207 208 //From PVMFMediaClockObserver 209 OSCL_IMPORT_REF void ClockTimebaseUpdated(); 210 OSCL_IMPORT_REF void ClockCountUpdated(); 211 OSCL_IMPORT_REF void ClockAdjusted(); 212 OSCL_IMPORT_REF void NotificationsInterfaceDestroyed(); 213 214 private: 215 216 217 PvmfSyncUtilDataQueueObserver* iObserver; 218 PvmfSyncUtil* iSyncUtil; 219 Oscl_Vector<PVMFSharedMediaMsgPtr, OsclMemAllocator> iDataQueue; 220 PVLogger* iLogger; 221 bool iLateFrameDropEnable; 222 OSCL_StackString<20> iName; 223 PVLogger* iDatapathLogger; 224 void LogMediaMsgInfo(PVMFSharedMediaMsgPtr aMediaMsg, const char* msg); 225 void LogMediaMsgInfo(PVMFSharedMediaMsgPtr aMediaMsg, const char* msg, uint32); 226 PVMFMediaClock* iClock; 227 PVMFMediaClockNotificationsInterface* iClockNotificationsInf; 228 bool iClockOwner; 229 PVMFStatus DoSetClock(PVMFMediaClock*, bool); 230 void PassClockToSyncUtil(); 231 232 //for frame-stepping. 233 int32 iClockFrameCount; 234 int32 iSyncFrameCount; 235 PVMFStatus FrameStep(); 236 bool FrameStepMode(); 237 bool FrameSyncMode(); 238 void FrameStepClkAdjust(PVMFTimestamp aTimestamp); 239 240 /* Diagnostic log related */ 241 PVLogger* iDiagnosticsLogger; 242 bool iDiagnosticsLogged; 243 void LogDiagnostics(); 244 uint32 iDropFrameCount; 245 246 OsclErrorTrapImp* iOsclErrorTrapImp; 247 248 }; 249 250 #endif // PVMF_SYNC_UTIL_DATA_QUEUE_H_INCLUDED 251 252 253 254 255 256