Merge lp:~vanvugt/mir/manual-vsync-api-v2 into lp:mir

[Daniel van Vugt]

Introducing a trivial API function that allows clients to throttle
themselves without ever blocking inside thirdparty code:
mir_window_get_microseconds_till_vblank

The intended methodology is for a client to set swap interval zero
and then use this new function to throttle its own swaps.

The intended use cases are:
 * Toolkits/apps that have an existing event loop (particularly
   single threaded ones) and don't want anything that complicates
   that architecture, but do want synchronized/throttled rendering.
 * Existing single-threaded users (Xmir only?) of the asynchronous
   mir_buffer_stream_swap_buffers(), can continue to have vsync and
   asynchronous buffer returns, and single-threaded simplicity,
   without putting a queuing/threading burden on libmirclient to
   throttle buffer returns at all. The existing client event loop can
   be used instead.

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

PASSED: Continuous integration, rev:4167
https://mir-jenkins.ubuntu.com/job/mir-ci/3380/
Executed test runs:
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-mir/4574
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-0-fetch/4700
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=xenial+overlay/4689
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-1-sourcepkg/release=zesty/4689
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/4606
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=clang,platform=mesa,release=zesty/4606/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/4606
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=xenial+overlay/4606/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/4606
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=amd64,compiler=gcc,platform=mesa,release=zesty/4606/artifact/output/*zip*/output.zip
    SUCCESS: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=zesty/4606
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=cross-armhf,compiler=gcc,platform=mesa,release=zesty/4606/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/4606
        deb: https://mir-jenkins.ubuntu.com/job/build-2-binpkg-mir/arch=i386,compiler=gcc,platform=mesa,release=xenial+overlay/4606/artifact/output/*zip*/output.zip

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

review: Approve (continuous-integration)

Unmerged revisions

4167. By Daniel van Vugt on 2017-04-27

Rename the new unit test to match what it actually does

4166. By Daniel van Vugt on 2017-04-27

Use the new feature in examples and fix up C symbol exports.

4165. By Daniel van Vugt on 2017-04-27

And use the new function

4164. By Daniel van Vugt on 2017-04-27

Implement a new FrameClock method for the new API, which eases unit
testing and is crucially also right... so the test now passes.

4163. By Daniel van Vugt on 2017-04-27

Reintroduce and rewrite the unit test

4162. By Daniel van Vugt on 2017-04-27

Revert back to a simpler algorithm

4161. By Daniel van Vugt on 2017-04-27

A little progress

4160. By Daniel van Vugt on 2017-04-26

A new approach. Needs testing...

4159. By Daniel van Vugt on 2017-04-26

Drop the new unit test

4158. By Daniel van Vugt on 2017-04-26

Add a unit test for the expected behaviour from the new MirWindow
function... presently failing.

=== modified file 'examples/eglapp.c'
--- examples/eglapp.c	2017-04-05 03:11:28 +0000
+++ examples/eglapp.c	2017-04-27 08:36:53 +0000
@@ -22,6 +22,7 @@
 #include <stdlib.h>
 #include <signal.h>
 #include <time.h>
+#include <errno.h>
 #include <string.h>
 #include <EGL/egl.h>
 #include <GLES2/gl2.h>
@@ -38,6 +39,7 @@
 static EGLSurface eglsurface;
 static volatile sig_atomic_t running = 0;
 static double refresh_rate = 0.0;
+static mir_eglapp_bool alt_vsync = 0;
 
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
@@ -84,6 +86,15 @@
     return running;
 }
 
