Merge lp:~kdub/mir/RFC-surface-arrangements into lp:mir

[Kevin DuBois]

do not land.

Just a RFC branch!

In looking at how to bypass nested servers, it seemed useful that advanced clients (such as a multi-windowed client, a OS virtualizer, or a nested mir server) need a way to specify the ordering of the surfaces that they have created. This obviously has to be done within the SurfaceSpecs to prevent violating the policies the shell has (eg, you can't lower a tooltip beneath your primary surface), but normal surfaces should be arrangeable as the client wishes.

This version has the arrangement done batched together (so multiple changes are applied to the SurfaceStack at once), but I suppose some clients might not care that the arrangement updates are batched.

Also, the arrangement only applies to the surfaces in client's connection, the client neither sets an absolute x,y position, nor an absolute z-ordering.

I got to the point of writing a failing acceptance test for this feature when I thought I'd gather some comments on the client api change.

[Kevin DuBois (kdub)]

Just an RFC on an unimplemented client api change. Resubmit after implementation.

review: Needs Resubmitting

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:2436
http://jenkins.qa.ubuntu.com/job/mir-ci/3403/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-vivid-i386-build/1875
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-vivid-amd64-build/1874/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-vivid-touch/1825
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-vivid-amd64-ci/1400/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/1825
        deb: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-builder-vivid-armhf/1825/artifact/work/output/*zip*/output.zip

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-ci/3403/rebuild

review: Needs Fixing (continuous-integration)

[Daniel van Vugt (vanvugt)]

(0) I've proposed an attribute batching API that will probably land soon and might be helpful. Check it out:
https://code.launchpad.net/~vanvugt/mir/rename-api/+merge/252864

Using that you could put relative ordering preferences of child surfaces in their MirSurfaceSpec instead. Which I think makes more sense.

(1) I think "order" is a more widely understood term than "arrangement" here. But also think the functions should be different in other ways than just name. See (0).

Instead, child surfaces could have an "int child_depth". Then their final Z-order is determined by (a) the depth of the parent surface within the main stack, plus (b) their relative int child_depth.

review: Needs Fixing

[Alan Griffiths (alan-griffiths)]

*Discussion*

I think this only addresses a part of a range of problems and would like to be sure that we have a consistent solution. As Daniel mentions, the stacking order of surfaces should be part of the problem domain here (at least to the extent that a client can e.g. "raise" some of its surfaces). We should also allow a client to shift the focus (or default focus) to a specific surface.

As proposed, this is making requests for a specific action without sufficient semantic content for the server to implement good alternative behavior if the request can't be met in full: if a window encounters an edge to the display should it overlap, resize or have an adjusted position?

Specifying top-left locations of surfaces seems like a simplistic layout rule. We should consider the existing solution domain of layout managers and, at least /consider/, allowing the specification of anchors, insets, fills, weights, etc.

review: Needs Information

[Alan Griffiths (alan-griffiths)]

> Specifying top-left locations of surfaces seems like a simplistic layout rule.
> We should consider the existing solution domain of layout managers and, at
> least /consider/, allowing the specification of anchors, insets, fills,
> weights, etc.

I'm not saying we can't do something adequate for now and evolve a more complex solution as needed, but that the current proposal is too specific to facilitate that evolution.

[Kevin DuBois (kdub)]

0) The batching api looks like it could be helpful in making sure that changes are applied at once. Packing the z-order into the MirSurfaceSpec might be more uniform, although I did not see a way to change the z order or the position once the surface was created.
1) I did consider specifying an int-depth as an attribute, but that seemed like additional processing for us, when the client is really just trying to establish a list of its surfaces. Also, if you have 2 surfaces at z-depth 4 and 5, and want 3rd surface in between, the client has to reassign one of the surfaces to fit that surface where they want (which seemed a bit easier to do if its just an array). A list or an array also eliminates the corner case of two surfaces at the same level that we'd have to check for.

I guess the other thing to point out is that I put this as a mir_connection_ function to avoid the idea of parent/child surfaces. It seems more flexible to just have a collection of surfaces ordered by the client in the way it prefers (while still sticking to our policies)

[Kevin DuBois (kdub)]

> I think this only addresses a part of a range of problems and would like to be
> sure that we have a consistent solution. As Daniel mentions, the stacking
> order of surfaces should be part of the problem domain here (at least to the
> extent that a client can e.g. "raise" some of its surfaces). We should also
> allow a client to shift the focus (or default focus) to a specific surface.

So the intent here is to let the client specify its own surface ordering, we're making no guarantees about what the final z-order or position the surface will be presented in on-screen. Its more that we're guaranteeing the client that their surfaces will be composited in a specific way amongst themselves.

>
> As proposed, this is making requests for a specific action without sufficient
> semantic content for the server to implement good alternative behavior if the
> request can't be met in full: if a window encounters an edge to the display
> should it overlap, resize or have an adjusted position?

