1 /* 2 * Copyright (C) 2012 The Android Open Source Project 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 express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_FRAMETRACKER_H 18 #define ANDROID_FRAMETRACKER_H 19 20 #include <stddef.h> 21 22 #include <utils/Mutex.h> 23 #include <utils/Timers.h> 24 #include <utils/RefBase.h> 25 26 namespace android { 27 28 class String8; 29 class Fence; 30 31 // FrameTracker tracks information about the most recently rendered frames. It 32 // uses a circular buffer of frame records, and is *NOT* thread-safe - 33 // mutexing must be done at a higher level if multi-threaded access is 34 // possible. 35 // 36 // Some of the time values tracked may be set either as a specific timestamp 37 // or a fence. When a non-NULL fence is set for a given time value, the 38 // signal time of that fence is used instead of the timestamp. 39 class FrameTracker { 40 41 public: 42 // NUM_FRAME_RECORDS is the size of the circular buffer used to track the 43 // frame time history. 44 enum { NUM_FRAME_RECORDS = 128 }; 45 46 FrameTracker(); 47 48 // setDesiredPresentTime sets the time at which the current frame 49 // should be presented to the user under ideal (i.e. zero latency) 50 // conditions. 51 void setDesiredPresentTime(nsecs_t desiredPresentTime); 52 53 // setFrameReadyTime sets the time at which the current frame became ready 54 // to be presented to the user. For example, if the frame contents is 55 // being written to memory by some asynchronous hardware, this would be 56 // the time at which those writes completed. 57 void setFrameReadyTime(nsecs_t readyTime); 58 59 // setFrameReadyFence sets the fence that is used to get the time at which 60 // the current frame became ready to be presented to the user. 61 void setFrameReadyFence(const sp<Fence>& readyFence); 62 63 // setActualPresentTime sets the timestamp at which the current frame became 64 // visible to the user. 65 void setActualPresentTime(nsecs_t displayTime); 66 67 // setActualPresentFence sets the fence that is used to get the time 68 // at which the current frame became visible to the user. 69 void setActualPresentFence(const sp<Fence>& fence); 70 71 // advanceFrame advances the frame tracker to the next frame. 72 void advanceFrame(); 73 74 // clear resets all the tracked frame data to zero. 75 void clear(); 76 77 // dump appends the current frame display time history to the result string. 78 void dump(String8& result) const; 79 80 private: 81 struct FrameRecord { FrameRecordFrameRecord82 FrameRecord() : 83 desiredPresentTime(0), 84 frameReadyTime(0), 85 actualPresentTime(0) {} 86 nsecs_t desiredPresentTime; 87 nsecs_t frameReadyTime; 88 nsecs_t actualPresentTime; 89 sp<Fence> frameReadyFence; 90 sp<Fence> actualPresentFence; 91 }; 92 93 // processFences iterates over all the frame records that have a fence set 94 // and replaces that fence with a timestamp if the fence has signaled. If 95 // the fence is not signaled the record's displayTime is set to INT64_MAX. 96 // 97 // This method is const because although it modifies the frame records it 98 // does so in such a way that the information represented should not 99 // change. This allows it to be called from the dump method. 100 void processFencesLocked() const; 101 102 // mFrameRecords is the circular buffer storing the tracked data for each 103 // frame. 104 FrameRecord mFrameRecords[NUM_FRAME_RECORDS]; 105 106 // mOffset is the offset into mFrameRecords of the current frame. 107 size_t mOffset; 108 109 // mNumFences is the total number of fences set in the frame records. It 110 // is incremented each time a fence is added and decremented each time a 111 // signaled fence is removed in processFences or if advanceFrame clobbers 112 // a fence. 113 // 114 // The number of fences is tracked so that the run time of processFences 115 // doesn't grow with NUM_FRAME_RECORDS. 116 int mNumFences; 117 118 // mMutex is used to protect access to all member variables. 119 mutable Mutex mMutex; 120 }; 121 122 } 123 124 #endif // ANDROID_FRAMETRACKER_H 125