services/viz/privileged/mojom/compositing/frame_sink_manager.mojom

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

module viz.mojom;

import "gpu/ipc/common/surface_handle.mojom";
import "mojo/public/mojom/base/shared_memory.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "services/viz/privileged/mojom/compositing/display_private.mojom";
import "services/viz/privileged/mojom/compositing/external_begin_frame_controller.mojom";
import "services/viz/privileged/mojom/compositing/features.mojom";
import "services/viz/privileged/mojom/compositing/frame_sink_manager_test_api.mojom";
import "services/viz/privileged/mojom/compositing/frame_sink_video_capture.mojom";
import "services/viz/privileged/mojom/compositing/frame_sinks_metrics_recorder.mojom";
import "services/viz/privileged/mojom/compositing/renderer_settings.mojom";
import "services/viz/public/mojom/compositing/compositor_frame_sink.mojom";
import "services/viz/public/mojom/compositing/copy_output_request.mojom";
import "services/viz/public/mojom/compositing/copy_output_result.mojom";
import "services/viz/public/mojom/compositing/frame_sink_bundle.mojom";
import "services/viz/public/mojom/compositing/frame_sink_bundle_id.mojom";
import "services/viz/public/mojom/compositing/frame_sink_id.mojom";
import "services/viz/public/mojom/compositing/local_surface_id.mojom";
import "services/viz/public/mojom/compositing/surface_id.mojom";
import "services/viz/public/mojom/compositing/surface_info.mojom";
import "services/viz/public/mojom/compositing/video_detector_observer.mojom";
import "services/viz/public/mojom/hit_test/aggregated_hit_test_region.mojom";
import "third_party/blink/public/mojom/tokens/tokens.mojom";
import "third_party/blink/public/mojom/widget/platform_widget.mojom";
import "ui/gfx/geometry/mojom/geometry.mojom";
import "components/input/render_input_router.mojom";

// Initialization parameters for a RootCompositorFrameSink.
struct RootCompositorFrameSinkParams {
  FrameSinkId frame_sink_id;
  gpu.mojom.SurfaceHandle widget;
  bool gpu_compositing = true;
  RendererSettings renderer_settings;
  bool send_swap_size_notifications = false;
  // Disables begin frame rate limiting for the display compositor.
  bool disable_frame_rate_limit = false;

  // Whether to create a surface control input receiver on Viz.
  [EnableIf=is_android]
  bool create_input_receiver = false;

  [EnableIf=is_android]
  float refresh_rate;

  pending_associated_receiver<CompositorFrameSink> compositor_frame_sink;
  pending_remote<CompositorFrameSinkClient> compositor_frame_sink_client;

  pending_associated_receiver<DisplayPrivate> display_private;
  pending_remote<DisplayClient> display_client;

  pending_associated_receiver<ExternalBeginFrameController>?
      external_begin_frame_controller;

  // If this value is set, `external_begin_frame_controller` must be set as
  // well. This field is not required to be set if
  // `external_begin_frame_controller` is set.
  pending_associated_remote<ExternalBeginFrameControllerClient>?
      external_begin_frame_controller_client;
};

// The FrameSinkManager interface is a privileged interface that allows the
// frame sink manager host (browser or window server) to create
// CompositorFrameSinks. Clients acquire a CompositorFrameSink connection
// through the frame sink manager host. Clients request a CompositorFrameSink
// interface, and implement a CompositorFrameSinkClient interface. The frame
// sink manager host holds one or more display CompositorFrameSinks that are
// tied to a valid |surface_handle| and Display. All other
// CompositorFrameSinks must be parented by another CompositorFrameSink.
// FrameSinkIds are fixed for a given client and are determined ahead of time.
// Thus, a client will typically simply request a CompositorFrameSink from the
// frame sink manager host which will forward the request to the frame sink
// manager.
[DirectReceiver]
interface FrameSinkManager {
  // Starts the scope of temporary references tied to this |frame_sink_id|.
  // Temporary references tied to this |frame_sink_id| will be dropped on
  // InvalidateFrameSinkId.This must be called before Create(Root)
  // CompositorFrameSink() is called. |report_activation| indicates whether
  // the Viz host is interested in FirstSurfaceActivation notifications of
  // surfaces from this |frame_sink_id|.
  RegisterFrameSinkId(FrameSinkId frame_sink_id, bool report_activation);

