// 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")
@banjo_layout("ddk-interface")
protocol DisplayCaptureInterface {
    OnCaptureComplete() -> ();
};

@transport("Banjo")
@banjo_layout("ddk-protocol")
protocol DisplayCaptureImpl {
    /// The function will only be called once, and it will be called before any other
    /// functions are called.
    SetDisplayCaptureInterface(resource struct {
        intf client_end:DisplayCaptureInterface;
    }) -> ();

    /// 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(struct {
        collection ZxUnownedHandle;
        index uint32;
    }) -> (struct {
        s zx.status;
        capture_handle uint64;
    });

    /// 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(struct {
        capture_handle uint64;
    }) -> (struct {
        s zx.status;
    });

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

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