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..9a271bec6ecbfd6257090514d2a24ec743398bbe
--- /dev/null
+++ b/components/mus/public/interfaces/display_compositor.mojom
@@ -0,0 +1,86 @@
+// 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.

[rjkroege, 2016/05/19 22:08:37]

I thought you were renaming the CFSF to DisplayCompositor?

[Fady Samuel, 2016/05/25 12:37:00]

I needed to separate privileged API and unprivileged API so I couldn't make that
work. I'm sure we'll end up renaming everything a few times. I'd like to get the
plumbing done first then we can rework naming.

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

please indicate very precisely which interfaces are for all and which are only
for mus-ws.

+// The client (a process) can use this interface to create
+// CompositorFrameSinks.
+// TODO(fsamuel): This needs a better name.
+interface CompositorFrameSinkFactory {
+  CreateCompositorFrameSink(int32 id,

[rjkroege, 2016/05/19 22:08:37]

document the arguments.

[Fady Samuel, 2016/05/25 12:37:01]

Done.

+                            CompositorFrameSink& sink,
+                            CompositorFrameSinkClient client);
+};
+
+// A CompositorFrameSink is an interface for receiving CompositorFrame structs.
+// A CompositorFrame contains the complete output meant for display.

[rjkroege, 2016/05/19 22:08:37]

Please say how a CFS is going to be used? Remember that these mojom are an
interface boundary

[Fady Samuel, 2016/05/25 12:37:00]

Done.

+interface CompositorFrameSink {
+  // After the submitted frame is drawn for the first time, the receiver will
+  // respond to the SubmitFrame message. Clients should use this acknowledgement
+  // to ratelimit frame submissions.
+  SubmitCompositorFrame(CompositorFrame frame) =>

[rjkroege, 2016/05/19 22:08:37]

How does the client provide its async callback to receive status? When does the
ack arrive? Perhaps the ack should be part of the CompositorFrameSinkClient? The
callback should perhaps include the CF

[Fady Samuel, 2016/05/25 12:37:00]

I don't think that makes sense. This callback will be used by the outputsurface
I believe. It could indeed live on the client interface, but it doesn't have to
I think. I don't think there are any compelling reasons to go one way or
another. I'll stick with this for now, and add more comments.

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

OK
I however believe that the ack should specify (in some way) which
CompositorFrame the ack is for -- I could easily imagine a situation where the
client has many CFs in flight -- e.g. blimp.

+      (CompositorFrameDrawStatus status);
+
+  // Lets the display know that the client wishes to receive the next

[rjkroege, 2016/05/19 22:08:37]

Display is ambiguous. Indicate what kind of display you mean.

[Fady Samuel, 2016/05/25 12:37:00]

Done.

+  // BeginFrame event.
+  SetNeedsBeginFrame(bool needs_begin_frame);

[Fady Samuel, 2016/05/19 15:17:42]

ReadbackBitmap API makes sense here.

[rjkroege, 2016/05/19 22:08:37]

add a TODO for it?

[Fady Samuel, 2016/05/25 12:37:00]

Done.

+};
+
+interface CompositorFrameSinkClient {
+  ReturnResources(array<ReturnedResource> resources);
+};
+
+// This is a public interface implemented by Display clients.

[rjkroege, 2016/05/19 22:08:37]

Only the window server will ever be a DisplayClient? Can you say this?

[Fady Samuel, 2016/05/25 12:37:00]

That is not the case. All things that talk to the Display are DisplayClients
even unprivileged clients.

There are two callbacks: "OnRootClientCreated" which only the window server gets
and "OnClientCreated" which non-root clients get.

+interface DisplayClient {
+  // 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(int32 client_id, CompositorFrameSinkFactory factory);
+
+  // TODO(fsamuel): Add BeginFrameArgs.

[rjkroege, 2016/05/19 22:08:37]

what did you have in mind?

[Fady Samuel, 2016/05/25 12:37:00]

See cc/output/begin_frame_args.h. I added a comment.

+  OnBeginFrame();
+};
+
+// This is a privileged API to be used only by the Mus Window Server.
+// There is one Display per physical display on Chrome OS,

[rjkroege, 2016/05/19 22:08:37]

is there an 1-1 correspondence between Display, PlatformWindow, accelerated
widget? If so, say so

[Fady Samuel, 2016/05/25 12:37:00]

Done.

+// and per window on other Chrome platforms.
+interface Display {
+  // Each client (process) has a unique |client_id| and implements the
+  // DisplayClient interface.
+  CreateClient(int32 client_id, DisplayClient& client);

[Fady Samuel, 2016/05/19 03:16:34]

The more I think about this, the more I think the signature of CreateClient
should be this:

CreateClient(int32 parent_id, int32 client_id, DisplayClient& client);

This API will only be used for non-root clients, and non-root clients need to
have a parent to be displayable. For top-level windows in Mus+Ash, the parent_id
will always be 0 (or whatever we use to represent the root display client).

[Fady Samuel, 2016/05/25 12:37:00]

Now that the security issue has been resolved here:
https://codereview.chromium.org/1996783002/ we can keep this API simple.

+
+  // Tells the Display that the DisplayClient |parent_id| can embed any
+  // CompositorFrameSink created by DisplayClient |client_id| or its
+  // descendants.
+  AddClient(int32 parent_id, int32 client_id);
+
+  // Tells the Display that the DisplayClient |parent_id| can no longer embed
+  // DisplayClient |child_id| or its descendants, unless they're explicitly
+  // allowed.
+  RemoveClient(int32 parent_id, int32 child_id);
+};
+
+// 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);
+};