  // Invalidates |frame_sink_id| which cleans up any unsatisified surface
  // sequences or dangling temporary references assigned to it. If there is a
  // CompositorFrameSink for |frame_sink_id| then it will be destroyed and the
  // message pipe to the client will be closed.
  InvalidateFrameSinkId(FrameSinkId frame_sink_id) => ();

  // |debug_label| is used when printing out the surface hierarchy so we know
  // which clients are contributing which surfaces.
  SetFrameSinkDebugLabel(FrameSinkId frame_sink_id, string debug_label);

  // Create a CompositorFrameSink for a privileged client (e.g. WindowServer).
  // This is only used by privileged clients. The client can call methods that
  // talks to the Display (e.g. ResizeDisplay(), SetDisplayVisible(), etc).
  // If |force_software_compositing| is true, then the resulting display
  // compositor will not use Gpu acceleration even if it would by default.
  // If |external_begin_frames_controller| and
  // |external_begin_frames_controller_client| are set, the resulting display
  // will be driven by a BeginFrameSource controlled by the client via the
  // ExternalBeginFrameController.
  CreateRootCompositorFrameSink(RootCompositorFrameSinkParams params);


  // Create a DisplayLinkMac instance for the privileged client
  // (e.g. CoreAnimation CADisplayLink). The client can call a method to signal
  // a VSync event to Viz. |external_begin_frames_controller_client| needs to be
  // set, so the VSync can be driven by ExternalBeginFrameSourceMojoMac via
  // ExternalBeginFrameController.
  [EnableIf=is_mac]
  CreateCompositorDisplayLink(CompositorDisplayLinkParams params);

  // Used by unprivileged clients to create a new FrameSinkBundle in the
  // service. Each bundle can be used to communicate aggregate notifications and
  // requests to and from any frame sinks belonging to the same client.
  CreateFrameSinkBundle(FrameSinkBundleId bundle_id,
                        pending_receiver<FrameSinkBundle> receiver,
                        pending_remote<FrameSinkBundleClient> client);

  // CreateCompositorFrameSink is used by unprivileged clients. This
  // CompositorFrameSink is not a root, and has to be parented by another
  // CompositorFrameSink in order to appear on screen.
  //
  // If `bundle_id` is provided, the new frame sink is added to the identified
  // bundle. This means its client will receive OnBeginFrame() and various
  // other notifications exclusively through the corresponding FrameSinkBundle,
  // in batch with notifications for other bundled frame sinks; it also means
  // the client can submit frames for this sink in batch with other bundled
  // sinks using the FrameSinkBundle interface.
  //
  // `config` is only set when `InputOnViz` flag is enabled,
  // and a layer tree frame sink for renderer is being requested.
  CreateCompositorFrameSink(
      FrameSinkId frame_sink_id,
      FrameSinkBundleId? bundle_id,
      pending_receiver<CompositorFrameSink> compositor_frame_sink,
      pending_remote<CompositorFrameSinkClient> compositor_frame_sink_client,
      input.mojom.RenderInputRouterConfig? config);

  // Destroys CompositorFrameSink created by Create[Root]CompositorFrameSink().
  // This function should only be used synchronously for destroying root
  // CompositorFrameSinks to ensure the GL context/surface is destroyed before
  // the platform window.
  [Sync, NoInterrupt]
  DestroyCompositorFrameSink(FrameSinkId frame_sink_id) => ();

  // Set up a BeginFrame relationship between two FrameSinkIds. In this case,
  // the child inherits the viz::BeginFrameSource from the parent if it doesn't
  // already have a viz::BeginFrameSource.
  RegisterFrameSinkHierarchy(
      FrameSinkId parent_frame_sink_id, FrameSinkId child_frame_sink_id);

