Merge lp:~cemil-azizoglu/mir/mir-render-surface-examples into lp:mir

[Cemil Azizoglu]

MirRenderSurface playground examples for CPU and GPU clients.

MirRenderSurface playground examples for CPU and GPU clients.

- These will be removed once the headers become public. Instead, RS support will be added to 'examples' activated by a switch.

[Mir CI Bot (mir-ci-bot)]

FAILED: Continuous integration, rev:3730
https://mir-jenkins.ubuntu.com/job/mir-ci/1762/
Executed test runs:
    FAILURE: https://mir-jenkins.ubuntu.com/job/build-mir/2209/console
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/2272
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/2263
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/2263
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=yakkety/2263
    FAILURE: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2237/console
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2237
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2237/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2237
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2237/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2237
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2237/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2237
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2237/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1762/rebuild

review: Needs Fixing (continuous-integration)

[Mir CI Bot (mir-ci-bot)]

FAILED: Continuous integration, rev:3730
https://mir-jenkins.ubuntu.com/job/mir-ci/1763/
Executed test runs:
    FAILURE: https://mir-jenkins.ubuntu.com/job/build-mir/2210/console
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/2273
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/2264
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/2264
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=yakkety/2264
    FAILURE: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2238/console
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2238
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2238/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2238
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2238/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2238
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2238/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2238
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2238/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1763/rebuild

review: Needs Fixing (continuous-integration)

[Mir CI Bot (mir-ci-bot)]

PASSED: Continuous integration, rev:3731
https://mir-jenkins.ubuntu.com/job/mir-ci/1768/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/2215
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/2278
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/2269
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/2269
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=yakkety/2269
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2243
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2243/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2243
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2243/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2243
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2243/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2243
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2243/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2243
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2243/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1768/rebuild

review: Approve (continuous-integration)

[Brandon Schaefer (brandontschaefer)]

Yay more examples +1

review: Approve

[Alan Griffiths (alan-griffiths)]

Trivial conflict:

Text conflict in src/client/symbols.map
1 conflicts encountered.

review: Needs Fixing

[Alan Griffiths (alan-griffiths)]

+As such functionality matures, related headers become public and the relevant playground

We tend to keep the line length to 80 in these files

[Mir CI Bot (mir-ci-bot)]

FAILED: Continuous integration, rev:3733
https://mir-jenkins.ubuntu.com/job/mir-ci/1847/
Executed test runs:
    FAILURE: https://mir-jenkins.ubuntu.com/job/build-mir/2329/console
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/2392
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/2384
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/2384
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=yakkety/2384
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2358
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2358/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2358
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2358/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2358
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2358/artifact/output/*zip*/output.zip
    FAILURE: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/2358/console
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/2358/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2358
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2358/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2358
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2358/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1847/rebuild

review: Needs Fixing (continuous-integration)

[Mir CI Bot (mir-ci-bot)]

PASSED: Continuous integration, rev:3734
https://mir-jenkins.ubuntu.com/job/mir-ci/1849/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/2332
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/2395
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/2387
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/2387
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=yakkety/2387
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2361
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2361/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2361
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2361/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2361
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2361/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/2361
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/2361/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2361
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2361/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2361
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2361/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1849/rebuild

review: Approve (continuous-integration)

[Alan Griffiths (alan-griffiths)]

OK

review: Approve

[Kevin DuBois (kdub)]

lgtm too, although once RS goes public, I'd guess we will get rid of eglflash_render_surface, and just make eglapp.c use RS?

review: Approve

[Cemil Azizoglu (cemil-azizoglu)]

> lgtm too, although once RS goes public, I'd guess we will get rid of
> eglflash_render_surface, and just make eglapp.c use RS?

As I mentioned in the description :

"These will be removed once the headers become public. Instead, RS support will be added to 'examples' activated by a switch."

So yeah a switch in eglapp.c, e.g..

[Mir CI Bot (mir-ci-bot)]

