MdigControlFeature

Filters
See also

User Guide:

DirectShow capture filter for MIL Grabbing with triggers Steps to use I/O signals Using MIL with GenICam

Reference:

MdigAlloc MdigControl MdigGetHookInfo MdigHookFunction MdigInquireFeature

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Host system (a)

Not supported on Matrox CronosPlus (b)

Not supported on Matrox GPU processing driver (d)

Not supported on Matrox IEEE 1394 IIDC driver (e)

Not supported on Matrox Iris GT (f)

Not supported on Matrox Morphis (g)

Not supported on Matrox Morphis QxT (h)

Not supported on Matrox Orion HD (i)

Not supported on Matrox Solios eA/XA (l)

Not supported on Matrox Vio (n)

Not supported on Matrox Iris GTR (requires Update 28) (t)

Partially supported on:

Partially supported on Matrox GigE Vision driver (c)

Partially supported on Matrox Radient eCL (j)

Partially supported on Matrox Radient eV-CXP (k)

Partially supported on Matrox Solios ecl/xcl/ev-cl (m)

Partially supported on Matrox USB3 Vision driver (requires Update 19) (o)

Partially supported on Matrox RadientPro-CL (requires Update 7) (p)

Partially supported on Matrox Radient eV-CL (requires Update 27) (r)

Partially supported on Matrox GigE Vision driver (requires Update 25) (s)

Fully supported on:

Fully supported on Matrox Radient eV-CLHS (requires Update 21) (q)

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/GPm

Available on Matrox Supersight

Function map

Examples

actiontrigger.cpp
baslertofexample.cpp
cameraevents.cpp
chunkmode.cpp
matroxgatoreye.cpp
milgige.cpp
packetdelay.cpp

Function Map

- DigId

- FeatureName

Table:

For specifying the name of the feature

- UserVarType

Table:	For specifying the UserVarPtr's data type
+ combination:	For specifying the length of the array

- UserVarPtr

Parameter Associations

Table:

For specifying the type of information about the feature to set and the data type returned

Compilation information

Synopsis

Controls a feature of the camera.

Syntax

void MdigControlFeature(

MIL_ID DigId,	//in
MIL_INT64 ControlType,	//in
MIL_CONST_TEXT_PTR FeatureName,	//in
MIL_INT64 UserVarType,	//in
const void *UserVarPtr	//in

)

Description

This function allows you to directly control various GenICam standard feature naming convention (SFNC) features and manufacturer-specific features of the camera. For more information, refer to the Using MIL with GenICam section of Chapter 25: Grabbing with your digitizer.

[Matrox Radient eCL; Matrox Radient eV-CL (requires Update 27); Matrox RadientPro-CL (requires Update 7); Matrox Solios ecl/xcl/ev-cl]

For Camera Link boards to work with this function, you must first configure and enable the GenICam CLProtocol module, using MdigControl() with M_GC_CLPROTOCOL. Note that this control type is only available after the required third-party vendor-supplied, standard compliant, CLProtocol library for your Camera Link camera is installed on your computer and M_GC_CLPROTOCOL_DEVICE_ID is set.

The features described in this function are primarily available to set existing settings using MIL code or to set information from which you can build your own interface for the camera device's description file (XML). MIL provides two versions of an interface that you can use to interactively inquire the camera's features. At design-time, you can use Matrox Intellicam's Feature Browser. At runtime, you can launch the Feature Browser, using MdigControl() with M_GC_FEATURE_BROWSER. Both versions of the Feature Browser provide a list of available feature names and associated possible values, as well as code snippets with the MIL functions and MIL constants associated with the settings selected; you can copy the code snippets to your MIL application code.

To inquire a camera's manufacturer-specific feature, use MdigInquireFeature().

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 accessing the camera to control. This parameter must be given a valid digitizer identifier, previously allocated using MdigAlloc().

ControlType

Specifies the type of information to control for the specified feature.

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

FeatureName

Specifies the name of the camera feature to control.

For specifying the name of the feature
Value	Description	MIL system-specific tooltip (‡)
MIL_TEXT("FeatureName") ¹	Specifies the name of the feature. Note that the feature name is case-sensitive. Refer to your camera's documentation for a list of the features available. (summarize) Specifies the name of the feature. (more details...)	‡	c	j	k	m	o	p	q	r	s

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

UserVarType

Specifies the data type of the address pointed to by the UserVarPtr parameter. If not setting the feature's value (using M_FEATURE_VALUE), set this parameter to M_DEFAULT.

Note that, in the case of a string (or a multi-byte register), the size of the array passed to the UserVarPtr parameter must be equal to or larger than the returned information; otherwise a GPF will occur.

