Specifying Device and Format Information

Every adaptor must include a getAvailHW() function. In this function, you provide the toolbox with information about the device (or devices) that are currently connected to the user's system. An adaptor can represent one particular device, multiple devices supported by a particular vendor, or a class of devices. For example, the toolbox includes an adaptor for Matrox devices that supports many different framegrabbers provided by that vendor.

When a user calls the imaqhwinfo function to find out which devices are available on their system, the toolbox engine calls your adaptor's getAvailHW() function to get this information. When you implement this function, you determine the names, device IDs, and format names that the toolbox displays to users.

This section includes the following topics

Using Objects to Store Device and Format Information

The adaptor kit provides three classes to store device and format information:

Adaptor Kit Object	Purpose
`IHardwareInfo`	Overall container class for hardware information
`IDeviceInfo`	Container for information about a particular device
`IDeviceFormat`	Container for information about the formats supported by a particular device

When the toolbox engine calls your adaptor's getAvailHW() function, it passes your adaptor a handle to an IHardwareInfo object.

For each device you want to make available through your adaptor, you must create an IDeviceInfo object and then store the object in the IHardwareInfo object. For each format supported by a device, you must create an IDeviceFormat object and then store the object in the IDeviceInfo object.

The following figure shows the relationship of these adaptor kit objects. The figure shows the IHardwareInfo object containing two IDeviceInfo objects, but it can contain more. Similarly, each IDeviceInfo object is shown containing two IDeviceFormat objects, but it can also contain more.

Note in the figure that both the IDeviceInfo and IDeviceFormat objects contain adaptor data. Adaptor data is an optional way to store additional information about a device or format in an IDeviceInfo or IDeviceFormat object. See Defining Classes to Hold Device-Specific Information for more information.

Adaptor Kit Objects Used to Store Device and Format Information

Suggested Algorithm

The getAvailHW() function accepts one argument: the handle to an IHardwareInfo object. The toolbox engine creates this IHardwareInfo object and passes the handle to your adaptor when it calls your adaptor's getAvailHW() function. The getAvailHW() function does not return a value.

void getAvailHW(imaqkit::IHardwareInfo* hardwareInfo)

Your adaptor's getAvailHW() function must provide the engine with the following information for each device:

Device ID
Device name
Formats supported by the device, including the default format
Whether or not the device supports device configuration files (also known as camera files)
Note
You can optionally store additional device-specific information in the adaptor data of an IDeviceInfo object or an IDeviceFormat object. See Defining Classes to Hold Device-Specific Information for more information.

The following outlines the steps typically performed by a getAvailHW() function. The figure that follows presents this algorithm in flowchart form.

Determine which devices are available through the adaptor. Adaptors typically make calls to the device's SDK to get this information.
For each device found, create an IDeviceInfo object — see Storing Device Information.
1. For each format supported by the device, create an IDeviceFormat object — see Storing Format Information.
2. Add each device format object that you create to the IDeviceInfo object.
Add the IDeviceInfo object to the IHardwareInfo object passed to your getAvailHW() function by the toolbox engine.
Repeat this procedure for each device available on the user's system.
Suggested Algorithm for getAvailHW() Function

Storing Device Information

You store device information in an IDeviceInfo object. To create this object, use the createDeviceInfo() member function of the IHardwareInfo object, as in the following example:

imaqkit::IDeviceInfo* deviceInfo = 
          hardwareInfo->createDeviceInfo(1,"MyDevice");

As arguments to createDeviceInfo(), you specify:

Name you want to assign to the device
ID you want to assign to the device

You can specify any values for these arguments, but note that they are visible to toolbox users in the structure returned by imaqhwinfo.

For device name, specify a character vector that easily identifies the device. For example, you might use the manufacturer's model number.

The ID you specify for the device must be unique because it identifies the device for the adaptor. Because MATLAB^® indexing starts at 1, start the numbering of device IDs at 1, not zero. The device with ID 1 is the default device for your adaptor.

The IDeviceInfo object you create supports member functions to perform many tasks, such as creating, adding, and retrieving the IDeviceFormat objects associated with the device, and indicating whether the device supports device configuration files (also known as camera files). For more information about this class, see the Image Acquisition Toolbox™ Adaptor Kit API Reference documentation.

Adding the IDeviceInfo Object to the IHardwareInfo Object

After you create the IDeviceInfo object, you must add it to the IHardwareInfo object that the engine passed to your getAvailHW() function. Use the addDevice() member function of the IHardwareInfo object, as in the following example:

hardwareInfo->addDevice(deviceInfo);

Storing Format Information

You store format information in an IDeviceFormat object. To create this object, use the createDeviceFormat() member function of an IDeviceInfo object, as in the following example:

imaqkit::IDeviceFormat* deviceFormat = 
            deviceInfo->createDeviceFormat(1,"RS170");

As arguments to createDeviceFormat(), you specify

Name you want to assign to the format
ID you want to assign to the format

For the format name, specify a character vector that describes the format. Note that the format name is visible to toolbox users. Use names that might be familiar to users of the device, such as a name similar to the format names used by the device manufacturer.

