MMDevice: adds functions to XYStage and Stage to let them signal whether they use callbacks

MMCore/Devices/StageInstance.cpp

@@ -60,6 +60,7 @@ StageInstance::SetFocusDirection(MM::FocusDirection direction)
    focusDirectionHasBeenSet_ = true;
 }
 
+int StageInstance::UsesOnStagePositionChanged(bool& result) const { RequireInitialized(__func__); return GetImpl()->UsesOnStagePositionChanged(result); }
 int StageInstance::IsStageSequenceable(bool& isSequenceable) const { RequireInitialized(__func__); return GetImpl()->IsStageSequenceable(isSequenceable); }
 int StageInstance::IsStageLinearSequenceable(bool& isSequenceable) const { RequireInitialized(__func__); return GetImpl()->IsStageLinearSequenceable(isSequenceable); }
 bool StageInstance::IsContinuousFocusDrive() const { RequireInitialized(__func__); return GetImpl()->IsContinuousFocusDrive(); }

MMCore/Devices/StageInstance.h

@@ -57,6 +57,7 @@ class StageInstance : public DeviceInstanceBase<MM::Stage>
    int GetLimits(double& lower, double& upper);
    MM::FocusDirection GetFocusDirection();
    void SetFocusDirection(MM::FocusDirection direction);
+   int UsesOnStagePositionChanged(bool& result) const;
    int IsStageSequenceable(bool& isSequenceable) const;
    int IsStageLinearSequenceable(bool& isSequenceable) const;
    bool IsContinuousFocusDrive() const;

MMCore/Devices/XYStageInstance.cpp

