MdigGetHookInfo

User Guide:

DirectShow capture filter for MIL Using input signals Using quadrature input from a rotary encoder

Reference:

MbufInquire MdigAlloc MdigControl MdigControlFeature MdigHookFunction MdigInquire MdigProcess MsysInquire

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Matrox GPU processing driver

Partially supported on:

Host system

Matrox CronosPlus

Matrox GigE Vision driver

Matrox IEEE 1394 IIDC driver

Matrox Iris GT

Matrox Morphis

Matrox Morphis QxT

Matrox Orion HD

Matrox Radient eCL

Matrox Radient eV-CXP

Matrox Solios eA/XA

Matrox Solios ecl/xcl/ev-cl

Matrox USB3 Vision driver (requires Update 19)

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

- EventId

Parameter Associations

Table:	For retrieving information about a general digitizer hook event
Table:	For retrieving information about a GenICam SFNC-compliant event
Table:	For retrieving information about a grab event
+ combination:	For specifying the timer to inquire
+ combination:	For retrieving information about the modified image buffer
Table:	For retrieving information about an I/O event
Table:	For retrieving information about a rotary decoder event
+ combination:	For specifying which rotary decoder to inquire

Return value

Compilation information

MdigFree

MdigGrab

Synopsis

Get information about a digitizer hook event.

Syntax

MIL_INT MdigGetHookInfo(

MIL_ID EventId,	//in
MIL_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 MdigProcess() and MdigHookFunction()).

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

EventId

Specifies the digitizer event identifier received by the hook-handler function (see MdigProcess() and MdigHookFunction()).

InfoType

Specifies the type of information about the event to return.

See the Parameter associations section for possible values that can be specified.

UserVarPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

MIL_DOUBLE
MIL_ID
MIL_INT

Specifies the address in which to write the requested information.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The tables below list possible values for the InfoType parameter and possible values returned to the UserVarPtr parameter.

For retrieving information about a general digitizer hook event
For retrieving information about a GenICam SFNC-compliant event
For retrieving information about a grab event
For retrieving information about an I/O event
For retrieving information about a rotary decoder event

The following allows you to retrieve information about various digitizer hook event. 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().

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

For retrieving information about a general digitizer hook event
InfoType		Description		MIL system-specific tooltip (†)
	UserVarPtr - Possible values returned	Description
M_DIGITIZER_ID		Retrieves the MIL identifier of the digitizer that was used by MdigProcess(). Note that this information is only available for digitizer events generated by MdigProcess(). (summarize) Retrieves the MIL identifier of the digitizer that was used by MdigProcess(). (more details...)																					†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	UserVarPtr data type info	Data type: MIL_ID		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	MIL digitizer identifier	Specifies the MIL identifier of the digitizer.		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_GC_CAMERA_TIME_STAMP		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. (summarize) Retrieves the time at which the event occurred. (more details...)		†			c											o				s
	UserVarPtr data type info	Data type: MIL_DOUBLE		†			c											o				s
	Value	Specifies the camera's time stamp, in secs.		†			c											o				s
M_GC_EVENT_TYPE		Retrieves the GigE Vision event type, as sent by the camera. Refer to your GenICam SFNC specification, or your camera's documentation for a list of GigE Vision event types. (summarize) Retrieves the GigE Vision event type, as sent by the camera. (more details...)		†			c											o				s
	Value	Specifies the GigE Vision event type.		†			c											o				s
M_GC_PACKET_SIZE		Retrieves the size of the data packet, used by the GenICam SFNC-compliant camera when streaming data to the Host. (summarize) Retrieves the size of the data packet, used by the GenICam SFNC-compliant camera when streaming data to the Host. (more details...)		†			c															s
	Value	Specifies the size of the packet, in bytes.		†			c															s
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. (summarize) Retrieves the operating system's time stamp at the point which the event generated a service request. (more details...)		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
			MIL system specific
			This value is generated by the operating system. To use the time stamp generated by the camera, use M_GC_CAMERA_TIME_STAMP.	†			c											o				s
	UserVarPtr data type info	Data type: MIL_DOUBLE		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies operating system's time stamp, in secs.		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

The following allows you to retrieve information about a GenICam SFNC-complaint 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.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

For retrieving information about a GenICam SFNC-compliant event
InfoType		Description	MIL system-specific tooltip (†)
	UserVarPtr - Possible values returned	Description
M_COUNTER_INDEX		Retrieves the index of a counter on your camera. You can retrieve this value if the hook-handler function was hooked using MdigHookFunction() 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(). (summarize) Retrieves the index of a counter on your camera. (more details...)					†	c	o	s
	Value	Specifies the index of the counter.	†	c	o	s
M_LINE_INDEX		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. (summarize) Retrieves the index of the I/O signal that generated the GenICam SFNC-compatible camera's event. (more details...)	†	c	o	s
	Value	Specifies the number of the I/O signal that generated the event.	†	c	o	s
