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

using fuchsia.sysmem;
using fuchsia.sysmem2;
using zx;

/// The set of error codes returned by Allocator::RegisterBufferCollection().
@strict_audit(bug="https://fxbug.dev/467128273", state="PENDING_REVIEW")
type RegisterBufferCollectionError = strict enum {
    BAD_OPERATION = 1;
};

/// A typed wrapper for an eventpair, representing the registry endpoint of a buffer collection.
type BufferCollectionExportToken = resource struct {
    value zx.Handle:EVENTPAIR;
};

/// A typed wrapper for an eventpair, representing the Image import endpoint of a buffer
/// collection.
type BufferCollectionImportToken = resource struct {
    value zx.Handle:EVENTPAIR;
};

/// The possible usages for registered buffer collection.
@strict_audit(bug="https://fxbug.dev/467128273", state="PENDING_REVIEW")
type RegisterBufferCollectionUsage = strict enum {
    /// DEFAULT means that the specified buffer collection will be used for
    /// Flatland and gfx image creation.
    ///
    /// See [`fuchsia.ui.composition/Flatland.CreateImage`] for more.
    DEFAULT = 0;

    /// SCREENSHOT means that the specified buffer collection will be used for
    /// screenshotting purposes.
    SCREENSHOT = 1;
};

/// The possible usages for a registered buffer collection. Can be a combination of options.
@available(added=9)
type RegisterBufferCollectionUsages = flexible bits : uint16 {
    /// The specified buffer collection can be used for Flatland and GFX image creation.
    ///
    /// See [`fuchsia.ui.composition/Flatland.CreateImage`] for more.
    DEFAULT = 0x0001;

    /// The specified buffer collection can be used for screenshotting purposes.
    SCREENSHOT = 0x0002;
};

/// The table of arguments for [`RegisterBufferCollection`]. Note that some
/// fields below are REQUIRED.
type RegisterBufferCollectionArgs = resource table {
    /// Clients can send [`export_token`] to register buffer collections with Allocator to be used
    /// later in [`fuchsia.ui.composition/Flatland`] instances or other Scenic APIs, such as
    /// Screenshot.
    ///
    /// For example, by passing a [`BufferCollectionImportToken`] containing the matching peer of
    /// [`BufferCollectionExportToken`], they can create image resources via
    /// [`fuchsia.ui.composition/Flatland.CreateImage`].
    ///
    /// Clients should wait for the response before using `import_token`.
    ///
    /// This field is REQUIRED.
    1: export_token BufferCollectionExportToken;

    /// Flatland participates in the allocation of buffers by setting constraints on the
    /// BufferCollection referenced by `buffer_collection_token`. It will not block on buffers
    /// being allocated until the client creates content using the BufferCollection.
    ///
    /// The buffer collection registered with `export_token` is available and kept alive as long
    /// as the client holds a valid [`BufferCollectionImportToken`]. They will be garbage collected
    /// when all [`BufferCollectionImportToken`]s are closed and all the associated Image resources
    /// are released.
    ///
    /// Exactly one of `buffer_collection_token2` / `buffer_collection_token` must be set.
    @available(added=25)
    5: buffer_collection_token2 client_end:fuchsia.sysmem2.BufferCollectionToken;
    @available(added=7, deprecated=25, note="use buffer_collection_token2")
    2: buffer_collection_token client_end:fuchsia.sysmem.BufferCollectionToken;

    /// The client can register a buffer collection for various uses, each
    /// coming with their own unique constraints.
    ///
    /// This field is OPTIONAL. If `usage` is omitted it will be treated as if
    /// it has the DEFAULT option.
    ///
    /// # Deprecation
    ///
    /// This arg is deprecated at API version 9 with addition of |usages|.
    ///
    /// If both the `usages` and `usage` fields are set, `usages` takes precedence and `usage` is
    /// ignored.
    @available(deprecated=9, note="use usages. Deletion tracking bug: https://fxbug.dev/42056432")
    3: usage RegisterBufferCollectionUsage;

    /// The client can register a buffer collection for various uses and has the ability to
    /// combine usages if multiple are needed.
    ///
    /// This field is OPTIONAL. If `usages` is omitted it will be treated as if
    /// it has only the DEFAULT option.
    @available(added=9)
    4: usages RegisterBufferCollectionUsages;
};

@discoverable
closed protocol Allocator {
    /// A BufferCollection is a set of VMOs created by Sysmem and shared by a number of
    /// participants, one of which is the Flatland Renderer. Some content, such as Images, use a
    /// BufferCollection as their backing memory.
    ///
    /// See [`RegisterBufferCollectionArgs`] for information on each argument.
    strict RegisterBufferCollection(resource struct {
        args RegisterBufferCollectionArgs;
    }) -> () error RegisterBufferCollectionError;
};