I don't know that we want to reinterpret what the client has said it wants to do... If it violates our window policies, we'll reject the request. (or perhaps I've misunderstood the point)

>
> Specifying top-left locations of surfaces seems like a simplistic layout rule.
> We should consider the existing solution domain of layout managers and, at
> least /consider/, allowing the specification of anchors, insets, fills,
> weights, etc.

I'm interested in being able to represent a SceneElementSequence-like specification of the composition that the client wants, although don't mind further expansion.

[Andreas Pokorny (andreas-pokorny)]

> Specifying top-left locations of surfaces seems like a simplistic layout rule.
> We should consider the existing solution domain of layout managers and, at
> least /consider/, allowing the specification of anchors, insets, fills,
> weights, etc.

I think we need to distinguish between surfaces and renderbuffers/scenelements here. What you wrote would be true for forwarding surfaces...

I do not think this is part of the problem to be solved (at least for now). A solution is needed that allows a nested server to forward all information necessary to allow the hosting server to draw the scene as if the nested server did the composition. At the moment and in the near future the super set of our efficient drawing operations (hwc + setting a scan out buffer + atomic planes) is what DefaultDisplayBufferCompositor implements. Hence the nested server has to submit the information a DefaultDisplayBufferCompositor needs for rendering. Thus a sequence of Renderables (i think we can ignore the Decoration accessor in SceneElement for that, and also put aside the oddness around the semantics Renderable::transformation() vs Renderable::screen_position()).

Still the idea of forwarding surfaces could be interesting too.

[Andreas Pokorny (andreas-pokorny)]

PS: oops hit save comment too soon.

So I see two different cases, a nested server should be allowed to forward surfaces as surfaces. That would nicely fulfill the case of the OS virtualizer, forwarding all windows of the guest system to the host system, hence the host is supposed to do all the window management and dispatch logic. In that case the nested server creates a surface at the host server for each client surfaces, and relays changes between those.

The other topic is that a nested server should be able to just relay all Renderable changes within the scene and buffer changes to the host server. So as a result a Surface then HasA sequence of Renderables.

[Andreas Pokorny (andreas-pokorny)]

Back to the nested bypass: On the client maybe:

MirBufferStreamAttachment* mir_surface_create_buffer_stream_attachment(MirSurface*, MirBufferStream*, int relative_pos_x, int relative_pos_y, float* transformation?, float opacity);

and respective setters, and a mir_surface_submit_buffer_stream_changes that sends all pending changes in a single batch. Or make that more generic mir_surfae_submit_changes?

[Chris Halse Rogers (raof)]

So, relevant prior art here is:
http://cgit.freedesktop.org/wayland/wayland/tree/protocol/wayland.xml#n1994 (for the purposes of that section, wl_surface == MirBufferStream, wl_surface.commit == mir_buffer_stream_swap_buffers)

The API contains the three obvious things - set_position, place_above, place_below - but also the non-obvious but important set_sync/set_desync. This serves two purposes - one is to batch up changes into a transaction, which we can easily satisfy by other means, the other is to ensure that the surface content of the whole subsurface tree is consistent.

When in synchronised mode, swap_buffers in all the subsurfaces is deferred until the parent surface enters swap_buffers; this ensures that the client can change the subsurface graph without flashing or components transiently moving out of place.

Like Andreas, I think that Surfaces are the wrong level to do this nesting. Surfaces have a whole bunch of semantics that USC simply doesn't care about, and can't do anything sensible with. What happens with input? Does USC generate enter/leave events? Etc.

Since Robert's animated-cursor branch has landed we've got a client API to create a raw BufferStream; What would seem most sensible to me is for this to add the ability to attach extra buffer streams to a surface.

mir_subsurface_position(MirSurface* in, MirBufferStream* to_place, int x, int y);
mir_subsurface_stack_above(MirSurface* in, MirBufferStream* to_raise, MirBufferStream* below);
mir_subsurface_stack_below(MirSurface* in, MirBufferStream* to_lower, MirBufferStream* above);
... etc

Here we never need to reject a (well-formed) subsurface request; as far as the shell is concerned there is only one surface, just with funky content.

[Daniel van Vugt (vanvugt)]

> Specifying top-left locations of surfaces seems like a simplistic layout rule.
> We should consider the existing solution domain of layout managers and, at
> least /consider/, allowing the specification of anchors, insets, fills,
> weights, etc.

That's going way too far down the path of making Mir a full-blown toolkit. Making Mir a toolkit with enforced semantics just makes it less welcoming to supporting actual toolkits with their own semantics.

[Daniel van Vugt (vanvugt)]

If you want a good example of what level of complexity to target this functionality at, have a look at:
  http://tronche.com/gui/x/xlib/window/stacking-order.html

That's _not_ a suggestion for a design, but an example of the level of detail we should be considering.

[Alan Griffiths (alan-griffiths)]

> > I think this only addresses a part of a range of problems and would like to
> be
> > sure that we have a consistent solution. As Daniel mentions, the stacking
> > order of surfaces should be part of the problem domain here (at least to the
> > extent that a client can e.g. "raise" some of its surfaces). We should also
> > allow a client to shift the focus (or default focus) to a specific surface.
>
> So the intent here is to let the client specify its own surface ordering,
> we're making no guarantees about what the final z-order or position the
> surface will be presented in on-screen. Its more that we're guaranteeing the
> client that their surfaces will be composited in a specific way amongst
> themselves.

I think the use case of "raise these surfaces and direct input towards this one" needs more explicit support than having to list all surfaces.

> > As proposed, this is making requests for a specific action without
> sufficient
> > semantic content for the server to implement good alternative behavior if
> the
> > request can't be met in full: if a window encounters an edge to the display
> > should it overlap, resize or have an adjusted position?
>
> I don't know that we want to reinterpret what the client has said it wants to
> do... If it violates our window policies, we'll reject the request. (or
> perhaps I've misunderstood the point)

The general approach we've taken with other requests is that the client makes a request and the server decided what to do and (mostly) tells the client that something happened.

But in the case of positioning the client doesn't know what it has to work with:

  o if a surface has a "snapped" border that limits its positioning.
  o The client is not informed when surfaces are moved by the user.
  o The client usually has no indication which screen(s) its surfaces are on.
  o if the WM is doing tiling there's no information on current tile size.

So, unless we provide more information to the client it can't always determine the perfect layout. Allowing the server the flexibility to make a "best effort" is consistent with other APIs.

[Kevin DuBois (kdub)]

Yay, the rfc is working (and has generated comments)!

With the client api structuring... (MirConnections have MirSurfaces, etc)
We currently have MirConnections have multiple MirSurfaces, and MirConnections have a single MirBufferStream. I didn't quite see why MirConnections with multiple MirSurfaces, each with multiple BufferStreams is better than keeping the structure that we have.

I think we're all pointing out that some sort of batching of position updates is needed if the client is to request arrangements of its own surfaces. The start of the batching work in Daniel's rename-api branch seems like a sensible starting point. The other suggestion seems to be the one in this original rfc (which seems to underpowered), and the suggestion in the wayland subsurface protocol of having a 'synced' and 'unsynced' surface. I don't know that we need swaps to batch with positioning updates, and I also don't know that we need a 'desynchronized mode'

[Kevin DuBois (kdub)]

> I think the use case of "raise these surfaces and direct input towards this
> one" needs more explicit support than having to list all surfaces.

Fair enough, and I think the rename-api detaches the user from having to list all the surfaces, and it also avoids the wart of "if you don't specify what to do with a surface, the server can do whatever it wants", as the other surfaces wo,uld just keep their state.

[Kevin DuBois (kdub)]

> But in the case of positioning the client doesn't know what it has to work
> with:
>
> o if a surface has a "snapped" border that limits its positioning.
> o The client is not informed when surfaces are moved by the user.
> o The client usually has no indication which screen(s) its surfaces are on.
> o if the WM is doing tiling there's no information on current tile size.

It is somewhat the goal to keep the client from knowing what its absolute final position though, and to mesh the preference the client gives us in terms of the coordinates of 'the clients plane' with the other policies that the window manager wants.

Like, if the client says "surface A at 100, 100, surface B at 200,100" the server won't honor that if it violates some of the rules, or if the user goes and moves the surface otherwise. Maybe the client needs a way to know if its request is being honored (or maybe how its being honored) via the event system so it can sort out what it wants to do.

[Chris Halse Rogers (raof)]

> Yay, the rfc is working (and has generated comments)!
>
> With the client api structuring... (MirConnections have MirSurfaces, etc)
> We currently have MirConnections have multiple MirSurfaces, and MirConnections
> have a single MirBufferStream. I didn't quite see why MirConnections with
> multiple MirSurfaces, each with multiple BufferStreams is better than keeping
> the structure that we have.

I think the idea of letting clients do relative positioning of their own surfaces is a poor one - Alan's raised all sorts of issues with it, and to that I'll add “what happens when a user moves one of the surfaces”?

The MirConnection has zero or more MirSurfaces which have one or more MirBufferStreams arrangement resolves this by providing a layer at which the client is in total control. The shell sees and acts on MirConnections and MirSurfaces, and Mir handles compositing (or not) the MirBufferStreams internally. In this case there's never any need to reject a MirBufferStream request (as long as all the objects it references exist and are valid, of course).

> I think we're all pointing out that some sort of batching of position updates
> is needed if the client is to request arrangements of its own surfaces. The
> start of the batching work in Daniel's rename-api branch seems like a sensible
> starting point. The other suggestion seems to be the one in this original rfc
> (which seems to underpowered), and the suggestion in the wayland subsurface
> protocol of having a 'synced' and 'unsynced' surface. I don't know that we
> need swaps to batch with positioning updates,

The obvious case where you need swaps to batch with positioning updates is when you're not drawing anything behind the overlaying surface. When you move the overlaying surface you need the underlay to be updated on the same frame as the move, otherwise you see bits of the unrendered area.

> and I also don't know that we need a 'desynchronized mode'

We don't, really. It's basically a client-courtesy-optimisation, where if you *don't* need frame-accurate moving etc you don't have to continually swap buffers on your main surface.

[Robert Carr (robertcarr)]

>> I think the idea of letting clients do relative positioning of their own surfaces is a poor >> one - Alan's raised all sorts of issues with it, and to that I'll add “what happens when a >> user moves one of the surfaces”?

>> The MirConnection has zero or more MirSurfaces which have one or more MirBufferStreams
>> arrangement resolves this by providing a layer at which the client is in total control. The >> shell sees and acts on MirConnections and MirSurfaces, and Mir handles compositing (or not) >> the MirBufferStreams internally.

+1

[Chris Halse Rogers (raof)]

54 +/** Specify the position of the stream within the surface. This establishes
55 + * positions relative to the other streams in the surface, and is not a
56 + * guarantee of the final composited ons

You appear to have garbled a comment here ☺. I'm not sure if what the comment says is right; we *should* be able to say that the relative position is guaranteed to be correct, but we guarantee nothing about the position of (0,0) onscreen.

This does raise the question of whether or not we want to clip streams to the parent surface; Wayland doesn't for subsurfaces, and I think GTK uses this for tooltips and such. That said, we know how to position tooltips and such better than the toolkit, so they shouldn't really be using it for this purpose.

I don't know if we should clip to the parent window or not; whichever way we go, we should document and test it, though.

This otherwise looks like sensible API to me. I do think we'll need at least an optional synchronise-on-swap_buffers mode, though.

=== modified file 'include/client/mir_toolkit/mir_surface.h'
--- include/client/mir_toolkit/mir_surface.h	2015-03-31 02:35:42 +0000
+++ include/client/mir_toolkit/mir_surface.h	2015-04-01 19:59:57 +0000
@@ -577,10 +577,88 @@
  * Change the title (name) of a surface.
  *   \param [in] surface  The surface to rename
  *   \param [in] name     The new name
- *   \returns             When the change has completed
+ *   \return              When the change has completed
  */
 MirWaitHandle* mir_surface_set_title(MirSurface* surf, char const* name);
 
+
+/** generate a batch of changes to apply to the surface via
+ *  mir_surface_spec_commit_changes. The returned spec must be released with
+ *  mir_surface_spec_release;
+ *  \param [in] surface  The surface the changes will take effect on
+ *  \return              A wait handle that can be passed to mir_wait_for
+ */
+MirSurfaceSpec* mir_surface_begin_changes(MirSurface* surface);
+
+/** Commit the changes accummulated in the MirSurfaceSpect to the surface
+ * \param [in] spec  The spec to apply
+ * \return           A wait handle that is
+ */
+MirWaitHandle* mir_surface_spec_commit_changes(MirSurfaceSpec* spec);
+
+/** rearrange the ordering of the buffer streams in the connection, placing
+ *  stream_to_place above stream_below. If stream_to_place is not associated
+ *  the surface, it will become associated with the surface. If it is already
+ *  in the ordering of the surface, it will be removed from its current position
+ *  and placed in the requested position.
+ *
+ *  Associated buffer streams are not owned by the surface and still must be
+ *  released.
+ *
+ *  \param [in] spec  The spec to accumulate the request in
+ *  \param [in] stream_to_place The stream to place
+ *  \param [in] reference_stream The stream which will be above stream_to_place
+ */
+void mir_surface_spec_place_buffer_stream_below(
+    MirSurfaceSpec* spec, MirBufferStream* stream_to_place, MirBufferStream* reference_stream);
+
+/** Same as mir_surface_spec_place_buffer_stream_below, except placing stream_to_place
+ *  below reference_stream.
+ *
+ *  \param [in] spec  The spec to accumulate the request in
+ *  \param [in] stream_to_place The stream to place
+ *  \param [in] reference_stream The stream which will be below stream_to_place
+ */
+void mir_surface_spec_place_buffer_stream_above(
+    MirSurfaceSpec* spec, MirBufferStream* stream_to_place, MirBufferStream* reference_stream);
+
+/** Specify the position of the stream within the surface. This establishes
+ *  positions relative to the other streams in the surface, and is not a
+ *  guarantee of the final composited ons
+ *
+ *  If stream_to_place is not associated the surface yet, it will become
+ *  associated with the surface at the given position.
+ *
+ *  Associated buffer streams are not owned by the surface and still must be
+ *  released.
+ *
+ *  \param [in] spec  The spec to accumulate the request in
+ *  \param [in] stream_to_move  The stream to movee
+ *  \param [in] x  The x coordinate of the stream
+ *  \param [in] y  The x coordinate of the stream
+ */
+void mir_surface_spec_place_buffer_stream_position(
+    MirSurfaceSpec* spec, MirBufferStream* stream_to_move, int x, int y);
+
+/* Returns the number of streams currently associated with surface
+ *  \param [in] surface  A surface
+ *  \return              The number of streams associated with surface
+ */
+unsigned int mir_surface_get_number_of_streams(MirSurface* surface);
+
+/* Query the streams associated with this surface and their positions.
+ * streams and positions must have the size of num_streams.
+ * streams and positions are filled in their z-order. (with is streams[0]
+ * being the bottom-most surface)
+ *
+ *  \param [in] surface  The surface to query
+ *  \param [out] streams An array of MirBufferStream* that is of size num_streams
+ *  \param [out] positions An array of MirRectangles that is of size num_streams
+ *  \param [in] num_streams The size of both positions and streams array
+ */
+void mir_surface_get_streams(
+    MirSurface* surface, MirBufferStream** streams, MirRectangle* positions, unsigned int num_streams);
+
 #ifdef __cplusplus
 }
 /**@}*/
 
