| MIL 10 Reference
| Customize Help
| Save Settings

MdigInquireFeature


See also
Availability
Available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Not supported on:
Not supported on Host system
Not supported on Matrox CronosPlus
Not supported on Matrox GPU processing driver
Not supported on Matrox IEEE 1394 IIDC driver
Not supported on Matrox Iris GT
Not supported on Matrox Morphis
Not supported on Matrox Morphis QxT
Not supported on Matrox Orion HD
Not supported on Matrox Solios eA/XA
Not supported on Matrox Vio
Partially supported on:
Partially supported on Matrox GigE Vision driver
Partially supported on Matrox Radient eCL
Partially supported on Matrox Radient eV-CXP
Partially supported on Matrox Solios ecl/xcl/ev-cl

Fully supported on:
Fully supported on Matrox USB3 Vision driver (requires Update 19)

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 Function map
Examples
MdigInquire
MdigProcess
Synopsis
Inquires a feature of the camera.
Syntax
void MdigInquireFeature(
MIL_ID DigId, //in
MIL_INT64 InquireType, //in
MIL_CONST_TEXT_PTR FeatureName, //in
MIL_INT64 FeatureType, //in
void *UserVarPtr //out
)
Description

This function allows you to directly inquire various GenICam standard feature naming convention (SFNC) features and manufacturer-specific features of the camera. When used with a GenICam SFNC-compliant camera, it allows you to directly inquire various manufacture-specific features specified with the camera's device description file (XML). Note that for the purpose of this function, a feature can also be of type category or command. Although category and command features lack a feature value, all other attributes of the feature can be inquired. For a list of standard category feature names, see the Standard Feature Naming Convention or your GenICam SFNC-compliant camera's documentation.

