Main Content

Event Types

The Image Acquisition Toolbox™ software supports several different types of events. Each event type has an associated video input object property that you can use to specify the function that executes when the event occurs.

This table lists the supported event types, the name of the video input object property associated with the event, and a brief description of the event. For detailed information about these callback properties, see the property reference list in Image Acquisition Toolbox Properties.

The toolbox generates a specific set of information for each event and stores it in an event structure. To learn more about the contents of these event structures and how to retrieve this information, see Retrieving Event Information.

Note

Callbacks, including ErrorFcn, are executed only when the video object is in a running state. If you need to use the ErrorFcn callback for error handling during previewing, you must start the video object before previewing. To do that without logging data, use a manual trigger.

Events and Callback Function Properties

Event

Callback Property

Description

Error

ErrorFcn

The toolbox generates an error event when a run-time error occurs, such as a hardware error or timeout. Run-time errors do not include configuration errors such as setting an invalid property value.

When an error event occurs, the toolbox executes the function specified by the ErrorFcn property. By default, the toolbox executes the default callback function for this event, imaqcallback, which displays the error message at the MATLAB® command line.

Frames Acquired

FramesAcquiredFcn

The toolbox generates a frames acquired event when a specified number of frames have been acquired. You use the FramesAcquiredFcnCount property to specify this number.

When a frames acquired event occurs, the toolbox executes the function specified by the FramesAcquiredFcn property.

Start

StartFcn

The toolbox generates a start event when an object is started. You use the start function to start an object.

When a start event occurs, the toolbox executes the function specified by the StartFcn property.

Note

The StartFcn callback executes synchronously. If you specify a StartFcn callback function, the toolbox waits for the function to finish executing before performing any other processing. If an error occurs in the start callback function, the object never starts.

Stop

StopFcn

The toolbox generates a stop event when the object stops running. An object stops running when the stop function is called, the specified number of frames is acquired, or a run-time error occurs.

When a stop event occurs, the toolbox executes the function specified by the StopFcn property.

Note

The StopFcn callback executes synchronously. If you specify a StopFcn callback function, the toolbox waits for the function to finish executing before performing any other processing.

Timer

TimerFcn

The toolbox generates a timer event when a specified amount of time expires. Time is measured relative to when the object starts running. You use the TimerPeriod property to specify the amount of time.

Note

Some timer events might not execute if your system is significantly slowed or if the TimerPeriod is set too small.

When a timer event occurs, the toolbox executes the function specified by the TimerFcn property.

Trigger

TriggerFcn

The toolbox generates a trigger event when a trigger executes. The video input object executes immediate triggers. You execute manual triggers by calling the trigger function. The image acquisition device executes hardware triggers when a specified condition is met.

When a trigger event occurs, the toolbox executes the function specified by the TriggerFcn property.