=== modified file 'include/server/mir/compositor/scene_element.h'
--- include/server/mir/compositor/scene_element.h	2015-03-31 02:35:42 +0000
+++ include/server/mir/compositor/scene_element.h	2015-04-01 19:59:57 +0000
@@ -19,7 +19,6 @@
 #ifndef MIR_COMPOSITOR_SCENE_ELEMENT_H_
 #define MIR_COMPOSITOR_SCENE_ELEMENT_H_
 
-#include "mir/compositor/decoration.h"
 #include <memory>
 
 namespace mir
@@ -30,7 +29,7 @@
 }
 namespace compositor
 {
-
+class Decoration;
 class SceneElement
 {
 public:
@@ -40,11 +39,9 @@
     virtual void rendered() = 0;
     virtual void occluded() = 0;
 
-    virtual Decoration const& decoration() const
-    {
-        static const Decoration none;
-        return none;
-    }
+    //TODO: Decoration is opaque on purpose. It is only used by an internal example,
+    //      and this function should be removed from the public API.
+    virtual std::unique_ptr<Decoration> decoration() const = 0; 
 
 protected:
     SceneElement() = default;
 
=== modified file 'playground/demo-shell/demo_compositor.cpp'
--- playground/demo-shell/demo_compositor.cpp	2015-03-31 02:35:42 +0000
+++ playground/demo-shell/demo_compositor.cpp	2015-04-01 19:59:57 +0000
@@ -83,8 +83,8 @@
         auto embellished = renderer.would_embellish(*renderable, viewport);
         auto any_part_drawn = (viewport.overlaps(renderable->screen_position()) || embellished);
         
-        if (auto const& decor = it->decoration())
-            decorated[renderable->id()] = decor;
+        if (auto decor = it->decoration())
+            decorated[renderable->id()] = std::move(decor);
         if (any_part_drawn)
         {
             renderable_list.push_back(renderable);
 
=== modified file 'playground/demo-shell/demo_renderer.cpp'
--- playground/demo-shell/demo_renderer.cpp	2015-03-31 02:35:42 +0000
+++ playground/demo-shell/demo_renderer.cpp	2015-04-01 19:59:57 +0000
@@ -221,7 +221,7 @@
 
 void DemoRenderer::begin(DecorMap&& d) const
 {
-    decor_map = d;
+    decor_map = std::move(d);
     title_cache.drop_unused();
     title_cache.mark_all_unused();
 }
@@ -236,7 +236,7 @@
         auto& decor = d->second;
         tessellate_shadow(primitives, renderable, shadow_radius);
         tessellate_frame(primitives, renderable, titlebar_height,
-                         decor.name.c_str());
+                         decor->name.c_str());
     }
 }
 
 