  // Removes a BeginFrame relationship between two FrameSinkIds.
  UnregisterFrameSinkHierarchy(
      FrameSinkId parent_frame_sink_id, FrameSinkId child_frame_sink_id);

  // Requests viz to notify |observer| whenever video activity is detected in
  // one of the clients. See viz::VideoDetector.
  AddVideoDetectorObserver(pending_remote<VideoDetectorObserver> observer);

  // Creates a FrameSinkVideoCapturer instance.
  CreateVideoCapturer(pending_receiver<FrameSinkVideoCapturer> receiver,
                      uint32 capture_version_source);

  // Marks the given SurfaceIds for destruction. The client must supply a sorted
  // `surface_ids`.
  EvictSurfaces(array<SurfaceId> surface_ids);

  // Throttles the frame sinks specified by |frame_sink_ids| and all their
  // descendant sinks to send BeginFrames at an interval of |interval|. This
  // operation clears out any previous throttling operation on any frame sinks.
  Throttle(
      array<FrameSinkId> frame_sink_ids, mojo_base.mojom.TimeDelta interval);

  // Throttles all current and future frame sinks to send BeginFrames at an
  // interval at least as long as |interval|. Because there is a single viz
  // process, which itself contains a single host frame sink manager, calling
  // this multiple times from anywhere will apply the throttling described by
  // the latest call.
  StartThrottlingAllFrameSinks(mojo_base.mojom.TimeDelta interval);

  // Disables the global throttling triggered by StartThrottlingAllFrameSinks().
  // If throttling is already disabled, this has no effect.
  StopThrottlingAllFrameSinks();

  // Takes a snapshot of |surface_id| or a newer surface with the same
  // FrameSinkId. The request will be queued up until such surface exists and is
  // reachable from the root surface.
  //
  // `capture_exact_surface_id`, when set to true, makes sure the snapshot will
  // only be taken by the surface with the exact `surface_id`.
  //
  // `timeout` when non-zero will ensure the CopyOutputResultSender is called
  // by, even with an empty snapshot. Note that there may be an arbitrary delay
  // in receiving the mojo message and this is not accounted for. The timeout
  // starts when this message is received.
  RequestCopyOfOutput(SurfaceId surface_id,
                      CopyOutputRequest request,
                      bool capture_exact_surface_id,
                      mojo_base.mojom.TimeDelta timeout);

  // Caches the back buffer for the |root_frame_sink_id|. The back buffer is
  // keyed using |cache_id| and evicted when EvictBackBuffer with the same id is
  // called.
  [EnableIf=is_android]
  CacheBackBuffer(uint32 cache_id, FrameSinkId root_frame_sink_id);

  // Evicts a previously cached back buffer for the |root_frame_sink_id|
  // matching the |cache_id|.
  [EnableIf=is_android, Sync]
  EvictBackBuffer(uint32 cache_id) => ();

  // This allows dynamic manipulation of the viz debug options stored in
  // |debug_settings| (show_overdraw_feedback, etc.).
  UpdateDebugRendererSettings(DebugRendererSettings debug_settings);

  // Clears the ViewTransition resources if they have not been claimed by a
  // CompositorFrameSink. `transition_token` identifies the navigation for which
  // the resources were cached.
  ClearUnclaimedViewTransitionResources(
      blink.mojom.ViewTransitionToken transition_token);

  // Initializes FrameSinksMetricsRecorder to enable the collection of metrics
  // related to frame sinks.
  [RuntimeFeature=EnableVizTestApis]
  CreateMetricsRecorderForTest(
      pending_receiver<FrameSinksMetricsRecorder> receiver);

  // Initializes FrameSinkManagerTestApi.
  [RuntimeFeature=EnableVizTestApis]
  EnableFrameSinkManagerTestApi(
      pending_receiver<FrameSinkManagerTestApi> receiver);

  // Sets up the RendererInputRouterDelegateRegistry interface for managing
  // RenderInputRouterDelegate connections between RenderWidgetHosts (on
  // CrBrowserMain thread) and the InputManager (on VizCompositor thread).
  SetupRendererInputRouterDelegateRegistry(
    pending_receiver<RendererInputRouterDelegateRegistry> receiver);

