MsysControl

Board	Supported
Host System	Partial
V4L2	Partial
Clarity UHD	Partial
Concord PoE	Partial
GenTL	Partial
GevIQ	Partial
GigE Vision	Partial
Indio	Partial
Iris GTX	Partial
Radient eV-CL	Partial
Rapixo CL	Partial
Rapixo CoF	Partial
Rapixo CXP	Partial
USB3 Vision	Partial

Control a system setting.

Syntax

void MsysControl(
    AIL_ID     SysId,        //out
    AIL_INT64  ControlType,  //in
    AIL_DOUBLE ControlValue  //in
)

Description

This function allows you to control the specified system setting.

Note: Note that, when a control type has only one supported control value on a given system, it is not documented in this function because it cannot be changed to another value. Instead, it can only be inquired.

To inquire the current value of a particular system setting, use MsysInquire.

You can also interactively control and test most of the system settings in real-time, using Aurora Imaging Intellicam's Feature Browser.

Parameters

`SysId` (out, AIL_ID)

Specifies the system identifier. This parameter should be set to one of the following values:

For the system identifier

Value	Description
`M_DEFAULT_HOST`	Specifies the default Host system of the current Aurora Imaging Library application.
`System identifier`	Specifies a valid system identifier, previously allocated using `MsysAlloc`.

`ControlType` (in, AIL_INT64)

Specifies the type of setting to control.

`ControlValue` (in, AIL_DOUBLE)

Specifies the new value to assign to the system setting specified by the ControlType parameter.

Parameter Associations

For general system settings

The following control types allow you to control the general system settings.

`M_ALLOCATION_OVERSCAN`

Sets whether image buffers, allocated on the system, are allocated by default with an overscan region. Specify the size of the overscan region using M_ALLOCATION_OVERSCAN_SIZE. Note that you can override this setting when allocating a buffer using the M_ALLOCATION_OVERSCAN attribute.

Value	Description
`M_DEFAULT`
`M_DISABLE`	Specifies that image buffers allocated on the system will have no overscan region.
`M_ENABLE` (default)	Specifies that image buffers are allocated on the system with an overscan region.

`M_ALLOCATION_OVERSCAN_SIZE`

Sets the size of the overscan region, added around all subsequently allocated image buffers (MbufAlloc...). The overscan settings previously allocated image buffers are not changed. For more information, see Buffer overscan region. To enable or disable the allocation of an overscan region, change the setting of M_ALLOCATION_OVERSCAN.

Value	Description
`M_DEFAULT` (default)	Specifies the default size of the overscan region.
`Value`	Specifies the size of the overscan region, in pixels. For example, if you specify a size of 2, a 2-pixel overscan border is added around subsequently allocated image buffers.

`M_DEBUG_LOG_INFO`

Board availability: GevIQ, GigE Vision, Host System, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision

Logs a user-defined event in Aurora Imaging Gecho Viewer. The event will appear in its thread's timeline. This control can be useful for debugging or monitoring specific sections of code or internal data for your application.

Value	Description
`Value`	Specifies the value that will be logged for the user-defined event.

`M_DEFAULT_PITCH_BYTE_MULTIPLE`

Sets the pitch (or stride) multiple (in bytes) for the buffers allocated on the system. The pitch is the number of bytes between the beginnings of any two adjacent rows of the buffer's data. The pitch multiple is the factor by which the pitch of a buffer must be divisible. When a buffer is allocated, if the specified width is not a multiple of this value, padding is added to the buffer so that the buffer's pitch meets this constraint. You would typically change this value when you need to reduce the padding of your buffer. Note that, allocating a buffer with an overscan region can also be a cause of buffer padding. For more information, refer to M_ALLOCATION_OVERSCAN and Accessing an Aurora Imaging Library buffer directly. When dealing with an on-board operation, changing the pitch multiple might force on-board operations to be performed off-board due to hardware limitations, thereby increasing the amount of time the operation might take.