M_TIMER_INDEX		Retrieves the index of the timer that generated the generic the GenICam SFNC-compatible camera's event. You can retrieve this value if the hook-handler function was hooked using MdigHookFunction() with M_GC_EVENT + M_TIMER_START + n or M_GC_EVENT + M_TIMER_END + M_TIMERn, where n is the timer index. (summarize) Retrieves the index of the timer that generated the generic the GenICam SFNC-compatible camera's event. (more details...)	†	c	o	s
	Value	Specifies the index of the timer that generated the event.	†	c	o	s

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 MdigProcess() with M_GRAB_..._END. If inquired from any other hook function, these information types will not return an error, but the result will be irrelevant.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

For retrieving information about a grab event
InfoType		Description		MIL system-specific tooltip (†)
	UserVarPtr - Possible values returned	Description
M_CORRUPTED_FRAME		Retrieves whether the currently grabbed frame is corrupt. (summarize) Retrieves whether the currently grabbed frame is corrupt. (more details...)																					†	c	i	o	s
	M_NO	Specifies that the frame is not corrupt.		†			c					i						o				s
	M_YES	Specifies that the frame is corrupt.		†			c					i						o				s
M_GC_FRAME_BLOCK_ID		Retrieves the contents of a 16-bit counter used by the camera to identify each frame grabbed. In this case, the value of the counter for the last frame grabbed is returned. (summarize) Retrieves the contents of a 16-bit counter used by the camera to identify each frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the block identifier.		†			c											o				s
M_GC_FRAME_ERROR_CODE		Retrieves the error code returned by the camera for the last frame grabbed. (summarize) Retrieves the error code returned by the camera for the last frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the GigE Vision error code.		†			c											o				s
M_GC_FRAME_LINE_COUNT		Retrieves the number of rows in the last frame grabbed. (summarize) Retrieves the number of rows in the last frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the row count.		†			c											o				s
M_GC_FRAME_PIXEL_TYPE		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 MIL installation folder, under the include\MilDyn subfolder. (summarize) Retrieves the data depth and raw color format of the last frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the data depth and raw color format of the last frame grabbed.		†			c											o				s
M_GC_FRAME_SIZE_X		Retrieves the width (size X) of the last frame grabbed. (summarize) Retrieves the width (size X) of the last frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the width of the last frame grabbed.		†			c											o				s
M_GC_FRAME_SIZE_Y		Retrieves the height (size Y) of the last frame grabbed. (summarize) Retrieves the height (size Y) of the last frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the height of the last frame grabbed, in pixels.		†			c											o				s
M_GC_FRAME_STATUS_CODE		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 MIL installation folder, under the include\MilDyn subfolder. (summarize) Retrieves the status code from the last frame grabbed. (more details...)		†			c											o				s
	Value	Specifies the status code.		†			c											o				s
M_GC_PACKETS_MISSED		Retrieves the number of missing packets in the corrupted frame. If 0 is returned, the frame is not corrupted. (summarize) Retrieves the number of missing packets in the corrupted frame. (more details...)		†			c															s
	Value	Specifies the number of missing packets.		†			c															s
M_GC_PACKETS_RECEIVED		Retrieves the number of packets in the frame. (summarize) Retrieves the number of packets in the frame. (more details...)		†			c															s
	Value	Specifies the number of packets in the frame.		†			c															s
M_GC_PACKETS_RECOVERED		Retrieves the number of packets successfully recovered in the frame. (summarize) Retrieves the number of packets successfully recovered in the frame. (more details...)		†			c															s
	Value	Specifies the number of recovered packets.		†			c															s
M_GC_PACKETS_RESENDS_NUM		Retrieves the number of resend commands sent to the camera for a frame. Note that one resend command can contain multiple consecutive packets. (summarize) Retrieves the number of resend commands sent to the camera for a frame. (more details...)		†			c															s
	Value	Specifies the number of resend commands sent.		†			c															s
M_GRAB_LINE		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. (summarize) Retrieves the number of the line (row) that, upon it being received by the digitizer, generated the event. (more details...)		†		b		e	f	g	h	i		k	l	m	n
	Value	Specifies the row number.		†		b		e	f	g	h	i		k	l	m	n
M_GRAB_LINE_COUNT		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. (summarize) Retrieves the number of lines (rows) grabbed. (more details...)		†			c							k	l	m		o	p	q	r	s
			MIL system specific
			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.	†			c											o				s
			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 using MdigProcess() or MdigHookFunction() with M_GRAB_END or M_GRAB_FRAME_END.	†										k	l	m			p	q	r
	Value	Specifies the row number.		†			c							k	l	m		o	p	q	r	s
M_GRAB_LINE_END		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. (summarize) Retrieves the number of the line (row) that, upon it being available in the grab buffer, generated the event. (more details...)		†											l	m
	Value	Specifies the row number.		†											l	m
