| Customize Help
| Save Settings

MdigHookFunction


Function Map
Syntax
Description
Parameters
- DigId
- HookType
Table: For specifying the digitizer event to which to hook the function
+ combination: For specifying to hook to all feature change events
+ combination: For unhooking a hooked function
+ combination: For specifying the type and number of the I/O signal to hook the function
+ combination: For GenICam camera events
+ combination: For specifying the GenICam SFNC-specific counter or I/O signal to which to hook the function
+ combination: For specifying the timer to which to hook the function
+ combination: For specifying the rotary decoder to which to hook the function
- HookHandlerPtr
- UserDataPtr
Compilation information
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-out
)
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.

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
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize 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
Click to summarize 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
M10		 g h i j l o p r
U27		 u
U36		 aa
MIL system specific

The preferred way to detect when a camera is connected or disconnected from the digitizer is to use MsysHookFunction() with M_CAMERA_PRESENT.

 ‡ c
M10		 o u
U36

For an explanation of when to use MsysHookFunction() with M_CAMERA_PRESENT (instead of MdigHookFunction() with M_CAMERA_PRESENT), see the Automatic camera detection with Matrox Clarity UHD section of the Matrox Clarity UHD chapter in the MIL Hardware-specific Notes.

 ‡ u
U36
Click to summarize M_EXPOSURE_END +

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

 ‡ t
U28
Click to summarize M_EXPOSURE_START +

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

 ‡ t
U28
Click to summarize M_FEATURE_CHANGE +

Hooks the function to the event that occurs when the value of a GenICam feature changes.

To enable an event to occur when the value of a specific feature changes, use MdigControlFeature() with M_FEATURE_CHANGE_HOOK set to M_ENABLE. Repeat for each feature for which you want to enable a feature change event. To enable an event to occur when the value of any feature changes, use M_FEATURE_CHANGE + M_ALL.

Within the hook function, use MdigGetHookInfo() with M_GC_FEATURE_CHANGE_NAME to retrieve the name of the feature that caused the event.

(summarize)
‡ c
U25		 k
M10		 v
Click to summarize 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
Click to summarize 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
Click to summarize 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
Click to summarize 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 p r
U27		 aa
Click to summarize 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
M10		 o v
Click to summarize 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 c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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)
‡ g h l
Click to summarize 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)
‡ g h l
Click to summarize 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)
‡ g h l
Click to summarize 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 c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize M_GRAB_FRAME_START +

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

 ‡ a c
M10		 g h j k
M10		 l m o p r
U27		 t
U28		 v y
U75		 aa
Click to summarize 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
M10		 l m p r
U27		 y
U75		 aa
Click to summarize 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
M10		 l m p r
U27		 y
U75		 aa
Click to summarize 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 c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize 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
M10		 j k
M10		 l m o p r
U27		 v y
U75		 aa
Click to summarize 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
M10		 m p r
U27		 y
U75		 aa
Click to summarize 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
M10		 l m p r
U27		 y
U75		 aa
Click to summarize 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
M10		 l m p r
U27		 y
U75		 aa
Combination values for M_FEATURE_CHANGE.

You can add one of the following values to the above-mentioned value to specify to hook the specified function to all featue change events.

function map For specifying to hook to all feature change events
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize

Specifies to display the GenTL stream configuration information.

(summarize)
‡ v
Parameters

Specifies the index of the GenTL stream.

 ‡ v
0 <= Value <= 33

Specifies the index of the GenTL stream.
‡ v
Click to summarize M_ALL

Specifies to hook the specified function to all feature change events.

 ‡ v
Click to summarize M_GENTL_DEVICE

Specifies to display the GenTL device configuration information.

 ‡ v
Click to summarize M_GENTL_REMOTE_DEVICE

Specifies to display the GenTL remote device (camera) configuration information.

 ‡ v
Combination value 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
Click to summarizeCombination value Description
Click to summarize M_UNHOOK

Unhooks a hooked function.
Combination values 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize 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
M10		 j k
M10		 l m o p r
U27		 v y
U75		 aa
MIL system specific

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

 ‡ c
M10		 o v
Click to summarize 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
M10		 y
U75
Combination values 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize M_EXPOSURE_END

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

 ‡ c
M10		 o v
Click to summarize M_EXPOSURE_START

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

 ‡ c
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Click to summarize 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
M10		 o v
Combination value for M_COUNTER_END; M_COUNTER_START; M_LINE_ANY_EDGE; M_LINE_FALLING_EDGE; M_LINE_RISING_EDGE.

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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize 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
M10		 o v
Combination value for M_TIMER_END; M_TIMER_END; M_TIMER_START; M_TIMER_START.

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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_TIMERn

Specifies the timer to hook.

(summarize)
‡ c
M10		 j k
M10		 l m o p r
U27		 v y
U75		 aa
MIL system specific

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

 ‡ c
M10		 o v

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

 ‡ j k
M10		 m p r
U27		 y
U75		 aa

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

 ‡ l
Combination value 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
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize 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
M10		 y
U75
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 EXPOSURE END EXPOSURE START FEATURE CHANGE 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 ALL GENTL DEVICE GENTL REMOTE DEVICE 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 M_GRAB_LINE_END + n M_GRAB_LINE + n M_AUX_IOn M_TIMERn M_ROTARY_ENCODERn