| MIL 10 Reference
| Customize Help
| Save Settings

MdigHookFunction


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Not supported on:
Not supported on Matrox GPU processing driver
Partially supported on:
Partially supported on Host system
Partially supported on Matrox CronosPlus
Partially supported on Matrox GigE Vision driver
Partially supported on Matrox IEEE 1394 IIDC driver
Partially supported on Matrox Iris GT
Partially supported on Matrox Morphis
Partially supported on Matrox Morphis QxT
Partially supported on Matrox Orion HD
Partially supported on Matrox Radient eCL
Partially supported on Matrox Radient eV-CXP
Partially supported on Matrox Solios eA/XA
Partially supported on Matrox Solios ecl/xcl/ev-cl
Partially supported on Matrox USB3 Vision driver (requires Update 19)
Partially supported on Matrox Vio

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MdigHalt
MdigInquire
Synopsis
Hook a function to a digitizer event.
Syntax
void MdigHookFunction(
MIL_ID DigId, //in
MIL_INT HookType, //in
MIL_DIG_HOOK_FUNCTION_PTR HookHandlerPtr, //in
void *UserDataPtr //in
)
Description

This function allows you to attach or detach a user-defined function to a specified digitizer event. Once a hook-handler function is defined and hooked to an event, it is automatically called when the event occurs.

You can hook more than one function to an event by making separate calls to MdigHookFunction() for each function that you want to hook. MIL automatically chains and keeps an internal list of all these hooked functions. When a function is hooked, this new function is added to the end of the list. When the event happens, all user-defined functions in the list will be executed in the same order that they were hooked to the event. You can also remove any function from the list; in this case, MIL preserves the order of the remaining functions in the list.

You can obtain more information about the event from within the hook handler function using MdigGetHookInfo().

Note that functions hooked to an event execute on a distinct thread. This permits the functions to run concurrently from the operation that fired the event and from functions hooked to other events. Although there is a small queue to permit a certain amount of overlap, hooked functions should not take longer to execute than the period in which two of their associated events can occur.

[Matrox IEEE 1394 IIDC driver]

Note that the following hook types are only available if they are supported by the camera. Refer to your camera's documentation for more details.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
DigId

Specifies the identifier of the digitizer.

HookType

Specifies the digitizer event to which to hook the function. This parameter can be set to one of the following values:

function map For specifying the digitizer event to which to hook the function
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_CAMERA_LOCK +

Hooks the function to the event that occurs when the camera is locked. Use MdigInquire() with M_CAMERA_LOCKED to inquire if the camera is currently locked.

(summarize)
† h l n
Collapse M_CAMERA_PRESENT +

Hooks the function to the presence of the camera. Use MdigInquire() with M_CAMERA_PRESENT to inquire if the camera is currently present.

(summarize)
† c e g h i j l n o p r s
MIL system specific

This event occurs when the camera is physically unplugged from your IEEE 1394 IIDC-compatible board.

 † e
Collapse M_FIELD_START +

Hooks the function to the event that occurs at the start of each field of the incoming signal.

Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

(summarize)
† g h l n
Collapse M_FIELD_START_EVEN +

Hooks the function to the event that occurs at the start of the incoming signal's even fields.

Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

(summarize)
† g h l n
Collapse M_FIELD_START_ODD +

Hooks the function to the event that occurs at the start of the incoming signal's odd fields.

Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

(summarize)
† g h l n
Collapse M_FRAME_START +

Hooks the function to the event that occurs at the start of each frame of the incoming signal.

Note that MIL need not be grabbing the incoming signal for this event to occur. The event is only dependent on the presence of a camera.

(summarize)
† g h j l m n p r
Collapse M_GC_EVENT +

Hooks the function to the message sent from your GenICam SFNC-compliant camera at the time of the specified event. Your camera sends specific messages using a dedicated message channel to inform your computer of specific events (such as the start and end of specific events in the process through which your camera acquires an image). When dealing with the messages sent from your camera, the exact timing and order of the messages is specific to your camera's manufacturer.

Note that, if you don't add a combination constant to M_GC_EVENT, the function is hooked to any GenICam event that has been enabled using MdigControlFeature(). In addition, the message channel must be supported by your camera.

(summarize)
† c o s
Collapse M_GRAB_END +

Hooks the function to the event that occurs at the end of each grab.

When grabbing continuously, the M_GRAB_END event is fired only when the last frame is grabbed. To be notified at the end of each frame, use the M_GRAB_FRAME_END event.

A function hooked to an M_GRAB_END event is called when all the data of the grab is transferred to the Host. This means that this hooked function can be called after the M_GRAB_START or M_GRAB_FRAME_START event of the next frame.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_GRAB_FIELD_END +

