1 /*
2  * Copyright (C) 2014 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 package android.view;
18 
19 import android.os.Parcel;
20 import android.os.Parcelable;
21 
22 /**
23  * This class contains window content frame statistics. For example, a window content
24  * is rendred in frames when a view is scrolled. The frame statistics are a snapshot
25  * for the time interval from {@link #getStartTimeNano()} to {@link #getEndTimeNano()}.
26  * <p>
27  * The key idea is that in order to provide a smooth user experience an application
28  * has to draw a frame at a specific time interval obtained by calling {@link
29  * #getRefreshPeriodNano()}. If the application does not render a frame every refresh
30  * period the user will see irregular UI transitions.
31  * </p>
32  * <p>
33  * An application posts a frame for presentation by synchronously rendering its contents
34  * in a buffer which is then posted or posting a buffer to which the application is
35  * asychronously rendering the content via GL. After the frame is posted and rendered
36  * (potentially asynchronosly) it is presented to the user. The time a frame was posted
37  * can be obtained via {@link #getFramePostedTimeNano(int)}, the time a frame content
38  * was rendered and ready for dsiplay (GL case) via {@link #getFrameReadyTimeNano(int)},
39  * and the time a frame was presented on the screen via {@link #getFramePresentedTimeNano(int)}.
40  * </p>
41  */
42 public final class WindowContentFrameStats extends FrameStats implements Parcelable {
43     private long[] mFramesPostedTimeNano;
44     private long[] mFramesReadyTimeNano;
45 
46     /**
47      * @hide
48      */
WindowContentFrameStats()49     public WindowContentFrameStats() {
50         /* do nothing */
51     }
52 
53     /**
54      * Initializes this isntance.
55      *
56      * @param refreshPeriodNano The display refresh period.
57      * @param framesPostedTimeNano The times in milliseconds for when the frame contents were posted.
58      * @param framesPresentedTimeNano The times in milliseconds for when the frame contents were presented.
59      * @param framesReadyTimeNano The times in milliseconds for when the frame contents were ready to be presented.
60      *
61      * @hide
62      */
init(long refreshPeriodNano, long[] framesPostedTimeNano, long[] framesPresentedTimeNano, long[] framesReadyTimeNano)63     public void init(long refreshPeriodNano, long[] framesPostedTimeNano,
64             long[] framesPresentedTimeNano, long[] framesReadyTimeNano) {
65         mRefreshPeriodNano = refreshPeriodNano;
66         mFramesPostedTimeNano = framesPostedTimeNano;
67         mFramesPresentedTimeNano = framesPresentedTimeNano;
68         mFramesReadyTimeNano = framesReadyTimeNano;
69     }
70 
WindowContentFrameStats(Parcel parcel)71     private WindowContentFrameStats(Parcel parcel) {
72         mRefreshPeriodNano = parcel.readLong();
73         mFramesPostedTimeNano = parcel.createLongArray();
74         mFramesPresentedTimeNano = parcel.createLongArray();
75         mFramesReadyTimeNano = parcel.createLongArray();
76     }
77 
78     /**
79      * Get the time a frame at a given index was posted by the producer (e.g. the application).
80      * It is either explicitly set or defaulted to the time when the render buffer was posted.
81      * <p>
82      * <strong>Note:</strong> A frame can be posted and still it contents being rendered
83      * asynchronously in GL. To get the time the frame content was completely rendered and
84      * ready to display call {@link #getFrameReadyTimeNano(int)}.
85      * </p>
86      *
87      * @param index The frame index.
88      * @return The posted time in nanoseconds.
89      */
getFramePostedTimeNano(int index)90     public long getFramePostedTimeNano(int index) {
91         if (mFramesPostedTimeNano == null) {
92             throw new IndexOutOfBoundsException();
93         }
94         return mFramesPostedTimeNano[index];
95     }
96 
97     /**
98      * Get the time a frame at a given index was ready for presentation.
99      * <p>
100      * <strong>Note:</strong> A frame can be posted and still it contents being rendered
101      * asynchronously in GL. In such a case this is the time when the frame contents were
102      * completely rendered.
103      * </p>
104      *
105      * @param index The frame index.
106      * @return The ready time in nanoseconds or {@link #UNDEFINED_TIME_NANO}
107      *         if the frame is not ready yet.
108      */
getFrameReadyTimeNano(int index)109     public long getFrameReadyTimeNano(int index) {
110         if (mFramesReadyTimeNano == null) {
111             throw new IndexOutOfBoundsException();
112         }
113         return mFramesReadyTimeNano[index];
114     }
115 
116     @Override
describeContents()117     public int describeContents() {
118         return 0;
119     }
120 
121     @Override
writeToParcel(Parcel parcel, int flags)122     public void writeToParcel(Parcel parcel, int flags) {
123         parcel.writeLong(mRefreshPeriodNano);
124         parcel.writeLongArray(mFramesPostedTimeNano);
125         parcel.writeLongArray(mFramesPresentedTimeNano);
126         parcel.writeLongArray(mFramesReadyTimeNano);
127     }
128 
129     @Override
toString()130     public String toString() {
131         StringBuilder builder = new StringBuilder();
132         builder.append("WindowContentFrameStats[");
133         builder.append("frameCount:" + getFrameCount());
134         builder.append(", fromTimeNano:" + getStartTimeNano());
135         builder.append(", toTimeNano:" + getEndTimeNano());
136         builder.append(']');
137         return builder.toString();
138     }
139 
140     public static final Parcelable.Creator<WindowContentFrameStats> CREATOR =
141             new Creator<WindowContentFrameStats>() {
142                 @Override
143                 public WindowContentFrameStats createFromParcel(Parcel parcel) {
144                     return new WindowContentFrameStats(parcel);
145                 }
146 
147                 @Override
148                 public WindowContentFrameStats[] newArray(int size) {
149                     return new WindowContentFrameStats[size];
150                 }
151             };
152 }
153