android/android-9.0.0_r35 : android/view/FrameMetrics.java

FrameMetrics
https://source.android.com/
/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.view;

import android.annotation.IntDef;

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

Class containing timing data for various milestones in a frame
lifecycle reported by the rendering subsystem.

Supported metrics can be queried via their corresponding identifier.

/**
 * Class containing timing data for various milestones in a frame
 * lifecycle reported by the rendering subsystem.
 * <p>
 * Supported metrics can be queried via their corresponding identifier.
 * </p>
 */
public final class FrameMetrics {

    Metric identifier for unknown delay.

Represents the number of nanoseconds elapsed waiting for the
UI thread to become responsive and process the frame. This
should be 0 most of the time.

/**
     * Metric identifier for unknown delay.
     * <p>
     * Represents the number of nanoseconds elapsed waiting for the
     * UI thread to become responsive and process the frame. This
     * should be 0 most of the time.
     * </p>
     */
    public static final int UNKNOWN_DELAY_DURATION = 0;

    Metric identifier for input handling duration.

Represents the number of nanoseconds elapsed issuing
input handling callbacks.

/**
     * Metric identifier for input handling duration.
     * <p>
     * Represents the number of nanoseconds elapsed issuing
     * input handling callbacks.
     * </p>
     */
    public static final int INPUT_HANDLING_DURATION = 1;

    Metric identifier for animation callback duration.

Represents the number of nanoseconds elapsed issuing
animation callbacks.

/**
     * Metric identifier for animation callback duration.
     * <p>
     * Represents the number of nanoseconds elapsed issuing
     * animation callbacks.
     * </p>
     */
    public static final int ANIMATION_DURATION = 2;

    Metric identifier for layout/measure duration.

Represents the number of nanoseconds elapsed measuring
and laying out the invalidated pieces of the view hierarchy.

/**
     * Metric identifier for layout/measure duration.
     * <p>
     * Represents the number of nanoseconds elapsed measuring
     * and laying out the invalidated pieces of the view hierarchy.
     * </p>
     */
    public static final int LAYOUT_MEASURE_DURATION = 3;
    Metric identifier for draw duration.

Represents the number of nanoseconds elapsed computing
DisplayLists for transformations applied to the view
hierarchy.

/**
     * Metric identifier for draw duration.
     * <p>
     * Represents the number of nanoseconds elapsed computing
     * DisplayLists for transformations applied to the view
     * hierarchy.
     * </p>
     */
    public static final int DRAW_DURATION = 4;

    Metric identifier for sync duration.

Represents the number of nanoseconds elapsed
synchronizing the computed display lists with the render
thread.

/**
     * Metric identifier for sync duration.
     * <p>
     * Represents the number of nanoseconds elapsed
     * synchronizing the computed display lists with the render
     * thread.
     * </p>
     */
    public static final int SYNC_DURATION = 5;

    Metric identifier for command issue duration.

Represents the number of nanoseconds elapsed
issuing draw commands to the GPU.

/**
     * Metric identifier for command issue duration.
     * <p>
     * Represents the number of nanoseconds elapsed
     * issuing draw commands to the GPU.
     * </p>
     */
    public static final int COMMAND_ISSUE_DURATION = 6;

    Metric identifier for swap buffers duration.

Represents the number of nanoseconds elapsed issuing
the frame buffer for this frame to the display
subsystem.

/**
     * Metric identifier for swap buffers duration.
     * <p>
     * Represents the number of nanoseconds elapsed issuing
     * the frame buffer for this frame to the display
     * subsystem.
     * </p>
     */
    public static final int SWAP_BUFFERS_DURATION = 7;

    Metric identifier for total frame duration.

Represents the total time in nanoseconds this frame took to render
and be issued to the display subsystem.


Equal to the sum of the values of all other time-valued metric
identifiers.

/**
     * Metric identifier for total frame duration.
     * <p>
     * Represents the total time in nanoseconds this frame took to render
     * and be issued to the display subsystem.
     * </p>
     * <p>
     * Equal to the sum of the values of all other time-valued metric
     * identifiers.
     * </p>
     */
    public static final int TOTAL_DURATION = 8;

