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 "mojo/public/mojom/base/unguessable_token.mojom";
import "gpu/ipc/common/surface_handle.mojom";
import "mojo/public/mojom/base/time.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/frame_sink_video_capture.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/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/hit_test/aggregated_hit_test_region.mojom";
import "services/viz/public/mojom/compositing/copy_output_result.mojom";
import "services/viz/public/mojom/compositing/video_detector_observer.mojom";
import "third_party/blink/public/mojom/tokens/tokens.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;

  [EnableIf=is_android]
  float refresh_rate;

  [EnableIf=is_win]
  bool set_present_duration_allowed = false;

  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;
};

// Response from StopFrameCounting that contains counted frames for all frame
// sinks during the tracked time window.
struct FrameCountingData {
  array<FrameCountingPerSinkData> per_sink_data;
};

// Container for collected data for a given frame sink.
struct FrameCountingPerSinkData {
  CompositorFrameSinkType type;
  bool is_root;
  string debug_label;

  // Bucket index of the first bucket in `presented_frames` based on the
  // timestamp of the first presented frame in the bucket and start time.
  uint16 start_bucket;

  // Collected number of presented frames for the specified bucket size.
  array<uint16> presented_frames;
};

// 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.
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);

  // 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.
  CreateCompositorFrameSink(
      FrameSinkId frame_sink_id,
      FrameSinkBundleId? bundle_id,
      pending_receiver<CompositorFrameSink> compositor_frame_sink,
      pending_remote<CompositorFrameSinkClient> compositor_frame_sink_client);

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

  // 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`.
  RequestCopyOfOutput(SurfaceId surface_id, CopyOutputRequest request,
                      bool capture_exact_surface_id);


  // 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.
  CacheBackBuffer(uint32 cache_id, FrameSinkId root_frame_sink_id);

  [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);

  // Starts frame counting per frame sink on the Viz thread.
  StartFrameCountingForTest(mojo_base.mojom.TimeTicks start_time,
                            mojo_base.mojom.TimeDelta bucket_size);

  // Stops frame counting on the Viz thread and returns all records to the
  // caller.
  StopFrameCountingForTest() => (FrameCountingData? data);

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

  // Returns true if there are any unclaimed ViewTransition resources. For
  // testing only.
  [Sync]
  HasUnclaimedViewTransitionResourcesForTest() => (bool has_resources);
};

// 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
  );
};