Skip to content

EventReference

Jump to bottom Edit New page
Arthur Nishimoto edited this page Jul 22, 2014 · 5 revisions

The omicron Event structure

Last revision: ver. 2.0 - 16 August 2013

This document explains the structure of events generated by omicron event services. The design rationale behind the event structure was to make it:

  • Generic enough to support a reasonable amount of physical and logical input devices.
  • Intuitive to use and interpret
  • Easy to pack and stream remotely

Inside omicron, event data is stored in the omicronConnector::EventData structure and in the omicron::Event class. Both types contain the same data and are organized similarly, but omicron::Event offers a few additional methods to interact with the data. if you are developing an omicronConnector application though, only the omicronConnector::EventData stucture is available to you.

In this guide we explain the meaning of fields inside the event types: this information should be helpful regardless of your choice of using Event or EventData.

Event Data Fields

The following fields make up an event:

  • timestamp (unsigned int): this is the event timestamp in milliseconds using the standard unix time see ftime
  • serviceType (enum): this is a value from the omicron::EventBase::ServiceType enumeration. It is used to classify event services into a few general categories. The categories will be explained later on this page
  • serviceId (int): a unique identifier of the service generating the event.
  • sourceId: the identifier of the source generating the event within the service. Some services generate events from a single source (i.e. a mouse service generating events for a single mouse). Other services support streams from multiple sources (like a tracking system tracking multiple rigid bodies, or a gamepad service generating events for two connected controllers). The specific semantics of the event sourceId depend on the service.
  • type: this is a value from the omicron::EventBase::Type enumeration, and it gives general information about the category of the event. For instance, a mouse may be generating Up and Down events for button changes, and Move events for changes in position. A tracking system will probably generate Update events and Trace, Untrace when a rigid body tracking is aquired and lost. Ui controls may generate ChangeValue events. As for sourceId, the specific meaning of a type depends on the service. It is up to the service developer to give the generated events a meaningful and intuitive type. The service type is usually an indication of the types of events the service will generate.
  • flags: this is a bitfield with bits set using the omicron::EventBase::Flags enumeration. Flags can be used to transmit the state of digital buttons on controllers, or to communicate specific states of the event (i.e. the Processed flag indicated that the event has been handled already by some other portion of a program).
  • posx, posy, posz (float): the 3d position of the event (for events that need it)
  • orx, ory, orz, orw (float): the 3d orientation of the event as a quaternion (for events that need it)
  • extraData: a byte array of fixed size, containing additional data associated with the event. Refer to the service generating the event for information about contents of this event section. ExtraData is at most 1kb as of version 1.2 of omicron.
  • extraDataType: this is a value from the omicron::EventBase::ExtraDataType enumeration. It indicates the format of the extra data section. The extra data can be formatted as:
  • A text string as a null-terminated char* array
  • An array of floating point numbers
  • An array of integer numbers
  • An array of float triplets representing 3d vectors
  • extraDataItems: the number of 'items' stored in the extra data array. NOTE this is not the size in bytes of the data in the extra data array. For instance, if the extra data is storing two floating point values, extraDataItems = 2, the actual data size is 2 * sizeof(float) = 8 bytes.
  • extraDataMask (unsigned int): a generic 32bit field used to specify flags about extra data items. For instance, it can be used to mark valid/invalid entries in the extra data array, but it's specific meaning is up to the service developers.

Example: PS3 Move Controller Button Mapping

Service Types

This section illustrates the general characteristics of event services, depending on their type. The service type is usually attached to the serviceType field of events generated by a service.

Pointer Services

Pointer services generate events coming from mice, multitouch surfaces and comparable devices. Events generated by pointer services usually store a 2d position, possibly some button state flags

Mocap Services

Motion capture services generate 3d tracking data for marked-tracked and markerless systems. Events generated by motion capture services always store a 3d position and may have a 3d orientation. Events are usually of the Update type. Mocap services may also notify user applications of lost/aquired tracking using Trace/Untrace events. Services that need to track multiple points with a single event (like the kinect skeleton tracker) may store additional points in the extra data section of the event.

Keyboard Services

Keyboard services generate keypress events from physical or logical keyboards. Events have no position and orientation fields. The key scan code is returned as the event source id. The event type is usually Up or Down to indicate key presses and releases. The event flags can store key modifiers (Shift, Contrl, Alt).

Controller Services

Controller services generate data from gamepads and similar devices. Events use the source id to identify the controller number. Digital buttons are reported in the event flags section. Analog controls are usually reported as a float array in the extra data section. Same goes for accelerometers and gyroscopes. The event types are Up, Down (for digital button changes) and Update for regular updates on the state of analog inputs.

  • Examples: XInputService, WiimoteService, DirextXInputService
  • NOTE: XInputService is currently the primary controller service used for OmegaLib applications in CAVE2. Although LegacyDirectXInputService generates controller events, it does not follow the convention described above.

UI Services

UI Services generate events linked to graphical user interfaces. The structure of events is defined more loosely than for the previous services. Button clicks usually generate Down events. Sliders and text boxes should generate ValueChange events, with the new value stored in the extra data section of the event. The source id should correspond to the unique identifier of the gui widget.

Generic Services

Catch-all service category.

Brain Services

Brain service generates events from electroencephalography (EEG) devices. The events have an array of float values corresponding to the state of the device and brain wave values such as delta and alpha waves.

Wand Services

Wand services generate events that are a hybrid between Pointer, Mocap and Controller events. The Events have a 3d position and orientation, but also have digital/analog button states saved in the flags and extra data sections of the event.

Add a custom footer
Add a custom sidebar
Clone this wiki locally