1 /* 2 * Copyright (C) 2016 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.annotation.IntDef; 20 import android.view.Window; 21 22 import java.lang.annotation.Retention; 23 import java.lang.annotation.RetentionPolicy; 24 25 /** 26 * Class containing timing data for various milestones in a frame 27 * lifecycle reported by the rendering subsystem. 28 * <p> 29 * Supported metrics can be queried via their corresponding identifier. 30 * </p> 31 */ 32 public final class FrameMetrics { 33 34 /** 35 * Metric identifier for unknown delay. 36 * <p> 37 * Represents the number of nanoseconds elapsed waiting for the 38 * UI thread to become responsive and process the frame. This 39 * should be 0 most of the time. 40 * </p> 41 */ 42 public static final int UNKNOWN_DELAY_DURATION = 0; 43 44 /** 45 * Metric identifier for input handling duration. 46 * <p> 47 * Represents the number of nanoseconds elapsed issuing 48 * input handling callbacks. 49 * </p> 50 */ 51 public static final int INPUT_HANDLING_DURATION = 1; 52 53 /** 54 * Metric identifier for animation callback duration. 55 * <p> 56 * Represents the number of nanoseconds elapsed issuing 57 * animation callbacks. 58 * </p> 59 */ 60 public static final int ANIMATION_DURATION = 2; 61 62 /** 63 * Metric identifier for layout/measure duration. 64 * <p> 65 * Represents the number of nanoseconds elapsed measuring 66 * and laying out the invalidated pieces of the view hierarchy. 67 * </p> 68 */ 69 public static final int LAYOUT_MEASURE_DURATION = 3; 70 /** 71 * Metric identifier for draw duration. 72 * <p> 73 * Represents the number of nanoseconds elapsed computing 74 * DisplayLists for transformations applied to the view 75 * hierarchy. 76 * </p> 77 */ 78 public static final int DRAW_DURATION = 4; 79 80 /** 81 * Metric identifier for sync duration. 82 * <p> 83 * Represents the number of nanoseconds elapsed 84 * synchronizing the computed display lists with the render 85 * thread. 86 * </p> 87 */ 88 public static final int SYNC_DURATION = 5; 89 90 /** 91 * Metric identifier for command issue duration. 92 * <p> 93 * Represents the number of nanoseconds elapsed 94 * issuing draw commands to the GPU. 95 * </p> 96 */ 97 public static final int COMMAND_ISSUE_DURATION = 6; 98 99 /** 100 * Metric identifier for swap buffers duration. 101 * <p> 102 * Represents the number of nanoseconds elapsed issuing 103 * the frame buffer for this frame to the display 104 * subsystem. 105 * </p> 106 */ 107 public static final int SWAP_BUFFERS_DURATION = 7; 108 109 /** 110 * Metric identifier for total frame duration. 111 * <p> 112 * Represents the total time in nanoseconds this frame took to render 113 * and be issued to the display subsystem. 114 * </p> 115 * <p> 116 * Equal to the sum of the values of all other time-valued metric 117 * identifiers. 118 * </p> 119 */ 120 public static final int TOTAL_DURATION = 8; 121 122 /** 123 * Metric identifier for a boolean value determining whether this frame was 124 * the first to draw in a new Window layout. 125 * <p> 126 * {@link #getMetric(int)} will return 0 for false, 1 for true. 127 * </p> 128 * <p> 129 * First draw frames are expected to be slow and should usually be exempt 130 * from display jank calculations as they do not cause skips in animations 131 * and are usually hidden by window animations or other tricks. 132 * </p> 133 */ 134 public static final int FIRST_DRAW_FRAME = 9; 135 136 private static final int FRAME_INFO_FLAG_FIRST_DRAW = 1 << 0; 137 138 /** 139 * Identifiers for metrics available for each frame. 140 * 141 * {@see #getMetric(int)} 142 * @hide 143 */ 144 @IntDef({ 145 UNKNOWN_DELAY_DURATION, 146 INPUT_HANDLING_DURATION, 147 ANIMATION_DURATION, 148 LAYOUT_MEASURE_DURATION, 149 DRAW_DURATION, 150 SYNC_DURATION, 151 COMMAND_ISSUE_DURATION, 152 SWAP_BUFFERS_DURATION, 153 TOTAL_DURATION, 154 FIRST_DRAW_FRAME, 155 }) 156 @Retention(RetentionPolicy.SOURCE) 157 public @interface Metric {} 158 159 /** 160 * Timestamp indices for frame milestones. 161 * 162 * May change from release to release. 163 * 164 * Must be kept in sync with frameworks/base/libs/hwui/FrameInfo.h. 165 * 166 * @hide 167 */ 168 @IntDef ({ 169 Index.FLAGS, 170 Index.INTENDED_VSYNC, 171 Index.VSYNC, 172 Index.OLDEST_INPUT_EVENT, 173 Index.NEWEST_INPUT_EVENT, 174 Index.HANDLE_INPUT_START, 175 Index.ANIMATION_START, 176 Index.PERFORM_TRAVERSALS_START, 177 Index.DRAW_START, 178 Index.SYNC_QUEUED, 179 Index.SYNC_START, 180 Index.ISSUE_DRAW_COMMANDS_START, 181 Index.SWAP_BUFFERS, 182 Index.FRAME_COMPLETED, 183 }) 184 @Retention(RetentionPolicy.SOURCE) 185 private @interface Index { 186 int FLAGS = 0; 187 int INTENDED_VSYNC = 1; 188 int VSYNC = 2; 189 int OLDEST_INPUT_EVENT = 3; 190 int NEWEST_INPUT_EVENT = 4; 191 int HANDLE_INPUT_START = 5; 192 int ANIMATION_START = 6; 193 int PERFORM_TRAVERSALS_START = 7; 194 int DRAW_START = 8; 195 int SYNC_QUEUED = 9; 196 int SYNC_START = 10; 197 int ISSUE_DRAW_COMMANDS_START = 11; 198 int SWAP_BUFFERS = 12; 199 int FRAME_COMPLETED = 13; 200 201 int FRAME_STATS_COUNT = 16; // must always be last 202 } 203 204 /* 205 * Bucket endpoints for each Metric defined above. 206 * 207 * Each defined metric *must* have a corresponding entry 208 * in this list. 209 */ 210 private static final int[] DURATIONS = new int[] { 211 // UNKNOWN_DELAY 212 Index.INTENDED_VSYNC, Index.HANDLE_INPUT_START, 213 // INPUT_HANDLING 214 Index.HANDLE_INPUT_START, Index.ANIMATION_START, 215 // ANIMATION 216 Index.ANIMATION_START, Index.PERFORM_TRAVERSALS_START, 217 // LAYOUT_MEASURE 218 Index.PERFORM_TRAVERSALS_START, Index.DRAW_START, 219 // DRAW 220 Index.DRAW_START, Index.SYNC_QUEUED, 221 // SYNC 222 Index.SYNC_START, Index.ISSUE_DRAW_COMMANDS_START, 223 // COMMAND_ISSUE 224 Index.ISSUE_DRAW_COMMANDS_START, Index.SWAP_BUFFERS, 225 // SWAP_BUFFERS 226 Index.SWAP_BUFFERS, Index.FRAME_COMPLETED, 227 // TOTAL_DURATION 228 Index.INTENDED_VSYNC, Index.FRAME_COMPLETED, 229 }; 230 231 /* package */ final long[] mTimingData; 232 233 /** 234 * Constructs a FrameMetrics object as a copy. 235 * <p> 236 * Use this method to copy out metrics reported by 237 * {@link Window.OnFrameMetricsAvailableListener#onFrameMetricsAvailable( 238 * Window, FrameMetrics, int)} 239 * </p> 240 * @param other the FrameMetrics object to copy. 241 */ FrameMetrics(FrameMetrics other)242 public FrameMetrics(FrameMetrics other) { 243 mTimingData = new long[Index.FRAME_STATS_COUNT]; 244 System.arraycopy(other.mTimingData, 0, mTimingData, 0, mTimingData.length); 245 } 246 247 /** 248 * @hide 249 */ FrameMetrics()250 FrameMetrics() { 251 mTimingData = new long[Index.FRAME_STATS_COUNT]; 252 } 253 254 /** 255 * Retrieves the value associated with Metric identifier {@code id} 256 * for this frame. 257 * <p> 258 * Boolean metrics are represented in [0,1], with 0 corresponding to 259 * false, and 1 corresponding to true. 260 * </p> 261 * @param id the metric to retrieve 262 * @return the value of the metric or -1 if it is not available. 263 */ getMetric(@etric int id)264 public long getMetric(@Metric int id) { 265 if (id < UNKNOWN_DELAY_DURATION || id > FIRST_DRAW_FRAME) { 266 return -1; 267 } 268 269 if (mTimingData == null) { 270 return -1; 271 } 272 273 if (id == FIRST_DRAW_FRAME) { 274 return (mTimingData[Index.FLAGS] & FRAME_INFO_FLAG_FIRST_DRAW) != 0 ? 1 : 0; 275 } 276 277 int durationsIdx = 2 * id; 278 return mTimingData[DURATIONS[durationsIdx + 1]] 279 - mTimingData[DURATIONS[durationsIdx]]; 280 } 281 } 282 283