PrepareSequenceAcqusition should be removed

[marktsuchida]

It looks like a number of cameras implement PrepareSequenceAcqusition (sic) by calling GetCoreCallback()->PrepareForAcq(this), which opens the shutter when autoshutter is enabled. Given that CMMCore::prepareSequenceAcquisition simply calls the device's PrepareSequenceAcqusition (and is not guaranteed to be followed by startSequenceAcquisition (and even when it is, the latter may fail before scheduling a shutter close)), this is incorrect.

The intended behavior of PrepareSequenceAcqusition (according to the comment on CMMCore::prepareSequenceAcquisition) was to commit the current settings to the camera, or otherwise make preparations, so that a subsequent call to StartSequenceAcquisition will be faster. It looks like very few, if any, camera adapters actually do this (correctly, at least).

Many other cameras, including the CCameraBase default, just return DEVICE_OK. This is harmless.

It also turns out that mmstudio and acqEngine (Clojure) currently do not call prepareSequenceAcquisition anywhere. AcqEngJ and pymmcore-plus each do in one place, but they probably don't rely on the call doing anything.

We already have a mechanism to avoid slow preparation after opening the autoshutter (such preparation should be done in StartSequenceAcquisition but before calling PrepareForAcq), so any advantage offered by (a correctly implemented) PrepareSequenceAcqusition would only be gained if the call were made well in advance, or in parallel with other motion, etc.

Also, among such preparations, reallocating the sequence buffer (V1) can be done explicitly by the application (initializeCircularBuffer). So PrepareSequenceAcqusition should have really been only about committing settings to the camera hardware. Again, this is rarely if ever done. And #593 proposes a new way to handle this (separate Arm + Start).

Given all this, I think we should just deprecate this function in CMMCore, make it a no-op, and remove it from MMDevice.

(Implementations in camera adapters can then be deleted in most cases if not called from within the adapter itself.)

Related: #453.

[henrypinkard]

AcqEngJ and pymmcore-plus each do in one place, but they probably don't rely on the call doing anything.

That's right. I added it because it was part of the core API but it never had any apparent use

Given all this, I think we should just deprecate this function in CMMCore, make it a no-op, and remove it from MMDevice.

agree