Clarifying MMCore sequence acquisition API with explicit camera label

[marktsuchida]

startSequenceAcquisition(label, ...), prepareSequenceAcquisition(label) (deprecated), stopSequenceAcquisition(label), and isSequenceRunning(label).

These have existed for a long time (since pre-2007) but were never robust:

• Originally, startSequenceAcquisition(label, ...) skipped sequence buffer initialization (allocation), meaning that it only worked correctly if explicitly initialized ahead of time. But this did allow two acquisitions to be run at the same time (sharing the sequence buffer — not sure if there was a robust mechanism to distinguish between images from the two cameras). Autoshutter coordination was broken. It should also be noted that this was done before MMCore gained (patchy) thread safety in 2012. The MM 1.4 ASIdiSPIM plugin used (still uses) the API to run two cameras concurrently, I believe.

• In 2023, Fix bug related to changing setting ROIs and starting sequence acquisitions #362 added sequence buffer initialization (contradicting the doc comment stating that the buffer is not initialized). This "fixed" the surprising difference but broke the hacky ability to run multiple cameras (provided same image size, etc.). There is no maintained ASIdiSPIM plugin for MM 2.0, so any breakage there would not have been noticed.

Now that the behavior is to initialize the sequence buffer on every start, concurrent sequence acquisitions are not meaningfully possible. So my interpretation is that future work on MMCore need only preserve behavior when running one acquisition at a time.

In the major refactor in #936 this might need to be taken into account. Specifically, I'm considering changing the label-less stop/isRunning functions to operate on "the acquisition started with label-less startSequenceAcquisition()", as opposed to the current "the acquisition running for the current camera". I don't think this is likely to break any practical code, because switching the current camera is not currently allowed when an acquisition is running on the default camera, but odd usage mixing labeled and label-less functions could change meaning.

(After #936, we may be able to add support for concurrent acquisitions using separate sequence buffers; that will require new CMMCore APIs for retrieving images from a specific acquisition (i.e., we'll need some sort of "handle" to a running acquisition).)

In the current micro-manager repo, ASIRingTIRF and the unsupported/unmaintained beta ASIdiSPIM plugins are the only code that calls these functions. ASIRingTIRF assumes the new (post-2023) behavior so should be easy to keep working (or we can update as needed, since it is in-tree).

This is not really a description of a bug directly but an informational note. Please let me know if you are aware of any situation I haven't taken into account here. @jondaniels @bls337 @ieivanov

[ieivanov]

No objections from me!

[jondaniels]

Zero concern about the ASIdiSPIM plugin in MM2. I expect Brandon can easily change the ASIRingTIRF plugin.