// 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.session.scene;

using fuchsia.ui.app;
using fuchsia.ui.views;

/// A protocol used to manage the scene graph of the session.
///
/// This protocol is exposed by the `scene_manager` component. The `scene_manager`
/// component configures and constructs a scene graph in Scenic. A product may
/// use the `scene_manager` to reduce Scenic-related configuration code in their session.
@discoverable
protocol Manager {
    /// Sets the root view of the scene graph to the view provided by `view_provider`.
    ///
    /// Subsequent calls will replace the view tree with the one starting at the new root view.
    /// The root view is shared between all clients of `Manager`.
    ///
    /// Returns a `fuchsia.ui.views.ViewRef` referencing the view provided by `view_provider`.
    /// If this ViewRef cannot be returned (e.g. in Flatland case, if the ViewCreationToken is
    /// dropped before it is given to Scenic), then the connection to the `Manager` will be closed.
    ///
    /// NOTE: the ViewRef is only returned after the child view is connected to the scene graph.
    /// Therefore, the caller must guarantee that the child view will eventually be connected before
    /// waiting for the ViewRef; if the child view doesn't connect, it is possible to deadlock.
    SetRootView(resource struct {
        view_provider client_end:fuchsia.ui.app.ViewProvider;
    }) -> (resource struct {
        view_ref fuchsia.ui.views.ViewRef;
    });
};