| Customize Help
| Save Settings

MbufControlFeature


Function Map
Syntax
Description
Parameters
- BufId
- 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
Compilation information
Synopsis
Controls a feature of a buffer.
Syntax
void MbufControlFeature(
MIL_ID BufId, //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 buffers. For more information, refer to Using Matrox GenTL Consumer driver with MIL.

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 GenTL buffer's description file (XML). MIL provides two versions of an interface that you can use to interactively inquire the buffer's features. At design-time, you can use Matrox Intellicam's Feature Browser. At runtime, you can launch Matrox Feature Browser, using MbufControl() with M_GC_FEATURE_BROWSER. Both versions of Matrox 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 buffer-specific feature, use MbufInquireFeature().

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
BufId

Specifies the identifier of the buffer to control. This parameter must be given a valid buffer identifier, previously allocated using MbufAlloc...().

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 buffer 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 the GenTL library's documentation for a list of the features available.

(summarize)
‡ v

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.

 ‡ v
Click to summarize M_TYPE_DOUBLE

Specifies that UserVarPtr is passed an address of type MIL_DOUBLE.

 ‡ v
Click to summarize M_TYPE_INT64

Specifies that UserVarPtr is passed an address of type MIL_DOUBLE.

 ‡ v
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)
‡ v
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)
‡ v
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)
‡ v
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 MbufInquireFeature() 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 MbufHookFunction() 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 MbufHookFunction() with M_FEATURE_CHANGE + M_ALL.

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

(summarize)
‡ v
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: address of a MIL_INT
 ‡ 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)
‡ v
Click to summarize M_ENABLE

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

 ‡ v
Click to summarize M_FEATURE_EXECUTE

Sets that the specified command feature must be executed.

(summarize)
‡ v
Expand data type infoCollapse data type info UserVarPtr extra info
Data type info: Data type: Set this parameter to M_NULL
 ‡ v
Click to summarize M_FEATURE_MAX

Specifies to set the feature to its maximum value.

(summarize)
‡ v
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
 ‡ v
Click to summarize M_FEATURE_MIN

Specifies to set the feature to its minimum value.

(summarize)
‡ v
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
 ‡ v
Click to summarize M_FEATURE_VALUE

Sets the current value of the feature.

(summarize)
‡ v
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
 ‡ 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 TYPE BOOLEAN TYPE DOUBLE TYPE INT64 TYPE UINT8 TYPE STRING