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:
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.
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
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)
Handle to a IDeviceInfo object
Specifies the image acquisition device
Specifies the video format or the path to a device configuration file
Handle to a IPropFactory object
Provides member functions used to create properties
Handle to a IVideoSourceInfo object
Defines the video sources available with this device, described in Identifying Video Sources
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:
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.
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.
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.