[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. For more information, refer to the Using MIL with GenICam section of Chapter 23: Grabbing with your digitizer.

There are also two ways to interactively inquire the camera's features in real-time. At design-time, you can use Matrox Intellicam's Feature Browser. At runtime, you can launch a more limited version of this Feature Browser, using MdigControl() with M_GC_FEATURE_BROWSER. Both versions of the Feature Browser provide a complete 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, which you can copy to your MIL application code.

To control a camera's manufacturer-specific feature, use MdigControlFeature().

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

InquireType

Specifies the type of information to inquire about the feature.

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

FeatureName

Specifies the name of the camera feature to inquire. Note that this parameter expects a case-sensitive string.

function map For specifying the name of the feature
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse 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 j k m o p q r s
Collapse MIL_TEXT("Root") 1

Specifies to inquire the highest-level feature of the XML structure; this feature is of type category and typically, its subfeatures are also of type category. Note that this value is only available when using M_SUBFEATURE_....

(summarize)
† c j k m o p q r s

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

FeatureType

Specifies the data type of the specified camera feature. If not inquiring the feature's value (using M_FEATURE_VALUE), set this parameter to M_DEFAULT.

function map For specifying the feature's type
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse M_DEFAULT

Specifies the default data type.

 † c j k m o p q r s
Collapse M_TYPE_BOOLEAN

Specifies that the feature value is expressed as a boolean.

 † c j k m o p q r s
Collapse M_TYPE_DOUBLE

Specifies that the feature value is expressed as a floating-point.

 † c j k m o p q r s
Collapse M_TYPE_ENUMERATION

Specifies that the feature value is expressed as an enumeration.

 † c j k m o p q r s
Collapse M_TYPE_INT64

Specifies that the feature value is expressed as a 64-bit integer.

 † c j k m o p q r s
Collapse M_TYPE_REGISTER

Specifies that the feature is mapped to a multi-byte register.

 † c j k m o p q r s
Collapse M_TYPE_STRING

Specifies that the feature value is expressed as a string.

 † c j k m o p q r s
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
  • MIL_BOOL
  • MIL_DOUBLE
  • MIL_INT
  • MIL_INT64
  • MIL_TEXT_CHAR

Specifies the address of the variable in which to return 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 InquireType parameter and possible values returned to the UserVarPtr parameter.

The following inquire types are used to specify the type of information about the feature to inquire and the data type returned.

function map For specifying the type of information to inquire about the feature and the data type returned
CollapseInquireType Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_FEATURE_ACCESS_MODE

Inquires whether the specified feature is implemented, available, readable, and/or writable.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse Bit-encoded access mode value

Specifies an encoded value that details the access mode. To retrieve the data stored as the access mode, use the following macros:

  • To learn whether the specified feature is available, use the M_FEATURE_IS_AVAILABLE macro. Note that if a feature is not available, use M_FEATURE_IS_IMPLEMENTED to learn whether the specified feature is only temporarily unavailable or actually not implemented in your camera. A feature that is temporarily unavailable typically relies on the setting of another feature (for example, when a trigger feature is set to off, its associated trigger polarity feature would be unavailable).

  • To learn whether the specified feature is implemented, use the M_FEATURE_IS_IMPLEMENTED macro.

  • To learn whether the specified feature can be read, use the M_FEATURE_IS_READABLE macro.

  • To learn whether the specified feature can be written to, use the M_FEATURE_IS_WRITABLE macro.

For example, a Bayer color feature would not be implemented on a monochrome camera because the hardware cannot support it.

Note that an error is generated if the feature does not exist in the camera's device description file (XML). To learn if the specified feature exists in the file and is implemented on your camera, use M_FEATURE_PRESENT.

(summarize)
† c j k m o p q r s
Collapse M_FEATURE_CACHING_MODE

Inquires whether a copy of the specified feature's value is stored in Host memory for faster access and retrieval. A cachable feature value is typically only retrieved from the camera whenever the cache is invalidated (such as, before the first read and the first read to occur after a write operation). A cachable feature value is typically a value that does not change on its own. Typically, if the feature is pollable, it is not cachable. For example, a temperature feature is not cachable.

To return a true/false value for this inquire, use the M_FEATURE_IS_CACHABLE macro on the returned result.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_FEATURE_CACHING_MODE_NONE

Specifies that the feature is not cachable.

 † c j k m o p q r s
Collapse M_FEATURE_CACHING_MODE_WRITE_AROUND

Specifies that feature values are written only to the camera, and the cache is updated the next time the feature value is inquired.

 † c j k m o p q r s
Collapse M_FEATURE_CACHING_MODE_WRITE_THROUGH

Specifies that when information is written to the camera, the cache is updated simultaneously.

 † c j k m o p q r s
Collapse M_FEATURE_DEPRECATED

Inquires whether the specified feature is deprecated and should no longer be used.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_FALSE

Specifies that the feature is not depreciated.

 † c j k m o p q r s
Collapse M_TRUE

Specifies that the feature is depreciated.

 † c j k m o p q r s
Collapse M_FEATURE_DESCRIPTION +

Inquires the description of the specified feature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† c j k m o p q r s
Collapse M_FEATURE_DISPLAY_NAME +

Inquires the specified feature's display name. Note that this can differ slightly from the internally-used feature name.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† c j k m o p q r s
Collapse M_FEATURE_ENUM_ENTRY_COUNT

Inquires the total number of enumeration entries in the supported enumerated list of the feature. Note that this inquire type can only be used when the feature type to inquire is an enumeration.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT

† c j k m o p q r s
Collapse M_FEATURE_ENUM_ENTRY_DISPLAY_NAME + n +

Inquires the display name of the specified enumeration entry of the specified feature, where n is the index into the enumerated list. Note that this can differ slightly from the internally-used enumeration string entry name.

(summarize)
† o
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† o
Collapse M_FEATURE_ENUM_ENTRY_NAME + n +

Inquires the possible enumeration string entry to which the feature can be set, where n is the index into the enumerated list. Note that this inquire type can only be used when the feature type to inquire is an enumeration.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† c j k m o p q r s
Collapse M_FEATURE_ENUM_ENTRY_VALUE + n

Inquires the possible enumeration integer value to which the feature can be set, where n is the index into the enumerated list. Note that this value can only be used when the feature type to inquire is an enumeration.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_FEATURE_INCREMENT

Inquires the feature's incremental value. For example, if a feature's possible values are 2, 4, 6, and so on, then its incremental value is 2.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

  • Data type: MIL_INT64
    Note: For when inquiring a feature whose feature data type is M_TYPE_INT64.

  • Data type: MIL_DOUBLE
    Note: For when inquiring a feature whose feature data type is M_TYPE_DOUBLE.

 † c j k m o p q r s
Collapse M_FEATURE_MAX

Inquires the maximum value possible for the feature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

  • Data type: MIL_INT64
    Note: For when inquiring a feature whose feature data type is M_TYPE_INT64.

  • Data type: MIL_DOUBLE
    Note: For when inquiring a feature whose feature data type is M_TYPE_DOUBLE.

 † c j k m o p q r s
Collapse M_FEATURE_MIN

Inquires the minimum value possible for the feature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

  • Data type: MIL_INT64
    Note: For when inquiring a feature whose feature data type is M_TYPE_INT64.

  • Data type: MIL_DOUBLE
    Note: For when inquiring a feature whose feature data type is M_TYPE_DOUBLE.

 † c j k m o p q r s
Collapse M_FEATURE_NAME +

Inquires the specified feature name. Note that this can differ slightly from the displayed name of the feature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† c j k m o p q r s
Collapse M_FEATURE_PRESENT

Inquires whether the specified feature name is supported on your camera. Note that, if the feature exists in the camera's device description file (XML), a similar result can be inquired using M_FEATURE_ACCESS_MODE and the M_FEATURE_IS_IMPLEMENTED macro. If the feature is not present in the file, M_FEATURE_PRESENT will return M_NO, whereas M_FEATURE_ACCESS_MODE will generate an error.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_BOOL

† c j k m o p q r s
Collapse M_NO

Specifies that the specified feature name is not present.

 † c j k m o p q r s
Collapse M_YES

Specifies that the specified feature name is present.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION

Inquires the data display format for the feature. This information is used by MdigControl() with M_GC_FEATURE_BROWSER to display the information correctly. Note that this can only be used with feature values that have a data type of MIL_INT64 or MIL_DOUBLE.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_BOOLEAN

Specifies that the feature should be displayed as a checkbox.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_HEX_NUMBER

Specifies that the feature should be displayed as a hexadecimal value.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_IPV4_ADDRESS

Specifies that the feature should be displayed as an IP address in dotted decimal notation.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_LINEAR

Specifies that the feature should be displayed as a slider with the appropriate range shown.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_LOGARITHMIC

Specifies that the feature should be displayed as a slider with the appropriate logarithmic range shown.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_MAC_ADDRESS

Specifies that the feature should be displayed as a hexadecimal MAC address.

 † c j k m o p q r s
Collapse M_FEATURE_REPRESENTATION_PURE_NUMBER

Specifies that the feature should be displayed as edit text-box with a decimal display.

 † c j k m o p q r s
Collapse M_FEATURE_SIZE

Inquires the size of the feature value, in bytes.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT

† c j k m o p q r s
Collapse M_FEATURE_STREAMABLE

Inquires whether the specified feature is streamable. A streamable feature uses a mechanism by which camera manufacturers can store configuration information to initialize the camera's state on startup, overwriting any changes made to the camera's description file (XML) during your application's execution. Streamable features are typically not persistent values (such as pixel format and image size). In most cases, these configuration files are designed to be shared between cameras, when possible.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_FALSE

Specifies that the feature is not streamable.

 † c j k m o p q r s
Collapse M_TRUE

Specifies that the feature is streamable.

 † c j k m o p q r s
Collapse M_FEATURE_TOOLTIP +

Inquires the tool tip of the specified feature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† c j k m o p q r s
Collapse M_FEATURE_TYPE

Inquires the specified feature type.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_TYPE_BOOLEAN

Specifies that the feature value is expressed as a boolean.

 † c j k m o p q r s
Collapse M_TYPE_CATEGORY

Specifies that the feature is a category feature, and its value cannot be inquired.

 † c j k m o p q r s
Collapse M_TYPE_COMMAND

Specifies that the feature is a command and its value cannot be inquired.

 † c j k m o p q r s
Collapse M_TYPE_DOUBLE

Specifies that the feature value is expressed as a floating-point.

 † c j k m o p q r s
Collapse M_TYPE_ENUMERATION

Specifies that the feature value is expressed as an enumeration.

 † c j k m o p q r s
Collapse M_TYPE_INT64

Specifies that the feature value is expressed as a 64-bit integer.

 † c j k m o p q r s
Collapse M_TYPE_REGISTER

Specifies that the feature value is mapped to a multi-byte register.

 † c j k m o p q r s
Collapse M_TYPE_STRING

Specifies that the feature value is expressed as a string.

 † c j k m o p q r s
Collapse M_FEATURE_VALUE +

Inquires the current value of the feature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info † c j k m o p q r s
Collapse M_FEATURE_VALUE_AS_STRING +

Inquires the current value of the feature as a string.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: array of type MIL_TEXT_CHAR
Array size: M_FEATURE_VALUE_AS_STRING + M_STRING_SIZE
Note: For when inquiring a feature whose feature data type is M_TYPE_ENUMERATION, M_TYPE_REGISTER, or any other type of string or non-string value to be returned as a string.

† c j k m o p q r s
Collapse M_FEATURE_VISIBILITY

Inquires the visibility level of the specified feature. The feature visibility is used in Matrox Intellicam's Feature Browser (as well as the limited version, launched using MdigControl() with M_GC_FEATURE_BROWSER). In these interfaces, specify which level of visibility should be displayed by selecting an option from the visibility drop-down. Since each feature has a visibility level, selecting a low level of visibility (such as beginner) would hide the features marked as expert and above in the interface.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_FEATURE_VISIBILITY_BEGINNER

Specifies that the feature is suggested for beginners.

 † c j k m o p q r s
Collapse M_FEATURE_VISIBILITY_EXPERT

Specifies that the feature is suggested for experts.

 † c j k m o p q r s
Collapse M_FEATURE_VISIBILITY_GURU

Specifies that the feature is suggested for advanced experts.

 † c j k m o p q r s
Collapse M_FEATURE_VISIBILITY_INVISIBLE

Specifies that the feature should not be shown. Note that these feature values can still be inquired or set using MdigControlFeature() and MdigInquireFeature().

(summarize)
† c j k m o p q r s

When the specified feature is of type category or "Root", you can use one of the following to inquire about its subfeatures. This is useful for enumerating the features of your camera.

function map For inquiring about the subfeatures of a feature
CollapseInquireType Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_SUBFEATURE_COUNT

Inquires the number of subfeatures that the specified category feature (node) has.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT

† c j k m o p q r s
Collapse Value

Specifies the number of subfeatures.

 † c j k m o p q r s
Collapse M_SUBFEATURE_NAME + n +

Inquires the name of the specified subfeature, where n is the index of subfeature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_TEXT_CHAR

† c j k m o p q r s
Collapse M_SUBFEATURE_TYPE + n

Inquires the type of the specified subfeature, where n is the index of subfeature.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT64

† c j k m o p q r s
Collapse M_TYPE_BOOLEAN

Specifies that the feature value is expressed as a boolean.

 † c j k m o p q r s
Collapse M_TYPE_CATEGORY

Specifies that the feature is a category.

 † c j k m o p q r s
Collapse M_TYPE_COMMAND

Specifies that the feature is a command to be executed.

 † c j k m o p q r s
Collapse M_TYPE_DOUBLE

Specifies that the feature value is expressed as a floating-point.

 † c j k m o p q r s
Collapse M_TYPE_ENUMERATION

Specifies that the feature value is expressed as an enumeration.

 † c j k m o p q r s
Collapse M_TYPE_INT64

Specifies that the feature value is expressed as a 64-bit integer.

 † c j k m o p q r s
Collapse M_TYPE_REGISTER

Specifies that the feature is mapped to a multi-byte register.

 † c j k m o p q r s
Collapse M_TYPE_STRING

Specifies that the feature value is expressed as a string.

 † c j k m o p q r s

You can add the following value to the above-mentioned values to get the size of a string.

function map To inquire the size of a string
CollapseInquireType combination value Description
MIL system-specific
tooltip (†)
UserVarPtr
- Possible values returned
Collapse M_STRING_SIZE

Inquires the size of the string. This returns the string length +1. For M_FEATURE_VALUE, you can only use this combination value if the feature is of type string.

(summarize)
† c j k m o p q r s
Collapse UserVarPtr data type info

Data type: MIL_INT

† c j k m o p q r s
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT TYPE BOOLEAN TYPE DOUBLE TYPE ENUMERATION TYPE INT64 TYPE REGISTER TYPE STRING FEATURE ACCESS MODE FEATURE CACHING MODE FEATURE CACHING MODE NONE FEATURE CACHING MODE WRITE AROUND FEATURE CACHING MODE WRITE THROUGH FEATURE DEPRECATED FALSE TRUE FEATURE DESCRIPTION FEATURE DISPLAY NAME FEATURE ENUM ENTRY COUNT FEATURE ENUM ENTRY DISPLAY NAME n FEATURE ENUM ENTRY NAME n FEATURE ENUM ENTRY VALUE n FEATURE INCREMENT FEATURE MAX FEATURE MIN FEATURE NAME FEATURE PRESENT NO YES FEATURE REPRESENTATION FEATURE REPRESENTATION BOOLEAN FEATURE REPRESENTATION HEX NUMBER FEATURE REPRESENTATION IPV4 ADDRESS FEATURE REPRESENTATION LINEAR FEATURE REPRESENTATION LOGARITHMIC FEATURE REPRESENTATION MAC ADDRESS FEATURE REPRESENTATION PURE NUMBER FEATURE SIZE FEATURE STREAMABLE FALSE TRUE FEATURE TOOLTIP FEATURE TYPE TYPE BOOLEAN TYPE CATEGORY TYPE COMMAND TYPE DOUBLE TYPE ENUMERATION TYPE INT64 TYPE REGISTER TYPE STRING FEATURE VALUE FEATURE VALUE AS STRING FEATURE VISIBILITY FEATURE VISIBILITY BEGINNER FEATURE VISIBILITY EXPERT FEATURE VISIBILITY GURU FEATURE VISIBILITY INVISIBLE SUBFEATURE COUNT SUBFEATURE NAME n SUBFEATURE TYPE n TYPE BOOLEAN TYPE CATEGORY TYPE COMMAND TYPE DOUBLE TYPE ENUMERATION TYPE INT64 TYPE REGISTER TYPE STRING STRING SIZE