Advanced Signaling

Advanced Signaling Mechanism

In order to achieve the highest level of control over the event flow between the user process and the MultiCam operation, a linkage to the regular Windows events is provided.

The experienced user can use one of the following Windows' API functions.

●

WaitForSingleObject

●

WaitForMultipleObject

●

MsgWaitForMultipleObjects

The application calls these functions with handles to events of any nature, including the MultiCam generated events.

A dedicated MultiCam parameter is included, called SignalEvent. This parameter is a collection of handles to events corresponding to all MultiCam signals.

The events pointed by these handles are set to the signaled state on each corresponding MultiCam signal occurrence. Restoring the events to the non-signaled state is automatically managed by the MultiCam driver.

A MultiCam function called McGetSignalInfo is specifically provided to retrieve all relevant information on a specified signal owned by a specified channel object.

Linkage of MultiCam Signals to Windows Events

To implement an advanced signaling mechanism of his own, the user has to associate a signal to a regular Windows event.

This is realized with an expert-level parameter called SignalEvent.

One such parameter exists for the channel class. It has the MultiCam type "integer collection".

Each item of the collection allows for retrieving the operating system event object associated to the addressed signal.

To address a specific signal, the by-ident parameter access method is used with the SignalEnable parameter belonging to the desired channel object. The parameter getting function is McSetParamInt with a parameter identifier established as follows:

To reach signal...	Use parameter identifier...
Start Exposure	MC_SignalEvent + MC_SIG_START_EXPOSURE
End Exposure	MC_SignalEvent + MC_SIG_END_EXPOSURE
Release (*)	MC_SignalEvent + MC_SIG_RELEASE
Surface Filled	MC_SignalEvent + MC_SIG_SURFACE_FILLED
Surface Processing	MC_SignalEvent + MC_SIG_SURFACE_PROCESSING
Cluster Unavailable	MC_SignalEvent + MC_SIG_CLUSTER_UNAVAILABLE
Acquisition failure	MC_SignalEvent + MC_SIG_ACQUISITION_FAILURE

The retrieved value may be cast into an operating system handle (HANDLE) and subsequently used in any of the following wait functions:

●

WaitForSingleObject

●

WaitForMultipleObject

●

MsgWaitForMultipleObjects

The operating system event is signaled each time an enabled MultiCam signal occurs. Enabling a MultiCam signal is done with the SignalEnable parameter. It is allowed to enable several signals.

When waiting for the Surface Processing signal, it is the application responsibility to reset the SurfaceState parameter of the PROCESSING surface to FREE when done. Failure to do so would prevent the surface from being used by subsequent acquisition phases.

The MultiCam signal information associated with the event may be retrieved by calling the McGetSignalInfo function.

If the advanced signaling mechanism is used, the callback signaling mechanism cannot be used. However, the waiting signaling mechanism can be used as long as the waiting function is not used to wait for an event used by the advanced signaling mechanism.

Example

HANDLE MyHandle;

McSetParamInt(hChannel, MC_SignalEnable + MC_SIG_SURFACE_FILLED, MC_SignalEnable_ON);

McGetParamInt(hChannel, MC_SignalEvent + MC_SIG_SURFACE_FILLED, (int*)&MyHandle);

WaitForSingleObject(MyHandle, INFINITE);