    Metric identifier for a boolean value determining whether this frame was
the first to draw in a new Window layout.
 getMetric(int) will return 0 for false, 1 for true. 

First draw frames are expected to be slow and should usually be exempt
from display jank calculations as they do not cause skips in animations
and are usually hidden by window animations or other tricks.

/**
     * Metric identifier for a boolean value determining whether this frame was
     * the first to draw in a new Window layout.
     * <p>
     * {@link #getMetric(int)} will return 0 for false, 1 for true.
     * </p>
     * <p>
     * First draw frames are expected to be slow and should usually be exempt
     * from display jank calculations as they do not cause skips in animations
     * and are usually hidden by window animations or other tricks.
     * </p>
     */
    public static final int FIRST_DRAW_FRAME = 9;

    Metric identifier for the timestamp of the intended vsync for this frame.
 The intended start point for the frame. If this value is different from VSYNC_TIMESTAMP, there was work occurring on the UI thread that prevented it from responding to the vsync signal in a timely fashion. 
/**
     * Metric identifier for the timestamp of the intended vsync for this frame.
     * <p>
     * The intended start point for the frame. If this value is different from
     * {@link #VSYNC_TIMESTAMP}, there was work occurring on the UI thread that
     * prevented it from responding to the vsync signal in a timely fashion.
     * </p>
     */
    public static final int INTENDED_VSYNC_TIMESTAMP = 10;

    Metric identifier for the timestamp of the actual vsync for this frame.
 The time value that was used in all the vsync listeners and drawing for the frame (Choreographer frame callbacks, animations, View.getDrawingTime(), etc…) 
/**
     * Metric identifier for the timestamp of the actual vsync for this frame.
     * <p>
     * The time value that was used in all the vsync listeners and drawing for
     * the frame (Choreographer frame callbacks, animations,
     * {@link View#getDrawingTime()}, etc…)
     * </p>
     */
    public static final int VSYNC_TIMESTAMP = 11;

    private static final int FRAME_INFO_FLAG_FIRST_DRAW = 1 << 0;

