// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[DartPackage="mojo_services"]
module mojo.gfx.composition;

import "mojo/services/geometry/interfaces/geometry.mojom";
import "mojo/services/gpu/interfaces/context_provider.mojom";
import "mojo/services/gfx/composition/interfaces/scene_token.mojom";
import "mojo/services/gfx/composition/interfaces/scenes.mojom";
import "mojo/services/gfx/composition/interfaces/renderers.mojom";

// Maximum length for a scene or renderer label.
const uint32 kLabelMaxLength = 32;

// The compositor manages scenes and scene graph renderers.
//
// Applications create scenes to describe graphical content they would like
// to render, including references to other scenes they would like to compose.
//
// The system creates a renderer to bind a scene graph to a particular display.
//
// Refer to |Scene| and |Renderer| for more information about these objects.
[ServiceName="mojo::gfx::composition::Compositor"]
interface Compositor {
  // Creates a scene.
  //
  // The |scene| is used to supply content for the scene.  The scene pipe
  // is private to the scene and should not be shared with anyone else.
  //
  // The |scene_token| is used as a transferable reference which can be passed
  // to owners of other scenes to allow them to embed this scene as a
  // resource.  The compositor itself does not describe how this interaction
  // should take place, only that the token may eventually be used to
  // construct a |SceneResource|.
  //
  // The |label| is an optional name to associate with the view for
  // diagnostic purposes.  The label will be truncated if it is longer
  // than |kLabelMaxLength|.
  //
  // To unregister the scene, simply close the |scene| message pipe.
  CreateScene(Scene& scene, string? label) => (SceneToken scene_token);

  // Creates a scene graph renderer.
  //
  // The |context_provider| provides the GL Context to which the content
  // should be rendered.  This will typically be a display.
  //
  // The |label| is an optional name to associate with the renderer for
  // diagnostic purposes.  The label will be truncated if it is longer
  // than |kLabelMaxLength|.
  //
  // To destroy the renderer, simply close the |renderer| message pipe.
  CreateRenderer(mojo.ContextProvider context_provider,
                 Renderer& renderer, string? label);
};