PASSED: Continuous integration, rev:3751
https://mir-jenkins.ubuntu.com/job/mir-ci/1960/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/2502
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/2565
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=vivid+overlay/2557
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/2557
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=yakkety/2557
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2531
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=yakkety/2531/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2531
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/2531/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2531
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=yakkety/2531/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/2531
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=android,release=vivid+overlay/2531/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2531
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=android,release=vivid+overlay/2531/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2531
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/2531/artifact/output/*zip*/output.zip

Click here to trigger a rebuild:
https://mir-jenkins.ubuntu.com/job/mir-ci/1960/rebuild

review: Approve (continuous-integration)

=== modified file 'playground/CMakeLists.txt'
--- playground/CMakeLists.txt	2016-08-09 08:13:02 +0000
+++ playground/CMakeLists.txt	2016-10-12 21:50:47 +0000
@@ -37,3 +37,22 @@
 target_link_libraries(mir_demo_client_chain_jumping_buffers
     mirclient
 )
+
+mir_add_wrapped_executable(mir_demo_client_render_surface
+  render_surface.cpp
+)
+
+target_link_libraries(mir_demo_client_render_surface
+    mirclient
+    eglapp
+)
+
+mir_add_wrapped_executable(mir_demo_client_eglflash_render_surface
+    eglflash_render_surface.c
+)
+
+target_link_libraries(mir_demo_client_eglflash_render_surface
+    mirclient
+    ${EGL_LIBRARIES}
+    ${GLESv2_LIBRARIES}
+)

=== modified file 'playground/README'
--- playground/README	2014-09-10 01:45:14 +0000
+++ playground/README	2016-10-12 21:50:47 +0000
@@ -1,6 +1,5 @@
 The Playground
 
-These are mir demos that excercise private in-flux mir functionality.
-As such functionality matures, related headers become public and the playground
-code may become an example of how to use such feature.
-
+These are mir demos that exercise private, in-flux mir functionality. As such
+functionality matures, related headers become public and the relevant playground
+code may be moved to 'examples/'.