=== modified file 'playground/demo-shell/demo_renderer.h'
--- playground/demo-shell/demo_renderer.h	2015-03-31 02:35:42 +0000
+++ playground/demo-shell/demo_renderer.h	2015-04-01 19:59:57 +0000
@@ -39,7 +39,7 @@
 };
 
 typedef std::unordered_map<graphics::Renderable::ID,
-                           compositor::Decoration> DecorMap;
+                           std::unique_ptr<compositor::Decoration>> DecorMap;
 
 class DemoRenderer : public compositor::GLRenderer
 {
 
=== modified file 'src/client/mir_surface_api.cpp'
--- src/client/mir_surface_api.cpp	2015-03-31 02:35:42 +0000
+++ src/client/mir_surface_api.cpp	2015-04-01 19:59:57 +0000
@@ -580,8 +580,6 @@
     return nullptr;
 }
 
-namespace { // Private for now. TODO: Finalize and publish later (LP: #1422522)
-
 MirSurfaceSpec* mir_surface_begin_changes(MirSurface* surf)
 {
     mir::require(mir_surface_is_valid(surf));
@@ -608,8 +606,6 @@
     return surface->modify(*spec);
 }
 
-} // Private namespace. TODO: finalize morphing API and publish.
-
 MirWaitHandle* mir_surface_set_title(MirSurface* surf, char const* name)
 {
     MirWaitHandle* result = nullptr;
@@ -621,3 +617,34 @@
     }
     return result;
 }
+
+void mir_surface_spec_place_buffer_stream_below(
+    MirSurfaceSpec* spec, MirBufferStream* stream_to_place, MirBufferStream* reference_stream)
+{
+    (void) spec;
+    (void) stream_to_place;
+    (void) reference_stream;
+}
+
+void mir_surface_spec_place_buffer_stream_position(
+    MirSurfaceSpec* spec, MirBufferStream* stream_to_move, int x, int y)
+{
+    (void) spec;
+    (void) stream_to_move;
+    (void) x;
+    (void) y;
+}
+
+unsigned int mir_surface_get_number_of_streams(MirSurface*)
+{
+    return 1;
+}
+
+void mir_surface_get_streams(
+    MirSurface* surface, MirBufferStream** streams, MirRectangle* positions, unsigned int num_streams)
+{
+    (void) surface;
+    (void) streams;
+    (void) positions;
+    (void) num_streams;
+}
 
=== renamed file 'include/server/mir/compositor/decoration.h' => 'src/include/server/mir/compositor/decoration.h'
=== modified file 'src/server/scene/surface_stack.cpp'
--- src/server/scene/surface_stack.cpp	2015-03-31 02:35:42 +0000
+++ src/server/scene/surface_stack.cpp	2015-04-01 19:59:57 +0000
@@ -23,6 +23,7 @@
 #include "mir/scene/surface.h"
 #include "mir/scene/scene_report.h"
 #include "mir/compositor/scene_element.h"
+#include "mir/compositor/decoration.h"
 #include "mir/graphics/renderable.h"
 
 #include <boost/throw_exception.hpp>
@@ -52,7 +53,7 @@
         : renderable_{surface->compositor_snapshot(id)},
           tracker{tracker},
           cid{id},
-          decor(mc::Decoration::Type::surface, surface->name())
+          surface_name(surface->name())
     {
     }
 
@@ -71,16 +72,16 @@
         tracker->occluded_in(cid);
     }
 
-    mc::Decoration const& decoration() const override
+    std::unique_ptr<mc::Decoration> decoration() const override
     {
-        return decor;
+        return std::make_unique<mc::Decoration>(mc::Decoration::Type::surface, surface_name);
     }
 
 private:
     std::shared_ptr<mg::Renderable> const renderable_;
     std::shared_ptr<ms::RenderingTracker> const tracker;
     mc::CompositorID cid;
-    mc::Decoration const decor;
+    std::string const surface_name;
 };
 
 //note: something different than a 2D/HWC overlay
@@ -106,6 +107,11 @@
     {
     }
 
+    std::unique_ptr<mc::Decoration> decoration() const override
+    {
+        return std::make_unique<mc::Decoration>();
+    }
+
 private:
     std::shared_ptr<mg::Renderable> const renderable_;
 };
 
=== modified file 'tests/acceptance-tests/CMakeLists.txt'
--- tests/acceptance-tests/CMakeLists.txt	2015-03-31 02:35:42 +0000
+++ tests/acceptance-tests/CMakeLists.txt	2015-04-01 19:59:57 +0000
@@ -30,6 +30,7 @@
   test_prompt_session_client_api.cpp
   test_client_screencast.cpp
   test_client_surface_visibility.cpp
+  test_client_surface_arrangement.cpp
   test_client_with_custom_display_config_deadlock.cpp
   test_server_without_active_outputs.cpp
   test_server_startup.cpp
@@ -39,6 +40,7 @@
   test_input_device_hub.cpp
   test_latency.cpp
   test_shell_control_of_surface_configuration.cpp
+  test_render_override.cpp
 )
 
 if (MIR_TEST_PLATFORM STREQUAL "mesa")
 
=== added file 'tests/acceptance-tests/test_client_surface_arrangement.cpp'
--- tests/acceptance-tests/test_client_surface_arrangement.cpp	1970-01-01 00:00:00 +0000
+++ tests/acceptance-tests/test_client_surface_arrangement.cpp	2015-04-01 19:59:57 +0000
@@ -0,0 +1,255 @@
+/*
+ * Copyright © 2015 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Kevin DuBois <[e-mail]>
+ */
+
+#include "mir_toolkit/mir_client_library.h"
+#include "mir_test_framework/connected_client_with_a_surface.h"
+#include "mir/compositor/display_buffer_compositor.h"
+#include "mir/compositor/display_buffer_compositor_factory.h"
+#include "mir/compositor/scene_element.h"
+#include "mir/graphics/renderable.h"
+
+#include <mutex>
+#include <condition_variable>
+#include <stdexcept>
+#include <gtest/gtest.h>
+#include <gmock/gmock.h>
+
+namespace mtf = mir_test_framework;
+namespace geom = mir::geometry;
+namespace mc = mir::compositor;
+namespace mg = mir::graphics;
+namespace
+{
+
+MirPixelFormat an_available_format(MirConnection* connection)
+{
+    using namespace testing;
+    MirPixelFormat format{mir_pixel_format_invalid};
+    unsigned int valid_formats{0};
+    mir_connection_get_available_surface_formats(connection, &format, 1, &valid_formats);
+    return format;
+}
+
+struct Stream
+{
+    Stream(MirBufferStream* stream, geom::Point pt) :
+        stream(stream),
+        pos{pt},
+        needs_release{false}
+    {
+    }
+
+    Stream(MirConnection* connection, geom::Rectangle rect) :
+        stream(mir_connection_create_buffer_stream_sync(
+            connection,
+            rect.size.width.as_int(),
+            rect.size.height.as_int(),
+            an_available_format(connection),
+            mir_buffer_usage_hardware)),
+        pos{rect.top_left},
+        needs_release{true}
+    {
+        mir_buffer_stream_swap_buffers_sync(stream);
+    }
+
+    ~Stream()
+    {
+        if (needs_release)
+            mir_buffer_stream_release_sync(stream);
+    }
+
+    operator MirBufferStream*() const
+    {
+        return stream;
+    }
+
+    geom::Point position()
+    {
+        return pos;
+    }
+
+    Stream(Stream const&) = delete;
+    Stream& operator=(Stream const&) = delete;
+private:
+    MirBufferStream* stream;
+    geom::Point const pos;
+    bool const needs_release;
+};
+
+struct Ordering
+{
+    void note_scene_element_sequence(mc::SceneElementSequence const& sequence)
+    {
+        std::unique_lock<decltype(mutex)> lk(mutex);
+        rectangles.clear();
+        for(auto const& element : sequence)
+            rectangles.emplace_back(element->renderable()->screen_position());
+        post_count++;
+        cv.notify_all();
+    }
+
+    template<typename T, typename S>
+    bool wait_for_another_post_within(std::chrono::duration<T,S> duration)
+    {
+        std::unique_lock<decltype(mutex)> lk(mutex);
+        auto count = post_count + 1;
+        return cv.wait_for(lk, duration, [this, count]{return (post_count >= count);});
+    }
+
+    bool ensure_last_ordering_is_consistent_with(
+        std::vector<MirRectangle> const& arrangement)
+    {
+        if (rectangles.size() != arrangement.size())
+            return false;
+        for(auto i = 0u; i < rectangles.size(); i++)
+        {
+            if ((rectangles[i].top_left.x.as_int() != arrangement[i].left) ||
+                (rectangles[i].top_left.y.as_int() != arrangement[i].top))
+                return false;
+        }
+        return true;
+    }
+private:
+    std::mutex mutex;
+    std::condition_variable cv;
+    unsigned int post_count{0};
+    std::vector<geom::Rectangle> rectangles;
+};
+
+struct OrderTrackingDBC : mc::DisplayBufferCompositor
+{
+    OrderTrackingDBC(
+        std::shared_ptr<mc::DisplayBufferCompositor> const& wrapped,
+        std::shared_ptr<Ordering> const& ordering) :
+        wrapped(wrapped),
+        ordering(ordering)
+    {
+    }
+
+    void composite(mc::SceneElementSequence&& scene_sequence) override
+    {
+        ordering->note_scene_element_sequence(scene_sequence);
+        wrapped->composite(std::move(scene_sequence));
+    }
+
+    std::shared_ptr<mc::DisplayBufferCompositor> const wrapped;
+    std::shared_ptr<Ordering> const ordering;
+};
+
+struct OrderTrackingDBCFactory : mc::DisplayBufferCompositorFactory
+{
+    OrderTrackingDBCFactory(
+        std::shared_ptr<mc::DisplayBufferCompositorFactory> const& wrapped,
+        std::shared_ptr<Ordering> const& ordering) :
+        wrapped(wrapped),
+        ordering(ordering)
+    {
+    }
+
+    std::unique_ptr<mc::DisplayBufferCompositor> create_compositor_for(mg::DisplayBuffer& db) override
+    {
+        return std::make_unique<OrderTrackingDBC>(wrapped->create_compositor_for(db), ordering);
+    }
+
+    std::shared_ptr<OrderTrackingDBC> last_dbc{nullptr};
+    std::shared_ptr<mc::DisplayBufferCompositorFactory> const wrapped;
+    std::shared_ptr<Ordering> const ordering;
+};
+
+struct MirSurfaceArrangements : mtf::ConnectedClientWithASurface
+{
+    void SetUp() override
+    {
+        ordering = std::make_shared<Ordering>();
+        server.wrap_display_buffer_compositor_factory(
+            [this](std::shared_ptr<mc::DisplayBufferCompositorFactory> const& wrapped)
+            {
+                order_tracker = std::make_shared<OrderTrackingDBCFactory>(wrapped, ordering);
+                return order_tracker;
+            });
+
+        ConnectedClientWithASurface::SetUp();
+
+        primary_stream = std::unique_ptr<Stream>(
+            new Stream(mir_surface_get_buffer_stream(surface), geom::Point{0,0}));
+
+        int const additional_streams{3};
+        for(auto i = 0; i < additional_streams; i++)
+        {
+            geom::Size size{30 * i + 1, 40* i + 1};
+            geom::Point position{i * 2, i * 3};
+            streams.emplace_back(std::unique_ptr<Stream>(
+                new Stream(connection, geom::Rectangle{position, size})));
+        }
+    }
+
+    void TearDown() override
+    {
+        streams.clear();
+        ConnectedClientWithASurface::TearDown();
+    }
+
+    std::shared_ptr<Ordering> ordering;
+    std::shared_ptr<OrderTrackingDBCFactory> order_tracker{nullptr};
+    std::unique_ptr<Stream> primary_stream;
+    std::vector<std::unique_ptr<Stream>> streams;
+};
+}
+
+TEST_F(MirSurfaceArrangements, arrangements_are_applied)
+{
+    using namespace testing;
+    MirBufferStream* above_stream = *primary_stream;
+    auto change_spec = mir_surface_begin_changes(surface);
+    for(auto& stream : streams)
+    {
+        mir_surface_spec_place_buffer_stream_below(change_spec, *stream, above_stream);
+        mir_surface_spec_place_buffer_stream_position(
+            change_spec, *stream, stream->position().x.as_int(), stream->position().y.as_int());
+        above_stream = *stream;
+    }
+    mir_wait_for(mir_surface_spec_commit_changes(change_spec));
+    mir_surface_spec_release(change_spec);
+
+    unsigned int num_streams = mir_surface_get_number_of_streams(surface);
+    ASSERT_THAT(num_streams, Eq(streams.size() + 1));
+    std::vector<MirBufferStream*> buffer_streams{num_streams};
+    std::vector<MirRectangle> positions{num_streams};
+    mir_surface_get_streams(surface, buffer_streams.data(), positions.data(), num_streams);
+    for(auto i = 0u; i < num_streams; ++i)
+    {
+        geom::Point pt{positions[i].top, positions[i].left};
+        if (i == 0u)
+        {
+            EXPECT_THAT(buffer_streams[i], Eq(static_cast<MirBufferStream*>(*primary_stream)));
+            EXPECT_THAT(pt, Eq(primary_stream->position()));
+        }
+        else
+        {
+            EXPECT_THAT(buffer_streams[i], Eq(static_cast<MirBufferStream*>(*streams[i-1])));
+            EXPECT_THAT(pt, Eq(streams[i-1]->position()));
+        }
+    }
+
+    //check that the compositor rendered correctly
+    using namespace std::literals::chrono_literals;
+    EXPECT_TRUE(ordering->wait_for_another_post_within(1s))
+         << "timed out waiting for another post";
+    EXPECT_TRUE(ordering->ensure_last_ordering_is_consistent_with(positions))
+         << "surface ordering was not consistent with the client request";
+}
 
=== added file 'tests/acceptance-tests/test_render_override.cpp'
--- tests/acceptance-tests/test_render_override.cpp	1970-01-01 00:00:00 +0000
+++ tests/acceptance-tests/test_render_override.cpp	2015-04-01 19:59:57 +0000
@@ -0,0 +1,130 @@
+/*
+ * Copyright © 2015 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Kevin DuBois <[e-mail]>
+ */
+
+#include "mir_toolkit/mir_client_library.h"
+#include "mir_test_framework/connected_client_with_a_surface.h"
+#include "mir/compositor/display_buffer_compositor.h"
+#include "mir/compositor/display_buffer_compositor_factory.h"
+#include "mir/compositor/scene_element.h"
+#include "mir/compositor/compositor.h"
+#include "mir/graphics/renderable.h"
+
+#include <mutex>
+#include <condition_variable>
+#include <gtest/gtest.h>
+#include <gmock/gmock.h>
+
+namespace mtf = mir_test_framework;
+namespace geom = mir::geometry;
+namespace mc = mir::compositor;
+namespace mg = mir::graphics;
+namespace
+{
+struct size_less
+{
+    bool operator() (geom::Size const& a, geom::Size const& b)
+    {
+        return a.width < b.width && a.height < b.height;
+    }
+};
+
+struct CompositionTracker
+{
+    bool wait_until_surface_is_rendered_with_size(geom::Size sz)
+    {
+        using namespace std::literals::chrono_literals;
+        std::unique_lock<decltype(mutex)> lk(mutex);
+        return cv.wait_for(lk, 4s, [this, sz] {
+            return std::find(rendered_sizes.begin(), rendered_sizes.end(), sz) != rendered_sizes.end();
+        });
+    }
+
+    void surface_rendered_with_size(geom::Size sz)
+    {
+        std::unique_lock<decltype(mutex)> lk(mutex);
+        rendered_sizes.emplace(sz);
+        cv.notify_all();
+    }
+
+private:
+    std::set<geom::Size, size_less> rendered_sizes;
+    std::mutex mutex;
+    std::condition_variable cv;
+};
+
+struct CustomDBC : mc::DisplayBufferCompositor
+{
+    CustomDBC(std::shared_ptr<CompositionTracker> const& tracker) :
+        tracker(tracker)
+    {
+    }
+
+    void composite(mc::SceneElementSequence&& sequence) override
+    {
+        for(auto const& element : sequence)
+        {
+            auto renderable = element->renderable(); 
+            renderable->buffer(); //consume buffer to stop compositor from spinning
+            tracker->surface_rendered_with_size(renderable->screen_position().size);
+        }
+    }
+private:
+    std::shared_ptr<CompositionTracker> const tracker;
+};
+
+struct CustomDBCFactory : mc::DisplayBufferCompositorFactory
+{
+    CustomDBCFactory(std::shared_ptr<CompositionTracker> const& tracker) :
+        tracker(tracker)
+    {
+    }
+ 
+    std::unique_ptr<mc::DisplayBufferCompositor> create_compositor_for(mg::DisplayBuffer&) override
+    {
+        return std::make_unique<CustomDBC>(tracker);
+    }
+private:
+    std::shared_ptr<CompositionTracker> const tracker;
+};
+
+struct DisplayBufferCompositorOverride : mtf::ConnectedClientWithASurface
+{
+    void SetUp() override
+    {
+        using namespace std::literals::chrono_literals;
+        server.override_the_display_buffer_compositor_factory([this]
+        {
+            return std::make_shared<CustomDBCFactory>(tracker);
+        });
+
+        mtf::ConnectedClientWithASurface::SetUp();
+    }
+    void TearDown() override
+    {
+        mtf::ConnectedClientWithASurface::TearDown();
+    }
+protected:
+    std::shared_ptr<CompositionTracker> const tracker{std::make_shared<CompositionTracker>()};
+};
+}
+
+TEST_F(DisplayBufferCompositorOverride, composite_called_with_surface)
+{
+    mir_buffer_stream_swap_buffers_sync(mir_surface_get_buffer_stream(surface));
+    EXPECT_TRUE(tracker->wait_until_surface_is_rendered_with_size({surface_params.width, surface_params.height}));
+}
 
=== modified file 'tests/include/mir_test_doubles/stub_scene_element.h'
--- tests/include/mir_test_doubles/stub_scene_element.h	2015-03-31 02:35:42 +0000
+++ tests/include/mir_test_doubles/stub_scene_element.h	2015-04-01 19:59:57 +0000
@@ -20,6 +20,7 @@
 #define MIR_TEST_DOUBLES_STUB_SCENE_ELEMENT_H_
 
 #include "mir/compositor/scene_element.h"
+#include "mir/compositor/decoration.h"
 #include "stub_renderable.h"
 
 namespace mir
@@ -55,6 +56,11 @@
     {
     }
 
+    std::unique_ptr<compositor::Decoration> decoration() const override
+    {
+        return nullptr;
+    }
+
 private:
     std::shared_ptr<graphics::Renderable> const renderable_;
 };
 
