Synchronize

Waits for the synchronization of node values with the camera hardware. Currently the synchronization with the camera hardware can only occur delayed for capture parameters, i.e. all subnodes of the Capture parameter node.

Description of Synchronization Procedure

Synchronization is the process of forwarding a node value in the NxLib parameter tree to the camera hardware and then reading back the parameter from the hardware to write the effective value into the parameter tree.

Examples

  • After writing an Exposure value into the tree you can read back the actual exposure which is clipped by the camera driver to some minimum or maximum and rounded to the hardware specific exposure granularity.

  • After changing the camera’s Binning parameter you can read back if the binning factor was accepted or if it was clipped by the driver to some hardware specific minimum or maximum.

  • (likewise for all other hardware parameters)

When to use the Synchronize command

Normally the described synchronization happens immediately when writing a tree node, but a few commands (listed below) that operate on the hardware will block the immediate parameter updates to the hardware and defer them until the command has finished executing. This is a safety measure to ensure that these commands have exclusive hardware access without interference from other threads.

If your application requires immediate feedback of the actually applied parameters you should either ensure that no commands with exclusive hardware lock are running while you modify the parameters, or you need to run the Synchronize command after modifying the parameters. Synchronize will wait for the hardware locking commands on the specified cameras are finished and ensure that all written parameter values have been forwarded to the driver and the actual values are fed back into the tree nodes. After the Synchronize command you can therefore read back the actual values including clipping and granularity rounding by the hardware driver.

Use Case

Assume you have a multi threaded application where thread 1 continuously captures images with Capture and thread 2 changes the Binning parameter to adjust processing speed and resolution asynchronously.

At some point thread 2 will change the binning value while thread 1 is still capturing. If thread 2 wants to know if the specified binning value was accepted by the current camera hardware it cannot immediately read back the value of the Binning node because thread 1 still runs the Capture command which has exclusive hardware access. That means that the new Binning value was not immediately forwarded to the driver and reading it back immediately will only return the written value, regardless of the hardware capabilities. Only after thread 1 has finished the Capture command the new value of the Binning node is written to the hardware and the actual value is transferred back into the tree node where it can then be read by thread 2.

So before reading back the actual Binning value thread 2 must either wait until no execution slot is running a command with exclusive hardware access or it can simply execute the Synchronize command which will take care of waiting until the specified camera’s parameters are updated from the hardware.

Note

When no command are running, the synchronization with the hardware driver will always happen immediately and the actual hardware value can be read back directly.