// Copyright 2022 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.ui.composition;

using fuchsia.math;
using zx;

/// The possible errors from the ScreenCapture protocol.
type ScreenCaptureError = flexible enum {
    /// One or more required arguments are missing in the table argument.
    MISSING_ARGS = 1;
    /// One or more of the arguments was not valid.
    INVALID_ARGS = 2;
    /// A general error occurred during the method call.
    BAD_OPERATION = 3;
    /// Error that is returned if [`GetNextFrame`] is called when all of the VMOs in the
    /// BufferCollection have been rendered to. [`ReleaseFrame`] must be called before a
    /// successful call to GetNextFrame can be made.
    BUFFER_FULL = 4;
};

/// The rotation to be applied to the image.
///
/// If a given display is rotated, say, 270 degrees according to its
/// `display_info` config file, then applying the equal and opposite rotation,
/// [`CW_270_DEGREES`], should cancel the display rotation leading to a
/// correctly rendered screenshot.
///
/// Clients should allocate an image according to the final dimensions they
/// ultimately want to use, i.e. after rotation. These would be identical
/// to the `width` and `height` values found in the `display_info` config file.
type Rotation = strict enum {
    CW_0_DEGREES = 0;
    CW_90_DEGREES = 1;
    CW_180_DEGREES = 2;
    CW_270_DEGREES = 3;
};

/// The arguments passed into the [`Configure`] call. Note that not all fields are necessary.
type ScreenCaptureConfig = resource table {
    /// The import token referencing a BufferCollection registered with
    /// Allocator. Required.
    1: import_token BufferCollectionImportToken;
    /// The size of the image in pixels. Required.
    2: size fuchsia.math.SizeU;
    /// The number of buffers in the BufferCollection. Required.
    // TODO(fxbug.dev/97057): Get buffer_count from the importer and remove this.
    3: buffer_count uint32;
    /// The rotation to be applied to the stream of images. Optional; if absent no rotation is
    /// applied.
    4: rotation Rotation;
    // TODO(fxbug.dev/97057): Add an option to exclude cursor capture.
};

/// The arguments passed into the [`GetNextFrame`] call. All fields are necessary.
type GetNextFrameArgs = resource table {
    /// The event that will signal when the requested frame has been rendered. Required.
    1: event zx.handle:EVENT;
};

/// Metadata about the frame rendered by [`GetNextFrame`].
type FrameInfo = resource table {
    /// The index of the VMO where the requested frame has been rendered. Required.
    1: buffer_id uint32;
};


/// This protocol provides a low-level ScreenCapture API for clients to use.
/// ScreenCapture clients should familiarize themselves with the
/// [`fuchsia.sysmem/BufferCollection`] and [`fuchsia.ui.composition/Allocator`] protocols
/// as those are necessary to create the BufferCollections and images ScreenCapture uses.
@discoverable
protocol ScreenCapture {
    /// Clients should first use the Allocator protocol to register a
    /// BufferCollection. This function will fail with BAD_OPERATION unless all clients of the
    /// BufferCollection have set their constraints.
    ///
    /// Afterwards, clients should create and configure the images that will
    /// eventually be rendered to using this method. All the buffers in the
    /// collection from 0 to (buffer_count-1) may be used for screen capture.
    ///
    /// Clients are responsible for determining the rotation of the display,
    /// and applying the corrective rotation. For instance, if the display is
    /// mounted 90 degrees clockwise (the "top" is on the right, when looking
    /// at the display), then the client should specify a 270 degree rotation
    /// to account for it.
    ///
    /// Similarly, the clients are responsible for specifying a buffer big
    /// enough for the rotated image. If the buffer is too small, a best effort
    /// attempt will be made to render the image.
    ///
    /// Finally, clients request the server to render the current screen to the
    /// shared buffers using [`GetNextFrame`].
    ///
    /// [`Configure`] can be called again with a new BufferCollectionImportToken
    /// if the client wishes to change any of the configuration settings. In
    /// this case all the buffers from the previous call to [`Configure`] will
    /// be released.
    Configure(ScreenCaptureConfig) -> (struct {}) error ScreenCaptureError;

    /// Following a successful call to [`Configure`], clients can call
    /// GetNextFrame. This will populate a buffer with the most recent frame.
    ///
    /// Clients should wait on the zx::event they pass for successful
    /// completion of the screenshot. It is not guaranteed that the screenshot
    /// will be completed by the time this function returns.
    ///
    /// The requested image will be in the BufferCollection that the client set
    /// up in the VMO at the index specified by buffer_id.
    ///
    /// When ScreenCapture is used to provide a stream, the rate that the
    /// client calls GetNextFrame will drive the frame rate.
    ///
    /// Errors:
    /// BAD_OPERATION if Configure was not called, or not called successfully
    /// MISSING_ARGS if a required argument is not present
    /// BUFFER_FULL if all buffers in the BufferCollection are in use. In this case, ReleaseFrame
    /// must be called to make a buffer available before this function can be called successfully.
    // TODO(fxbug.dev/97057): Add a way to notify clients of the display
    // refresh rate, perhaps through the Display API.
    GetNextFrame(GetNextFrameArgs) -> (FrameInfo) error ScreenCaptureError;

    /// Once the client no longer needs an image, they can call ReleaseFrame on
    /// the VMO index of the buffer so that the server can reuse it in the future.
    ReleaseFrame(struct {
        buffer_id uint32;
    }) -> (struct {}) error ScreenCaptureError;
};