Value	Description
`M_DEFAULT`	Specifies the default value for the pitch multiple. The default value is highly Aurora Imaging Library system-dependent. Always inquire the current pitch multiple before setting it, using `MsysInquire` with `M_DEFAULT_PITCH_BYTE_MULTIPLE`.
`Value`	Specifies the pitch multiple, in bytes.

`M_DEVICE_NAME`

Board availability: Concord PoE

Sets a user-defined name for the board. The user-defined name is written to the board, making it persistent, and allows the board to be allocated using this user-defined name in the future. The name is typically assigned and written to the board from a separate executable that allocates a system for the board with M_DEVn and then calls MsysControl with the control type (M_DEVICE_NAME). > Note: This control type is also available for the Zebra Concord PoE base model.

Value	Description
`"DeviceName"`	Specifies the name of the board. Note that this must be a unique name with a string that can be up to `M_DEVICE_NAME_MAX_SIZE` characters.

`M_GC_FEATURE_BROWSER`

Board availability: GenTL

Sets whether to open or close a dialog box that allows you to view and edit the GenTL SFNC-compliant system and interface configuration information interactively. This window is referred to as the Feature Browser.

Value	Description
`M_DEFAULT`
`M_CLOSE`	Closes Feature Browser.
`M_OPEN` (default)	Opens Feature Browser.

`M_GC_FEATURE_EXECUTE_POLLING_MODE`

Board availability: GenTL, GevIQ, GigE Vision, Rapixo CXP, Rapixo CoF

Sets whether the executable feature is executed synchronously or asynchronously.

Value	Description
`M_DEFAULT`
`M_AUTOMATIC`	Specifies that the specific executable camera feature is executed synchronously. When in automatic mode, the executable feature is executed synchronously. Aurora Imaging Library polls the feature to establish if the executable feature has completed, returning control only when the operation is complete. Get the polling interval using `M...InquireFeature` with `M_FEATURE_POLLING_INTERVAL`.
`M_MANUAL` (default)	Specifies that the executable camera feature is executed asynchronously. When in manual mode, the executable feature is executed asynchronously, and control is returned once the executable operation begins. To determine whether the executable feature completed, use `M...InquireFeature` with `M_FEATURE_EXECUTE_COMPLETED`.

`M_LED_USER`

Board availability: Iris GTX

Sets the color of the user LED on your Zebra Iris GTX.

Value	Description
`M_DEFAULT`
`M_GREEN`	Specifies to turn the user LED green.
`M_OFF` (default)	Specifies to turn the user LED off.
`M_ORANGE`	Specifies to turn the user LED orange.
`M_RED`	Specifies to turn the user LED red.

`M_MODIFIED_BUFFER_HOOK_MODE`

Board availability: Clarity UHD, GenTL, GevIQ, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision, V4L2

Sets whether to run user-defined functions hooked to a buffer modification on separate threads, up to the number of CPU cores present in the computer. This is particularly useful when functions are hooked using MdigProcess.

Value	Description
`M_DEFAULT`
`M_MULTI_THREAD`	Specifies to run user-defined functions hooked to a buffer modification on separate threads. The hooked functions are executed by any available CPU core. Aurora Imaging Library cannot guarantee the processing order of any image on such a computer, because they are executed concurrently. If required, use Microsoft Windows functions to synchronize the threads. > Note: Note that by default, this control value will allocate, as necessary, up to 16 threads, or the total number of CPU cores in the computer, whichever is least.
`M_SINGLE_THREAD` (default)	Specifies that only one thread should be created and that all user-defined functions hooked to buffer modifications are run on the same thread.

`M_POWER_OVER_CABLE`

Board availability: Concord PoE, Host System, Rapixo CXP

Sets whether the board provides power to connected devices.

System specific

Board(s)	Note
Host System	For a Host system, this sets whether PoE (Power over Ethernet) is enabled on the specified port. This constant is only available on a Host system if the Host system was previously allocated on a Zebra 4Sight EV6/EV7. It is not available on Zebra 4Sight XV6/XV7.
Concord PoE	For Zebra Concord PoE, this sets whether PoE (Power over Ethernet) is enabled on all ports. > Note: This control type is also available for the Zebra Concord PoE base model.
Rapixo CXP	For Zebra Rapixo CXP, this sets whether PoCXP (Power over CXP) is automatically enabled when a PoCXP-compliant camera is connected to the specified connector.

