Retrieving Event Information

Introduction

Each event has associated with it a set of information, generated by the toolbox and stored in an event structure. This information includes the event type, the time the event occurred, and other event-specific information. While a video input object is running, the toolbox records event information in the object's EventLog property. You can also access the event structure associated with an event in a callback function.

This section

Defines the information in an event structure for all event types
Describes how to retrieve information from the EventLog property

For information about accessing event information in a callback function, see Creating and Executing Callback Functions.

Event Structures

An event structure contains two fields: Type and Data. For example, this is an event structure for a trigger event:

Type: 'Trigger'
Data: [1x1 struct]

The Type field is a character vector that specifies the event type. For a trigger event, this field contains the character vector 'Trigger'.

The Data field is a structure that contains information about the event. The composition of this structure varies depending on which type of event occurred. For details about the information associated with specific events, see the following sections:

Data Fields for Start, Stop, Frames Acquired, and Trigger Events
Data Fields for Error Events
Data Fields for Timer Events

Data Fields for Start, Stop, Frames Acquired, and Trigger Events

For start, stop, frames acquired, and trigger events, the Data structure contains these fields.

Field Name	Description
`AbsTime`	Absolute time the event occurred, returned in MATLAB^® clock format `[year month day hour minute seconds]`
`FrameNumber`	Frame number relative to when the object was started
`RelativeFrame`	Frame number relative to the execution of a trigger
`TriggerIndex`	Trigger the event is associated with. For example, upon start, the associated trigger is 0. Upon stop, it is equivalent to the `TriggersExecuted` property.

Data Fields for Error Events

For error events, the Data structure contains these fields.

Field Name	Description
`AbsTime`	Absolute time the event occurred, returned in MATLAB clock format `[year month day hour minute seconds]`
`Message`	Text message associated with the error
`MessageID`	MATLAB message identifier associated with the error

Field Name

Description

AbsTime

Absolute time the event occurred, returned in MATLAB clock format

[year month day hour minute seconds]

Message

Text message associated with the error

MessageID

MATLAB message identifier associated with the error

Data Fields for Timer Events

For timer events, the Data structure contains these fields.

Field Name	Description
`AbsTime`	Absolute time the event occurred, returned in MATLAB clock format `[year month day hour minute seconds]`

Field Name

Description

AbsTime

Absolute time the event occurred, returned in MATLAB clock format

[year month day hour minute seconds]

Accessing Data in the Event Log

While a video input object is running, the toolbox stores event information in the object's EventLog property. The value of this property is an array of event structures. Each structure represents one event. For detailed information about the composition of an event structure for each type of event, see Event Structures.

The toolbox adds event structures to the EventLog array in the order in which the events occur. The first event structure reflects the first event recorded, the second event structure reflects the second event recorded, and so on.

Note

Only start, stop, error, and trigger events are recorded in the EventLog property. Frames-acquired events and timer events are not included in the EventLog. Event structures for these events (and all the other events) are available to callback functions. For more information, see Creating and Executing Callback Functions.

To illustrate the event log, this example creates a video input object, runs it, and then examines the object's EventLog property:

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);
```
Start the image acquisition object — Start the image acquisition object. By default, the object executes an immediate trigger, acquires 10 frames of data, and then stops.
```
start(vid)
```
View the event log — Access the EventLog property of the video input object. The execution of the video input object generated three events: start, trigger, and stop. Thus the value of the EventLog property is a 1x3 array of event structures.
```
events = vid.EventLog
events = 

1x3 struct array with fields:
    Type
    Data
```
To list the events that are recorded in the EventLog property, examine the contents of the Type field.
```
{events.Type}
ans = 
    'Start'    'Trigger'    'Stop'
```
To get information about a particular event, access the Data field in that event structure. The example retrieves information about the trigger event.
```
trigdata = events(2).Data

trigdata = 

             AbsTime: [2004 12 29 16 40 52.5990] 
         FrameNumber: 0
       RelativeFrame: 0
        TriggerIndex: 1
```
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
```