| Customize Help

Using GigE Vision with MIL


To use your Matrox GigE Vision driver with MIL, you must allocate a MIL GigE Vision system (M_SYSTEM_GIGE_VISION), using MsysAlloc(). This allocation opens general communication with (allows you to discover) all GigE Vision-compliant cameras (or other devices) found on your network(s) (through all Gigabit Ethernet, or faster, network adapters in your computer). You must then allocate a digitizer for each camera that you want to use to grab images and/or access directly, using MdigAlloc(). In the case where you have only one network camera, use MdigAlloc() with M_DEV0. If, however, you have multiple network cameras, you should use the M_GC_CAMERA_ID() macro and specify the device's name; this will make for more portable code. You can use the Matrox Capture Assistant utility to view a list of available GigE Vision-compliant cameras and their user-defined name. For information on this utility, refer to the Matrox GigE Vision tools section later in this chapter. For information regarding working with multiple GigE Vision-compliant devices, refer to the Working with one or more GigE Vision-compliant cameras subsection of this section.

Each process (executable) can allocate only one MIL GigE Vision system; an error will occur if you try to allocate more than one. Multiple processes can allocate a MIL GigE Vision system.

Typically, multiple processes cannot allocate a digitizer for the same GigE vision-compliant camera simultaneously. However, this is not a restriction when using IP multicasting, as long as only one digitizer is allocated as a multicast master digitizer (by using MdigAlloc() with M_GC_MULTICAST_MASTER). For information regarding IP multicasting, refer to the Using IP multicast section later in this chapter.

All GigE Vision-compliant devices support configuration using the GenICam standard. To learn the list of GenICam-standard features available, refer to GenICam's standard feature naming convention (SFNC), available on the GenICam website at: http://www.genicam.org. Your camera might support additional GenICam features that do not appear in the GenICam SFNC; check your camera's manual and Matrox Capture Assistant's Feature Browser for details. Matrox Camera Assistant's Feature Browser accesses the GigE Vision-compliant camera's device description file (XML), providing an interface to view and change the camera's information.

In most cases you should control and inquire GigE Vision devices features using the conventional MIL functions MdigInquire() and MdigControl(). However, some GigE Vision-compliant device have features that can only be accessed using MdigInquireFeature() and MdigControlFeature() functions. For more information about accessing the features of your GigE Vision-compliant device, refer to the Using MIL with GenICam section of Chapter 25: Grabbing with your digitizer.

GigE Vision information in the MIL Reference can be found in the paragraphs and values marked as being supported by the Matrox GigE Vision driver. Refer to the Matrox GigE Vision driver release notes for any additions/modifications to this chapter.

Working with more than one Gigabit Ethernet network adapter

When your computer has more than one Gigabit Ethernet network adapter installed, you can use each network adapter to access cameras on different networks. Alternatively, multiple network adapters can simply be used to increase the number of cameras to which you have access. Unless otherwise specified, this documentation uses the model of one network adapter connected to a local network on which one or more GigE Vision-compliant cameras exist.

When dealing with more than one Gigabit Ethernet network adapter, the list of your GigE Vision-compliant devices in the Matrox Capture Assistant utility is subdivided by the network adapter to which they are visible. Both the network adapters and their associated GigE Vision-compliant devices are listed in the order of their MAC addresses.

For more detailed information regarding network configurations and GigE Vision-compliant camera setup, refer to the Matrox Capture Assistant white paper (located in your Matrox Imaging\Tools folder).

Working with one or more GigE Vision-compliant cameras

When there is more than one network camera available, the network discovery process (in the Matrox Discovery Service) ranks the GigE Vision-compliant cameras according to their MAC address. For example, the camera having the lowest MAC address is ranked as device zero; the rank increments by one for each camera having a subsequently greater MAC address. MIL uses the camera's rank when you allocate a digitizer with a device number (using MdigAlloc() with M_DEVn); so the rank 0 camera becomes M_DEV0. When you replace a GigE Vision-compliant camera on your network, its rank might not be the same as the camera you are replacing. This means that the rank of all the GigE Vision-compliant cameras could shift to allow the new camera into the sequence the next time you stop and restart your application. When you try to allocate a digitizer for the new camera (to replace the old camera), if the rank is different, the allocation might fail or worse, it might succeed, but the images captured by the camera actually allocated will not be of what you expect.

To avoid this problem, assign the camera a user-defined name or IP address, using Matrox Capture Assistant (on the Device information tab), and then use this name when you allocate a digitizer for this camera.

To allocate a digitizer for a camera with a user-defined name, use MdigAlloc() with M_GC_DEVICE_NAME and specify your camera's name. Then, when a camera needs to be replaced, set the user-defined name of the new camera to match the name of the camera that it replaced. Allocating your GigE Vision-compliant camera using the camera's name allows your application to work with the new camera without modifying either your application or your application's configuration. Alternatively, if your camera uses a persistent (static) IP address, you can use that IP address to identify your camera (using M_GC_DEVICE_IP_ADDRESS).

A new GigE Vision-compliant camera (added to the network as a new camera or a replacement) is not allocated by default and, although it is present, it is not available to your application until you allocate it using MdigAlloc(). If an allocated camera is removed from your network, free it using MdigFree().

To watch for new cameras on your network, use MsysHookFunction() with M_CAMERA_PRESENT. Note that verifying the camera's state (through the hooked function) should be done before your application relies on information from the camera.

Use MsysInquire() with M_DIGITIZER_NUM to determine the number of cameras available. This number is updated when you allocate your system, and again if called by a function hooked to a M_CAMERA_PRESENT event. Note that this number is not affected by the number of digitizers allocated for the cameras.

Working without a Matrox board as your Gigabit Ethernet network adapter

To successfully allocate a MIL GigE Vision system without a Matrox board as your Gigabit Ethernet network adapter, you must already have purchased the Matrox GigE Vision driver license (regardless if you have a license for MIL development, MIL runtime, or MIL-Lite). To determine whether you have a Matrox GigE Vision driver license, use MappInquire() with M_LICENSE_MODULES; it should return M_LICENSE_INTERFACE.