Value	Description
`M_DEFAULT`	Specifies the default value.
`M_AUTOMATIC`	Specifies to automatically enable or disable PoCXP on this CXP connector, depending on detected device support. [Rapixo CXP]
`M_OFF`	Specifies not to provide power to connected devices.
`M_ON`	Specifies to provide power to connected devices.
`M_RESET`	Specifies to reset an over- or under-current condition. To learn whether there is an over- or under-current condition, use `MsysInquire`with `M_POWER_OVER_CABLE_STATUS`. > Note: Typically, to prevent the over- or under-current condition from immediately recurring, you should first restart PoCXP for this connector by setting this control type to `M_OFF` and then returning it to its previous setting (`M_AUTOMATIC` is recommended). If the condition persists, discontinue using PoCXP with your camera by leaving this control type set to `M_OFF`. [Rapixo CXP]

`M_THREAD_MODE`

Sets whether threads allocated on the system can execute in asynchronous mode. If you specify that threads on the system can execute in asynchronous mode, the MthrControl M_THREAD_MODE control type setting of each of its threads is taken into account; otherwise, their M_THREAD_MODE control type setting is ignored.

System specific

Board(s)	Note
Concord PoE	> Note: This inquire type is also available for the Zebra Concord PoE base model.

Value	Description
`M_DEFAULT`	Specifies the default value.
`M_ASYNCHRONOUS`	Specifies that threads allocated on the system can execute in asynchronous mode. In asynchronous mode, control is returned to the Host immediately after an Aurora Imaging Library function is sent to the processor of the system (when the system and function allow an immediate return). [Clarity UHD, GenTL, GevIQ, GigE Vision, Iris GTX, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision, V4L2]
`M_SYNCHRONOUS`	Specifies that threads allocated on the system can only execute in synchronous mode. In synchronous mode, the execution of an Aurora Imaging Library function sent to the processor of a system must be completed (execution terminated) before returning control to the Host.

`M_TIMEOUT`

Board availability: Clarity UHD, Concord PoE, GenTL, GevIQ, GigE Vision, Iris GTX, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision, V4L2

Sets the maximum amount of time for the Host to wait for a synchronous function to return before generating a time-out error, in sec. Note that this value only works with functions that are performed on-board, such as MbufCopy when copying from (or to) on-board memory or functions using an on-board processing FPGA.

System specific

Board(s)	Note
Concord PoE	> Note: This inquire type is also available for the Zebra Concord PoE base model.

Value	Description
`M_DEFAULT`	Specifies the default value.
`M_INFINITE`	Waits indefinitely. [Iris GTX]
`Value`	Specifies the time to wait, in sec.

Combination Constants — For specifying which connector or port to control

Essential.

Usage: You must add one of the following values to the above-mentioned values to specify which connector or port to control.

Board availability: Host System, Rapixo CXP

Value	Description
`M_ALL`	Specifies to control all relevant connectors or ports on your board or industrial computer.
`M_CONNECTIONn`	Specifies to control connector_n_, where n corresponds to a physical connector or port on your board or industrial computer.

Combination Constants — For specifying which configuration information file to access

Optional.

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

Board availability: GenTL

Value	Description
`M_GENTL_INTERFACE_NUMBER`	Specifies which instance of the GenTL interface configuration file is associated with the feature.
`M_GENTL_SYSTEM`	Specifies to display the GenTL system configuration information.

Combination Constants — For specifying whether Feature Browser should be synchronous or asynchronous

Essential.

Usage: You must add one of the following values to the above-mentioned values to set whether the Feature Browser should be synchronous or asynchronous.

Board availability: GenTL