M_MODIFIED_BUFFER +		Retrieves information about a modified-buffer type of event. (summarize) Retrieves information about a modified-buffer type of event. (more details...)		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
			MIL system specific
			You can only retrieve this information if the hook-handler function was hooked using MdigProcess() or MdigHookFunction() with M_GRAB....	†		b		e
	UserVarPtr data type info	Data type: MIL_ID		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies information about a modified-buffer event.		†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_TIMER_TRIGGER_MISSED +		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 end of grab event using MdigHookFunction() with M_GRAB_END or if the hook-handler function was hooked using MdigProcess(). You must specify a combination value from the following table: To set the timer to inquire (summarize) Retrieves the number of triggers missed by the specified timer. (more details...)		†									j	k	l	m			p	q	r
	Value	Specifies the number of missed triggers.		†									j	k	l	m			p	q	r

Combination constant for M_TIMER_TRIGGER_MISSED.

You must add the following value to the above-mentioned value to set the timer to inquire.

For specifying the timer to inquire
Combination value	Description	MIL system-specific tooltip (†)
M_TIMERn	Specifies the timer, where n can be from 1 to 4.	†	j	k	l	m	p	q	r

Combination constants for M_MODIFIED_BUFFER.

You can add one of the following values to the above-mentioned value to specify the type of information to return about the modified image buffer.

For retrieving information about the modified image buffer
InfoType		Description	MIL system-specific tooltip (†)
	UserVarPtr - Possible values returned	Description
M_BUFFER_ID		Retrieves the MIL identifier of the modified image buffer. (summarize) Retrieves the MIL identifier of the modified image buffer. (more details...)																				†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	UserVarPtr data type info	Data type: MIL_ID	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	MIL buffer identifier	Specifies the MIL identifier of the modified image buffer associated with the event.	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
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. (summarize) 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(). (more details...)	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies the index of the modified image buffer.	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_REGION_OFFSET_X		Retrieves the X-offset of the modified region (of the image buffer). (summarize) Retrieves the X-offset of the modified region (of the image buffer). (more details...)	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies the X-offset of the modified region.	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_REGION_OFFSET_Y		Retrieves the Y-offset of the modified region (of the image buffer). (summarize) Retrieves the Y-offset of the modified region (of the image buffer). (more details...)	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies the Y-offset of the modified region.	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_REGION_SIZE_X		Retrieves the width of the modified region (of the image buffer). (summarize) Retrieves the width of the modified region (of the image buffer). (more details...)	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies the width of the modified region.	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_REGION_SIZE_Y		Retrieves the height of the modified region (of the image buffer). (summarize) Retrieves the height of the modified region (of the image buffer). (more details...)	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
	Value	Specifies the height of the modified region.	†	a	b	c	e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

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.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

For retrieving information about an I/O event
InfoType		Description	MIL system-specific tooltip (†)
	UserVarPtr - Possible values returned	Description
M_IO_INTERRUPT_SOURCE		Retrieves the auxiliary input signal that generated the interrupt. (summarize) Retrieves the auxiliary input signal that generated the interrupt. (more details...)												†	c	j	k	l	m	o	p	q	r	s
	M_AUX_IOn	Specifies the auxiliary input signal that generated the interrupt, where n is the signal number.	†	c	j	k	l	m	o	p	q	r	s
M_IO_STATUS		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. (summarize) Retrieves the state of the input signal that generated the interrupt. (more details...)	†	c	j	k	l	m	o	p	q	r	s
	M_OFF	Specifies that the auxiliary input signal that generated the interrupt is off.	†	c	j	k	l	m	o	p	q	r	s
	M_ON	Specifies that the auxiliary input signal that generated the interrupt is on.	†	c	j	k	l	m	o	p	q	r	s

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.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_INT.

For retrieving information about a rotary decoder event
InfoType		Description	MIL system-specific tooltip (†)
	UserVarPtr - Possible values returned	Description
M_ROTARY_ENCODER_FRAME_END_POSITION +		Retrieves the value of the rotary decoder's counter at the end of the last frame grabbed before the counter reached its trigger position. (summarize) Retrieves the value of the rotary decoder's counter at the end of the last frame grabbed before the counter reached its trigger position. (more details...)								†	j	k	m	p	q	r
	Value	Specifies the value of the rotary decoder's counter when the last frame was grabbed.	†	j	k	m	p	q	r

Combination constant for M_ROTARY_ENCODER_FRAME_END_POSITION.

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

For specifying which rotary decoder to inquire
Combination value	Description	MIL system-specific tooltip (†)
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. (summarize) Specifies to inquire rotary decoder n, where n is a number between 1 and 4. (more details...)	†	k	p	q	r

Return value

The returned value is M_NULL if successful. If the operation fails, a non-null (!M_NULL) value is returned.

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.