| Customize Help

Using input signals


You can route any external signal that meets electrical specifications, to an auxiliary input signal (or a bidirectional I/O signal set to input); your application can then use it for a specific purpose, as long as the functionality is supported by the auxiliary input signal. For example, if the input signal supports user input (user-defined input), you can poll (inquire) the state of the input signal to monitor or react to its state. Alternatively, if your hardware supports it, you can enable the generation of an interrupt when the user input signal changes state, and then hook a function to it. You can also use an input signal as a trigger for some operation or performing image acquisition. Some Matrox boards can also decode an input from a rotary encoder, which you can use to trigger an event; for more information on rotary decoders, refer to the Using quadrature input from a rotary encoder section later in this chapter.

Depending on your hardware, you will need to use either the Mdig...() functions or the Msys...() functions to use the input signals. For more information on which functions to use and which functionalities are supported by the signals for your hardware, refer to the Connectors and signal names section of the MIL Hardware-specific Notes chapter for your Matrox product.

Polling the state of input signals

For input signals (or bidirectional I/O signals set to input) which support user input, you can use a continuous loop to poll (inquire) the input signal to determine if it is high or low, and then, react to its state or a change in its state. To inquire the current state of one specific I/O signal, use either MdigInquire() or MsysInquire() with M_IO_STATUS.

To inquire the current state of all the I/O signals, use either MdigInquire() or MsysInquire() with M_IO_STATUS_ALL. M_IO_STATUS_ALL returns a bit-encoded value that specifies the current state of each of the input and output signals of your hardware (if their state is inquirable), whereby M_AUX_IO0 is represented by the least-significant bit of the bit-encoded value. For example, inquiring M_IO_STATUS_ALL for auxiliary signals could return 0x44, equivalent to 101100 in binary, which would mean that I/O signals associated with MIL constants M_AUX_IO2, M_AUX_IO3, and M_AUX_IO5 are high, and all other I/O signals are low.

Note that the state of certain signals cannot be inquired (for example, signals exclusively dedicated for triggers). When using M_IO_STATUS_ALL to inquire the status of all the I/O signals, if there are I/O signals that cannot be inquired, the bits representing those signals, in the bit-encoded value returned, are not necessarily valid; these bits should be ignored.

Using interrupts with input signals

If supported in hardware, instead of polling an input signal (that supports user input) to check its state and react to it, you can have a signal generate an interrupt when it changes state. You can then hook a function to this event to perform some operation or action upon this event.

To react to a change in the state of a specified input signal, based on an interrupt, perform the following steps:

  1. Specify whether the input signal should generate an interrupt upon a rising edge, falling edge, or both, using either MdigControl() or MsysControl() with M_IO_INTERRUPT_ACTIVATION + M_AUX_IOn.

  2. Hook a function to the input signal's change of state, using either MdigHookFunction() or MsysHookFunction() with M_IO_CHANGE.

    Within the scope of the hook function itself, inquire which signal(s) generated the interrupt, using either MdigGetHookInfo() or MsysGetHookInfo() with M_IO_INTERRUPT_SOURCE, and then, execute according to the result of the inquiry.

  3. If the signal to be used is a bidirectional signal, set the signal to input mode, using either MdigControl() or MsysControl() with M_IO_MODE + M_AUX_IOn set to M_INPUT.

  4. Enable the interrupt state for the input signal, using M_IO_INTERRUPT_STATE + M_AUX_IOn set to M_ENABLE.

The following code snippet demonstates how to declare your hook handler function and to use an auxiliary input signal (M_AUX_IO8) to generate an interrupt when its state changes from low to high.

/* Hook function declaration. */
MIL_INT MFTYPE HookHandlerFnct(MIL_INT HookType, MIL_ID EventId, void* UserDataPtr)
{
   MIL_INT IOSource = 0;
   MdigGetHookInfo(EventId, M_IO_INTERRUPT_SOURCE, &IOSource);
   // IOSource will be M_AUX_IO8 when interrupt is fired.
   if (IOSource == M_AUX_IO8)
   {
      /* Perform some action.*/
   }      
   return 0;
}   


void UsingInputSignals(MIL_ID MilDigitizer, MIL_ID MilImage)
{
void* HookData = 0;

/* Specify to generate an interrupt upon the low-to-high input signal state transition. */
MdigControl(MilDigitizer, M_IO_INTERRUPT_ACTIVATION + M_AUX_IO8, M_EDGE_RISING);
     
/* Specify to hook a function to the specified interrupt. */
MdigHookFunction(MilDigitizer, M_IO_CHANGE,
                     HookHandlerFnct, (void*) &HookData);

/* Enable the specified interrupt. */
MdigControl(MilDigitizer, M_IO_INTERRUPT_STATE + M_AUX_IO8, M_ENABLE); 

/* ... */

Using input signals as triggers

If supported in hardware, you can use an input signal (or a bidirectional signal set to input) as a trigger source. For example, you can specify to use a specific input signal to trigger a timer using MdigControl() with M_TIMER_TRIGGER_SOURCE set to M_AUX_IOn, or you can use a specific input signal to trigger image acquisition using MdigControl() with M_GRAB_TRIGGER_SOURCE set to M_AUX_IOn. You must establish how to use the signal to trigger, using MdigControl() with M_TIMER_TRIGGER_ACTIVATION or M_GRAB_TRIGGER_ACTIVATION; you can specify whether to generate a trigger upon a signal state transition or to trigger continuously according to signal polarity (high or low state). To use the trigger signal, you must first enable the timer or enable grabbing upon a trigger, so that it is ready to receive a trigger signal; to do so, use MdigControl() with M_TIMER_STATE or M_GRAB_TRIGGER_STATE, respectively.

For information on this topic, see the Grabbing with triggers section of Chapter 25: Grabbing with your digitizer.

The following code snippet demonstrates how to use auxiliary input signal 1 (M_AUX_IO1) to trigger the grab of an image sent from a connected camera.

/* Specify to use an input signal as the trigger source for grabbing an image.*/   
MdigControl(MilDigitizer, M_GRAB_TRIGGER_SOURCE, M_AUX_IO1);

/* Specify to trigger the grab when the signal transitions from low to high.*/
MdigControl(MilDigitizer, M_GRAB_TRIGGER_ACTIVATION, M_EDGE_RISING);

/* Enable digitizer to wait for a trigger to grab. */
MdigControl(MilDigitizer, M_GRAB_TRIGGER_STATE, M_ENABLE);

/* Execute grab (upon trigger). */
MdigGrab(MilDigitizer, MilImage);