Because the ID is not exposed to users, you can specify any convenient value. For example, if the device's SDK uses numerical identifiers to indicate a format, use these values for your format IDs.

You can use IDeviceFormat member functions to perform many tasks, such as, retrieving the format name and format ID, and determining whether the format is the default format. For more information about this class, see the Image Acquisition Toolbox Adaptor Kit API Reference documentation.

Adding an IDeviceFormat Object to an IDeviceInfo Object

After you create the IDeviceFormat object, add it to the IDeviceInfo object that represents the device. Use the addDeviceFormat() member function of the IDeviceInfo object, as in the following example:

deviceInfo->addDeviceFormat(deviceFormat,true);

Specifying the Default Format

When you add a format to an IDeviceInfo object, you use the second argument to the addDeviceFormat() function to specify whether the format should be used as the default format for the device. The imaqhwinfo function returns the name of the default format in the DefaultFormat field. To make a format the default, set this argument to true.

Configuring Device Configuration File (Camera File) Support

Some devices use device configuration files (also known as camera files) to configure formats and other properties. If a device supports device configuration files, you do not need to create IDeviceFormat objects. Instead, use the setDeviceFileSupport() member function of the IDeviceInfo object to indicate that the device supports device configuration files, as in the following example:

 deviceInfo->setDeviceFileSupport(true);

For these devices, users pass the full path of the device configuration file as the third argument to the videoinput function, instead of specifying a device format. Adaptor writers do not need to perform any processing of the device configuration file; you just pass the file name to the device.

Example: Providing Device and Format Information

The following example presents a simple implementation of a getAvailHW() function that specifies information for one device with two formats. The intent of this example is to show how you create the objects necessary to store device and format information. If you add this code to the mydeviceimaq adaptor, you can run imaqhwinfo('mydeviceimaq') to view the device information.

Replace the stub implementation of the getAvailHW() function, created in Creating a Stub Adaptor, with this code:

void getAvailHW(imaqkit::IHardwareInfo* hardwareInfo)
{ 
	// Create a Device Info object. 
	imaqkit::IDeviceInfo* deviceInfo = 
                  hardwareInfo->createDeviceInfo(1,"MyDevice");

   // Create a Device Format object.
	imaqkit::IDeviceFormat* deviceFormat = 
                  deviceInfo->createDeviceFormat(1,"RS170");

   // Add the format object to the Device object.
   // Specifying "true' makes this format the default format.
	deviceInfo->addDeviceFormat(deviceFormat, true);

   // Create a second Device Format object. 
	imaqkit::IDeviceFormat* deviceFormat2 = 
                   deviceInfo->createDeviceFormat(2,"PAL");

   // Add the second format object to the Device object.
  	deviceInfo->addDeviceFormat(deviceFormat2, false);

    // Add the device object to the hardware info object.
	hardwareInfo->addDevice(deviceInfo);

}

Rebuild the mydeviceimaq project to create a new DLL.

Start the MATLAB software and run the imaqhwinfo function, specifying the adaptor name mydeviceimaq as an argument. Note how the DeviceIDs field and the DeviceInfo field of the structure returned by imaqhwinfo now contain data.

dev = imaqhwinfo('mydeviceimaq')

dev = 

       AdaptorDllName: 'C:\My_Adaptor\mydeviceimaq.dll'
    AdaptorDllVersion: '4.1 (R2011a)'
          AdaptorName: 'mydeviceimaq'
            DeviceIDs: {[1]}
           DeviceInfo: [1x1 struct]

To view detailed information about the device, view the structure in the DeviceInfo field. The DeviceInfo field is an array of structures, where each structure provides detailed information about a particular device.

dev_info = dev.DeviceInfo

dev_info = 

          DefaultFormat: 'RS170'
    DeviceFileSupported: 0
             DeviceName: 'MyDevice'
               DeviceID: 1
      ObjectConstructor: 'videoinput('mydeviceimaq', 1)'
       SupportedFormats: {'PAL'  'RS170'}

The following table describes the information in each field, with references to other sections that provide more information.

Field	Description
`DefaultFormat`	Character vector that specifies the default format used by the device. You define the default format when you add the `IDeviceFormat` object to the `IDeviceInfo` object; see Specifying the Default Format.
`DeviceFileSupported`	Boolean value that tells whether the device supports device configuration files (also known as camera files). You use the `setDeviceFileSupport`() member function of the `IDeviceInfo` object to set this value; see Configuring Device Configuration File (Camera File) Support.
`DeviceName`	Character vector that identifies a particular device. You define this value when you create the `IDeviceInfo` object; see Storing Device Information.
`DeviceID`	Numeric value that uniquely identifies a particular device. You define this value when you create the `IDeviceInfo` object; see Storing Device Information.
`ObjectConstructor`	Character vector that contains the `videoinput` function syntax required to create an object instance for this device. The toolbox engine creates this character vector.
`SupportedFormats`	Cell array of character vectors that identifies the formats this device supports. You define this value when you create the `IDeviceFormat` objects associated with a particular device; see Storing Format Information.