=== added file 'playground/eglflash_render_surface.c'
--- playground/eglflash_render_surface.c	1970-01-01 00:00:00 +0000
+++ playground/eglflash_render_surface.c	2016-10-12 21:50:47 +0000
@@ -0,0 +1,176 @@
+/*
+ * Trivial GL demo; flashes the screen with colors using a MirRenderSurface.
+ *
+ * Copyright © 2016 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/>.
+ *
+ * Author: Daniel van Vugt <[e-mail]>
+ *         Cemil Azizoglu <[e-mail]>
+ */
+
+#include "mir_toolkit/mir_client_library.h"
+#include "mir_toolkit/mir_render_surface.h"
+
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+#include <signal.h>
+#include <pthread.h>
+#include <EGL/egl.h>
+#include <GLES2/gl2.h>
+
+static volatile sig_atomic_t running = 0;
+
+static void shutdown(int signum)
+{
+    if (running)
+    {
+        running = 0;
+        printf("Signal %d received. Good night.\n", signum);
+    }
+}
+
+typedef struct Color
+{
+    GLfloat r, g, b, a;
+} Color;
+
+#define CHECK(_cond, _err) \
+    if (!(_cond)) \
+    { \
+       printf("%s\n", (_err)); \
+       return -1; \
+    }
+
+int main(int argc, char *argv[])
+{
+    (void) argc;
+    (void) argv;
+    const char* appname = "EGL Render Surface Demo";
+    int width = 100;
+    int height = 100;
+    EGLDisplay egldisplay;
+    EGLSurface eglsurface;
+    EGLint ctxattribs[] =
+    {
+        EGL_CONTEXT_CLIENT_VERSION, 2,
+        EGL_NONE
+    };
+    EGLContext eglctx;
+    EGLConfig eglconfig;
+    EGLint neglconfigs;
+    EGLBoolean ok;
+    MirConnection* connection = NULL;
+    MirSurface* surface = NULL;
+    MirRenderSurface* render_surface = NULL;
+
+    signal(SIGINT, shutdown);
+    signal(SIGTERM, shutdown);
+    signal(SIGHUP, shutdown);
+
+    connection = mir_connect_sync(NULL, appname);
+    CHECK(mir_connection_is_valid(connection), "Can't get connection");
+
+    egldisplay = eglGetDisplay(
+                    mir_connection_get_egl_native_display(connection));
+    CHECK(egldisplay != EGL_NO_DISPLAY, "Can't eglGetDisplay");
+
+    ok = eglInitialize(egldisplay, NULL, NULL);
+    CHECK(ok, "Can't eglInitialize");
+
+    const EGLint attribs[] =
+    {
+        EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
+        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
+        EGL_RED_SIZE, 8,
+        EGL_GREEN_SIZE, 8,
+        EGL_BLUE_SIZE, 8,
+        EGL_ALPHA_SIZE, 8,
+        EGL_NONE
+    };
+
+    ok = eglChooseConfig(egldisplay, attribs, &eglconfig, 1, &neglconfigs);
+    CHECK(ok, "Could not eglChooseConfig");
+    CHECK(neglconfigs > 0, "No EGL config available");
+
+    MirPixelFormat pixel_format =
+        mir_connection_get_egl_pixel_format(connection, egldisplay, eglconfig);
+
+    printf("Mir chose pixel format %d.\n", pixel_format);
+
+    MirSurfaceSpec *spec =
+        mir_connection_create_spec_for_normal_surface(connection, width, height, pixel_format);
+    CHECK(spec, "Can't create a surface spec");
+
+    mir_surface_spec_set_name(spec, appname);
+    mir_surface_spec_set_buffer_usage(spec, mir_buffer_usage_hardware);
+
+    render_surface = mir_connection_create_render_surface(connection);
+    CHECK(mir_render_surface_is_valid(render_surface), "could not create render surface");
+
+    MirBufferStream* buffer_stream =
+        mir_render_surface_create_buffer_stream_sync(render_surface,
+                                                     width, height,
+                                                     pixel_format,
+                                                     mir_buffer_usage_hardware);
+
+    mir_surface_spec_add_render_surface(spec, render_surface, width, height, 0, 0);
+
+    surface = mir_surface_create_sync(spec);
+
+    mir_surface_spec_release(spec);
+
+    eglsurface = eglCreateWindowSurface(egldisplay, eglconfig,
+        (EGLNativeWindowType)render_surface, NULL);
+    CHECK(eglsurface != EGL_NO_SURFACE, "eglCreateWindowSurface failed");
+
+    eglctx = eglCreateContext(egldisplay, eglconfig, EGL_NO_CONTEXT,
+                              ctxattribs);
+    CHECK(eglctx != EGL_NO_CONTEXT, "eglCreateContext failed");
+
+    ok = eglMakeCurrent(egldisplay, eglsurface, eglsurface, eglctx);
+    CHECK(ok, "Can't eglMakeCurrent");
+
+    Color red = {1.0f, 0.0f, 0.0f, 1.0f};
+    Color green = {0.0f, 1.0f, 0.0f, 1.0f};
+    Color blue = {0.0f, 0.0f, 1.0f, 1.0f};
+
+    running = 1;
+    while (running)
+    {
+        glClearColor(red.r, red.g, red.b, red.a);
+        glClear(GL_COLOR_BUFFER_BIT);
+        eglSwapBuffers(egldisplay, eglsurface);
+        sleep(1);
+
+        glClearColor(green.r, green.g, green.b, green.a);
+        glClear(GL_COLOR_BUFFER_BIT);
+        eglSwapBuffers(egldisplay, eglsurface);
+        sleep(1);
+
+        glClearColor(blue.r, blue.g, blue.b, blue.a);
+        glClear(GL_COLOR_BUFFER_BIT);
+        eglSwapBuffers(egldisplay, eglsurface);
+        sleep(1);
+    }
+
+    eglMakeCurrent(egldisplay, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
+    eglTerminate(egldisplay);
+    mir_buffer_stream_release_sync(buffer_stream);
+    mir_render_surface_release(render_surface);
+    mir_surface_release_sync(surface);
+    mir_connection_release(connection);
+
+    return 0;
+}

=== added file 'playground/render_surface.cpp'
--- playground/render_surface.cpp	1970-01-01 00:00:00 +0000
+++ playground/render_surface.cpp	2016-10-12 21:50:47 +0000
@@ -0,0 +1,255 @@
+/*
+ * Copyright © 2016 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/>.
+ *
+ * Author: Christopher James Halse Rogers <[e-mail]>
+ *         Cemil Azizoglu <[e-mail]>
+ */
+
+#include <boost/program_options.hpp>
+#include <iostream>
+#include <thread>
+#include <signal.h>
+#include <sys/signalfd.h>
+#include <poll.h>
+
+#include "mir_toolkit/mir_client_library.h"
+#include "mir_toolkit/mir_render_surface.h"
+
+#include "client_helpers.h"
+
+namespace me = mir::examples;
+
+class Pixel
+{
+public:
+    Pixel(void* addr, MirPixelFormat format)
+        : addr{addr},
+          format{format}
+    {
+    }
+
+    void write(int r, int g, int b, int a)
+    {
+        switch (format)
+        {
+        case mir_pixel_format_abgr_8888:
+            *((uint32_t*) addr) =
+                (uint32_t) a << 24 |
+                (uint32_t) b << 16 |
+                (uint32_t) g << 8 |
+                (uint32_t) r;
+            break;
+        case mir_pixel_format_xbgr_8888:
+            *((uint32_t*) addr) =
+                /* Not filling in the X byte is correct but buggy (LP: #1423462) */
+                (uint32_t) b << 16 |
+                (uint32_t) g << 8 |
+                (uint32_t) r;
+            break;
+        case mir_pixel_format_argb_8888:
+            *((uint32_t*) addr) =
+                (uint32_t) a << 24 |
+                (uint32_t) r << 16 |
+                (uint32_t) g << 8 |
+                (uint32_t) b;
+            break;
+        case mir_pixel_format_xrgb_8888:
+            *((uint32_t*) addr) =
+                /* Not filling in the X byte is correct but buggy (LP: #1423462) */
+                (uint32_t) r << 16 |
+                (uint32_t) g << 8 |
+                (uint32_t) b;
+            break;
+        case mir_pixel_format_rgb_888:
+            *((uint8_t*) addr) = r;
+            *((uint8_t*) addr + 1) = g;
+            *((uint8_t*) addr + 2) = b;
+            break;
+        case mir_pixel_format_bgr_888:
+            *((uint8_t*) addr) = b;
+            *((uint8_t*) addr + 1) = g;
+            *((uint8_t*) addr + 2) = r;
+            break;
+        default:
+            throw std::runtime_error{"Pixel format unsupported by Pixel::write!"};
+        }
+    }
+
+public:
+    void* const addr;
+    MirPixelFormat const format;
+};
+
+class pixel_iterator : std::iterator<std::random_access_iterator_tag, Pixel>
+{
+public:
+    pixel_iterator(MirGraphicsRegion const& region, int x, int y)
+        : x{x},
+          y{y},
+          buffer(region)
+    {
+    }
+
+    pixel_iterator(MirGraphicsRegion const& region)
+       : pixel_iterator(region, 0, 0)
+    {
+    }
+
+
+    pixel_iterator& operator++()
+    {
+        x++;
+        if (x == buffer.width)
+        {
+            x = 0;
+            y++;
+        }
+        return *this;
+    }
+    pixel_iterator operator++(int)
+    {
+        auto old = *this;
+        ++(*this);
+        return old;
+    }
+
+    Pixel operator*() const
+    {
+        return Pixel{
+            buffer.vaddr + (x * MIR_BYTES_PER_PIXEL(buffer.pixel_format))
+                         + (y * buffer.stride), buffer.pixel_format};
+    }
+
+    bool operator==(pixel_iterator const& rhs)
+    {
+        return rhs.buffer.vaddr == buffer.vaddr &&
+               rhs.x == x &&
+               rhs.y == y;
+    }
+
+    bool operator!=(pixel_iterator const& rhs)
+    {
+        return !(*this == rhs);
+    }
+
+private:
+    int x, y;
+    MirGraphicsRegion const buffer;
+};
+
+pixel_iterator begin(MirGraphicsRegion const& region)
+{
+    return pixel_iterator(region);
+}
+
+pixel_iterator end(MirGraphicsRegion const& region)
+{
+    return pixel_iterator{region, 0, region.height};
+}
+
+void fill_stream_with(MirBufferStream* stream, int r, int g, int b, int a)
+{
+    MirGraphicsRegion buffer;
+    mir_buffer_stream_get_graphics_region(stream, &buffer);
+
+    for (auto pixel : buffer)
+    {
+        pixel.write(r, g, b, a);
+    }
+}
+
+void bounce_position(int& position, int& delta, int min, int max)
+{
+    if (position <= min || position >= max)
+    {
+        delta = -delta;
+    }
+    position += delta;
+}
+
+int main(int /*argc*/, char* /*argv*/[])
+{
+    char const* socket = nullptr;
+    int const width = 200;
+    int const height = 200;
+    int baseColour = 255, dbase = 1;
+    unsigned int nformats{0};
+    MirPixelFormat pixel_format;
+
+    me::Connection connection{socket, "MirRenderSurface example"};
+
+    mir_connection_get_available_surface_formats(connection, &pixel_format, 1, &nformats);
+    if (nformats == 0)
+        throw std::runtime_error("no pixel formats for buffer stream");
+    printf("Mir selected pixel format %d\n", pixel_format);
+
+    auto render_surface = mir_connection_create_render_surface(connection);
+
+    if (!mir_render_surface_is_valid(render_surface))
+        throw std::runtime_error(std::string("could not create render surface"));
+
+    auto spec = mir_connection_create_spec_for_normal_surface(
+        connection,
+        width, height,
+        pixel_format);
+
+    mir_surface_spec_set_name(spec, "Stream");
+    mir_surface_spec_set_buffer_usage(spec, mir_buffer_usage_software);
+
+    auto buffer_stream =
+        mir_render_surface_create_buffer_stream_sync(render_surface,
+                                                     width, height,
+                                                     pixel_format,
+                                                     mir_buffer_usage_software);
+
+    mir_surface_spec_add_render_surface(spec, render_surface, width, height, 0, 0);
+
+    auto surface = mir_surface_create_sync(spec);
+    mir_surface_spec_release(spec);
+
+    fill_stream_with(buffer_stream, 255, 0, 0, 128);
+    mir_buffer_stream_swap_buffers_sync(buffer_stream);
+
+    sigset_t halt_signals;
+    sigemptyset(&halt_signals);
+    sigaddset(&halt_signals, SIGTERM);
+    sigaddset(&halt_signals, SIGQUIT);
+    sigaddset(&halt_signals, SIGINT);
+
+    sigprocmask(SIG_BLOCK, &halt_signals, nullptr);
+    int const signal_watch{signalfd(-1, &halt_signals, SFD_CLOEXEC)};
+
+    pollfd signal_poll{
+        signal_watch,
+        POLLIN | POLLERR,
+        0
+    };
+
+    while (poll(&signal_poll, 1, 0) <= 0)
+    {
+        bounce_position(baseColour, dbase, 128, 255);
+
+        fill_stream_with(buffer_stream, baseColour, 0, 0, 128);
+
+        mir_buffer_stream_swap_buffers_sync(buffer_stream);
+    }
+
+    mir_buffer_stream_release_sync(buffer_stream);
+    mir_render_surface_release(render_surface);
+    mir_surface_release_sync(surface);
+    close(signal_watch);
+
+    return 0;
+}