    Identifiers for metrics available for each frame.
{@see #getMetric(int)}
@hide /**
     * Identifiers for metrics available for each frame.
     *
     * {@see #getMetric(int)}
     * @hide
     */
    @IntDef({
            UNKNOWN_DELAY_DURATION,
            INPUT_HANDLING_DURATION,
            ANIMATION_DURATION,
            LAYOUT_MEASURE_DURATION,
            DRAW_DURATION,
            SYNC_DURATION,
            COMMAND_ISSUE_DURATION,
            SWAP_BUFFERS_DURATION,
            TOTAL_DURATION,
            FIRST_DRAW_FRAME,
            INTENDED_VSYNC_TIMESTAMP,
            VSYNC_TIMESTAMP,
    })
    @Retention(RetentionPolicy.SOURCE)
    public @interface Metric {}

    Timestamp indices for frame milestones.
May change from release to release.
Must be kept in sync with frameworks/base/libs/hwui/FrameInfo.h.
@hide /**
     * Timestamp indices for frame milestones.
     *
     * May change from release to release.
     *
     * Must be kept in sync with frameworks/base/libs/hwui/FrameInfo.h.
     *
     * @hide
     */
    @IntDef ({
            Index.FLAGS,
            Index.INTENDED_VSYNC,
            Index.VSYNC,
            Index.OLDEST_INPUT_EVENT,
            Index.NEWEST_INPUT_EVENT,
            Index.HANDLE_INPUT_START,
            Index.ANIMATION_START,
            Index.PERFORM_TRAVERSALS_START,
            Index.DRAW_START,
            Index.SYNC_QUEUED,
            Index.SYNC_START,
            Index.ISSUE_DRAW_COMMANDS_START,
            Index.SWAP_BUFFERS,
            Index.FRAME_COMPLETED,
    })
    @Retention(RetentionPolicy.SOURCE)
    private @interface Index {
        int FLAGS = 0;
        int INTENDED_VSYNC = 1;
        int VSYNC = 2;
        int OLDEST_INPUT_EVENT = 3;
        int NEWEST_INPUT_EVENT = 4;
        int HANDLE_INPUT_START = 5;
        int ANIMATION_START = 6;
        int PERFORM_TRAVERSALS_START = 7;
        int DRAW_START = 8;
        int SYNC_QUEUED = 9;
        int SYNC_START = 10;
        int ISSUE_DRAW_COMMANDS_START = 11;
        int SWAP_BUFFERS = 12;
        int FRAME_COMPLETED = 13;

        int FRAME_STATS_COUNT = 16; // must always be last
    }

    /*
     * Bucket endpoints for each Metric defined above.
     *
     * Each defined metric *must* have a corresponding entry
     * in this list.
     */
    private static final int[] DURATIONS = new int[] {
        // UNKNOWN_DELAY
        Index.INTENDED_VSYNC, Index.HANDLE_INPUT_START,
        // INPUT_HANDLING
        Index.HANDLE_INPUT_START, Index.ANIMATION_START,
        // ANIMATION
        Index.ANIMATION_START, Index.PERFORM_TRAVERSALS_START,
        // LAYOUT_MEASURE
        Index.PERFORM_TRAVERSALS_START, Index.DRAW_START,
        // DRAW
        Index.DRAW_START, Index.SYNC_QUEUED,
        // SYNC
        Index.SYNC_START, Index.ISSUE_DRAW_COMMANDS_START,
        // COMMAND_ISSUE
        Index.ISSUE_DRAW_COMMANDS_START, Index.SWAP_BUFFERS,
        // SWAP_BUFFERS
        Index.SWAP_BUFFERS, Index.FRAME_COMPLETED,
        // TOTAL_DURATION
        Index.INTENDED_VSYNC, Index.FRAME_COMPLETED,
    };

    /* package */ final long[] mTimingData;

    Constructs a FrameMetrics object as a copy.
 Use this method to copy out metrics reported by OnFrameMetricsAvailableListener.onFrameMetricsAvailable(Window, FrameMetrics, int) 
Params: other – the FrameMetrics object to copy./**
     * Constructs a FrameMetrics object as a copy.
     * <p>
     * Use this method to copy out metrics reported by
     * {@link Window.OnFrameMetricsAvailableListener#onFrameMetricsAvailable(
     * Window, FrameMetrics, int)}
     * </p>
     * @param other the FrameMetrics object to copy.
     */
    public FrameMetrics(FrameMetrics other) {
        mTimingData = new long[Index.FRAME_STATS_COUNT];
        System.arraycopy(other.mTimingData, 0, mTimingData, 0, mTimingData.length);
    }

    @hide /**
     * @hide
     */
    FrameMetrics() {
        mTimingData = new long[Index.FRAME_STATS_COUNT];
    }

    Retrieves the value associated with Metric identifier id for this frame. 
Boolean metrics are represented in [0,1], with 0 corresponding to
false, and 1 corresponding to true.

Params: id – the metric to retrieve
Returns: the value of the metric or -1 if it is not available./**
     * Retrieves the value associated with Metric identifier {@code id}
     * for this frame.
     * <p>
     * Boolean metrics are represented in [0,1], with 0 corresponding to
     * false, and 1 corresponding to true.
     * </p>
     * @param id the metric to retrieve
     * @return the value of the metric or -1 if it is not available.
     */
    public long getMetric(@Metric int id) {
        if (id < UNKNOWN_DELAY_DURATION || id > VSYNC_TIMESTAMP) {
            return -1;
        }

        if (mTimingData == null) {
            return -1;
        }

        if (id == FIRST_DRAW_FRAME) {
            return (mTimingData[Index.FLAGS] & FRAME_INFO_FLAG_FIRST_DRAW) != 0 ? 1 : 0;
        } else if (id == INTENDED_VSYNC_TIMESTAMP) {
            return mTimingData[Index.INTENDED_VSYNC];
        } else if (id == VSYNC_TIMESTAMP) {
            return mTimingData[Index.VSYNC];
        }

        int durationsIdx = 2 * id;
        return mTimingData[DURATIONS[durationsIdx + 1]]
                - mTimingData[DURATIONS[durationsIdx]];
    }
}
Params:	id – the metric to retrieve
Returns:	the value of the metric or -1 if it is not available.
/

android/ android-9.0.0_r35/ android/view/FrameMetrics.java