+/* Apparently usleep is deprecated so we write own own... */
+static void micro_sleep(unsigned long usec)
+{
+    struct timespec ts = {0, usec * 1000};
+    while (nanosleep(&ts, &ts) && errno == EINTR)
+    {
+    }
+}
+
 void mir_eglapp_swap_buffers(void)
 {
     EGLint width, height;
@@ -92,6 +103,8 @@
         return;
 
     eglSwapBuffers(egldisplay, eglsurface);
+    if (alt_vsync)
+        micro_sleep(mir_window_get_microseconds_till_vblank(window));
 
     /*
      * Querying the surface (actually the current buffer) dimensions here is
@@ -347,6 +360,7 @@
         {"-h", "!", &help, "Show this help text"},
         {"-m <socket>", "=", &mir_socket, "Mir server socket"},
         {"-n", "!", &no_vsync, "Don't sync to vblank"},
+        {"-v", "!", &alt_vsync, "Sync to vblank using the alternate method (manual timing)"},
         {"-o <id>", "%u", &output_id, "Force placement on output monitor ID"},
         {"-q", "!", &quiet, "Quiet mode (no messages output)"},
         {"-s <width>x<height>", "=", &dims, "Force window size"},
@@ -372,7 +386,7 @@
         return 0;
     }
 
-    if (no_vsync)
+    if (no_vsync || alt_vsync)
         swapinterval = 0;
 
     if (dims)

=== modified file 'include/client/mir_toolkit/mir_window.h'
--- include/client/mir_toolkit/mir_window.h	2017-04-13 07:00:27 +0000
+++ include/client/mir_toolkit/mir_window.h	2017-04-27 08:36:53 +0000
@@ -859,6 +859,22 @@
 MirPersistentId* mir_window_request_persistent_id_sync(MirWindow* window)
 __attribute__((deprecated("Use mir_window_request_window_id_sync")));
 MirWindowId* mir_window_request_window_id_sync(MirWindow* window);
+
+/**
+ * Query the approximate time interval in microseconds until the next vblank for
+ * a given window (actually the next vblank for the monitor deemed most
+ * relevant to the window's current placement). A relative time is returned so
+ * as to avoid clock/API portability issues. And microsecond precision is used
+ * because it's the largest unit of time that still provides ample precision
+ * to be a few orders or magnitude more precise than human perception, or than
+ * the refresh inverval of display hardware).
+ *
+ *   \param [in] w  The MirWindow
+ *   \return        Time in microseconds to the next vblank for the given
+ *                  window (may be as low as zero).
+ */
+unsigned long mir_window_get_microseconds_till_vblank(MirWindow const* w);
+
 #ifdef __cplusplus
 }
 /**@}*/

=== modified file 'src/client/frame_clock.cpp'
--- src/client/frame_clock.cpp	2016-11-29 08:00:45 +0000
+++ src/client/frame_clock.cpp	2017-04-27 08:36:53 +0000
@@ -154,3 +154,13 @@
 
     return target;
 }
+
+PosixTimestamp FrameClock::next_frame_after_now() const
+{
+    auto result = next_frame_after({});
+    auto const now = get_current_time(result.clock_id);
+    if (result <= now)
+        result = next_frame_after(now);  
+    return result;
+}
+

=== modified file 'src/client/frame_clock.h'
--- src/client/frame_clock.h	2016-12-15 08:15:54 +0000
+++ src/client/frame_clock.h	2017-04-27 08:36:53 +0000
@@ -57,6 +57,14 @@
      */
     time::PosixTimestamp next_frame_after(time::PosixTimestamp prev) const;
 
+    /**
+     * Return the next frame that's in the future. This is a simplified
+     * stateless version of next_frame_after() with the caveat that it lacks
+     * the ability to detect and catch up missed frames (because there is no
+     * state information indicating which frame deadline the caller last met).
+     */
+    time::PosixTimestamp next_frame_after_now() const;
+
 private:
     time::PosixTimestamp fallback_resync_callback() const;
 

=== modified file 'src/client/mir_surface.cpp'
--- src/client/mir_surface.cpp	2017-04-13 07:00:27 +0000
+++ src/client/mir_surface.cpp	2017-04-27 08:36:53 +0000
@@ -238,6 +238,22 @@
      */
 }
 
