Retrieving Event Information

On this page…
Introduction Event Structures Example: Accessing Data in the Event Log

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.

Back to Top

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 text string that specifies the event type. For a trigger event, this field contains the text string '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 information 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 inMATLAB clock format [year month day hour minute seconds]
FrameMemoryLimit	Amount of memory allotted for frame storage. You can specify this value using the imaqmem function.
FrameMemoryUsed	Amount of frame memory that is currently in use
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]
FrameMemoryLimit	Amount of memory allotted for frame storage. You can specify this value using the imaqmem function.
FrameMemoryUsed	Amount of frame memory that is currently in use
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]
FrameMemoryLimit	Amount of memory allotted for frame storage. You can specify this value using the imaqmem function.
FrameMemoryUsed	Amount of frame memory that is currently in use

Back to Top

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

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

3. 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] 
       FrameMemoryLimit: 139427840
        FrameMemoryUsed: 0
            FrameNumber: 0
          RelativeFrame: 0
           TriggerIndex: 1

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

Event Types

Creating and Executing Callback Functions

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