MdigGetHookInfo
| Board | Supported |
|---|---|
| Host System | Partial |
| V4L2 | Partial |
| Clarity UHD | Partial |
| Concord PoE | No |
| GenTL | Partial |
| GevIQ | Partial |
| GigE Vision | Partial |
| Indio | No |
| Iris GTX | Partial |
| Radient eV-CL | Partial |
| Rapixo CL | Partial |
| Rapixo CoF | Partial |
| Rapixo CXP | Partial |
| USB3 Vision | Partial |
Get information about a digitizer hook event.
Syntax
AIL_INT MdigGetHookInfo(
AIL_ID EventId, //in
AIL_INT64 InfoType, //in
void * UserVarPtr //out
)
Description
This function retrieves information about the digitizer event that caused the hook-handler function to be called. MdigGetHookInfo should only be called within the scope of a digitizer hook-handler function (see MdigProcessand MdigHookFunction).
Parameters
EventId (in, AIL_ID)
Specifies the digitizer event identifier received by the hook-handler function (see MdigProcessand MdigHookFunction).
InfoType (in, AIL_INT64)
Specifies the type of information about the event to return.
UserVarPtr *(out, void)
Specifies the address in which to write the requested information.
Parameter Associations
For retrieving information about a general digitizer hook event
The following allows you to retrieve information about various digitizer hook events. Unless otherwise specified, you can retrieve these information types if you call this function from within a function hooked to any digitizer event using MdigHookFunction or MdigProcess.
M_DIGITIZER_ID
Retrieves the Aurora Imaging Library identifier of the digitizer that was used by MdigProcess or MdigHookFunction.
| Value | Description |
|---|---|
Digitizer identifier | Specifies the Aurora Imaging Library identifier of the digitizer. |
M_GC_CAMERA_TIME_STAMP
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision
Retrieves the time at which the event occurred. This value was generated by the camera, using a specialized counter. To inquire the time stamp generated by the operating system, use M_TIME_STAMP.
| Value | Description |
|---|---|
Value | Specifies the camera's time stamp, in secs. |
M_GC_EVENT_TYPE
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision
Retrieves the GenICam event type, as sent by the camera. Refer to your GenICam SFNC specification, or your camera's documentation for a list of GenICam event types.
| Value | Description |
|---|---|
Value | Specifies the GigE Vision event type. |
M_GC_PACKET_SIZE
Board availability: GevIQ, GigE Vision
Retrieves the size of the data packet, used by the GenICam SFNC-compliant camera when streaming data to the Host.
| Value | Description |
|---|---|
Value | Specifies the size of the packet, in bytes. |
M_GRAB_TRIGGER_MISSED
Board availability: Iris GTX
Retrieves the number of grab triggers missed. This result is available only when MdigControl withM_GRAB_TRIGGER_MISSED is set to M_ENABLE.
| Value | Description |
|---|---|
Value | Specifies the number of missed triggers. |
M_TIME_STAMP
Retrieves the operating system's time stamp at the point which the event generated a service request. The time stamp is generated by the operating system's performance counter. Time stamps can be used to see if a frame has been missed since the last time stamp.
System specific
| Board(s) | Note |
|---|---|
| GenTL, GevIQ, GigE Vision, USB3 Vision | This value is generated by the operating system. To use the time stamp generated by the camera, use M_GC_CAMERA_TIME_STAMP. |
| Value | Description |
|---|---|
Value | Specifies the operating system's time stamp, in secs. |
For retrieving information about a GenICam SFNC-compliant event
The following allows you to retrieve information about a GenICam SFNC-compliant event. The following information types are only available if MdigGetHookInfo was called from a function hooked to a GenICam event using M_GC_EVENT. In addition, the GenICam event must be enabled using MdigControlFeature, and the message channel must be supported by your camera.
M_COUNTER_INDEX
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision
Retrieves the index of a counter on your camera. You can retrieve this value if the hook-handler function was hooked usingMdigHookFunction with M_GC_EVENT + M_COUNTER_START + n or M_GC_EVENT + M_COUNTER_END + n, where n is the counter's index. Counters are unique to GenICam SFNC-compliant cameras. To configure your GenICam SFNC-compliant counters, use MdigControlFeature.
| Value | Description |
|---|---|
Value | Specifies the index of the counter. |
M_LINE_INDEX
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision
Retrieves the index of the I/O signal that generated the GenICam SFNC-compatible camera's event. You can only retrieve this information if the hook-handler function was hooked using MdigHookFunction with M_GC_EVENT + M_LINE_ANY_EDGE + n, M_GC_EVENT + M_LINE_FALLING_EDGE + n, or M_GC_EVENT + M_LINE_RISING_EDGE + n, where n is the I/O signal's number.
| Value | Description |
|---|---|
Value | Specifies the number of the I/O signal that generated the event. |
For retrieving information about a grab event
The following allows you to retrieve information about a grab event. Unless otherwise specified, the following information types are only available if MdigGetHookInfo was called from a function hooked to an event using MdigHookFunction or MdigProcesswith M_GRAB_..._END. If inquired from any other hook function, these information types will not return an error, but the result will be irrelevant.
M_CORRUPTED_FRAME
Board availability: Clarity UHD, GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves whether the currently grabbed frame is corrupt.
| Value | Description |
|---|---|
M_NO | Specifies that the frame is not corrupt. |
M_YES | Specifies that the frame is corrupt. |
M_GC_FRAME_BLOCK_ID
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves the value of the counter (block ID) set by the camera for each grabbed frame. In this case, the value of the counter for the last frame grabbed is returned.
System specific
| Board(s) | Note |
|---|---|
| GevIQ, GigE Vision | Note that a GigE Vision 2.0 camera has a 64-bit frame counter, while a GigE Vision 1.0 camera has a 16-bit frame counter. |
| Value | Description |
|---|---|
Value | Specifies the value of the counter. |
M_GC_FRAME_BLOCK_ID64
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves the value of the 64-bit counter (block ID) set by the camera for each grabbed frame. In this case, the value of the counter for the last frame grabbed is returned.
System specific
| Board(s) | Note |
|---|---|
| GevIQ, GigE Vision | Note that a GigE Vision 2.0 camera has a 64-bit frame counter, while a GigE Vision 1.0 camera has a 16-bit frame counter. |
| Value | Description |
|---|---|
Value | Specifies the value of the counter. |
M_GC_FRAME_ERROR_CODE
Board availability: GevIQ, GigE Vision, USB3 Vision
Retrieves the error code returned by the camera for the last frame grabbed.
| Value | Description |
|---|---|
Value | Specifies the GigE Vision error code. |
M_GC_FRAME_LINE_COUNT
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves the number of rows in the last frame grabbed.
| Value | Description |
|---|---|
Value | Specifies the row count. |
M_GC_FRAME_PIXEL_TYPE
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves the data depth and raw color format of the last frame grabbed. Note that this value is a value, specified by GenICam's standard feature naming convention (SFNC). The predefined list of possible pixel formats are in the PFNC.h header file in the installed aildyn folder (for example, C:\Program Files\Aurora Imaging Library\11\include\classic\aildyn).
| Value | Description |
|---|---|
Value | Specifies the data depth and raw color format of the last frame grabbed. |
M_GC_FRAME_SIZE_X
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves the width (size X) of the last frame grabbed.
| Value | Description |
|---|---|
Value | Specifies the width of the last frame grabbed. |
M_GC_FRAME_SIZE_Y
Board availability: GenTL, GevIQ, GigE Vision, USB3 Vision, V4L2
Retrieves the height (size Y) of the last frame grabbed.
| Value | Description |
|---|---|
Value | Specifies the height of the last frame grabbed, in pixels. |
M_GC_FRAME_STATUS_CODE
Board availability: GevIQ, GigE Vision, USB3 Vision
Retrieves the status code from the last frame grabbed. The predefined list of frame status codes are in the GVCP_Status_Codes.h header file in the installed aildyn folder (for example, C:\Program Files\Aurora Imaging Library\11\include\classic\aildyn).
| Value | Description |
|---|---|
Value | Specifies the status code. |
M_GC_PACKETS_MISSED
Board availability: GigE Vision
Retrieves the number of missing packets in the corrupted frame. If 0 is returned, the frame is not corrupted.
| Value | Description |
|---|---|
Value | Specifies the number of missing packets. |
M_GC_PACKETS_RECEIVED
Board availability: GevIQ, GigE Vision
Retrieves the number of packets in the frame.
| Value | Description |
|---|---|
Value | Specifies the number of packets in the frame. |
M_GC_PACKETS_RECOVERED
Board availability: GigE Vision
Retrieves the number of packets successfully recovered in the frame.
| Value | Description |
|---|---|
Value | Specifies the number of recovered packets. |
M_GC_PACKETS_RESENDS_NUM
Board availability: GigE Vision
Retrieves the number of resend commands sent to the camera for a frame. Note that one resend command can contain multiple consecutive packets.
| Value | Description |
|---|---|
Value | Specifies the number of resend commands sent. |
M_GRAB_LINE
Board availability: Iris GTX, Rapixo CL, Rapixo CXP, Rapixo CoF
Retrieves the number of the line (row) that, upon it being received by the digitizer, generated the event. You can only retrieve this information if the hook-handler function was hooked using MdigHookFunction with M_GRAB_LINE + n, where n is the row number. Note that upon this event, the row has not necessarily been written to the grab buffer.
| Value | Description |
|---|---|
Value | Specifies the row number. |
M_GRAB_LINE_COUNT
Board availability: GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision
Retrieves the number of lines (rows) grabbed. Note that the data contained in the line is available for processing. This is useful when grabbing from a line-scan camera with frames of variable length.
System specific
| Board(s) | Note |
|---|---|
| GigE Vision, USB3 Vision | You can only retrieve this value if the hook-handler function was hooked using MdigProcess or MdigHookFunction with M_GRAB_END or M_GRAB_FRAME_END. |
| Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF | You can only retrieve this value if the row count was enabled using MdigControl with M_GRAB_LINE_COUNTER and the hook-handler function was hooked usingMdigProcess or MdigHookFunction with M_GRAB_END or M_GRAB_FRAME_END. |
| Value | Description |
|---|---|
Value | Specifies the row number. |
M_GRAB_LINE_END
Board availability: Rapixo CL, Rapixo CXP, Rapixo CoF
Retrieves the number of the line (row) that, upon it being available in the grab buffer, generated the event. You can only retrieve this information if the hook-handler function was hooked using MdigHookFunction with M_GRAB_LINE_END + n, where n is the row number. Note that upon this event, the row is available in the grab buffer.
| Value | Description |
|---|---|
Value | Specifies the row number. |
M_MODIFIED_BUFFER
Retrieves information about a modified buffer or container type of event.
For retrieving information about a timer
The following allows you to retrieve information about a timer. Refer to the individual information types for restrictions.
M_TIMER_INDEX
Board availability: GenTL, GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision
Retrieves the index of the timer that generated the event. You can only retrieve this value if MdigGetHookInfo was called from a function hooked to an event using MdigHookFunction with M_TIMER_START +M_TIMERn, M_TIMER_END +M_TIMERn, M_GC_EVENT+M_TIMER_START +M_TIMERn, or M_GC_EVENT+M_TIMER_END + M_TIMERn, where n is the timer index.
| Value | Description |
|---|---|
Value | Specifies the index of the timer that generated the event. |
M_TIMER_TRIGGER_MISSED
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
Retrieves the number of triggers missed by the specified timer. You can only retrieve this value if MdigGetHookInfo was called from a function hooked to an event using MdigProcess, or MdigHookFunction with M_GRAB_END, M_TIMER_START +M_TIMERn, or M_TIMER_END +M_TIMERn, where n is the timer index.
| Value | Description |
|---|---|
Value | Specifies the number of missed triggers. |
Combination Constants — For specifying the timer to inquire
Essential.
Usage: You must add one of the following values to the above-mentioned values to set the timer to inquire.
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
| Value | Description |
|---|---|
M_TIMERn | Specifies the timer, where n can be from 1 to 4. |
Combination Constants — For retrieving information about the modified image buffer
Essential.
Usage: You must add one of the following values to the above-mentioned values to specify the type of information to return about the modified image buffer.
M_BUFFER_ID
Retrieves the Aurora Imaging Library identifier of the modified image buffer or container.
| Value | Description |
|---|---|
Container identifier | Specifies the Aurora Imaging Library identifier of the modified container associated with the event. |
Image buffer identifier | Specifies the Aurora Imaging Library identifier of the modified image buffer associated with the event. |
M_BUFFER_INDEX
Retrieves the index of the modified image buffer in the image buffer array passed to MdigProcess, if the hook-handler function was hooked using MdigProcess. This index always starts at 0.
| Value | Description |
|---|---|
Value | Specifies the index of the modified image buffer. |
M_REGION_OFFSET_X
Retrieves the X-offset of the modified region (of the image buffer).
| Value | Description |
|---|---|
Value | Specifies the X-offset of the modified region. |
M_REGION_OFFSET_Y
Retrieves the Y-offset of the modified region (of the image buffer).
| Value | Description |
|---|---|
Value | Specifies the Y-offset of the modified region. |
M_REGION_SIZE_X
Retrieves the width of the modified region (of the image buffer).
| Value | Description |
|---|---|
Value | Specifies the width of the modified region. |
M_REGION_SIZE_Y
Retrieves the height of the modified region (of the image buffer).
| Value | Description |
|---|---|
Value | Specifies the height of the modified region. |
For retrieving information about an I/O event
The following allows you to retrieve information about an I/O event. These information types are only available if MdigGetHookInfo was called from a function hooked to event using MdigHookFunction with M_IO_CHANGE.
M_IO_INTERRUPT_SOURCE
Board availability: GenTL, GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision
Retrieves the auxiliary input signal that generated the interrupt.
| Value | Description |
|---|---|
M_AUX_IOn | Specifies the auxiliary input signal that generated the interrupt, where n is the signal number. |
M_IO_STATUS
Board availability: GenTL, GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision
Retrieves the state of the input signal that generated the interrupt. The returned value reflects the state of the input signal at the time of the interrupt.
| Value | Description |
|---|---|
M_OFF | Specifies that the auxiliary input signal that generated the interrupt is off. |
M_ON | Specifies that the auxiliary input signal that generated the interrupt is on. |
For retrieving information about a reference latch value
The following allows you to retrieve information about a reference latch event. The following information types are only available if using a latch that has previously saved the time or counter value upon a hardware event and using MdigHookFunction with any hook event.
Board availability: Iris GTX
M_REFERENCE_LATCH_VALUE
Retrieves the last timestamp or counter value stored by the specified latch.
| Value | Description |
|---|---|
Value | Specifies the last timestamp or counter value stored by the specified latch. |
Combination Constants — For specifying the I/O command list to use
Essential, cannot be used alone.
Usage: You must add one of the following values to the above-mentioned values to specify which of the I/O command lists to use.
Board availability: Iris GTX
| Value | Description |
|---|---|
M_IO_COMMAND_LIST1 | Specifies to inquire about I/O command list1. |
For retrieving information about a rotary decoder event
The following allows you to retrieve information about a rotary decoder event. This information type is only available if MdigGetHookInfo was called from a function hooked to event using MdigHookFunction with M_ROTARY_ENCODER. In addition, you must have enabled the rotary decoder to store this information (before the grab), using MdigControl with M_ROTARY_ENCODER_FRAME_END_READ. Note that the current value of the rotary decoder's counter can be inquired using MdigInquire with M_ROTARY_ENCODER_POSITION.
M_ROTARY_ENCODER_FRAME_END_POSITION
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
Retrieves the value of the rotary decoder's counter at the end of the last frame grabbed before the counter reached its trigger position.
| Value | Description |
|---|---|
Value | Specifies the value of the rotary decoder's counter when the last frame was grabbed. |
Combination Constants — For specifying which rotary decoder to inquire
Optional, cannot be used alone.
Usage: You can add one of the following values to the above-mentioned values to specify which rotary decoder to inquire.
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
| Value | Description |
|---|---|
M_ROTARY_ENCODERn | Specifies to inquire 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 (using MdigHookFunction with DigId) will be used. For example, when the device number of the specified digitizer is M_DEV2, rotary decoder M_ROTARY_ENCODER3 is used. |
For retrieving information from a data latch
The following allows you to retrieve information from a data latch. These information types are only available if MdigGetHookInfo was called from a function hooked to an end of grabbed frame event using MdigHookFunction with M_GRAB_FRAME_END or from the hook-handler function (callback function) of MdigProcess. In addition, you must have enabled the data latch to store this information, using MdigControl with M_DATA_LATCH_STATE. > Note: Note that you can only use data latches in association with the Aurora Imaging Library digitizer allocated using MdigAlloc with M_DEV0.
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
M_DATA_LATCH_VALUE
Retrieves the stored data of the specified data latch. If there are multiple instances of this data (for example, your data latch is triggered at the end of each grabbed line), use + M_VALUE_INDEX().
| Value | Description |
|---|---|
M_NULL | Specifies that the stored data could not be read. |
Value | Specifies the stored data. |
M_DATA_LATCH_VALUE_ALL
Retrieves all the stored data of the specified data latch.
| Value | Description |
|---|---|
Value | Specifies all the stored data. |
M_DATA_LATCH_VALUE_COUNT
Counts the number of items stored inside a data latch. Note that a data latch is reset at every frame event.
| Value | Description |
|---|---|
Value | Specifies the number of instances. Note that a data latch is reset at every frame event. |
Combination Constants — For specifying the data latch to inquire
Essential.
Usage: You must add one of the following values to the above-mentioned values to specify which data latch to inquire about.
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
| Value | Description |
|---|---|
M_LATCHn | Specifies the data latch from which to retrieve information, where n is a value from 0 to 15. |
Combination Constants — For identifying the instance of the stored information to retrieve
Optional.
Usage: You can add one of the following values to the above-mentioned values to specify the instance of the stored information to retrieve.
Board availability: Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF
| Value | Description |
|---|---|
M_VALUE_INDEX | Specifies the instance of stored information to retrieve. |
For retrieving information from a GenICam feature change event
The following allows you to retrieve information from a GenICam feature change event. These information types are only available if MdigGetHookInfo was called from a function hooked to GenICam feature change event using MdigHookFunction with M_FEATURE_CHANGE.
Board availability: GenTL, GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision
M_GC_FEATURE_CHANGE_NAME
Retrieves the name of the GenICam feature that changed. This information type is only available ifMdigGetHookInfo is used from a function hooked to GenTL feature change events using MdigHookFunction with M_FEATURE_CHANGE.
| Value | Description |
|---|---|
Value | Specifies the feature name. |
Combination Constants — For getting the string size
Optional.
Usage: You can add one of the following values to the above-mentioned values to get the string's length.
Board availability: GenTL, GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision
M_STRING_SIZE
Retrieves the length of the string, including the terminating null character ("\0").
For retrieving information from a grab frame burst event
The following allows you to retrieve information about events that occur when grabbing into a multi-frame buffer (frame burst events). Unless otherwise specified, you can retrieve these information types if you call this function from within a function hooked to a frame end event using MdigHookFunction with M_GRAB_FRAME_END or MdigProcess.
Board availability: Rapixo CL, Rapixo CXP, Rapixo CoF
M_GRAB_FRAME_BURST_COUNT
Retrieves the number of frames grabbed into the multi-frame buffer.
| Value | Description |
|---|---|
Value | Specifies the number of frames grabbed. |
M_GRAB_FRAME_BURST_END_SOURCE
Retrieves the type of event(s) that ended the grab of sequential frames into the multi-frame buffer (end of the frame burst). Simultaneous events might have caused the end of grab to happen, so a combination of the values below can be returned. Bitwise operators must be used to verify the presence of a specific returned value.
| Value | Description |
|---|---|
M_BURST_COUNT | Specifies that the entire group of sequential frames have been grabbed into the multi-frame buffer. To specify the number of frames in a frame burst, use MdigControl with M_GRAB_FRAME_BURST_SIZE. |
M_BURST_MAX_TIME | Specifies that the maximum frame burst time has elapsed. To specify the maximum time for a frame burst to complete, use MdigControl with M_GRAB_FRAME_BURST_MAX_TIME. |
M_BURST_TRIGGER | Specifies that an end-of-frame-burst trigger occurred. To enable using an end-of-frame-burst trigger to end the grab, use MdigControl with M_GRAB_FRAME_BURST_END_TRIGGER_STATE. |
Return Value
Type: AIL_INT
The returned value is M_NULL if successful. If the operation fails, a non-null (!M_NULL) value is returned.