+std::chrono::microseconds MirSurface::microseconds_till_vblank() const
+{
+    std::chrono::microseconds ret(0);
+
+    auto const target = frame_clock->next_frame_after_now();
+    auto const now = mir::time::PosixTimestamp::now(target.clock_id);
+
+    if (target > now)
+    {
+        auto const delta = target - now;
+        ret = std::chrono::duration_cast<std::chrono::microseconds>(delta);
+    }
+
+    return ret;
+}
+
 MirWindowParameters MirSurface::get_parameters() const
 {
     std::lock_guard<decltype(mutex)> lock(mutex);

=== modified file 'src/client/mir_surface.h'
--- src/client/mir_surface.h	2017-04-13 07:00:27 +0000
+++ src/client/mir_surface.h	2017-04-27 08:36:53 +0000
@@ -224,6 +224,8 @@
     std::shared_ptr<mir::client::FrameClock> get_frame_clock() const;
     std::shared_ptr<mir::input::receiver::XKBMapper> get_keymapper() const;
 
+    std::chrono::microseconds microseconds_till_vblank() const;
+
 private:
     std::mutex mutable mutex; // Protects all members of *this
 

=== modified file 'src/client/mir_surface_api.cpp'
--- src/client/mir_surface_api.cpp	2017-04-13 07:00:27 +0000
+++ src/client/mir_surface_api.cpp	2017-04-27 08:36:53 +0000
@@ -1385,3 +1385,8 @@
         wh->wait_for_all();
     return result;
 }
+
+unsigned long mir_window_get_microseconds_till_vblank(MirWindow const* w)
+{
+    return w->microseconds_till_vblank().count();
+}

=== modified file 'src/client/symbols.map'
--- src/client/symbols.map	2017-04-13 07:00:27 +0000
+++ src/client/symbols.map	2017-04-27 08:36:53 +0000
@@ -579,7 +579,7 @@
     };
 } MIR_CLIENT_DETAIL_0.26.1;
 
-MIR_CLIENT_0.27 {  # New functions in Mir 0.27 or 1.0
+MIR_CLIENT_0.27 {  # New functions in Mir 0.27
   global:
     mir_connection_apply_session_input_config;
     mir_connection_set_base_input_config;
@@ -611,3 +611,8 @@
     mir_touchscreen_config_set_mapping_mode;
     mir_touchscreen_config_set_output_id;
 } MIR_CLIENT_0.26.1;
+
+MIR_CLIENT_0.28 {  # New functions in Mir 0.28 (or 1.0)
+  global:
+    mir_window_get_microseconds_till_vblank;
+} MIR_CLIENT_0.27;

=== modified file 'tests/unit-tests/client/test_frame_clock.cpp'
--- tests/unit-tests/client/test_frame_clock.cpp	2017-03-13 08:12:52 +0000
+++ tests/unit-tests/client/test_frame_clock.cpp	2017-04-27 08:36:53 +0000
@@ -426,3 +426,28 @@
     EXPECT_EQ(one_frame, in2 - in1);
     EXPECT_EQ(one_frame, out2 - out1);
 }
+
+TEST_F(FrameClockTest, next_frame_after_now_is_exactly_that)
+{
+    auto const& now = fake_time[CLOCK_MONOTONIC];
+    FrameClock clock(with_fake_time);
+    clock.set_period(one_frame);
+
+    auto a = now;
+    auto b = clock.next_frame_after_now();
+    EXPECT_GE(b, a);
+    EXPECT_LE(b-now, one_frame);
+
+    for (int same = 0; same < 3; ++same)
+        EXPECT_EQ(b, clock.next_frame_after_now()) << "i=" << same;
+
+    fake_sleep_until(b);
+
+    auto c = clock.next_frame_after_now();
+    EXPECT_LT(b, c);
+    EXPECT_EQ(b+one_frame, c);
+    EXPECT_LE(c-now, one_frame);
+
+    for (int same = 0; same < 3; ++same)
+        EXPECT_EQ(c, clock.next_frame_after_now()) << "i=" << same;
+}