For specifying the UserVarPtr's data type
Value	Description	MIL system-specific tooltip (‡)
M_TYPE_BOOLEAN	Specifies that UserVarPtr is passed an address of type MIL_BOOL.	‡	c	j	k	m	o	p	q	r	s
M_TYPE_DOUBLE	Specifies that UserVarPtr is passed an address of type MIL_DOUBLE.	‡	c	j	k	m	o	p	q	r	s
M_TYPE_INT64	Specifies that UserVarPtr is passed an address of type MIL_DOUBLE.	‡	c	j	k	m	o	p	q	r	s
M_TYPE_STRING +	Specifies that UserVarPtr is passed an address of type MIL_TEXT_CHAR. You must specify a combination value from the following table: To specify the length of the array (summarize) Specifies that UserVarPtr is passed an address of type MIL_TEXT_CHAR. (more details...)	‡	c	j	k	m	o	p	q	r	s
M_TYPE_UINT8 +	Specifies that UserVarPtr is passed an address of type MIL_UINT8. You must specify a combination value from the following table: To specify the length of the array (summarize) Specifies that UserVarPtr is passed an address of type MIL_UINT8. (more details...)	‡	c	j	k	m	o	p	q	r	s

Combination value for M_TYPE_STRING; M_TYPE_UINT8.

You must add the following value to the above-mentioned values to specify the length of the array.

For specifying the length of the array
Combination value	Description		MIL system-specific tooltip (‡)
M_FEATURE_USER_ARRAY_SIZE( MIL_INT Length )	Specifies the length of the array. (summarize) Specifies the length of the array. (more details...)		‡	‡	c	j	k	m	o	p	q	r	s	c	j	k	m	o	p	q	r	s
		Parameters
		Length Sets the length, in bytes.

UserVarPtr

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

array of type MIL_TEXT_CHAR
array of type MIL_UINT8
M_NULL
MIL_BOOL
MIL_DOUBLE
MIL_INT
MIL_INT64

Specifies the address of the variable in which to write the value of the feature.

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

Parameter associations

The table below lists possible values for the ControlType and UserVarPtr parameters.

For specifying the type of information about the feature to set and the data type returned

To determine the data type of the FeatureName specified, use MdigInquireFeature() with M_FEATURE_VALUE.

For specifying the type of information about the feature to set and the data type returned
ControlType		Description	MIL system-specific tooltip (‡)
	UserVarPtr	Description
M_FEATURE_CHANGE_HOOK		Sets whether to enable an event to occur when the value of the specified feature changes. Once enabled, use MdigHookFunction() with M_FEATURE_CHANGE to hook a specified function to the feature change event. Repeat for each feature that you want to enable a feature change event. Alternatively, to enable an event to occur when the value of any feature changes, use MdigHookFunction() with 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) Sets whether to enable an event to occur when the value of the specified feature changes. (more details...)											‡	q	s
	UserVarPtr extra info	Data type info: Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT	‡							q		s
	M_DISABLE	Specifies that no event is generated when the value of the specified feature changes. This is the default value. (summarize) Specifies that no event is generated when the value of the specified feature changes. (more details...)	‡							q		s
	M_ENABLE	Specifies that an event is generated when the value of the specified feature changes.	‡							q		s
M_FEATURE_EXECUTE		Sets that the specified command feature must be executed. (summarize) Sets that the specified command feature must be executed. (more details...)	‡	c	j	k	m	o	p	q	r	s
	UserVarPtr extra info	Data type info: Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL	‡	c	j	k	m	o	p	q	r	s
