Introduce DisplayCompositor Mojo API for Mus

components/mus/public/interfaces/display_compositor.mojom

Index: components/mus/public/interfaces/display_compositor.mojom
diff --git a/components/mus/public/interfaces/display_compositor.mojom b/components/mus/public/interfaces/display_compositor.mojom
new file mode 100644
index 0000000000000000000000000000000000000000..88a89602abbf576b59b90c55dced37bf0bdc928d
--- /dev/null
+++ b/components/mus/public/interfaces/display_compositor.mojom
@@ -0,0 +1,92 @@
+// Copyright 2016 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.
+
+module mus.mojom;
+
+import "components/mus/public/interfaces/compositor_frame.mojom";
+
+// Indicates whether the submitted CompositorFrame has been drawn to the display
+// or has been skipped (e.g. another frame may have been submitted before
+// vblank).
+enum CompositorFrameDrawStatus {
+  DRAW_SKIPPED,
+  DRAWN
+};
+
+// A CompositorFrameSinkFactory represents a single Display client.
+// The client (a process) can use this interface to create
+// CompositorFrameSinks.
+// TODO(fsamuel): This needs a better name.
+interface CompositorFrameSinkFactory {
+  // Requests a CompositorFrameSink interface from the display compositor.
+  // A CompositorFrameSink has an associated ID consisting of three components:
+  // 1. Namespace picked by the service associated with this
+  //    CompositorFrameSinkFactory
+  // 2. |local_id| which is a monotonically increasing ID allocated by the
+  //    client.
+  // 3. |nonce| is a cryptographically secure random number making this Sink

[rjkroege, 2016/05/25 19:14:20]

the client picks the nonce? Clients can lie. Should mus be providing the nonce?

[Fady Samuel, 2016/05/25 21:55:34]

Privileged clients will pick a cryptographically secure number. If a bad client
wishes to be embedded so be it. The goal here is for one client to bike an
unguessable id so that another client cannot embed it.

+  //    unguessable by other clients.
+  CreateCompositorFrameSink(uint32 local_id,
+                            uint64 nonce,
+                            CompositorFrameSink& sink,
+                            CompositorFrameSinkClient client);
+};
+
+// A CompositorFrameSink is an interface for receiving CompositorFrame structs.
+// A CompositorFrame contains the complete output meant for display. Each time a
+// client has a graphical update, and receives an OnBeginFrame, it is
+// responsible for creating a CompositorFrame to update its portion of the
+// screen.
+interface CompositorFrameSink {
+  // After the submitted frame is either drawn for the first time by the display
+  // compositor or discarded, the callback will be called with the status of the
+  // submitted frame. Clients should use this acknowledgement to ratelimit frame
+  // submissions.

[rjkroege, 2016/05/25 19:14:19]

Why would the CompositorFrame be discarded?

[Fady Samuel, 2016/05/25 21:55:34]

If the client is submitting frames faster than the display is ticking.

+  SubmitCompositorFrame(CompositorFrame frame) =>
+      (CompositorFrameDrawStatus status);
+
+  // Lets the display compositor know that the client wishes to receive the next
+  // BeginFrame event.
+  SetNeedsBeginFrame(bool needs_begin_frame);
+
+  // TODO(fsamuel): ReadbackBitmap API would be useful here.
+};
+
+interface CompositorFrameSinkClient {
+  ReturnResources(array<ReturnedResource> resources);
+};
+
+// This is a public interface implemented by Display clients.
+interface DisplayClient {

[rjkroege, 2016/05/25 19:14:20]

If only musws get OnRootClientCreated, why is this part of the same interface? A
!ws client would never get OnRootClientCreated?

If so, the interface should be separate yes?

Moreover, the manifest file structure would suggest that the WS API be in a
different mojom from the general client?

[Fady Samuel, 2016/05/25 21:55:34]

Things like OnBeginFrame would overlap. I don't want to create two interfaces
when the concept of a "DisplayClient" is universal.

+  // The Mus Window Server is a root client, and so it will receive this
+  // callback. There can only be one root CompositorFrameSink per Display and so
+  // it does not get a CompositorFrameSinkFactory.
+  OnRootClientCreated(CompositorFrameSink sink,
+                      CompositorFrameSinkClient& client);
+
+  // Non-root clients will receive this callback. Clients can create
+  // CompositorFrameSinks via the provided |factory|.
+  OnClientCreated(uint32 client_id, CompositorFrameSinkFactory factory);

[rjkroege, 2016/05/25 19:14:20]

question for my education: mojom maps uint32 to uint32_t in C++?

[Fady Samuel, 2016/05/25 21:55:34]

Yes.

+
+  // TODO(fsamuel): Add BeginFrameArgs.
+  // See cc/output/begin_frame_args.h.

[rjkroege, 2016/05/25 19:14:20]

words to the effect of "OnBeginFrame needs to take a BeginFrameArgs instance per
cc/output/begin_frame_args.h" would make your intent even clearer.

[Fady Samuel, 2016/05/25 21:55:34]

Acknowledged.

+  OnBeginFrame();
+};
+
+// This is a privileged API to be used only by the Mus Window Server.
+// There is one Display per accelerated widget. This corresponds to a physical
+// display on Chrome OS, and a window on other Chrome platforms.
+interface Display {
+  // Each client (process) has a unique |client_id| and implements the
+  // DisplayClient interface.
+  CreateClient(uint32 client_id, DisplayClient& client);

[rjkroege, 2016/05/25 19:14:20]

bike-shedding: CreateRootClient or CreateWindowTreeClient?

[Fady Samuel, 2016/05/25 21:55:34]

This does not create a root client and it should not know about the window tree.

Maybe CreateDisplayClient?

+};
+
+// This is a privileged API to be used only by the Mus Window Server.
+// There should be only one DisplayCompositor connection.
+interface DisplayCompositor {
+  CreateDisplay(int32 accelerated_widget,
+                Display& display,
+                DisplayClient client);
+};