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

library fuchsia.hardware.display.capture;

using zx;

alias ZxUnownedHandle = uint32;

[Transport = "Banjo", BanjoLayout = "ddk-interface"]
protocol DisplayCaptureInterface {
  OnCaptureComplete() -> ();
};

[Transport = "Banjo", BanjoLayout = "ddk-protocol"]
protocol DisplayCaptureImpl {
    /// The function will only be called once, and it will be called before any other
    /// functions are called.
    SetDisplayCaptureInterface(DisplayCaptureInterface intf) -> ();

    /// Import BufferCollection backed VMO pointed to by index.
    /// Importing the VMO usually involves pinning the VMO and updating display
    /// controller hardware registers with the physical address of the VMO to be
    /// used for capture. Returns out_capture_handle which maps to the allocated
    /// resource
    ImportImageForCapture(ZxUnownedHandle collection, uint32 index)
        -> (zx.status s, uint64 capture_handle);

    /// Starts capture into the resource mapped by capture_handle (non-blocking)
    /// Only one active capture is allowed at a time.
    /// A valid image must be displayed during capture. Otherwise unexpected hardware
    /// behavior might occur.
    /// Drivers should not leave display hardware in this unexpected state.
    /// Drivers are expected to stop and/or abort capture if no valid
    /// image is being displayed.
    StartCapture(uint64 capture_handle) -> (zx.status s);

    /// Releases resources allocated by capture_handle.
    /// Releasing resources from an active capture is not allowed and will cause
    /// unexpected behavior.
    ReleaseCapture(uint64 capture_handle) -> (zx.status s);

    /// Returns true if capture is completed. False otherwise.
    IsCaptureCompleted() -> (bool b);
};