  // Notifies list of RenderInputRouters of their block state changes for input
  // event handling on the VizCompositorThread.
  NotifyRendererBlockStateChanged(
    bool blocked,
    array<FrameSinkId> render_input_routers);

  // Requests input handling to be transferred back to the CrBrowserMain thread
  // from the VizCompositorThread. Safe to call even if the VizCompositorThread
  // is not currently handling input, the request is a no-op in that case.
  RequestInputBack();
};

// The FrameSinkManagerClient interface is implemented by the Display
// Compositor Host, a stable, and privileged peer service to the display
// compositor. The frame sink manager host is either the browser process in
// Chrome or the window server process.
interface FrameSinkManagerClient {
  // Called by the frame sink manager when a CompositorFrame with a new
  // SurfaceId activates for the first time.
  OnFirstSurfaceActivation(SurfaceInfo surface_info);

  // Sends new |hit_test_data| to the client.
  OnAggregatedHitTestRegionListUpdated(
      FrameSinkId frame_sink_id,
      array<AggregatedHitTestRegion> hit_test_data);

  // Sends |frame_sink_id|, |frame_token|, and |activation_time| to the client
  // when a surface of the provided |frame_sink_id| activates.
  OnFrameTokenChanged(FrameSinkId frame_sink_id,
                      uint32 frame_token,
                      mojo_base.mojom.TimeTicks activation_time);

  // Verifies that |thread_ids| do not belong to the host process. Renderer
  // processes send their thread ids to the GPU process to be added to the ADPF
  // session. GPU needs to make sure that they do not belong to the host
  // process or the GPU process (i.e. itself) before adding the threads to the
  // ADPF hint session.
  [EnableIf=is_android]
  VerifyThreadIdsDoNotBelongToHost(array<int32> thread_ids)
      => (bool passed_verification);

  // Allows the GPU process to send the result of a screenshot back to the host
  // process. The host stores the screenshot to the destination specified by
  // `destination_token`.
  //
  // This is used to copy a screenshot after same-document navigation committed
  // in the renderer process.
  OnScreenshotCaptured(
      blink.mojom.SameDocNavigationScreenshotDestinationToken destination_token,
      CopyOutputResult copy_output_result);

  // Called by Viz when the connection is established and the shared memory for
  // touch state is available.
  OnVizTouchStateAvailable(mojo_base.mojom.ReadOnlySharedMemoryRegion region);

  // Called by Viz when a view transition requests to allow the browser to
  // shutdown the old renderer process.
  OnViewTransitionResourcesCaptured(
      blink.mojom.ViewTransitionToken transition_token);
};

// Implemented by the GPU process (VizCompositorThread) and called from the
// browser process (CrBrowserMain thread). This allows the
// RenderInputRouterDelegate[Client] interface to use the same mojo pipe to
// send/receive information for input handling between the CrBrowserMain and the
// VizCompositorThread.
[DirectReceiver]
interface RendererInputRouterDelegateRegistry {
  // Setup the connection between the Browser (at RenderWidgetHost level) and
  // the VizCompositor thread (at InputManager level) in both directions to
  // allow transferring information from Viz to the Browser and vice versa,
  // when the VizCompositor thread is handling input using RenderInputRouters
  // with InputVizard. This connection is per FrameSinkId.
  SetupRenderInputRouterDelegateConnection(
      FrameSinkId id,
      pending_associated_remote<input.mojom.RenderInputRouterDelegateClient>
          rir_delegate_client_remote,
      pending_associated_receiver<input.mojom.RenderInputRouterDelegate>
          rir_delegate_receiver);
};

// Initialization parameters for CreateCompositorDisplayLink.
  [EnableIf=is_mac]
struct CompositorDisplayLinkParams {
  pending_receiver<ExternalBeginFrameController>?
      external_begin_frame_controller;

  pending_remote<ExternalBeginFrameControllerClient>?
      external_begin_frame_controller_client;
};