Value	Description
`M_ASYNCHRONOUS`	Specifies that this function returns immediately once a Feature Browser window opens.
`M_SYNCHRONOUS` (default)	Specifies that this function is blocked until a Feature Browser window closes.

Combination Constants — For specifying the number of hook threads

Optional.

Usage: You can add one of the following values to the above-mentioned values to set the number of hook threads to allocate.

Board availability: GenTL, GigE Vision, Radient eV-CL, Rapixo CL, Rapixo CXP, Rapixo CoF, USB3 Vision, V4L2

Value	Description
`Value >= 1`	Specifies the number of hook threads to allocate. Note that this value cannot exceed the number of CPU cores available.

For discovering connected devices

The following control type allows you to refresh the list of discovered devices.

Board availability: GenTL, GevIQ, GigE Vision, Rapixo CXP, Rapixo CoF, USB3 Vision, V4L2

`M_DISCOVER_DEVICE`

Refresh the list of discovered devices that can be accessed by the specified system (for example, all cameras connected to a frame grabber, or all GigE Vision devices accessible on the local subnet). After you have refreshed the list, you can inquire information about connected devices using MsysInquirewith settings fromDiscoverySettings. > Note: Note that this does not affect which devices are available for you to allocate using MdigAlloc; you do not need to discover a device before allocating it.

System specific

Board(s)	Note
GevIQ, GigE Vision, USB3 Vision	This can trigger an`M_CAMERA_PRESENT` event.

Value	Description
`M_DEFAULT`	Specifies the default mode of operation for `M_DISCOVER_DEVICE`.

For routing I/O signals and setting their mode

The following control types allow you to set the mode and the routing of your Zebra imaging board's I/O signals (such as, auxiliary signal). Once the routing and mode are determined for an I/O signal, the Aurora Imaging Library function that you should use to act upon an input signal or setup the source of an output signal depends on the functionality. For example, you can use MsysControl with M_USER_BIT... control types, MdigControl with M_GRAB_TRIGGER... control types, or MdigControl with M_TIMER... control types. Note that for other Zebra imaging boards that have auxiliary I/O signals, but are not supported with the constants below, see MdigControl. Each Zebra imaging board and Aurora Imaging Library driver has its own list of limitations regarding the signals you can control with this function. While general limitations are listed in the table below, for a complete list of the available signals and their limitations, see the Connectors and signal names section of the Aurora Imaging Library Hardware-specific Notes chapter for your Zebra imaging board or Aurora Imaging Library driver.

Board availability: Concord PoE, Host System, Indio, Iris GTX

`M_IO_DEBOUNCE_TIME`

Board availability: Concord PoE, Host System, Indio, Iris GTX

Sets the amount of time that the specified auxiliary input signal is debounced.

System specific

Board(s)	Note
Host System	When a signal is debounced on Zebra 4Sight EV6/EV7, after detecting a valid input signal edge any other transitions are considered noise and are suppressed for the specified time, to ignore any additional transitions caused by the contact bounce of mechanical switches.
Iris GTX	When a signal is debounced on Zebra Iris GTX, after detecting a valid input signal edge any other transitions are considered noise and are suppressed for the specified time, to ignore any additional transitions caused by the contact bounce of mechanical switches. To remove problems occurring at the edge of a signal, use `M_IO_GLITCH_FILTER_STATE`.

Value	Description
`Value >= 0`	Specifies the minimum amount of time to ignore any additional signal transitions after accepting a signal transition, in nsec.

`M_IO_GLITCH_FILTER_STATE`

Board availability: Concord PoE, Host System, Indio, Iris GTX

Sets whether to enable a glitch filter on input signals. A glitch is an unexpected signal transition of a short duration. Enabling the glitch filter will eliminate glitches of less than 500 nsec on all input signals.

System specific

Board(s)	Note
Host System	This constant is only available on a Host system if the Host system was previously allocated on a Zebra 4Sight EV6/EV7. It is not available on Zebra 4Sight XV6/XV7.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies not to use a glitch filter.
`M_ENABLE`	Specifies to use a glitch filter.

`M_IO_INTERRUPT_ACTIVATION`