@@ -42,6 +42,7 @@ int XYStageInstance::SetYOrigin() { RequireInitialized(__func__); return GetImpl
 int XYStageInstance::GetStepLimits(long& xMin, long& xMax, long& yMin, long& yMax) { RequireInitialized(__func__); return GetImpl()->GetStepLimits(xMin, xMax, yMin, yMax); }
 double XYStageInstance::GetStepSizeXUm() { RequireInitialized(__func__); return GetImpl()->GetStepSizeXUm(); }
 double XYStageInstance::GetStepSizeYUm() { RequireInitialized(__func__); return GetImpl()->GetStepSizeYUm(); }
+int XYStageInstance::UsesOnXYStagePositionChanged(bool& result) const { RequireInitialized(__func__); return GetImpl()->UsesOnXYStagePositionChanged(result); }
 int XYStageInstance::IsXYStageSequenceable(bool& isSequenceable) const { RequireInitialized(__func__); return GetImpl()->IsXYStageSequenceable(isSequenceable); }
 int XYStageInstance::GetXYStageSequenceMaxLength(long& nrEvents) const { RequireInitialized(__func__); return GetImpl()->GetXYStageSequenceMaxLength(nrEvents); }
 int XYStageInstance::StartXYStageSequence() { RequireInitialized(__func__); return GetImpl()->StartXYStageSequence(); }

MMCore/Devices/XYStageInstance.h

@@ -56,6 +56,7 @@ class XYStageInstance : public DeviceInstanceBase<MM::XYStage>
    int GetStepLimits(long& xMin, long& xMax, long& yMin, long& yMax);
    double GetStepSizeXUm();
    double GetStepSizeYUm();
+   int UsesOnXYStagePositionChanged(bool& result) const;
    int IsXYStageSequenceable(bool& isSequenceable) const;
    int GetXYStageSequenceMaxLength(long& nrEvents) const;
    int StartXYStageSequence();

MMCore/MMCore.cpp

@@ -106,7 +106,7 @@ namespace mmi = mmcore::internal;
  * (Keep the 3 numbers on one line to make it easier to look at diffs when
  * merging/rebasing.)
  */
-const int MMCore_versionMajor = 11, MMCore_versionMinor = 11, MMCore_versionPatch = 0;
+const int MMCore_versionMajor = 11, MMCore_versionMinor = 12, MMCore_versionPatch = 0;
 
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -2265,6 +2265,24 @@ void CMMCore::loadExposureSequence(const char* cameraLabel, std::vector<double>
       throw CMMError(getDeviceErrorText(ret, pCamera));
 }
 
+/**
+* Queries whether this stage uses callbacks to signal position changes
+* When false, use polling to stay updated about the positionf of the stage
+*/
+bool CMMCore::isStageUsingCallbacks(const char* label) MMCORE_LEGACY_THROW(CMMError)
+{
+   std::shared_ptr<mmi::StageInstance> pStage =
+      deviceManager_->GetDeviceOfType<mmi::StageInstance>(label);
+
+   mmi::DeviceModuleLockGuard guard(pStage);
+
+   bool result;
+   int ret = pStage->UsesOnStagePositionChanged(result);
+   if (ret != DEVICE_OK)
+      throw CMMError(getDeviceErrorText(ret, pStage));
+   return result;
+}
+
 
 /**
  * Queries stage if it can be used in a sequence
@@ -2417,6 +2435,26 @@ void CMMCore::setStageLinearSequence(const char* label, double dZ_um, int nSlice
       throw CMMError(getDeviceErrorText(ret, pStage));
 }
 
+
+/**
+* Queries whether this XYStage uses callbacks to signal position changes
+* When false, use polling to stay updated about the positionf of the stage
+*/
+bool CMMCore::isXYStageUsingCallbacks(const char* label) MMCORE_LEGACY_THROW(CMMError)
+{
+   std::shared_ptr<mmi::XYStageInstance> pStage =
+      deviceManager_->GetDeviceOfType<mmi::XYStageInstance>(label);
+
+   mmi::DeviceModuleLockGuard guard(pStage);
+
+   bool result;
+   int ret = pStage->UsesOnXYStagePositionChanged(result);
+   if (ret != DEVICE_OK)
+      throw CMMError(getDeviceErrorText(ret, pStage));
+
+   return result;
+}
+
 /**
  * Queries XY stage if it can be used in a sequence
  * @param label    the XY stage device label

MMCore/MMCore.h

@@ -499,6 +499,7 @@ class CMMCore
    void setFocusDirection(const char* stageLabel, int sign);
    int getFocusDirection(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
 
+   bool isStageUsingCallbacks(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
    bool isStageSequenceable(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
    bool isStageLinearSequenceable(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
    void startStageSequence(const char* stageLabel) MMCORE_LEGACY_THROW(CMMError);
@@ -536,6 +537,7 @@ class CMMCore
          double newXUm, double newYUm) MMCORE_LEGACY_THROW(CMMError);
    void setAdapterOriginXY(double newXUm, double newYUm) MMCORE_LEGACY_THROW(CMMError);
 
+   bool isXYStageUsingCallbacks(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);
    bool isXYStageSequenceable(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);
    void startXYStageSequence(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);
    void stopXYStageSequence(const char* xyStageLabel) MMCORE_LEGACY_THROW(CMMError);

MMDevice/DeviceBase.h

@@ -1893,6 +1893,15 @@ class CStageBase : public CDeviceBase<MM::Stage, U>
       return DEVICE_OK;
    }
 
+   /**
+   * @brief Return true when your device adapter uses OnStagePositionChanged callbacks.
+   */
+   virtual int UsesOnStagePositionChanged(bool& result) const
+   {
+      result = false;
+      return DEVICE_OK;
+   }
+
    virtual int IsStageLinearSequenceable(bool& isSequenceable) const
    {
       isSequenceable = false;
@@ -2103,6 +2112,15 @@ class CXYStageBase : public CDeviceBase<MM::XYStage, U>
       return this->SetPositionSteps(xSteps+x, ySteps+y);
    }
 
+   /**
+    * @brief Return true when your device adapter uses OnXYStagePositionChanged callbacks.
+   */
+   virtual int UsesOnXYStagePositionChanged(bool& result) const
+   {
+      result = false;
+      return DEVICE_OK;
+   }
+
    virtual int Move(double /*vx*/, double /*vy*/)
    {
       return DEVICE_UNSUPPORTED_COMMAND;

MMDevice/MMDevice.h

@@ -28,7 +28,7 @@
 // Header version
 // If any of the class definitions changes, the interface version
 // must be incremented
-#define DEVICE_INTERFACE_VERSION 74
+#define DEVICE_INTERFACE_VERSION 75
 ///////////////////////////////////////////////////////////////////////////////
 
 // N.B.
@@ -603,6 +603,15 @@ namespace MM {
       virtual int SetOrigin() = 0;
       virtual int GetLimits(double& lower, double& upper) = 0;
 
+      /**
+      * @brief Stages can use the OnStagePositionChanged callback to signal
+      * updates about their position.  Some adapters do so, others do not,
+      * in which case the UI code should use polling.  This function signals whether
+      * the device adapters uses callbacks, so that the UI knows it does not need
+      * to poll this device
+      */
+      virtual int UsesOnStagePositionChanged(bool& result) const = 0;
+
       /**
        * @brief Return the focus direction.
        *
@@ -709,6 +718,15 @@ namespace MM {
       virtual int Home() = 0;
       virtual int Stop() = 0;
 
+      /**
+      * @brief XY stages can use the OnXYStagePositionChanged callback to signal
+      * updates about their position.  Some stage adapters do so, others do not,
+      * in which case the UI code can use polling.  This function signals whether
+      * the device adapters uses callbacks, so that the UI knows it does not need
+      * to poll this device
+      */
+      virtual int UsesOnXYStagePositionChanged(bool &result) const = 0;
+
       /**
        * @brief Define the current position as the (hardware) origin (0, 0).
        */