// 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 zx;

/// The set of error codes returned by Allocator::RegisterBufferCollection().
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.
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 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.
    ///
    /// This field is REQUIRED.
    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.
    3: usage RegisterBufferCollectionUsage;
};

@discoverable
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.
    RegisterBufferCollection(resource struct {
        args RegisterBufferCollectionArgs;
    }) -> (struct {}) error RegisterBufferCollectionError;
};