Sets the signal transition upon which to generate an interrupt, if interrupt generation has been enabled for the specified I/O signal. Use M_IO_INTERRUPT_STATE to enable interrupt generation. Note that this only applies to input signals. Note that this control type only has an effect when M_IO_INTERRUPT_STATE is enabled.

System specific

Board(s)	Note
Iris GTX	This control type is only available with auxiliary I/O signals 3-6.
Host System	This constant is only available on a Host system if the Host system was previously allocated on a Zebra 4Sight EV6/EV7. It is not available on Zebra 4Sight XV6/XV7.

Value	Description
`M_DEFAULT`
`M_ANY_EDGE`	Specifies to generate an interrupt upon both a low-to-high and a high-to-low signal transition. [Host System, Indio, Iris GTX]
`M_EDGE_FALLING`	Specifies that an interrupt will be generated upon a high-to-low signal transition.
`M_EDGE_RISING` (default)	Specifies that an interrupt will be generated upon a low-to-high signal transition.

`M_IO_INTERRUPT_STATE`

Sets whether to generate an interrupt upon the specified transition of the I/O signal. Use M_IO_INTERRUPT_ACTIVATION to specify the transition.

System specific

Board(s)	Note
Iris GTX	This control type is only available with auxiliary I/O signals 3-6.
Host System	This constant is only available on a Host system if the Host system was previously allocated on a Zebra 4Sight EV6/EV7. It is not available on Zebra 4Sight XV6/XV7.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies not to generate an interrupt.
`M_ENABLE`	Specifies to generate an interrupt.

`M_IO_INVERTER`

Board availability: Concord PoE, Host System, Indio, Iris GTX

Sets whether the specified I/O signal should be inverted. This causes the low portion of the signal (the delay period) to be high and the high portion of the signal (the active portion) to be low.

System specific

Board(s)	Note
Host System	This constant is only available on a Host system if the Host system was previously allocated on a Zebra 4Sight EV6/EV7. It is not available on Zebra 4Sight XV6/XV7.

Value	Description
`M_DEFAULT`
`M_DISABLE` (default)	Specifies not to invert the specified I/O signal.
`M_ENABLE`	Specifies to invert the specified I/O signal.

`M_IO_SOURCE`

Board availability: Concord PoE, Host System, Indio, Iris GTX

Sets the type of signal to route to an output signal, or a bidirectional signal set to output mode.

System specific

Board(s)	Note
Host System	This constant is only available on a Host system if the Host system was previously allocated on a Zebra 4Sight EV6/EV7. It is not available on Zebra 4Sight XV6/XV7.

Value	Description
`M_DEFAULT`
`M_EXPOSURE`	Specifies to route the exposure signal of the camera. [Iris GTX]
`M_GRAB_TRIGGER_READY`	Specifies to route the internal grab trigger ready signal. [Iris GTX]
`M_IO_COMMAND_LISTn`	Specifies to route a bit of the I/O command register of I/O command list n, where n is the number of the I/O command list. [Concord PoE, Host System, Indio, Iris GTX]
`M_ROTARY_ENCODERn`	Specifies to route the output of rotary encoder n, where n is the number of rotary encoders available.
`M_TIMER_STROBE`	Specifies to route the internal timer strobe signal. [Iris GTX]
`M_TIMERn`	Specifies to route the output of timer n, where n is the number of timers available.
`M_USER_BITn` (default)	Specifies to route the state of bit n of the main static-user-output register, where n is the bit number.

Combination Constants — For specifying the type and number of the I/O signal to affect

Essential, cannot be used alone.

Usage: You must add one of the following values to the above-mentioned values to set the type and number of the I/O signal to affect.

Board availability: Concord PoE, Host System, Indio, Iris GTX

Value	Description
`M_AUX_IOn`	Specifies to affect auxiliary signal n, where n is the signal number. For a list of the available auxiliary I/O signals, see the Connectors and signal names section of the Aurora Imaging Library Hardware-specific Notes chapter for your Zebra imaging board.