Hooks the function to event that occurs at the end of grabbed fields. Note that, in this case, the grabbed data might not be completely transferred to the Host.

(summarize)
† b g h l
Collapse M_GRAB_FIELD_END_EVEN +

Hooks the function to the event that occurs at the end of grabbed even fields. Note that, in this case, the grabbed data might not be completely transferred to the Host.

(summarize)
† b g h l
Collapse M_GRAB_FIELD_END_ODD +

Hooks the function to the event that occurs at the end of grabbed odd fields. Note that, in this case, the grabbed data might not be completely transferred to the Host.

(summarize)
† b g h l
Collapse M_GRAB_FRAME_END +

Hooks the function to the event that occurs at the end of grabbed frames. Note that, in this case, the grabbed data might not be completely transferred to the Host.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_GRAB_FRAME_START +

Hooks the function to the event that occurs at the start of grabbed frames.

 † a b c e f g h j k l m n o p q r s
Collapse M_GRAB_LINE_END + n +

Hooks the function to the event that occurs when the data of the specified line (row) is in the buffer and ready to be processed, where n is the specified line. For example, M_GRAB_LINE_END + 200 would call the hook-handler function when the data of line number 200 is in the buffer.

You can call this function with this value up to 32 times during one grab.

(summarize)
† j k l m p q r
Collapse M_GRAB_LINE + n +

Hooks the function to the event that occurs when the specified line (row) is reached, where n is the specified line. For example, M_GRAB_LINE + 200 would call the hook-handler function when line number 200 is reached.

Note that the data of the specified line number might not be in the buffer.

You can call this function with this value up to 32 times during one grab.

(summarize)
† j k l m p q r
Collapse M_GRAB_START +

Hooks the function to the event that occurs at the start of each grab.

When grabbing continuously, the M_GRAB_START event is fired only when the first frame is grabbed. To be notified at the start of each frame, use the M_GRAB_FRAME_START event.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_IO_CHANGE +

Hooks the function to the event that occurs when an I/O signal changes in accordance with its specified interrupt activation mode, set using MdigControl() with M_IO_INTERRUPT_ACTIVATION. Within the scope of the hook-handler function, it is prudent to verify that the appropriate I/O signal triggered the hook-handler function, using MdigGetHookInfo() with M_IO_INTERRUPT_SOURCE.

If more than one input signal triggers an interrupt at the same time, the hook-handler function (or chain of hook-handler functions) is called for each input signal that generated an interrupt. As a result, any and all user-specified function(s) hooked using this hook type will be executed for each interrupt.


You must specify a combination value from the following table:
(summarize)
† c j k l m o p q r s
Collapse M_ROTARY_ENCODER +

Hooks the function to the event that occurs when the rotary decoder's counter reaches its trigger position (specified using MdigControl() with M_ROTARY_ENCODER_POSITION_TRIGGER).

 † j k m p q r
Collapse M_TIMER_END +

Hooks the function to the event that occurs when the active period of the specified timer ends (specified using MdigControl() with M_TIMER_DURATION).


You must specify a combination value from the following table:
(summarize)
† j k l m p q r
Collapse M_TIMER_START +

Hooks the function to the event that occurs when the specified timer is triggered.


You must specify a combination value from the following table:
(summarize)
† j k l m p q r
Combination constant for any of the possible values of the HookType parameter.

You can add the following value to the above-mentioned values to specify to unhook a hooked function.

function map For unhooking a hooked function
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_UNHOOK

Unhooks a hooked function.

 † a b c e f g h i j k l m n o p q r s
Combination constants for M_IO_CHANGE.

You must add one of the following values to the above-mentioned value to specify the type and number of the I/O signal to hook the function.

function map For specifying the type and number of the I/O signal to hook the function
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_AUX_IOn

Specifies to affect auxiliary signal n, where n is the signal number.

For a list of the available auxiliary I/O signals, see the Connectors and signal names section of the MIL Hardware-specific Notes chapter for your Matrox imaging board or MIL driver.

(summarize)
† c j k l m o p q r s
MIL system specific

With a GenICam SFNC-compliant camera, n is a number from 0 to 31.

 † c o s
Collapse M_TL_TRIGGER

Specifies to affect the transport layer trigger signal. The transport layer trigger signal is an embedded bidirectional signal from the physical transport layer connection of your camera. Typically, the TL trigger signal is reserved for trigger information and is sent with other control and data signals along the same cable.

(summarize)
† k q
Combination constants for M_GC_EVENT.

You can add one of the following values to the above-mentioned value to set the type of GenICam camera event.

The following events occur on the camera, as opposed to your frame grabber or the Host.

