Looking at the Demo Adaptor

A good way to get a quick introduction to adaptors and adaptor development is by looking at the demo adaptor that is included with the Image Acquisition Toolbox™ Adaptor Kit. The demo adaptor is a functioning adaptor that does not require any hardware. You can build the demo adaptor and run it to get familiar with how an adaptor works.

• Finding the Demo Adaptor Source Files

• Viewing the Demo Adaptor Source Files

• Setting Breakpoints

• Building the Demo Adaptor

• Registering an Adaptor with the Toolbox

• Running the Demo Adaptor

Finding the Demo Adaptor Source Files

The demo adaptor C++ source files reside in the following folder:

$MATLAB\toolbox\imaq\imaqadaptors\kit\demo\

The following table lists all the files in the demo folder in alphabetical order, with brief descriptions.

Source File	Description
DemoAdaptor.cpp	Demo adaptor class implementation
DemoAdaptor.h	Demo adaptor class definition
DemoDeviceFormat.cpp	Implementation of class that holds device format information
DemoDeviceFormat.h	Definition of class that holds device format information
DemoPropListener.cpp	Implementation of class that notifies demo adaptor when the value of a device property changes
DemoPropListener.h	Definition of class that notifies demo adaptor when the value of a device property changes
DemoSourceListener.cpp	Implementation of class that listens for changes in the selected video source
DemoSourceListener.h	Definition of class used to listen for changes in the selected video source
DemoTimestampGetFcn.cpp	Implementation of class that provides a custom get function for the timestamp properties.
DemoTimestampGetFcn.h	Definition of class that provides a custom get function for the timestamp properties.
mwdemoimaq.cpp	Implementation of the five functions that every adaptor must export.
mwdemoimaq.dll	Demo adaptor library. This is the compiled and linked Dynamic Link Library (DLL) that implements the demo adaptor.
mwdemoimaq.h	Header file that defines the five functions that every adaptor must export
mwdemoimaq.imdf	Demo adaptor image device file (IMDF) that contains property definitions
mwdemoimaq.vcxproj	Microsoft® Visual C++® project file for the demo adaptor

Viewing the Demo Adaptor Source Files

This section describes a suggested order in which you should look at the demo adaptor source files.

mwdemoimaq.h

A good place to start looking at the demo adaptor is to open the mwdemoimaq.h file. This file defines the five functions that every adaptor must export. The toolbox engine calls these functions to get information about supported hardware, instantiate a video input object, and acquire data. Implementing these functions is typically the first step an adaptor writer takes. This header file contains comments that explain the purpose of each function.

mwdemoimaq.cpp

After seeing the definition of the adaptor exported functions, see how they are implemented in the corresponding C++ implementation file, mwdemoimaq.cpp.

DemoAdaptor.h

After viewing the exported functions, take a look at the definition of the DemoAdaptor class in DemoAdaptor.h. The adaptor class is a subclass of the IAdaptor class, which defines the virtual functions an adaptor must implement. This header file contains comments that explain the purpose of each member function.

DemoAdaptor.cpp

After seeing the definition of the adaptor class, look at the implementation of the class in the DemoAdaptor.cpp file. This file contains the acquisition thread function which is the main frame acquisition loop. This is where the adaptor connects to the device and acquires image frames.

Other Demo Adaptor Files

The demo directory contains other files that implement optional adaptor kit capabilities.

For example, the DemoDeviceFormat.h and corresponding .cpp files illustrate one way to store device-specific format information using adaptor data. You define a class that is a subclass of the IMAQInterface class to hold the information. See Defining Classes to Hold Device-Specific Information for more information.

The DemoPropListener.h and corresponding .cpp files and the DemoSourceListener.h and .cpp files illustrate how your adaptor can get notified if a user changes the setting of a property. See Implementing Get and Set Support for Device-Specific Properties for more information.

Setting Breakpoints

You can use debugger breakpoints to examine which adaptor functions are called when users call toolbox functions, such as imaqhwinfo, videoinput, start, and stop. The following table lists places in the demo adaptor where you can set a breakpoints.

MATLAB® Command	Breakpoint
imaqhwinfo	initializeAdaptor()
imaqreset	uninitializeAdaptor()
imaqhwinfo(adaptorname)	getAvailHW()
videoinput	getDeviceAttributes() createInstance()
imaqhwinfo(obj)	getDriverDescription() getDriverVersion() getMaxWidth() getMaxHeight() getFrameType()
videoinput	getNumberOfBands()
start	openDevice()
start or trigger, if manual trigger	startCapture()
stop	stopCapture() closeDevice()

Building the Demo Adaptor

After familiarizing yourself with the demo adaptor source files, build the demo adaptor. There is a pre-built version of the demo adaptor in matlabroot/toolbox/imaq/imaqadaptors/kit/demo/$ARCH. The Visual Studio project file and the makefile build the adaptor file in a subfolder of this folder.

Note

To build the demo adaptor on Windows, you must have an environment variable named MATLAB defined on your system. Set the value of this environment variable to the location of your MATLAB installation directory.

Registering an Adaptor with the Toolbox

After creating an adaptor, you must inform the Image Acquisition Toolbox software of its existence by registering it with the imaqregister function. This function tells the toolbox where to find third-party adaptor libraries. You only need to register your adaptor once. The toolbox stores adaptor location information in your MATLAB preferences.

Note

Because the toolbox caches adaptor information, you might need to reset the toolbox, using imaqreset, before a newly registered adaptor appears in the imaqhwinfo listing.

For example, the following code registers the demo adaptor with the toolbox using the imaqregister function, where <your_directory> represents the name of the directory where you created the demo adaptor.

imaqregister('<your_directory>\mwdemoimaq.dll');

Running the Demo Adaptor

Start MATLAB and call the imaqhwinfo function. You should be able to see the demo adaptor included in the adaptors listed in the InstalledAdaptors field. For example, on a Windows system, imaqhwinfo returns the following.

ans = 

    InstalledAdaptors: {'demo'  'matrox'  'winvideo'}
        MATLABVersion: '7.12 (R2011a)'
          ToolboxName: 'Image Acquisition Toolbox'
       ToolboxVersion: '4.1 (R2011a)'

Create a video input object with the demo adaptor.

vid = videoinput('demo');

Get a preview of the data being returned by the demo adaptor using the preview function. Note that the demo adaptor generates a grayscale pattern to mimic the data returned by a real image acquisition device. The demo adaptor does not connect to an actual device.

preview(vid);

Preview Windows Containing Demo Adaptor Data