Fix PBD::MMTIMER::reset_resolution and add some documentation

timeEndPeriod must be called with the same timer resolution value used in
timeBeginPeriod. When the process exits the timer resolution is restored anyway
so this is not very important.

2 files changed, 47 insertions, 47 deletions

diff --git a/libs/pbd/pbd/windows_timer_utils.h b/libs/pbd/pbd/windows_timer_utils.h
index 2e4f800bd5..72d3cc5431 100644
--- a/libs/pbd/pbd/windows_timer_utils.h
+++ b/libs/pbd/pbd/windows_timer_utils.h
@@ -26,30 +26,34 @@ namespace PBD {
 namespace MMTIMERS {
 
 /**
- * Set the minimum Multimedia Timer resolution as supported by the system
- * @return true if min timer resolution was successfully set
- *
- * Call reset_resolution to restore old timer resolution
+ * Get the minimum Multimedia Timer resolution as supported by the system
+ * @return true if getting min timer resolution was not successful
  */
-bool set_min_resolution ();
+bool get_min_resolution (uint32_t& timer_resolution_ms);
 
 /**
- * Get current Multimedia Timer resolution
- * @return true if getting the timer value was successful
+ * Set the minimum Multimedia Timer resolution as supported by the system
+ * @return true if setting min timer resolution was successful
  */
-bool get_resolution(uint32_t& timer_resolution_us);
+bool set_min_resolution ();
 
 /**
- * Set current Multimedia Timer resolution
- * @return true if setting the timer value was successful
+ * Set current Multimedia Timer resolution. If the timer resolution has already
+ * been set then reset_resolution() must be called before set_resolution will
+ * succeed.
+ * @return true if setting the timer value was successful, false if setting the
+ * timer resolution failed or the resolution has already been set.
  */
-bool set_resolution(uint32_t timer_resolution_us);
+bool set_resolution(uint32_t timer_resolution_ms);
 
 /**
- * Reset the Multimedia Timer back to what it was originally before
- * setting the timer resolution.
+ * Reset Multimedia Timer resolution. In my testing, if the timer resolution is
+ * set below the default, then resetting the resolution will not reset the
+ * timer resolution back to 15ms. At least it does not reset immediately
+ * even after calling Sleep.
+ * @return true if setting the timer value was successful
  */
-bool reset_resolution ();
+bool reset_resolution();
 
 } // namespace MMTIMERS
 
diff --git a/libs/pbd/windows_timer_utils.cc b/libs/pbd/windows_timer_utils.cc
index fcf8fa8003..d95a69e0c7 100644
--- a/libs/pbd/windows_timer_utils.cc
+++ b/libs/pbd/windows_timer_utils.cc
@@ -29,20 +29,20 @@
 namespace {
 
 UINT&
-old_timer_resolution ()
+timer_resolution ()
 {
 	static UINT timer_res_ms = 0;
 	return timer_res_ms;
 }
 
-} // anon namespace
+}
 
 namespace PBD {
 
 namespace MMTIMERS {
 
 bool
-set_min_resolution ()
+get_min_resolution (uint32_t& min_resolution_ms)
 {
 	TIMECAPS caps;
 
@@ -50,61 +50,57 @@ set_min_resolution ()
 		DEBUG_TIMING ("Could not get timer device capabilities.\n");
 		return false;
 	}
-	return set_resolution(caps.wPeriodMin);
+
+	min_resolution_ms = caps.wPeriodMin;
+	return true;
 }
 
 bool
-set_resolution (uint32_t timer_resolution_ms)
+set_min_resolution ()
 {
-	TIMECAPS caps;
+	uint32_t min_resolution = 0;
 
-	if (timeGetDevCaps (&caps, sizeof(TIMECAPS)) != TIMERR_NOERROR) {
-		DEBUG_TIMING ("Could not get timer device capabilities.\n");
+	if (!get_min_resolution (min_resolution)) {
 		return false;
 	}
 
-	UINT old_timer_res = caps.wPeriodMin;
-
-	if (timeBeginPeriod(timer_resolution_ms) != TIMERR_NOERROR) {
-		DEBUG_TIMING(
-		    string_compose("Could not set minimum timer resolution to %1(ms)\n",
-		                   timer_resolution_ms));
+	if (!set_resolution (min_resolution)) {
 		return false;
 	}
-
-	old_timer_resolution () = old_timer_res;
-
-	DEBUG_TIMING (string_compose ("Multimedia timer resolution set to %1(ms)\n",
-	                              caps.wPeriodMin));
 	return true;
 }
 
 bool
-get_resolution (uint32_t& timer_resolution_ms)
+set_resolution (uint32_t timer_resolution_ms)
 {
-	TIMECAPS caps;
+	if (timer_resolution() != 0) {
+		DEBUG_TIMING(
+		    "Timer resolution must be reset before setting new resolution.\n");
+	}
 
-	if (timeGetDevCaps(&caps, sizeof(TIMECAPS)) != TIMERR_NOERROR) {
-		DEBUG_TIMING ("Could not get timer device capabilities.\n");
+	if (timeBeginPeriod(timer_resolution_ms) != TIMERR_NOERROR) {
+		DEBUG_TIMING(
+		    string_compose("Could not set timer resolution to %1(ms)\n",
+		                   timer_resolution_ms));
 		return false;
 	}
-	timer_resolution_ms = caps.wPeriodMin;
+
+	timer_resolution() = timer_resolution_ms;
+
+	DEBUG_TIMING (string_compose ("Multimedia timer resolution set to %1(ms)\n",
+	                              timer_resolution_ms));
 	return true;
 }
 
 bool
 reset_resolution ()
 {
-	if (old_timer_resolution ()) {
-		if (timeEndPeriod (old_timer_resolution ()) != TIMERR_NOERROR) {
-			DEBUG_TIMING ("Could not reset timer resolution.\n");
-			return false;
-		}
+	// You must match calls to timeBegin/EndPeriod with the same resolution
+	if (timeEndPeriod(timer_resolution()) != TIMERR_NOERROR) {
+		DEBUG_TIMING("Could not reset the Timer resolution.\n");
+		return false;
 	}
-
-	DEBUG_TIMING (string_compose ("Multimedia timer resolution set to %1(ms)\n",
-	                              old_timer_resolution ()));
-
+	timer_resolution() = 0;
 	return true;
 }