Your camera informs the Host (your computer) of these events by sending specific messages on the dedicated message channel. When dealing with the messages sent from your camera, the order of the messages can be specific to your camera's manufacturer. Typically, however, they follow the GenICam SFNC. Check your camera's documentation for potential discrepancies.

Note that, if you don't add a combination constant to M_GC_EVENT, the function is hooked to any GenICam event that has been enabled using MdigControlFeature(). In addition, the message channel must be supported by your camera and the specified event must also be supported by your camera.

When dealing specifically with acquisition-related events on the camera, typically the events occur in the following sequence, which starts when your grab command sets up the camera to start the acquisition of images. You can hook a function to the start and end of each of the following events: expose the sensor (CCD or CMOS) of the camera, perform the sensor readout and save the frame to an internal buffer, and then transfer the frame from your camera to your computer.

For error handling of acquisition-related events on the camera, hook a function on the acquisition error event (using M_ACQUISITION_ERROR).

function map For GenICam camera events
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_ACQUISITION_END

Hooks the function to the event that occurs when acquisition ends on your camera. When the camera is in single frame acquisition mode, this event occurs at (or before) the end of each frame. When the camera is in multiframe or continuous acquisition mode, this event occurs at (or before) the end of multiple frames.

Note that, whether the acquisition end includes the acquisition transfer end is specific to your camera's manufacturer.

(summarize)
† c o s
Collapse M_ACQUISITION_ERROR

Hooks the function to the event that occurs if an error is generated at some point while the camera exposes an image, stores it in an internal buffer, and transfers it from the camera to your computer.

 † c o s
Collapse M_ACQUISITION_START

Hooks the function to the event that occurs when acquisition begins on your camera. When the camera is in single frame acquisition mode, this event occurs at (or before) the beginning of each frame. When the camera is in multiframe or continuous acquisition mode, this event occurs at (or before) the beginning of multiple frames.

Note that, whether the acquisition start includes the first frame start and the exposure start is specific to your camera's manufacturer.

(summarize)
† c o s
Collapse M_ACQUISITION_TRANSFER_END

Hooks the function to the event that occurs after transferring the image from your camera to your computer. When the camera is in single frame acquisition mode, this event occurs at the end of transferring each frame. When the camera is in multiframe or continuous acquisition mode, this event occurs at the end of transferring multiple frames.

Note that, whether the acquisition transfer end includes the last frame transfer end is specific to your camera's manufacturer.

(summarize)
† c o s
Collapse M_ACQUISITION_TRANSFER_START

Hooks the function to the event that occurs before transferring the image from your camera to your computer. When the camera is in single frame acquisition mode, this event occurs at the beginning of transferring each frame. When the camera is in multiframe or continuous acquisition mode, this event occurs at the beginning of transferring multiple frames.

Note that, whether the acquisition transfer start includes the first frame transfer start is specific to your camera's manufacturer.

(summarize)
† c o s
Collapse M_ACQUISITION_TRIGGER

Hooks the function to the event that occurs when acquisition is triggered on the camera. When the camera is in continuous acquisition mode, the M_ACQUISITION_TRIGGER event is fired only once, when your camera receives the initial acquisition trigger.

(summarize)
† c o s
Collapse M_COUNTER_END +

Hooks the function to the event that occurs when the specified camera counter stops.

Counters are unique to GenICam SFNC-cameras. To configure your GenICam SFNC-counters, use MdigControlFeature().


You must specify a combination value from the following table:
(summarize)
† c o s
Collapse M_COUNTER_START +

Hooks the function to the event that occurs when the specified camera counter starts.

Counters are unique to GenICam SFNC-cameras. To configure your GenICam SFNC-counters, use MdigControlFeature().


You must specify a combination value from the following table:
(summarize)
† c o s
Collapse M_EXPOSURE_END

Hooks the function to the event that occurs at the end of each exposure period of your camera.

 † c o s
Collapse M_EXPOSURE_START

Hooks the function to the event that occurs at the start of each exposure period of your camera.

 † c o s
Collapse M_FRAME_END

Hooks the function to the event that occurs when the frame ends on your camera. Regardless of the acquisition mode of your camera, this event occurs at the end of each frame.

(summarize)
† c o s
Collapse M_FRAME_START

Hooks the function to the event that occurs when the frame begins on your camera. Regardless of the acquisition mode of your camera, this event occurs at the beginning of each frame.

(summarize)
† c o s
Collapse M_FRAME_TRANSFER_END

Hooks the function to the event that occurs after transferring the frame from your camera to your computer. Regardless of the acquisition mode of your camera, this event occurs at the end of each frame.

Instead of this event, it is more efficient to use M_GRAB_FRAME_END or MdigProcess() with a hook-handler function. This reduces overhead both on the camera and the Host.

(summarize)
† c o s
Collapse M_FRAME_TRANSFER_START

