Home | History | Annotate | Download | only in surfaceflinger 
      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 {
     82         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