// Copyright 2021 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.

library fuchsia.media2;

using zx;

/// Describes any active producer, including single-stream and multi-stream producers.
/// All active producers should compose this protocol. Single-stream active producers
/// and streams exposed by multi-stream active producers should also compose
/// `ActiveProducerStream`.
protocol ActiveProducer {
    /// Starts the production of packets.
    ///
    /// + request `when` time when the production of packets should
    ///   start as a system time or reference time. If this parameter
    ///   is not supplied, packet production starts as soon as
    ///   possible.
    /// - response `reference_time` the reference time at which packet
    ///   production was actually started.
    ///
    /// When a call to this method succeeds, the response is sent when
    /// the operation actually occurs (that is, when it was scheduled
    /// to occur), indicating that the service is ready for a `Stop`
    /// command. When a call to this method fails, the response is
    /// sent when the failure is detected.
    ///
    /// If this method is called when packet production is already
    /// underway, the call fails immediately with an `ALREADY_STARTED`
    /// error.
    ///
    /// Otherwise, if this method is called, and `when` specifies a
    /// time in the past, the call fails immediately with a
    /// `SCHEDULED_IN_PAST` error.
    ///
    /// Otherwise, if this method is called when a `Start` operation
    /// is already pending (requested but not completed), the pending
    /// operation fails with a `CANCELED` error.
    Start(struct {
        when RealTime:optional;
    }) -> (struct {
        reference_time zx.time;
    }) error StartError;

    /// Stops packet production.
    ///
    /// + request `when` time when the production of packets should
    ///   stop as a system time, reference time or presentation time. If
    ///   this parameter is not supplied or specifies a time in the
    ///   past, packet production stops as soon as possible.
    /// - response `reference_time` the reference time at which packet
    ///   production was actually stopped.
    ///
    /// When a call to this method succeeds, the response is sent when
    /// the operation actually occurs (that is, when it was scheduled
    /// to occur), indicating that the service is ready for a `Start`
    /// command. When a call to this method fails, the response is
    /// sent when the failure is detected.
    ///
    /// If this method is called when packet production is stopped,
    /// the call fails immediately with an `ALREADY_STOPPED` error.
    ///
    /// Otherwise, if this method is called, and `when` specifies a
    /// time in the past, the call fails immediately with a
    /// `SCHEDULED_IN_PAST` error.
    ///
    /// Otherwise, if this method is called when a `Stop` operation
    /// is already pending (requested but not completed), the pending
    /// operation fails with a `CANCELED` error.
    Stop(struct {
        when RealOrPresentationTime:optional;
    }) -> (struct {
        reference_time zx.time;
    }) error StopError;

    /// Causes the producer to send a clear signal via its produced
    /// stream(s) with the specified parameters.
    ///
    /// + request `hold_last_frame` whether a video renderer receiving
    ///   the clear signal should hold the last frame (true) or show
    ///   black (false).
    /// + request `completion_fence` an eventpair to be passed along with
    ///   the clear signal and closed when the signal reaches the end of
    ///   the pipeline. See `fuchsia.media2.StreamSink/Clear`.
    Clear(resource struct {
        hold_last_frame bool;
        completion_fence zx.handle:<EVENTPAIR, optional>;
    });
};

/// Describes any passive producer, including single-stream and multi-stream producers.
/// All passive producers should compose this protocol.
protocol PassiveProducer {
    /// Starts packet production at the specified presentation time in
    /// the file.
    ///
    /// + request presentation_time the presentation time at which
    ///   the producer should start reading and producing packets.
    ///   Compressed packets prior to `presentation_time` may be
    ///   produced if they are required to decode packets that have
    ///   been requested.
    /// TODO: edge cases
    StartAt(struct {
        presentation_time zx.duration;
    });

    /// Stops packet production at the specified presentation time in
    /// the file.
    ///
    /// + request presentation_time the presentation time at which
    ///   the producer should stop reading and producing packets.
    /// - response presentation_time the actual presentation time at
    ///   which reading actually stopped.
    /// TODO: edge cases
    StopAt(struct {
        presentation_time zx.duration;
    }) -> (struct {
        presentation_time zx.duration;
    });

    /// Stops packet production as soon as possible.
    ///
    /// - response presentation_time the actual presentation time at
    ///   which reading actually stopped.
    /// TODO: edge cases
    Stop() -> (struct {
        presentation_time zx.duration;
    });

    /// Causes the producer to send a clear signal via its produced
    /// stream(s) with the specified parameters.
    ///
    /// + request `hold_last_frame` whether a video renderer receiving
    ///   the clear signal should hold the last frame (true) or show
    ///   black (false).
    /// + request `completion_fence` an eventpair to be passed along with
    ///   the clear signal and closed when the signal reaches the end of
    ///   the pipeline. See `fuchsia.media2.StreamSink/Clear`.
    Clear(resource struct {
        hold_last_frame bool;
        completion_fence zx.handle:<EVENTPAIR, optional>;
    });
};

/// Describes any active producer stream, including single-stream producers and streams exposed by
/// multi-stream producers. All single-stream active producers and all streams exposed by
/// multi-stream active producers should compose this protocol.
protocol ActiveProducerStream {
    /// Returns buffer availability lead time when it falls outside
    /// the specified limits or when a new `WatchBufferLeadTime` request arrives. Buffer lead
    /// time is the interval between the time the producer becomes aware that a buffer is no
    /// longer is in use and the time at which the producer needs to allocate that buffer.
    /// Underflow (when no buffer is available when one is needed) is indicated by a negative lead
    /// time value, if the value is known, or `WatchLeadTimeResult.underflow` if it is not.
    /// For the purposes of filtering, `WatchLeadTimeResult.underflow` is equivalent to a lead time
    /// value of -1.
    ///
    /// + request `min` the margin below which buffer availability
    ///   lead time must fall in order for the reply to be sent.  For example, passing zero
    ///   indicates that the reply should be sent when the connection has overflowed.
    /// + request `max` the margin above which buffer availability
    ///   lead time must rise in order for the reply to be sent.
    /// - response `buffer_lead_time` the actual buffer availability
    ///   lead time measured when the response was generated. This value will only be within
    ///   the specified limits if the response is generated due to
    ///   the arrival of a new `WatchBufferLeadTime` request.
    /// * error `NO_LEAD_TIME_REPORTED` indicates a new `WatchBufferLeadTime` request arrived before
    ///   any lead time values were reported.
    ///
    /// Only one `WatchBufferLeadTime` operation may be pending at any
    /// given time. If a `WatchBufferLeadTime` request is received
    /// when another such request is pending, the producer responds
    /// to the older request with the current buffer lead time value or the error
    /// `NO_LEAD_TIME_REPORTED`.
    ///
    /// Implementation note:
    /// Because buffers may be allocated out of order with respect to their release, producers
    /// generate buffer lead time values using a queue of times that are not explicitly correlated
    /// to actual buffers. Initially, when all buffers are available by default, the queue should
    /// contain N placeholder entries for a buffer collection containing N buffers. When a buffer
    /// is allocated, the time value at the head of the queue is compared to the current time to
    /// produce a lead  time value, and the queue is popped. If the time value at the head of the
    /// queue is a placeholder, lead time is not calculated. When the producer is signaled that a
    /// buffer is available, the current time is pushed onto the queue.
    WatchBufferLeadTime(struct {
        min zx.duration;
        max zx.duration;
    }) -> (struct {
        result WatchLeadTimeResult;
    });
};