kStatus kLight_SetCouplingMode	(	kLight	light,
		kLightCouplingMode	mode
	)

Sets the light coupling mode.

The light coupling mode affects exposure timing when the light control mode is set to kLIGHT_CONTROL_COUPLED_TO_CAMERA. Three coupling modes are supported.

In kLIGHT_COUPLING_MODE_FULL mode, light and camera timing are coordinated to take all lead-in/lead-out timing offsets into account. For example, if the light priming mode is set to kLIGHT_PRIMING_MODE_ALWAYS, then the light will often have a non-zero lead-in time, and this offset will be factored into coupled camera+light exposure timing. Similarly, camera lead-out is taken into account such that the light exposes for the full extent of the camera's nominal exposure time rather than only the physical imager exposure time. The result is that exposures are optimally synchronized between cameras and lights. This is the recommended mode for new applications and may become the default in a future FireSync platform version.

In kLIGHT_COUPLING_MODE_NONE mode, light timing is coupled to physical imager exposure timing. Light lead-in/lead-out are not taken into account in camera or light timing, and camera lead-in/lead-out are not taken into account in light timing. This was the original FireSync platform behavior and (as a result) is still the default behavior. However, this mode is supported for backwards compatibility only.

In kLIGHT_COUPLING_MODE_LEAD_IN mode, light and camera lead-ins are coordinated, but leads-outs are not. This mode was introduced as an intermediate migration step for existing applications. The benefits of this mode are that a) per-frame light priming (kLIGHT_PRIMING_MODE_ALWAYS) can be factored into coupled camera timing, and b) the effective exposure for coupled configurations remains very similar to the original FireSync platform behavior (in contrast with kLIGHT_COUPLING_MODE_FULL, which can increase effective exposure for the same nominal camera exposure value due to lead-out coordination).

This option is not configurable for DM647 (M2, M50) controllers, which only support kLIGHT_COUPLING_MODE_NONE.

Parameters

light	Light object.
mode	Light priming mode.

Returns

Operation status.