Waiting for an Acquisition to Finish

Using the wait Function

The start function and the trigger function are asynchronous functions. That is, they start the acquisition of frames and return control to the MATLAB^® command line immediately.

In some scenarios, you might want your application to wait until the acquisition completes before proceeding with other processing. To do this, call the wait function immediately after the start or trigger function returns. The wait function blocks the MATLAB command line until an acquisition completes or a timeout value expires, whichever comes first.

By default, wait blocks the command line until a video input object stops running. You can optionally specify that wait block the command line until the object stops logging. For acquisitions using an immediate trigger, video input objects always stop running and stop logging at the same time. However, with a manual trigger configured for multiple executions (TriggerRepeat > 0), you can use wait immediately after each call to the trigger function to block the command line while logging is in progress, even though the object remains in running state throughout the entire acquisition.

The following figure illustrates the flow of control at the MATLAB command line for a single execution of an immediate trigger and a manual trigger, with and without the wait function. A hardware trigger is similar to the manual trigger diagram, except that the acquisition is triggered by an external signal to the camera or frame grabber board, not by the trigger function. For an example, see Blocking the Command Line Until an Acquisition Completes.

Using wait to Block the MATLAB Command Line

Blocking the Command Line Until an Acquisition Completes

The following example illustrates how to use the wait function to put a 60 second time limit on the execution of a hardware trigger. If the hardware trigger does not execute within the time limit, wait returns control to the MATLAB command line.

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 a hardware trigger — Use the triggerinfo function to determine valid configurations of the TriggerSource and TriggerCondition properties. See Determining Valid Configurations for more information. In this example, triggerinfo returns the following valid trigger configurations.
```
triggerinfo(vid)
Valid Trigger Configurations:

      TriggerType:   TriggerCondition:   TriggerSource:
      'immediate'    'none'              'none'        
      'manual'       'none'              'none' 
	    'hardware'     'risingEdge'        'TTL' 
	    'hardware'     'fallingEdge'       'TTL' 
```
Configure the video input object trigger properties to one of the valid combinations returned by triggerinfo. You can specify each property value as an argument to the triggerconfig function
```
triggerconfig(vid, 'hardware','risingEdge','TTL')
```
Alternatively, you can set these values by passing one of the structures returned by the triggerinfo function to the triggerconfig function.
```
configs = triggerinfo(vid);
triggerconfig(vid,configs(3));
```
Configure other object properties — This example also sets the value of the FramesPerTrigger property to configure an acquisition large enough to produce a noticeable duration. (The default is 10 frames per trigger.)
```
vid.FramesPerTrigger = 100
```
Start the image acquisition object — Call the start function to start the image acquisition object.
```
start(vid)
```
The start function sets the object running and returns control to the command line.
Block the command line until the acquisition finishes — After the start function returns, call the wait function.
```
wait(vid,60)
```
The wait function blocks the command line until the hardware trigger fires and acquisition completes or until the amount of time specified by the timeout value expires.
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
```