| Customize Help
| Save Settings

MdigControlFeature


Function Map
Syntax
Description
Parameters
- DigId
- ControlType
- 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
+ combination: For specifying the configuration file associated with the feature
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 (introduced U27); Matrox RadientPro-CL (Update 7); Matrox Rapixo CL Pro (Update 96); 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.

function map For specifying the name of the feature
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize MIL_TEXT("FeatureName") 1

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)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa

1 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 an application crash will occur.

function map For specifying the UserVarPtr's data type
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize M_TYPE_BOOLEAN

Specifies that UserVarPtr is passed an address of type MIL_BOOL.

 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize M_TYPE_DOUBLE

Specifies that UserVarPtr is passed an address of type MIL_DOUBLE.

 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize M_TYPE_INT64

Specifies that UserVarPtr is passed an address of type MIL_DOUBLE.

 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize 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:
(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize M_TYPE_UINT8 +

Specifies that UserVarPtr is passed an address of type MIL_UINT8.


You must specify a combination value from the following table:
(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
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.

function map For specifying the length of the array
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize

Specifies the length of the array.

(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Parameters

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 [optionally, in C++: a reference to a MIL_STRING]
  • array of type MIL_UINT8 [optionally, in C++: a reference to a constant std::vector<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.

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

function map For specifying the type of information about the feature to set and the data type returned
Click to summarize
ControlType		 Description MIL system-specific
tooltip (‡)
UserVarPtr
Click to summarize 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 and at the same time hook a function to any feature change, use MdigHookFunction() with M_FEATURE_CHANGE + M_ALL.

(summarize)
‡ c
U25		 v
MIL system specific

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

 ‡ v
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ c
U25		 v
Click to summarize M_DISABLE

Specifies that no event is generated when the value of the specified feature changes.

This is the default value.

(summarize)
‡ c
U25		 v
Click to summarize M_ENABLE

Specifies that an event is generated when the value of the specified feature changes.

 ‡ c
U25		 v
Click to summarize M_FEATURE_EXECUTE +

Sets that the specified command feature must be executed.

(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: Set this parameter to M_NULL
 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize M_FEATURE_MAX +

Specifies to set the feature to its maximum value.

(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_DOUBLE  |  Set this parameter to M_NULL MORE
 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize M_FEATURE_MIN +

Specifies to set the feature to its minimum value.

(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_DOUBLE  |  address of a MIL_INT64 MORE
 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Click to summarize M_FEATURE_VALUE +

Sets the current value of the feature.

(summarize)
‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Expand data type infoCollapse data type info 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 [optionally, in C++: a reference to a constant std::vector<MIL_UINT8> ]  |  array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE
 ‡ c
M10		 j k
M10		 m o p r
U27		 v y
U75		 aa
Combination values for the values listed in For specifying the type of information about the feature to set and the data type returned.

You can add one of the following values to the above-mentioned values to specify the GenTL configuration file (XML file) that is associated with the feature.

function map For specifying the configuration file associated with the feature
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize

Specifies the feature is associated with an instance of the GenTL stream configuration information.

(summarize)
‡ v
Parameters

Specifies the instance (index number) of the GenTL library stream configuration information file associated with the feature.

 ‡ v
0 <= Value <= M_GENTL_STREAM_COUNT

Specifies the index.
‡ v
Click to summarize M_GENTL_DEVICE

Specifies that the feature is associated with the GenTL device configuration information.

 ‡ v
Click to summarize M_GENTL_REMOTE_DEVICE

Specifies that the feature is associated with the GenTL remote device configuration information.

This is the default value.

(summarize)
‡ v
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
TYPE BOOLEAN TYPE DOUBLE TYPE INT64 TYPE STRING TYPE UINT8 FEATURE CHANGE HOOK DISABLE ENABLE FEATURE EXECUTE FEATURE MAX FEATURE MIN FEATURE VALUE GENTL STREAM COUNT GENTL DEVICE GENTL REMOTE DEVICE TYPE BOOLEAN TYPE DOUBLE TYPE INT64 TYPE UINT8 TYPE STRING