Creating and Executing Callback Functions

On this page…
Introduction Creating Callback Functions Specifying Callback Functions Example: Viewing a Sample Frame Example: Monitoring Memory Usage

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

  • Uses callback to implement a simple memory monitoring function

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

Back to Top

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.

Example: 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 Example: Viewing a Sample Frame.

Back to Top

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:

• Text string

• Cell array

• Function handle

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 Text String to Specify Callback Functions

You can specify the callback function as a string. 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 text string 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(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(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.

Back to Top

Example: 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 Example: 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.

1. 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);

2. 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 Example: Writing a Callback Function. The object will execute the FramesAcquiredFcn every five frames, as specified by the value of the FramesAcquiredFcnCount property.

   set(vid,'FramesPerTrigger', 30);
   set(vid,'TriggerRepeat', 4);
   set(vid,'FramesAcquiredFcnCount', 5);
   set(vid,'FramesAcquiredFcn', {'display_frame'});

3. 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)

4. 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

Back to Top

Example: Monitoring Memory Usage

This example creates a callback function for a timer event that displays the toolbox's current memory usage and stops the acquisition when the available memory for frame storage falls below a specified amount.

Creating the Memory Monitor Callback Function

This callback function implements a simple memory usage monitoring function. The callback function uses the imaqmem function to retrieve two memory usage statistics, FrameMemoryLimit and FrameMemoryUsed, and then calculates the amount of memory that is currently left for allocating frames. When the amount of memory available falls below a specified value, the function outputs a message and stops the object.

function mem_mon(obj,event)

out = imaqmem;

mem_left = out.FrameMemoryLimit - out.FrameMemoryUsed;

msg = 'Memory left for frames';
msg2 = 'Memory load';
low_limit = 2000000;

if(mem_left > low_limit)
    sprintf('%s: %d \n%s: %d',msg, mem_left,msg2, out.MemoryLoad)
else
    disp('Memory available for frames getting low.');
    disp('Stopping acquisition.')
    stop(obj);
end

Running the Example

The example acquires frames until the amount of memory left for frame storage reaches a lower limit specified in the callback function.

1. 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);

2. Configure property values — This example sets up a continuous acquisition by setting the FramesPerTrigger value to Inf. The example also specifies the timer event callback function mem_mon, created in Creating the Memory Monitor Callback Function, as the value of the TimerFcn callback. The object will execute the TimerFcn every five seconds, as specified by the value of the TimerPeriod property.

   set(vid,'FramesPerTrigger',Inf);
   set(vid,'TimerPeriod',5);
   set(vid,'TimerFcn',{'mem_mon'});

3. Acquire data — Start the video input object. Every 5 seconds, the object executes the callback function associated with the timer event. This function outputs the current memory available for frame storage and the memory load statistic. When the amount of memory reaches the specified lower limit, the callback function stops the acquisition.

   start(vid)
   ans =
   
   ans =
   
   Memory left for frames: 27791360 
   Memory load: 88
   
   ans =
   
   Memory left for frames: 26316800 
   Memory load: 88
   
   ans =
   
   Memory left for frames: 24842240 
   Memory load: 89
   
   .
   .
   .
   
   Memory left for frames: 2969600 
   Memory load: 97
   
   Memory available for frames getting low.
   Stopping acquisition.

4. 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

Back to Top

Retrieving Event Information

Using the From Video Device Block in Simulink

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS