Merge lp:~kdub/mir/fix-1299977-take3 into lp:mir

[Kevin DuBois]

fix lp: #1299977 in the demo shell by accounting for the demo shell's additional decorations in the occlusion filtering.

fix lp: #1299977 in the demo shell by accounting for the demo shell's additional decorations in the occlusion filtering.

This is the third attempt at correcting this problem, the first two being:
https://code.launchpad.net/~vanvugt/mir/unocclude/+merge/216690 (delete occlusion filtering), and
https://code.launchpad.net/~kdub/mir/fix-1299977/+merge/222844 (share the production code with the examples).

The problem is that the bug isn't conceptually that tough, but coming to an agreement on how to share/evolve the demo shell vs the usc shell vs the default mir shell vs the qtsg is. Here's where we got to in the previous attempts:
0) We should keep the occlusion filtering (even if there are gaps in the default implementation as of today)
1) We don't want to try to provide an occlusion algorithm for the users, as every user is likely to need something a bit different.
2) Our example code should provide an example of the proper use of the public headers. Example code shouldn't have access to mir internal code that a 'normal user' doesn't have access to.
3) The occlusion code in the default/demo cases is pretty similar, and it goes against the 'don't copy code' instinct to have two algorithms. The demo compositor's needs is largely the same with the exceptions of having to factor in the shadow/titlebar. As time goes on, I'd expect we'd have to factor in more and more stuff.

This attempt satisfies the concerns 0), 1), and 2) at the expense of 3)... the occlusion code is copied from the production code with the additional logic to factor in the titlebar/shadows. This lets the different needs of the different compositors evolve differently. I hope that as time goes on, we'll sift through the code and organically pull the truly universal compositor stuff into a handy library for shell writers.

Note:
I'm interested in this because its blocking me turning on HWC 2d optimizations by default. The demo shell has to start accounting for its decorations if it hopes to use the 2d optimizations on android correctly. My primary interest is having the demo compositor discern when it can use mg::DisplayBuffer::post_renderables_if_optimizable().

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1690
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-ci/2099/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/869
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/875/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/868
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/620
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/620/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/618
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/618/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/2767
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/2767/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/2012
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/9497

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-team-mir-development-branch-ci/2099/rebuild

review: Needs Fixing (continuous-integration)

[Daniel van Vugt (vanvugt)]

I started on a proper solution for bug 1299977 back in May. That involves separating the concepts of window size and client size (as you'll find all existing windowing systems do). Once that's clear, we just switch the occlusion test to use the extents (including frame) of a window instead of its client region.

So the right (and elegant) solution is coming. I'm concerned about any change that appears to fix bug 1299977 without implementing this. It's suspicious but I haven't done a review yet...

If the only goal is to resolve bug 1299977 then I suspect this is probably the wrong answer.

[Kevin DuBois (kdub)]

I think the disagreement goes a little bit deeper because we haven't come to a consensus about the concepts that we're incorporating into the scene. I argue that we shouldn't have the concept of window size and client size in the scene because we have 1 user that handles this in a custom way (U8) and one user that doesn't need this at all (USC).

Once we start getting the concept of window size vs decoration side, we will have this awkward situation where the android hwc code will just have to start rejecting renderables with decorations.

So really, this solution puts the demo shell on the trajectory of reimplementing the scene in the same way that the users have chosen to reimplement the scene (that is, reimplementing parts of the compositing system at a higher level than the Renderer).

I want to protect the core (buffer swapping, turning the display on, setting up the GL context) from the desktop-style additional needs (animations, window decorations, 'bling', cursor images, etc etc).

My idea/"unconcensussed plan" for this is to have the SceneElement be expandable so that a compositor writer can pack it with data that the core mir will preserve, but this data will be opaque to the "core mir". So for instance, the compositor can 'tag' each SceneElement with a bunch of information about its window decorations, which will be specific to the compositor implementation. On the next pass of the shell's render the data would be preserved (or perhaps updated in some universal way, like timing info).

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:1691
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-ci/2113/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/886
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/892
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/885
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/634
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/634/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/632
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/632/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/2831
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/2831/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/2029
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/9562

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-team-mir-development-branch-ci/2113/rebuild

review: Approve (continuous-integration)

[Cemil Azizoglu (cemil-azizoglu)]

I'm interested in seeing Daniel's solution as well. Since Kevin is blocked by this for hwc optimizations, I'll go ahead with the review.

Minor things:

9 +add_library(mirdraw STATIC graphics_utils.cpp demo-shell/occlusion.cpp)

mirdraw should be a lib that others (besides demo-shell) can use and hence its source should not be part of a particular example program. So occlusion.cpp should move outside demo-shell/.

294 -
295 +namespace mc = mir::compositor;

preserve the blank line?

review: Approve

[Alan Griffiths (alan-griffiths)]

I'm not entirely sure how to validate this but the code looks OK and it runs. We can fix problems later if they arise.

review: Approve

[PS Jenkins bot (ps-jenkins)]

FAILED: Autolanding.
More details in the following jenkins job:
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-autolanding/885/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/950/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/956/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/948/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-autolanding/269/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-autolanding/269/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/3147/console

review: Needs Fixing (continuous-integration)

[Alexandros Frantzis (afrantzis)]

OK for now.

> SceneElement be expandable so that a compositor writer can pack it with data that the core mir will > preserve, but this data will be opaque to the "core mir"

Interesting idea.

review: Approve

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1692
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-ci/2192/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/997
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/1003/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/992/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/713/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/711/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/3362/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-team-mir-development-branch-ci/2192/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:1693
http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-ci/2193/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-android-utopic-i386-build/1000
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-clang-utopic-amd64-build/1006
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-utopic-touch/995
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/715
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-amd64-ci/715/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/716
        deb: http://jenkins.qa.ubuntu.com/job/mir-team-mir-development-branch-utopic-armhf-ci/716/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/3374
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/3374/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/mir-mediumtests-runner-mako/2123
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/10091

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/mir-team-mir-development-branch-ci/2193/rebuild

review: Approve (continuous-integration)

[Daniel van Vugt (vanvugt)]

I don't like to be the spoilsport, but will block this for two reasons:

(1) As mentioned in the description this proposal branches (duplicates) functionality on the assumption we will re-unify it later. I think that's a bad assumption and unlikely to happen.

(2) A generic solution is possible. One that works for all (most?) shells. I think I'd prefer to continue with that (started in May) instead of landing solutions that are shell-specific.

review: Disapprove

[Daniel van Vugt (vanvugt)]

P.S. If you want to enable overlay optimizations by default, then you should probably be focusing more on how the Ubuntu touch Qt shell needs it.

In the least you can overlay full-screen surfaces (on the host server when nesting) right now using the bypass detection algorithm. Then worry about enabling hardware overlays in the nested server later. So we can get most of the performance benefits of overlays turned on right now without worrying at all about anything to to with demo shell.

[Kevin DuBois (kdub)]

Its more that the default occlusion algorithm and the demo occlusion algorithm are doing different things, with the demo occlusion algorithm having to factor in the decorations on the top,bottom & right. There is some overlap because both are rectangle-based occlusion filtering but this is an attempt to satisfy the primary complaints about lp:~kdub/mir/fix-1299977. Namely, we don't want to use a private algorithm in the demos, yet, we don't want to expose the algorithm publicly because its not universal.

[Kevin DuBois (kdub)]

> (2) A generic solution is possible. One that works for all (most?) shells. I
> think I'd prefer to continue with that (started in May) instead of landing
> solutions that are shell-specific.

If we try to come up with a generic solution that addresses all shells, we will end up with some shells that don't use some of the features. We also end up with some shells trying to jam features into the "one algorithm" that other shells don't want, and we limit those shells if they don't get their special feature landed. (eg, say someone wants an obscure fragment shader that affects occlusion detection). Given the flexibility and extensibility that we're aiming for, I'd rather see compositor writers rewriting things that are specific to that shell's needs, then aiming for one set of behaviors that covers every shell we encounter.

Like, every shell writer can be expected to write GL code, and every shell writer would have the responsibility to do occlusions and visibility detection, based on the unique things that the shell wants to appear on the screen. This is the role of the compositor object, and would let us pop in new compositor objects that have differing behavior (LSP) without changing the correctness of the mir system. (and also without burdening core mir with the responsibility to make the most universal drawing code to assist the shell writers)

As we determine things that are truly universal to all shells we should pull them into core mir. For instance mg::DisplayBuffer is needed by every shell so its proper to have that interface there. Other things like an animation framework might also fit in with core mir. Occlusion seems to me that there are as many variations as there are possible shells, so it seems less likely that it belongs in core mir.

[Kevin DuBois (kdub)]

> (2) A generic solution is possible. One that works for all (most?) shells. I
> think I'd prefer to continue with that (started in May) instead of landing
> solutions that are shell-specific.

If we try to come up with a generic solution that addresses all shells, we will end up with some shells that don't use some of the features. We also end up with some shells trying to jam features into the "one algorithm" that other shells don't want, and we limit those shells if they don't get their special feature landed. (eg, say someone wants an obscure fragment shader that affects occlusion detection). Given the flexibility and extensibility that we're aiming for, I'd rather see compositor writers rewriting things that are specific to that shell's needs, then aiming for one set of behaviors that covers every shell we encounter.

Like, every shell writer can be expected to write GL code, and every shell writer would have the responsibility to do occlusions and visibility detection, based on the unique things that the shell wants to appear on the screen. This is the role of the compositor object, and would let us pop in new compositor objects that have differing behavior (LSP) without changing the correctness of the mir system. (and also without burdening core mir with the responsibility to make the most universal drawing code to assist the shell writers)

As we determine things that are truly universal to all shells we should pull them into core mir. For instance mg::DisplayBuffer is needed by every shell so its proper to have that interface there. Other things like an animation framework might also fit in with core mir. Occlusion seems to me that there are as many variations as there are possible shells, so it seems less likely that it belongs in core mir.

[Kevin DuBois (kdub)]

I don't know why Launchpad posted twice, but same content in each posting.

[Daniel van Vugt (vanvugt)]

Yeah, if you do assume in future every shell should provide its own compositor then this partially makes sense. However I don't think that's a path we want to go down, and have explicitly decided not to. We do want to unify and provide common compositing ability where possible. A shell shouldn't be forced to write a new compositor. If we did it then I'd like to see it done absolutely, and the default compositor removed at the same time (and thus get team agreement on the plan).

Other things like occlusion testing between windows that are kind-of rectangular and have a little bit of shape to them are common problems. We shouldn't re-invent occlusion testing every time a new shell comes along... On the other hand, if we defaulted to no occlusion testing at all and make it an optional feature that some shells can implement then I'm happy with that -- It would not be a required feature to build a shell and bug 1299977 would also be solved.

Back to the primary problem, where occlusion testing needs to deal with decorations, I think there are three good options:
  1. No occlusion testing by default. Put it all in your shell if you want it but make it optional for shells.
  2. Continue with the work I started in May and provide extended region information allowing window-based shells to detect occlusions accurately. This is relatively simple in theory, but blocked by other RTM-related work taking precedent. It also has to be finished to implement correct window placement anyway.
  3. Continue with the plan that everything is a node of the scene graph. Then occlusion testing is a generic graph traversal algorithm that can support any primitives. Not just decorations.

[Daniel van Vugt (vanvugt)]

I particularly do not want this branch to land because it adds complexity that would be hard to wind back. And we would unwind it as at least options (2) and (3) above are going to be implemented (already begun).

[Cemil Azizoglu (cemil-azizoglu)]

Daniel, will you be providing your version soon? If it'll take some time, perhaps we should let kdub proceed and when you get to it, you can put up an MP the way you like it. I just feel that progress should continue. But it's all software and can be changed later.

Or perhaps there is some way that this MP can be fixed in a minimally acceptible (to you) manner. If so, please comment and let Kevin take a stab at it.

[Kevin DuBois (kdub)]

> Yeah, if you do assume in future every shell should provide its own compositor
> then this partially makes sense. However I don't think that's a path we want
> to go down, and have explicitly decided not to. We do want to unify and
> provide common compositing ability where possible. A shell shouldn't be forced
> to write a new compositor. If we did it then I'd like to see it done
> absolutely, and the default compositor removed at the same time (and thus get
> team agreement on the plan).

In the present we have 3 shells/clients between USC, demo, and unity8, that have all chosen to have different compositor implementations. We've already gone down the path, but haven't been able to shepherd all the implementations into using the interfaces that we intended. :)
This hopefully gets the demo/usc using the mc::Compositor interface like we intended, and we'll have to work more closely to get qtcomp/unity8 not to replace the MultiThreadedCompositor system.

> Other things like occlusion testing between windows that are kind-of
> rectangular and have a little bit of shape to them are common problems. We
> shouldn't re-invent occlusion testing every time a new shell comes along... On
> the other hand, if we defaulted to no occlusion testing at all and make it an
> optional feature that some shells can implement then I'm happy with that -- It
> would not be a required feature to build a shell and bug 1299977 would also be
> solved.

I agree that the easier we make things for the shell writers, but I think its more important not to force the shell writers into extending implementations. So, to put it another way, the best way to make things nice for the shell writers is to have a system of objects that we can plug into the core. Code reuse is good of course, but my first attempt was thwarted because we decided that code reuse doesn't trump exposing an additional 'shell writers api/abi'. The hard problem is how to get those public server interfaces right, and this seems to favor making it a bit easier by rallying around the interfaces that we want the users to implement, and by not introducing a mini-toolkit (or a big swiss army object) that aims to 'make opengl easy' :)
In this case, the judgement call comes at the expense of having occlusion look somewhat the same, but doing different things to factor in the shell's decorations.

[Kevin DuBois (kdub)]

> Yeah, if you do assume in future every shell should provide its own compositor
> then this partially makes sense. However I don't think that's a path we want
> to go down, and have explicitly decided not to. We do want to unify and
> provide common compositing ability where possible. A shell shouldn't be forced
> to write a new compositor. If we did it then I'd like to see it done
> absolutely, and the default compositor removed at the same time (and thus get
> team agreement on the plan).

In the present we have 3 shells/clients between USC, demo, and unity8, that have all chosen to have different compositor implementations. We've already gone down the path, but haven't been able to shepherd all the implementations into using the interfaces that we intended. :)
This hopefully gets the demo/usc using the mc::Compositor interface like we intended, and we'll have to work more closely to get qtcomp/unity8 not to replace the MultiThreadedCompositor system.

> Other things like occlusion testing between windows that are kind-of
> rectangular and have a little bit of shape to them are common problems. We
> shouldn't re-invent occlusion testing every time a new shell comes along... On
> the other hand, if we defaulted to no occlusion testing at all and make it an
> optional feature that some shells can implement then I'm happy with that -- It
> would not be a required feature to build a shell and bug 1299977 would also be
> solved.

I agree that the easier we make things for the shell writers, but I think its more important not to force the shell writers into extending implementations. So, to put it another way, the best way to make things nice for the shell writers is to have a system of objects that we can plug into the core. Code reuse is good of course, but my first attempt was thwarted because we decided that code reuse doesn't trump exposing an additional 'shell writers api/abi'. The hard problem is how to get those public server interfaces right, and this seems to favor making it a bit easier by rallying around the interfaces that we want the users to implement, and by not introducing a mini-toolkit (or a big swiss army object) that aims to 'make opengl easy' :)
In this case, the judgement call comes at the expense of having occlusion look somewhat the same, but doing different things to factor in the shell's decorations.

[Kevin DuBois (kdub)]

strange launchpad keeps double-posting me...

[Daniel van Vugt (vanvugt)]

Yes it does appear people are writing their own compositors despite us recommending against it. And I too want to resolve the blurry seams that have formed between compositor classes and renderers.

OK I can make suggestions for moving forward:

(1) Remove all references to bug 1299977. Because what's proposed here is only for demo shell, and not a generic fix for bug 1299977. We can do enough work to unblock overlay enablement without waiting for a full fix of bug 1299977 to land.

(2) Make demo-shell's flagging of occlusions simple and dumb, so that the word "decoration" is never mentioned. Just allow overlays for the surface that's "on top" (last on the render list). A generic solution which accounts for decorations more carefully will come later. You don't need to wait for that to unblock.

We can argue about the existence of DefaultDisplayByfferCompositor another day.

It's a little bit silly that demo shell should block unity8 progress so let's get over this hump with minimal code change (which also makes it more likely to get backported to stable series 0.5 for RTM).

review: Needs Fixing

[Kevin DuBois (kdub)]

Cool, sounds good to me. Working on fixing.

[Kevin DuBois (kdub)]

okay, so the new approach of doing a much more simple filtering of the renderable list is significantly different than improving the algorithm, in that it doesn't fix 1299977, it just averts it.

So I'll move this MP to rejected. I'll push the improvements to lp:~kdub/mir/fix-1348330 and submit a new merge proposal (which is mostly the same as this one, but it helps to document the problem better, and remove the references to the 1299977 bug)

=== modified file 'examples/CMakeLists.txt'
--- examples/CMakeLists.txt	2014-06-11 16:11:32 +0000
+++ examples/CMakeLists.txt	2014-07-18 18:49:52 +0000
@@ -95,7 +95,7 @@
 add_executable(mir_demo_client_prompt_session prompt_session.c)
 target_link_libraries(mir_demo_client_prompt_session mirclient)
 
-add_library(mirdraw STATIC graphics_utils.cpp)
+add_library(mirdraw STATIC graphics_utils.cpp demo-shell/occlusion.cpp)
 target_link_libraries(mirdraw ${GLESv2_LIBRARIES})
 
 include_directories(

=== modified file 'examples/demo-shell/CMakeLists.txt'
--- examples/demo-shell/CMakeLists.txt	2014-03-06 06:05:17 +0000
+++ examples/demo-shell/CMakeLists.txt	2014-07-18 18:49:52 +0000
@@ -1,5 +1,6 @@
 add_executable(mir_demo_server_shell
   demo_shell.cpp
+  demo_compositor.cpp
   demo_renderer.cpp
   fullscreen_placement_strategy.cpp
   window_manager.cpp
@@ -8,6 +9,7 @@
 
 target_link_libraries(mir_demo_server_shell
   mirserver
+  mirdraw
 )
 
 install(TARGETS mir_demo_server_shell RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})

=== added file 'examples/demo-shell/demo_compositor.cpp'
--- examples/demo-shell/demo_compositor.cpp	1970-01-01 00:00:00 +0000
+++ examples/demo-shell/demo_compositor.cpp	2014-07-18 18:49:52 +0000
@@ -0,0 +1,96 @@
+/*
+ * Copyright © 2014 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/graphics/display_buffer.h"
+#include "mir/compositor/compositor_report.h"
+#include "mir/compositor/scene.h"
+#include "mir/compositor/scene_element.h"
+#include "mir/compositor/destination_alpha.h"
+#include "demo_compositor.h"
+#include "occlusion.h"
+
+namespace me = mir::examples;
+namespace mg = mir::graphics;
+namespace mc = mir::compositor;
+namespace geom = mir::geometry;
+
+namespace
+{
+mc::DestinationAlpha destination_alpha(mg::DisplayBuffer const& db)
+{
+    return db.uses_alpha() ? mc::DestinationAlpha::generate_from_source : mc::DestinationAlpha::opaque;
+}
+}
+
+me::DemoCompositor::DemoCompositor(
+    mg::DisplayBuffer& display_buffer,
+    std::shared_ptr<mc::Scene> const& scene,
+    mg::GLProgramFactory const& factory,
+    std::shared_ptr<mc::CompositorReport> const& report) :
+    display_buffer(display_buffer),
+    scene(scene),
+    report(report),
+    shadow_radius(80),
+    titlebar_height(30),
+    renderer(
+        factory,
+        display_buffer.view_area(),
+        destination_alpha(display_buffer),
+        static_cast<float>(shadow_radius),
+        static_cast<float>(titlebar_height)) 
+{
+}
+
+mg::RenderableList me::DemoCompositor::generate_renderables()
+{
+    mg::RenderableList renderable_list;
+    auto elements = scene->scene_elements_for(this);
+    auto occluded = me::filter_occlusions_from(elements, display_buffer.view_area(), shadow_radius, titlebar_height);
+    for(auto const& it : elements)
+    {
+        renderable_list.push_back(it->renderable());
+        it->rendered_in(this);
+    }
+    for(auto const& it : occluded)
+        it->occluded_in(this);
+    
+    return renderable_list;
+}
+
+void me::DemoCompositor::composite()
+{
+    report->began_frame(this);
+
+    auto renderable_list = generate_renderables();
+    if (display_buffer.post_renderables_if_optimizable(renderable_list))
+    {
+        renderer.suspend();
+        report->finished_frame(true, this);
+    }
+    else
+    {
+        display_buffer.make_current();
+
+        renderer.set_rotation(display_buffer.orientation());
+        renderer.begin();
+        renderer.render(renderable_list);
+        display_buffer.post_update();
+        renderer.end();
+        report->finished_frame(false, this);
+    }
+}

=== added file 'examples/demo-shell/demo_compositor.h'
--- examples/demo-shell/demo_compositor.h	1970-01-01 00:00:00 +0000
+++ examples/demo-shell/demo_compositor.h	2014-07-18 18:49:52 +0000
@@ -0,0 +1,65 @@
+/*
+ * Copyright © 2014 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]>
+ */
+
+#ifndef MIR_EXAMPLES_DEMO_COMPOSITOR_H_
+#define MIR_EXAMPLES_DEMO_COMPOSITOR_H_
+
+#include "mir/compositor/display_buffer_compositor.h"
+#include "mir/compositor/scene.h"
+#include "mir/graphics/renderable.h"
+#include "demo_renderer.h"
+
+namespace mir
+{
+namespace compositor
+{
+class Scene;
+class CompositorReport;
+}
+namespace graphics
+{
+class DisplayBuffer;
+}
+namespace examples
+{
+
+class DemoCompositor : public compositor::DisplayBufferCompositor
+{
+public:
+    DemoCompositor(
+        graphics::DisplayBuffer& display_buffer,
+        std::shared_ptr<compositor::Scene> const& scene,
+        graphics::GLProgramFactory const& factory,
+        std::shared_ptr<compositor::CompositorReport> const& report);
+
+    void composite() override;
+
+private:
+    graphics::RenderableList generate_renderables();
+    graphics::DisplayBuffer& display_buffer;
+    std::shared_ptr<compositor::Scene> const scene;
+    std::shared_ptr<compositor::CompositorReport> const report;
+    int const shadow_radius;
+    int const titlebar_height;
+    DemoRenderer renderer;
+};
+
+} // namespace examples
+} // namespace mir
+
+#endif // MIR_EXAMPLES_DEMO_COMPOSITOR_H_

=== modified file 'examples/demo-shell/demo_renderer.cpp'
--- examples/demo-shell/demo_renderer.cpp	2014-06-18 12:50:31 +0000
+++ examples/demo-shell/demo_renderer.cpp	2014-07-18 18:49:52 +0000
@@ -139,12 +139,16 @@
 DemoRenderer::DemoRenderer(
     graphics::GLProgramFactory const& program_factory,
     geometry::Rectangle const& display_area,
-    compositor::DestinationAlpha dest_alpha)
-    : GLRenderer(program_factory,
+    compositor::DestinationAlpha dest_alpha,
+    float shadow_radius,
+    float titlebar_height) :
+    GLRenderer(program_factory,
         std::unique_ptr<graphics::GLTextureCache>(new compositor::RecentlyUsedCache()),
         display_area,
-        dest_alpha)
-    , corner_radius(0.5f)
+        dest_alpha),
+    corner_radius(0.5f),
+    shadow_radius(shadow_radius),
+    titlebar_height(titlebar_height)
 {
     shadow_corner_tex = generate_shadow_corner_texture(0.4f);
     titlebar_corner_tex = generate_frame_corner_texture(corner_radius,
@@ -177,8 +181,8 @@
                               graphics::Renderable const& renderable) const
 {
     GLRenderer::tessellate(primitives, renderable);
-    tessellate_shadow(primitives, renderable, 80.0f);
-    tessellate_frame(primitives, renderable, 30.0f);
+    tessellate_shadow(primitives, renderable, shadow_radius);
+    tessellate_frame(primitives, renderable, titlebar_height);
 }
 
 void DemoRenderer::tessellate_shadow(std::vector<graphics::GLPrimitive>& primitives,

=== modified file 'examples/demo-shell/demo_renderer.h'
--- examples/demo-shell/demo_renderer.h	2014-06-06 10:03:54 +0000
+++ examples/demo-shell/demo_renderer.h	2014-07-18 18:49:52 +0000
@@ -29,8 +29,12 @@
 class DemoRenderer : public compositor::GLRenderer
 {
 public:
-    DemoRenderer(graphics::GLProgramFactory const& factory, geometry::Rectangle const& display_area,
-        compositor::DestinationAlpha dest_alpha);
+    DemoRenderer(
+        graphics::GLProgramFactory const& factory,
+        geometry::Rectangle const& display_area,
+        compositor::DestinationAlpha dest_alpha,
+        float shadow_radius,
+        float titlebar_height);
     ~DemoRenderer();
 
     void begin() const override;
@@ -45,6 +49,8 @@
 
 private:
     float const corner_radius;
+    float const shadow_radius;
+    float const titlebar_height;
     GLuint shadow_corner_tex;
     GLuint titlebar_corner_tex;
 };

=== modified file 'examples/demo-shell/demo_shell.cpp'
--- examples/demo-shell/demo_shell.cpp	2014-07-17 07:53:26 +0000
+++ examples/demo-shell/demo_shell.cpp	2014-07-18 18:49:52 +0000
@@ -18,7 +18,7 @@
 
 /// \example demo_shell.cpp A simple mir shell
 
-#include "demo_renderer.h"
+#include "demo_compositor.h"
 #include "window_manager.h"
 #include "fullscreen_placement_strategy.h"
 #include "../server_configuration.h"
@@ -28,6 +28,8 @@
 #include "mir/report_exception.h"
 #include "mir/graphics/display.h"
 #include "mir/input/composite_event_filter.h"
+#include "mir/compositor/display_buffer_compositor_factory.h"
+#include "mir/compositor/destination_alpha.h"
 #include "mir/compositor/renderer_factory.h"
 #include "mir/shell/host_lifecycle_event_listener.h"
 
@@ -39,6 +41,7 @@
 namespace mf = mir::frontend;
 namespace mi = mir::input;
 namespace mo = mir::options;
+namespace mc = mir::compositor;
 namespace msh = mir::shell;
 
 namespace mir
@@ -46,22 +49,30 @@
 namespace examples
 {
 
-class DemoRendererFactory : public compositor::RendererFactory
+class DisplayBufferCompositorFactory : public mc::DisplayBufferCompositorFactory
 {
 public:
-    DemoRendererFactory(std::shared_ptr<graphics::GLProgramFactory> const& gl_program_factory) :
-        gl_program_factory(gl_program_factory)
-    {
-    }
-
-    std::unique_ptr<compositor::Renderer> create_renderer_for(
-        geometry::Rectangle const& rect,
-        mir::compositor::DestinationAlpha dest_alpha) override
-    {
-        return std::unique_ptr<compositor::Renderer>(new DemoRenderer(*gl_program_factory, rect, dest_alpha));
-    }
+    DisplayBufferCompositorFactory(
+        std::shared_ptr<mc::Scene> const& scene,
+        std::shared_ptr<mg::GLProgramFactory> const& gl_program_factory,
+        std::shared_ptr<mc::CompositorReport> const& report) :
+        scene(scene),
+        gl_program_factory(gl_program_factory),
+        report(report)
+    {
+    }
+
+    std::unique_ptr<mc::DisplayBufferCompositor> create_compositor_for(
+        mg::DisplayBuffer& display_buffer) override
+    {
+        return std::unique_ptr<mc::DisplayBufferCompositor>(
+            new me::DemoCompositor{display_buffer, scene, *gl_program_factory, report});
+    }
+
 private:
-    std::shared_ptr<graphics::GLProgramFactory> const gl_program_factory;
+    std::shared_ptr<mc::Scene> const scene;
+    std::shared_ptr<mg::GLProgramFactory> const gl_program_factory;
+    std::shared_ptr<mc::CompositorReport> const report;
 };
 
 class DemoServerConfiguration : public mir::examples::ServerConfiguration
@@ -84,6 +95,19 @@
     {
     }
 
+
+    std::shared_ptr<compositor::DisplayBufferCompositorFactory> the_display_buffer_compositor_factory()
+    {
+        return display_buffer_compositor_factory(
+            [this]()
+            {
+                return std::make_shared<me::DisplayBufferCompositorFactory>(
+                    the_scene(),
+                    the_gl_program_factory(),
+                    the_compositor_report());
+            });
+    }
+
     std::shared_ptr<ms::PlacementStrategy> the_placement_strategy() override
     {
         return shell_placement_strategy(
@@ -105,11 +129,6 @@
         return composite_filter;
     }
 
-    std::shared_ptr<compositor::RendererFactory> the_renderer_factory() override
-    {
-        return std::make_shared<DemoRendererFactory>(the_gl_program_factory());
-    }
-
     class NestedLifecycleEventListener : public msh::HostLifecycleEventListener
     {
     public:

=== added file 'examples/demo-shell/occlusion.cpp'
--- examples/demo-shell/occlusion.cpp	1970-01-01 00:00:00 +0000
+++ examples/demo-shell/occlusion.cpp	2014-07-18 18:49:52 +0000
@@ -0,0 +1,110 @@
+/*
+ * Copyright © 2014 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]>
+ *
+ * based on src/server/compositor/occlusion.cpp, which was:  
+ * Authored by: Daniel van Vugt <[e-mail]>
+ */
+
+#include <mir/graphics/renderable.h>
+#include <mir/compositor/scene_element.h>
+#include "occlusion.h"
+
+namespace me = mir::examples;
+namespace mg = mir::graphics;
+namespace mc = mir::compositor;
+namespace geom = mir::geometry;
+
+namespace
+{
+bool renderable_is_occluded(
+    mg::Renderable const& renderable, 
+    geom::Rectangle const& area,
+    std::vector<geom::Rectangle>& coverage,
+    int shadow_radius,
+    int titlebar_height)
+{
+    static const glm::mat4 identity;
+    if (renderable.transformation() != identity)
+        return false;  // Weirdly transformed. Assume never occluded.
+
+    if (!renderable.visible())
+        return true;  //invisible; definitely occluded.
+
+    //account for titlebar/shadows that the demo shell adds
+    auto const& undecorated_window = renderable.screen_position();
+    using namespace mir::geometry;
+    geom::Rectangle decorated_window{
+        geom::Point{
+            undecorated_window.top_left.x,
+            undecorated_window.top_left.y - geom::DeltaY{titlebar_height}
+        },
+        geom::Size{
+            undecorated_window.size.width.as_int() + shadow_radius,
+            undecorated_window.size.height.as_int() + shadow_radius + titlebar_height
+        }
+    };
+
+    auto const& clipped_decorated_window = decorated_window.intersection_with(area);
+    
+    if (clipped_decorated_window == geom::Rectangle{})
+        return true;  // Not in the area; definitely occluded.
+
+    // Not weirdly transformed but also not on this monitor? Don't care...
+    if (!area.overlaps(clipped_decorated_window))
+        return true;  // Not on the display; definitely occluded.
+
+    bool occluded = false;
+    for (const auto &r : coverage)
+    {
+        if (r.contains(clipped_decorated_window))
+        {
+            occluded = true;
+            break;
+        }
+    }
+
+    if (!occluded && renderable.alpha() == 1.0f && !renderable.shaped())
+        coverage.push_back(decorated_window);
+
+    return occluded;
+}
+}
+
+mc::SceneElementSequence me::filter_occlusions_from(
+    mc::SceneElementSequence& elements_list,
+    geom::Rectangle const& area,
+    int shadow_radius,
+    int titlebar_height)
+{
+    mc::SceneElementSequence elements;
+    std::vector<geom::Rectangle> coverage;
+    auto it = elements_list.rbegin();
+    while (it != elements_list.rend())
+    {
+        auto const renderable = (*it)->renderable();
+        if (renderable_is_occluded(*renderable, area, coverage, shadow_radius, titlebar_height))
+        {
+            elements.insert(elements.begin(), *it);
+            it = mc::SceneElementSequence::reverse_iterator(elements_list.erase(std::prev(it.base())));
+        }
+        else
+        {
+            it++;
+        }
+    }
+    return elements;
+}

=== added file 'examples/demo-shell/occlusion.h'
--- examples/demo-shell/occlusion.h	1970-01-01 00:00:00 +0000
+++ examples/demo-shell/occlusion.h	2014-07-18 18:49:52 +0000
@@ -0,0 +1,39 @@
+/*
+ * Copyright © 2014 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]>
+ */
+
+#ifndef MIR_EXAMPLES_OCCLUSION_H_
+#define MIR_EXAMPLES_OCCLUSION_H_
+
+#include "mir/compositor/scene.h"
+#include "mir/geometry/rectangle.h"
+
+namespace mir
+{
+namespace examples
+{
+
+compositor::SceneElementSequence filter_occlusions_from(
+    compositor::SceneElementSequence& list,
+    geometry::Rectangle const& area,
+    int shadow_radius,
+    int titlebar_height);
+
+} // namespace examples
+} // namespace mir
+
+#endif // MIR_EXAMPLES_OCCLUSION_H_

=== modified file 'tests/unit-tests/compositor/test_occlusion.cpp'
--- tests/unit-tests/compositor/test_occlusion.cpp	2014-07-16 03:38:05 +0000
+++ tests/unit-tests/compositor/test_occlusion.cpp	2014-07-18 18:49:52 +0000
@@ -18,6 +18,7 @@
 
 #include "mir/geometry/rectangle.h"
 #include "src/server/compositor/occlusion.h"
+#include "examples/demo-shell/occlusion.h"
 #include "mir_test_doubles/fake_renderable.h"
 #include "mir_test_doubles/stub_scene_element.h"
 
@@ -32,6 +33,49 @@
 
 namespace
 {
+struct DefaultOcclusion
+{
+    SceneElementSequence filter(SceneElementSequence& list, Rectangle const& area)
+    {
+        return filter_occlusions_from(list, area);
+    }
+};
+
+struct DecoratedOcclusion
+{   
+    SceneElementSequence filter(SceneElementSequence& list, Rectangle const& area)
+    {
+        return mir::examples::filter_occlusions_from(list, area, 0, 0);
+    }
+};
+
+SceneElementSequence scene_elements_from(
+    std::vector<std::shared_ptr<mg::Renderable>> renderables)
+{
+    SceneElementSequence elements;
+    for (auto const& renderable : renderables)
+        elements.push_back(std::make_shared<mtd::StubSceneElement>(renderable));
+
+    return elements;
+}
+
+mg::RenderableList renderables_from(SceneElementSequence const& elements)
+{
+    mg::RenderableList renderables;
+    for (auto const& element : elements)
+        renderables.push_back(element->renderable());
+
+    return renderables;
+}
+
+template<typename T>
+SceneElementSequence filter(SceneElementSequence& list, Rectangle const& area)
+{
+    T filter;
+    return filter.filter(list, area);
+}
+
+template<typename T>
 struct OcclusionFilterTest : public Test
 {
     OcclusionFilterTest()
@@ -40,42 +84,25 @@
         monitor_rect.size = {1920, 1200};
     }
 
-    SceneElementSequence scene_elements_from(
-        std::vector<std::shared_ptr<mg::Renderable>> renderables)
-    {
-        SceneElementSequence elements;
-        for (auto const& renderable : renderables)
-            elements.push_back(std::make_shared<mtd::StubSceneElement>(renderable));
-
-        return elements;
-    }
-
-    mg::RenderableList renderables_from(SceneElementSequence const& elements)
-    {
-        mg::RenderableList renderables;
-        for (auto const& element : elements)
-            renderables.push_back(element->renderable());
-
-        return renderables;
-    }
-
     Rectangle monitor_rect;
 };
+typedef ::testing::Types<DefaultOcclusion, DecoratedOcclusion> OcclusionTypes;
+TYPED_TEST_CASE(OcclusionFilterTest, OcclusionTypes);
 
 }
 
-TEST_F(OcclusionFilterTest, single_window_not_occluded)
+TYPED_TEST(OcclusionFilterTest, single_window_not_occluded)
 {
     auto window = std::make_shared<mtd::FakeRenderable>(12, 34, 56, 78);
     auto elements = scene_elements_from({window});
- 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), IsEmpty());
     EXPECT_THAT(renderables_from(elements), ElementsAre(window));
 }
 
-TEST_F(OcclusionFilterTest, partially_offscreen_still_visible)
+TYPED_TEST(OcclusionFilterTest, partially_offscreen_still_visible)
 { // Regression test for LP: #1301115
     auto left =   std::make_shared<mtd::FakeRenderable>(-10,   10, 100, 100);
     auto right =  std::make_shared<mtd::FakeRenderable>(1900,  10, 100, 100);
@@ -83,96 +110,96 @@
     auto bottom = std::make_shared<mtd::FakeRenderable>(200, 1000, 100, 1000);
     auto elements = scene_elements_from({left, right, top, bottom});
  
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), IsEmpty());
     EXPECT_THAT(renderables_from(elements), ElementsAre(left, right, top, bottom));
 }
 
-TEST_F(OcclusionFilterTest, smaller_window_occluded)
+TYPED_TEST(OcclusionFilterTest, smaller_window_occluded)
 {
     auto top = std::make_shared<mtd::FakeRenderable>(10, 10, 10, 10);
     auto bottom = std::make_shared<mtd::FakeRenderable>(12, 12, 5, 5);
     auto elements = scene_elements_from({bottom, top});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), ElementsAre(bottom));
     EXPECT_THAT(renderables_from(elements), ElementsAre(top));
 }
 
-TEST_F(OcclusionFilterTest, translucent_window_occludes_nothing)
+TYPED_TEST(OcclusionFilterTest, translucent_window_occludes_nothing)
 {
     auto top = std::make_shared<mtd::FakeRenderable>(Rectangle{{10, 10}, {10, 10}}, 0.5f);
     auto bottom = std::make_shared<mtd::FakeRenderable>(Rectangle{{12, 12}, {5, 5}}, 1.0f);
     auto elements = scene_elements_from({bottom, top});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), IsEmpty());
     EXPECT_THAT(renderables_from(elements), ElementsAre(bottom, top));
 }
 
-TEST_F(OcclusionFilterTest, hidden_window_is_self_occluded)
+TYPED_TEST(OcclusionFilterTest, hidden_window_is_self_occluded)
 {
     auto window = std::make_shared<mtd::FakeRenderable>(Rectangle{{10, 10}, {10, 10}}, 1.0f, true, false);
     auto elements = scene_elements_from({window});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), ElementsAre(window));
     EXPECT_THAT(renderables_from(elements), IsEmpty());
 }
 
-TEST_F(OcclusionFilterTest, hidden_window_occludes_nothing)
+TYPED_TEST(OcclusionFilterTest, hidden_window_occludes_nothing)
 {
     auto top = std::make_shared<mtd::FakeRenderable>(Rectangle{{10, 10}, {10, 10}}, 1.0f, true, false);
     auto bottom = std::make_shared<mtd::FakeRenderable>(12, 12, 5, 5);
     auto elements = scene_elements_from({bottom, top});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), ElementsAre(top));
     EXPECT_THAT(renderables_from(elements), ElementsAre(bottom));
 }
 
-TEST_F(OcclusionFilterTest, shaped_window_occludes_nothing)
+TYPED_TEST(OcclusionFilterTest, shaped_window_occludes_nothing)
 {
     auto top = std::make_shared<mtd::FakeRenderable>(Rectangle{{10, 10}, {10, 10}}, 1.0f, false, true);
     auto bottom = std::make_shared<mtd::FakeRenderable>(12, 12, 5, 5);
     auto elements = scene_elements_from({bottom, top});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), IsEmpty());
     EXPECT_THAT(renderables_from(elements), ElementsAre(bottom, top));
 }
 
-TEST_F(OcclusionFilterTest, identical_window_occluded)
+TYPED_TEST(OcclusionFilterTest, identical_window_occluded)
 {
     auto top = std::make_shared<mtd::FakeRenderable>(10, 10, 10, 10);
     auto bottom = std::make_shared<mtd::FakeRenderable>(10, 10, 10, 10);
     auto elements = scene_elements_from({bottom, top});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), ElementsAre(bottom));
     EXPECT_THAT(renderables_from(elements), ElementsAre(top));
 }
 
-TEST_F(OcclusionFilterTest, larger_window_never_occluded)
+TYPED_TEST(OcclusionFilterTest, larger_window_never_occluded)
 {
     auto top = std::make_shared<mtd::FakeRenderable>(10, 10, 10, 10);
     auto bottom = std::make_shared<mtd::FakeRenderable>(9, 9, 12, 12);
     auto elements = scene_elements_from({bottom, top});
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), IsEmpty());
     EXPECT_THAT(renderables_from(elements), ElementsAre(bottom, top));
 }
 
-TEST_F(OcclusionFilterTest, cascaded_windows_never_occluded)
+TYPED_TEST(OcclusionFilterTest, cascaded_windows_never_occluded)
 {
     std::vector<std::shared_ptr<mg::Renderable>> renderables;
     unsigned int const num_windows{10u};
@@ -181,13 +208,13 @@
 
     auto elements = scene_elements_from(renderables);
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), IsEmpty());
     EXPECT_THAT(renderables_from(elements), ElementsAreArray(renderables));
 }
 
-TEST_F(OcclusionFilterTest, some_occluded_and_some_not)
+TYPED_TEST(OcclusionFilterTest, some_occluded_and_some_not)
 {
     auto window0 = std::make_shared<mtd::FakeRenderable>(10, 20, 400, 300);
     auto window1 = std::make_shared<mtd::FakeRenderable>(10, 20, 5, 5);
@@ -204,13 +231,13 @@
         window0  //not occluded
     });
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), ElementsAre(window3, window2, window1));
     EXPECT_THAT(renderables_from(elements), ElementsAre(window5, window4, window0));
 }
 
-TEST_F(OcclusionFilterTest,
+TYPED_TEST(OcclusionFilterTest,
        occludes_partially_onscreen_window_when_onscreen_part_is_covered_by_another_window)
 {
     auto const partially_onscreen = std::make_shared<mtd::FakeRenderable>(-50, 100, 150, 100);
@@ -220,8 +247,29 @@
         covering
     });
 
-    auto const& occlusions = filter_occlusions_from(elements, monitor_rect);
+    auto const& occlusions = filter<TypeParam>(elements, this->monitor_rect);
 
     EXPECT_THAT(renderables_from(occlusions), ElementsAre(partially_onscreen));
     EXPECT_THAT(renderables_from(elements), ElementsAre(covering));
 }
+
+//example compositor
+TEST(DecoratedOcclusionFilter, accounts_for_decorations_while_filtering) //lp: 1299977
+{
+    Rectangle monitor_rect{{0,0},{100, 100}};
+    auto window0 = std::make_shared<mtd::FakeRenderable>(0, 100, 10, 10);
+    auto window1 = std::make_shared<mtd::FakeRenderable>(-5, -5, 5, 5);
+    auto window2 = std::make_shared<mtd::FakeRenderable>(0, 30, 1, 1);
+    auto window3 = std::make_shared<mtd::FakeRenderable>(0, 30, 15, 15);
+    auto elements = scene_elements_from({
+        window0, //surface offscreen, but titlebar should still appear
+        window1, //surface offscreen, but shadow should still appear
+        window2, //occluded
+        window3, //not occluded
+    });
+
+    auto const& occlusions = mir::examples::filter_occlusions_from(elements, monitor_rect, 10, 20);
+
+    EXPECT_THAT(renderables_from(occlusions), ElementsAre(window2));
+    EXPECT_THAT(renderables_from(elements), ElementsAre(window0, window1, window3));
+}