// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=7)
library fuchsia.scenic.scheduling;

using zx;

/// The times we predict for a future presentation, expressed in nanoseconds in
/// the `CLOCK_MONOTONIC` timebase.
type PresentationInfo = table {
    /// The time where Scenic processes all pending updates to its scene graph
    /// and render a new frame. Clients should aim to have all  commands sent
    /// and acquire fences reached in order to have their  content be
    /// presented at the corresponding `presentation_time`. The `latch_point`
    /// is guaranteed to be less than `presentation_time`.
    1: latch_point zx.Time;

    /// The time in which the enqueued operations submitted before `latch_point`
    /// take visible effect. This time is usually but not necessarily vsync.
    2: presentation_time zx.Time;
};

/// The times we record for each Present2, expressed in nanoseconds in the
/// `CLOCK_MONOTONIC` timebase.
type PresentReceivedInfo = table {
    /// The time Scenic receives the Present2 call.
    1: present_received_time zx.Time;

    /// The time Scenic latched the Present2 call to. This is guaranteed to be
    /// greater than the `present_received_time`.
    2: latched_time zx.Time;
};

/// The data type returned in `fuchsia.ui.scenic::RequestPresentationTimes`. See
/// that method description for more information.
type FuturePresentationTimes = struct {
    /// The future estimated presentation times. They represent the times Scenic
    /// intends to let the client's work be presented over the next few frames.
    /// These values may change after they are queried.
    ///
    /// Clients who wish to minimize latency should use these values to schedule
    /// their work accordingly.
    future_presentations vector<PresentationInfo>:8;

    /// The amount of Present() calls the client is currently allowed. If the
    /// client calls Present() when this number is zero, the session will be
    /// shut down.
    ///
    /// This value is decremented every Present() call, and is incremented every
    /// OnFramePresented() event.
    remaining_presents_in_flight_allowed int64;
};

type FramePresentedInfo = struct {
    /// The time the frame was presented to the user. This value was captured
    /// after the fact, differentiating it from the `presentation_time`s
    /// included in `FuturePresentationTimes`.
    actual_presentation_time zx.Time;

    /// The presentation informations for each Present2() that comprised the
    /// content of this frame. These are ordered by present submission order.
    presentation_infos vector<PresentReceivedInfo>:32;

    /// The number of times remaining that the client can call `Present2`.
    num_presents_allowed uint64;
};