Hooks the function to the event that occurs before transferring the frame from your camera to your computer. Regardless of the acquisition mode of your camera, this event occurs at the beginning of each frame.

Instead of this event, it is more efficient to use M_GRAB_FRAME_START. This reduces overhead both on the camera and the Host.

(summarize)
† c o s
Collapse M_FRAME_TRIGGER

Hooks the function to the event that occurs for each image when the acquisition of each image is triggered on the camera.

 † c o s
Collapse M_LINE_ANY_EDGE +

Hooks the function to the event that occurs when the specified I/O signal changes on the camera.


You must specify a combination value from the following table:
(summarize)
† c o s
Collapse M_LINE_FALLING_EDGE +

Hooks the function to the event that occurs on the falling edge of the specified I/O signal on the camera.


You must specify a combination value from the following table:
(summarize)
† c o s
Collapse M_LINE_RISING_EDGE +

Hooks the function to the event that occurs on the rising edge of the specified I/O signal on the camera.


You must specify a combination value from the following table:
(summarize)
† c o s
Collapse M_TIMER_END +

Hooks the function to the event that occurs when the specified timer ends.


You must specify a combination value from the following table:
(summarize)
† c o s
Collapse M_TIMER_START +

Hooks the function to the event that occurs when the specified timer is triggered.


You must specify a combination value from the following table:
(summarize)
† c o s

You must add the following value to the above-mentioned values to specify the GenICam SFNC-specific counter, or I/O signal to which to hook the function.

function map For specifying the GenICam SFNC-specific counter or I/O signal to which to hook the function
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse Value >= 0

Specifies to hook to counter n or I/O signal n.

When dealing with counters, n is a value from 0 to 8.

When dealing with an I/O signal, n is a value from 0 to 31.

(summarize)
† c o s

You must add the following value to the above-mentioned values to specify the timer to which to hook the function.

function map For specifying the timer to which to hook the function
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_TIMERn

Specifies the timer to hook.

(summarize)
† c j k l m o p q r s
MIL system specific

With a GenICam SFNC-compliant camera, n can be a value from 0 to 8.

 † c o s

In this case, n can be a value from 1 to 4.

 † j k m p q r

With Matrox Solios eA/XA, n can be a value from 1 to 2.

 † l
Combination constant for M_ROTARY_ENCODER.

You can add the following value to the above-mentioned value to specify the rotary decoder to which to hook the function.

function map For specifying the rotary decoder to which to hook the function
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_ROTARY_ENCODERn

Specifies to hook to rotary decoder n, where n is a number between 1 and 4.

Note that if you do not use this combination constant to specify a rotary decoder, the rotary decoder corresponding to 1+ the device number of the specified digitizer (DigId) will be used. For example, when the device number of the specified digitizer is M_DEV2, rotary decoder M_ROTARY_ENCODER3 is used.

(summarize)
† k q
HookHandlerPtr

Specifies the address of the function that should be called when the specified event occurs.

The hook-handler function, pointed to by HookHandlerPtr, must be declared as follows:

MIL_INT MFTYPE HookHandler(
MIL_INT HookType,
MIL_ID EventId,
void *UserDataPtr
)
Parameters
HookType

Type of event hooked.

EventId

Event identifier. You can pass the identifier to MdigGetHookInfo() to inquire about the hooked event.

UserDataPtr

User data pointer.

Upon successful completion, the hook-handler function should return M_NULL. Note, MFTYPE and MIL_DIG_HOOK_FUNCTION_PTR are reserved MIL predefined types for functions and data pointers.

UserDataPtr

Specifies the address of the user data that you want to make available to the hook-handler function. This address is passed to the hook-handler function, through its UserDataPtr parameter, when the specified event occurs. Set this parameter to M_NULL if not used.

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
CAMERA LOCK CAMERA PRESENT FIELD START FIELD START EVEN FIELD START ODD FRAME START GC EVENT GRAB END GRAB FIELD END GRAB FIELD END EVEN GRAB FIELD END ODD GRAB FRAME END GRAB FRAME START GRAB LINE END n GRAB LINE n GRAB START IO CHANGE ROTARY ENCODER TIMER END TIMER START UNHOOK AUX IOn TL TRIGGER ACQUISITION END ACQUISITION ERROR ACQUISITION START ACQUISITION TRANSFER END ACQUISITION TRANSFER START ACQUISITION TRIGGER COUNTER END COUNTER START EXPOSURE END EXPOSURE START FRAME END FRAME START FRAME TRANSFER END FRAME TRANSFER START FRAME TRIGGER LINE ANY EDGE LINE FALLING EDGE LINE RISING EDGE TIMER END TIMER START TIMERn ROTARY ENCODERn