=== modified file 'tests/include/mir_test_framework/connected_client_with_a_surface.h'
--- tests/include/mir_test_framework/connected_client_with_a_surface.h	2014-11-18 16:15:00 +0000
+++ tests/include/mir_test_framework/connected_client_with_a_surface.h	2015-04-01 19:59:57 +0000
@@ -26,6 +26,14 @@
 struct ConnectedClientWithASurface : ConnectedClientHeadlessServer
 {
     MirSurface* surface{nullptr};
+    MirSurfaceParameters const surface_params =
+    {
+        "ConnectedClientWithASurfaceFixtureSurface",
+        640, 480,
+        mir_pixel_format_abgr_8888,
+        mir_buffer_usage_hardware,
+        mir_display_output_id_invalid
+    };
 
     void SetUp() override;
 
 
=== modified file 'tests/mir_test_framework/connected_client_with_a_surface.cpp'
--- tests/mir_test_framework/connected_client_with_a_surface.cpp	2014-11-18 16:15:00 +0000
+++ tests/mir_test_framework/connected_client_with_a_surface.cpp	2015-04-01 19:59:57 +0000
@@ -24,16 +24,7 @@
 {
     ConnectedClientHeadlessServer::SetUp();
 
-    MirSurfaceParameters request_params =
-    {
-        __PRETTY_FUNCTION__,
-        640, 480,
-        mir_pixel_format_abgr_8888,
-        mir_buffer_usage_hardware,
-        mir_display_output_id_invalid
-    };
-
-    surface = mir_connection_create_surface_sync(connection, &request_params);
+    surface = mir_connection_create_surface_sync(connection, &surface_params);
     ASSERT_TRUE(mir_surface_is_valid(surface));
 }
 
 
=== modified file 'tests/unit-tests/compositor/test_default_display_buffer_compositor.cpp'
--- tests/unit-tests/compositor/test_default_display_buffer_compositor.cpp	2015-03-31 02:35:42 +0000
+++ tests/unit-tests/compositor/test_default_display_buffer_compositor.cpp	2015-04-01 19:59:57 +0000
@@ -18,12 +18,14 @@
 
 #include "src/server/compositor/default_display_buffer_compositor.h"
 #include "mir/compositor/display_buffer_compositor.h"
+#include "mir/compositor/decoration.h"
 #include "src/server/report/null_report_factory.h"
 #include "mir/compositor/scene.h"
 #include "mir/compositor/renderer.h"
 #include "mir/geometry/rectangle.h"
 #include "mir_test_doubles/mock_renderer.h"
 #include "mir_test/fake_shared.h"
+#include "mir_test/gmock_fixes.h"
 #include "mir_test_doubles/mock_display_buffer.h"
 #include "mir_test_doubles/mock_renderable.h"
 #include "mir_test_doubles/fake_renderable.h"
@@ -57,17 +59,22 @@
     {
     }
 
-    std::shared_ptr<mir::graphics::Renderable> renderable() const
+    std::shared_ptr<mir::graphics::Renderable> renderable() const override
     {
         return renderable_;
     }
 
-    void rendered()
-    {
-    }
-
-    void occluded()
-    {
+    void rendered() override
+    {
+    }
+
+    void occluded() override
+    {
+    }
+
+    std::unique_ptr<mc::Decoration> decoration() const override
+    {
+        return nullptr;
     }
 
 private:
@@ -317,7 +324,7 @@
     }
 
     MOCK_CONST_METHOD0(renderable, std::shared_ptr<mir::graphics::Renderable>());
-    MOCK_CONST_METHOD0(decoration, mc::Decoration const&());
+    MOCK_CONST_METHOD0(decoration, std::unique_ptr<mc::Decoration>());
     MOCK_METHOD0(rendered, void());
     MOCK_METHOD0(occluded, void());
 };
 
=== modified file 'tests/unit-tests/examples/test_demo_compositor.cpp'
--- tests/unit-tests/examples/test_demo_compositor.cpp	2015-03-31 02:35:42 +0000
+++ tests/unit-tests/examples/test_demo_compositor.cpp	2015-04-01 19:59:57 +0000
@@ -30,6 +30,7 @@
 #include "mir_test_doubles/stub_buffer_stream.h"
 #include "mir_test_doubles/stub_renderable.h"
 #include "mir_test/fake_shared.h"
+#include "mir_test/gmock_fixes.h"
 
 #include <gtest/gtest.h>
 #include <gmock/gmock.h>
@@ -47,7 +48,7 @@
 struct MockSceneElement : mc::SceneElement
 {
     MOCK_CONST_METHOD0(renderable, std::shared_ptr<mir::graphics::Renderable>());
-    MOCK_CONST_METHOD0(decoration, mc::Decoration const&());
+    MOCK_CONST_METHOD0(decoration, std::unique_ptr<mc::Decoration>());
     MOCK_METHOD0(rendered, void());
     MOCK_METHOD0(occluded, void());
 };
 
=== modified file 'tests/unit-tests/scene/test_surface_stack.cpp'
--- tests/unit-tests/scene/test_surface_stack.cpp	2015-03-31 02:35:42 +0000
+++ tests/unit-tests/scene/test_surface_stack.cpp	2015-04-01 19:59:57 +0000
@@ -22,6 +22,7 @@
 #include "mir/scene/observer.h"
 #include "mir/scene/surface_creation_parameters.h"
 #include "mir/compositor/scene_element.h"
+#include "mir/compositor/decoration.h"
 #include "src/server/report/null_report_factory.h"
 #include "src/server/scene/basic_surface.h"
 #include "mir/input/input_channel_factory.h"
@@ -251,10 +252,10 @@
 
     auto& element = elements.front();
 
-    auto const& decor = element->decoration();
-    EXPECT_TRUE(decor);
-    EXPECT_EQ(mc::Decoration::Type::surface, decor.type);
-    EXPECT_EQ("Mary had a little lamb", decor.name);
+    auto decor = element->decoration();
+    ASSERT_THAT(decor, Ne(nullptr));
+    EXPECT_EQ(mc::Decoration::Type::surface, decor->type);
+    EXPECT_EQ("Mary had a little lamb", decor->name);
 }
 
 TEST_F(SurfaceStack, gets_surface_renames)
@@ -286,10 +287,10 @@
 
     auto& element = elements.front();
 
-    auto const& decor = element->decoration();
-    EXPECT_TRUE(decor);
-    EXPECT_EQ(mc::Decoration::Type::surface, decor.type);
-    EXPECT_EQ("username@hostname: ~/Documents", decor.name);
+    auto decor = element->decoration();
+    ASSERT_THAT(decor, Ne(nullptr));
+    EXPECT_EQ(mc::Decoration::Type::surface, decor->type);
+    EXPECT_EQ("username@hostname: ~/Documents", decor->name);
 }
 
 TEST_F(SurfaceStack, scene_counts_pending_accurately)