Main Content

Defining Device-Specific Properties

You define which properties of your image acquisition device you want to expose to toolbox users. You make this determination by reading the device SDK documentation, determining its capabilities, and deciding which capabilities toolbox users will expect to configure. Once you decide to expose a property, define the following characteristics of the property:

  • Name

  • Data type

  • Range of valid values (optional)

Adaptor writers typically wait to define properties until after they are able to acquire data from the device. To see the effect of some properties, you need to be able to acquire data.

User Scenario

The properties that you define for your device appear to users as properties of the video source object associated with the video input object. The toolbox defines the properties of the video input object, which represent general properties that are common to all image acquisition devices.

To view the device-specific properties you define, get a handle to the video source object and use the get function. To set the value of device-specific properties you define, get a handle to the video source object and use the set function. For example, this code creates a video input object and uses the getselectedsource function to get a handle to the currently selected video source object. With this handle, you can then use the get command to view the properties of the video source object. 

vid = videoinput('winvideo',1)
src = getselectedsource(vid);
get(src)
General Settings:
    Parent = [1x1 videoinput]
    Selected = on
    SourceName = input1
    Tag = 
    Type = videosource

  Device Specific Properties:
    Brightness = -10
    Contrast = 266
    Exposure = 1024
    ExposureMode = auto
    Hue = 0
    Saturation = 340
    Sharpness = 40

Suggested Algorithm

When a user calls the videoinput function, the engine calls the getDeviceAttributes() function to set up any device-specific properties you have defined for the device. The engine passes several arguments to your adaptor's getDeviceAttributes() function: 

void getDeviceAttributes(const imaqkit::IDeviceInfo* deviceInfo,  
                                         const char* acqFormat, 
                              imaqkit::IPropFactory* devicePropFact, 
                          imaqkit::IVideoSourceInfo* sourceContainer, 
                              imaqkit::ITriggerInfo* hwTriggerInfo)

Argument

Data Type

Description

deviceInfo

Handle to a IDeviceInfo object

Specifies the image acquisition device

acqformat

Character vector

Specifies the video format or the path to a device configuration file

devicePropFact

Handle to a IPropFactory object

Provides member functions used to create properties

sourceContainer

Handle to a IVideoSourceInfo object

Defines the video sources available with this device, described in Identifying Video Sources

hwTriggerInfo

Handle to a ITriggerInfo object

Specifies hardware triggers. The toolbox handles the other two trigger types (immediate and manual) automatically.

The algorithm for getDeviceAttributes() typically includes these steps:

  1. Determine the device the user wants to establish a connection with, specified by device ID.

  2. Determine the format the user wants to use with the device, specified by format name (or the path of a camera file). To get format information, retrieve the IDeviceFormat object associated with the format from the IDeviceInfo object.

  3. Create any device-specific properties. You create a property object appropriate to the data type of the property and store the property object in the device-specific property container — see Creating Device Properties.

  4. Find all trigger configurations supported by the device and store the information in the ITriggerInfo object — see Supporting Hardware Triggers.

There are several ways your adaptor can determine this property, source, and trigger information:

  • By querying the device SDK at run-time

  • By reading information from an imaging device file (IMDF). If you know the device information in advance, you can store it in an IMDF file using an XML-based markup language. This section describes how to read information from an IMDF file. To learn how to create an IMDF file, see Using the IMDF Markup Language.

  • A mixture of both methods.