Creating and Executing Callback Functions

Introduction

The power of using event callbacks is the processing that you can perform in response to events. You decide which events you want to associate callbacks with and the functions these callbacks execute.

This section

Describes how to create a callback function
Describes how to specify the function as the value of a callback property
Provides two examples of using event callbacks:
- Shows how to use callbacks to view a sample frame from the frames being acquired

Note

Callback function execution might be delayed if the callback involves a CPU-intensive task such as updating a figure.

Creating Callback Functions

This section explains how to create callback functions for the TimerFcn, FramesAcquiredFcn, StartFcn, StopFcn, TriggerFcn, and ErrorFcn callbacks.

Callback functions require at least two input arguments:

The image acquisition object
The event structure associated with the event

The function header for this callback function illustrates this basic syntax.

function mycallback(obj,event)

The first argument, obj, is the image acquisition object itself. Because the object is available, you can use in your callback function any of the toolbox functions, such as getdata, that require the object as an argument. You can also access all object properties.

The second argument, event, is the event structure associated with the event. This event information pertains only to the event that caused the callback function to execute. For a complete list of supported event types and their associated event structures, see Event Structures.

In addition to these two required input arguments, you can also specify additional, application-specific arguments for your callback function.

Note

To receive the object and event arguments, and any additional arguments, you must use a cell array when specifying the name of the function as the value of a callback property. For more information, see Specifying Callback Functions.

Writing a Callback Function

To illustrate, this example implements a callback function for a frames-acquired event. This callback function enables you to monitor the frames being acquired by viewing a sample frame periodically.

To implement this function, the callback function acquires a single frame of data and displays the acquired frame in a MATLAB^® figure window. The function also accesses the event structure passed as an argument to display the timestamp of the frame being displayed. The drawnow command in the callback function forces MATLAB to update the display.

function display_frame(obj,event)

sample_frame = peekdata(obj,1);

imagesc(sample_frame);

drawnow; % force an update of the figure window

abstime = event.Data.AbsTime;

t = fix(abstime);

sprintf('%s %d:%d:%d','timestamp', t(4),t(5),t(6))

To see how this function can be used as a callback, see Viewing a Sample Frame.

Specifying Callback Functions

You associate a callback function with a specific event by setting the value of the event's callback property. The video input object supports callback properties for all types of events.

You can specify the callback function as the value of the property in any of three ways:

The following sections provide more information about each of these options.

Note

To access the object or event structure passed to the callback function, you must specify the function as a cell array or as a function handle.

Using a Character Vector to Specify Callback Functions

You can specify the callback function as a character vector. For example, this code specifies the callback function mycallback as the value of the start event callback property StartFcn for the video input object vid.

vid.StartFcn = 'mycallback';

In this case, the callback is evaluated in the MATLAB workspace.

Using a Cell Array to Specify Callback Functions

You can specify the callback function as a character vector inside a cell array.

For example, this code specifies the callback function mycallback as the value of the start event callback property StartFcn for the video input object vid.

vid.StartFcn = {'mycallback'};

To specify additional parameters, include them as additional elements in the cell array.

time = datestr(datetime('now'),0);
vid.StartFcn = {'mycallback',time};

The first two arguments passed to the callback function are still the video input object (obj) and the event structure (event). Additional arguments follow these two arguments.

Using Function Handles to Specify Callback Functions

You can specify the callback function as a function handle.

For example, this code specifies the callback function mycallback as the value of the start event callback property StartFcn for the video input object vid.

vid.StartFcn = @mycallback;

To specify additional parameters, include the function handle and the parameters as elements in the cell array.

time = datestr(datetime('now'),0);
vid.StartFcn = {@mycallback,time};

If you are executing a local callback function from within a MATLAB file, you must specify the callback as a function handle.

Specifying a Toolbox Function as a Callback

In addition to specifying callback functions of your own creation, you can also specify the start, stop, or trigger toolbox functions as callbacks. For example, this code sets the value of the stop event callback to Image Acquisition Toolbox™ start function.

vid.StopFcn = @start;

Disabling Callbacks

If an error occurs in the execution of the callback function, the toolbox disables the callback and displays a message similar to the following.

start(vid)
??? Error using ==> frames_cb
Too many input arguments.

Warning: The FramesAcquiredFcn callback is being disabled.

To enable a callback that has been disabled, set the value of the property associated with the callback or restart the object.

Viewing a Sample Frame

This example creates a video input object and sets the frames acquired event callback function property to the display_frame function, created in Writing a Callback Function.

The example sets the TriggerRepeat property of the object to 4 so that 50 frames are acquired. When run, the example displays a sample frame from the acquired data every time five frames have been acquired.

Create an image acquisition object — This example creates a video input object for a Matrox^® image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
```
vid = videoinput('matrox', 1);
```
Configure property values — This example sets the FramesPerTrigger value to 30 and the TriggerRepeat property to 4. The example also specifies as the value of the FramesAcquiredFcn callback the event callback function display_frame, created in Writing a Callback Function. The object will execute the FramesAcquiredFcn every five frames, as specified by the value of the FramesAcquiredFcnCount property.
```
vid.FramesPerTrigger = 30;
vid.TriggerRepeat = 4;
vid.FramesAcquiredFcnCount = 5;
vid.FramesAcquiredFcn = {'display_frame'};
```
Acquire data — Start the video input object. Every time five frames are acquired, the object executes the display_frame callback function. This callback function displays the most recently acquired frame logged to the memory buffer.
```
start(vid)
```
Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
```
delete(vid)
clear vid
```