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
17package android.view;
18
19import android.os.Parcel;
20import 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 */
42public final class WindowContentFrameStats extends FrameStats implements Parcelable {
43    private long[] mFramesPostedTimeNano;
44    private long[] mFramesReadyTimeNano;
45
46    /**
47     * @hide
48     */
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     */
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
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     */
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     */
109    public long getFrameReadyTimeNano(int index) {
110        if (mFramesReadyTimeNano == null) {
111            throw new IndexOutOfBoundsException();
112        }
113        return mFramesReadyTimeNano[index];
114    }
115
116    @Override
117    public int describeContents() {
118        return 0;
119    }
120
121    @Override
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
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