M_FEATURE_MAX		Specifies to set the feature to its maximum value. (summarize) Specifies to set the feature to its maximum value. (more details...)	‡	c	j	k	m	o	p	q	r	s
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE \| Set this parameter to M_NULL (more details...) Data type: address of a MIL_DOUBLE Note: For when controlling a feature whose feature data type is a double-precision floating-point; set UserVarType to M_TYPE_DOUBLE. Data type: Set this parameter to M_NULL Note: For when controlling a feature whose feature data type is a 64-bit integer; set UserVarType to M_TYPE_INT64. Data type info: Data type: address of a MIL_DOUBLE \| Set this parameter to M_NULL (more details...) Data type: address of a MIL_DOUBLE Note: For when controlling a feature whose feature data type is a double-precision floating-point; set UserVarType to M_TYPE_DOUBLE. Data type: Set this parameter to M_NULL Note: For when controlling a feature whose feature data type is a 64-bit integer; set UserVarType to M_TYPE_INT64.	‡	c	j	k	m	o	p	q	r	s
M_FEATURE_MIN		Specifies to set the feature to its minimum value. (summarize) Specifies to set the feature to its minimum value. (more details...)	‡	c	j	k	m	o	p	q	r	s
	UserVarPtr extra info	Data type info: Data type: address of a MIL_DOUBLE \| address of a MIL_INT64 (more details...) Data type: address of a MIL_DOUBLE Note: For when controlling a feature whose feature data type is a double-precision floating-point; set UserVarType to M_TYPE_DOUBLE. Data type: address of a MIL_INT64 Note: For when controlling a feature whose feature data type is a 64-bit integer; set UserVarType to M_TYPE_INT64. Data type info: Data type: address of a MIL_DOUBLE \| address of a MIL_INT64 (more details...) Data type: address of a MIL_DOUBLE Note: For when controlling a feature whose feature data type is a double-precision floating-point; set UserVarType to M_TYPE_DOUBLE. Data type: address of a MIL_INT64 Note: For when controlling a feature whose feature data type is a 64-bit integer; set UserVarType to M_TYPE_INT64.	‡	c	j	k	m	o	p	q	r	s
M_FEATURE_VALUE		Sets the current value of the feature. (summarize) Sets the current value of the feature. (more details...)	‡	c	j	k	m	o	p	q	r	s
	UserVarPtr extra info	Data type info: Data type: address of a MIL_BOOL \| address of a MIL_DOUBLE \| address of a MIL_INT64 \| array of type MIL_UINT8 \| array of type MIL_TEXT_CHAR (more details...) Data type: address of a MIL_BOOL Note: For when controlling a feature value whose feature data type is a boolean; set UserVarType to M_TYPE_BOOLEAN. Data type: address of a MIL_DOUBLE Note: For when controlling a feature whose feature data type is a double-precision floating-point; set UserVarType to M_TYPE_DOUBLE. Data type: address of a MIL_INT64 Note: For when controlling a feature whose feature data type is a 64-bit integer; set UserVarType to M_TYPE_INT64. Data type: array of type MIL_UINT8 Required array size:(Length) Note: For when controlling a feature whose feature data type is a multi-byte register set UserVarType to M_TYPE_UINT8 + M_FEATURE_USER_ARRAY_SIZE(). Data type: array of type MIL_TEXT_CHAR Required array size:(Length) Note: For when controlling a feature whose feature data type is a string; set UserVarType to M_TYPE_STRING + M_FEATURE_USER_ARRAY_SIZE(). Data type info: Data type: address of a MIL_BOOL \| address of a MIL_DOUBLE \| address of a MIL_INT64 \| array of type MIL_UINT8 \| array of type MIL_TEXT_CHAR (more details...) Data type: address of a MIL_BOOL Note: For when controlling a feature value whose feature data type is a boolean; set UserVarType to M_TYPE_BOOLEAN. Data type: address of a MIL_DOUBLE Note: For when controlling a feature whose feature data type is a double-precision floating-point; set UserVarType to M_TYPE_DOUBLE. Data type: address of a MIL_INT64 Note: For when controlling a feature whose feature data type is a 64-bit integer; set UserVarType to M_TYPE_INT64. Data type: array of type MIL_UINT8 Required array size:(Length) Note: For when controlling a feature whose feature data type is a multi-byte register set UserVarType to M_TYPE_UINT8 + M_FEATURE_USER_ARRAY_SIZE(). Data type: array of type MIL_TEXT_CHAR Required array size:(Length) Note: For when controlling a feature whose feature data type is a string; set UserVarType to M_TYPE_STRING + M_FEATURE_USER_ARRAY_SIZE().	‡	c	j	k	m	o	p	q	r	s
M_FEATURE_VALUE_AS_STRING		Sets the current value of the feature as a string. Note that this inquire will return the current string's length. The length of the string to be written can be shorter and is determined automatically by MIL. (summarize) Sets the current value of the feature as a string. (more details...)	‡	c	j	k	m	o	p	q	r
	UserVarPtr extra info	Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size:(Length) Note: For when controlling a feature whose feature data type is a string; set UserVarType to M_TYPE_STRING + M_FEATURE_USER_ARRAY_SIZE(). Data type info: Data type: array of type MIL_TEXT_CHAR (more details...) Data type: array of type MIL_TEXT_CHAR Required array size:(Length) Note: For when controlling a feature whose feature data type is a string; set UserVarType to M_TYPE_STRING + M_FEATURE_USER_ARRAY_SIZE().	‡	c	j	k	m	o	p	q	r

Compilation information

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