Class Leap::Controller

class Leap.Controller : public Leap.IController

The Controller class is your main interface to the Leap Motion Controller.

Create an instance of this Controller class to access frames of tracking data and configuration information.Frame data can be polled at any time using the Controller.Frame() function.Call frame() or frame(0) to get the most recent frame.Set the history parameter to a positive integer to access previous frames.A controller stores up to 60 frames in its frame history.

Polling is an appropriate strategy for applications which already have an intrinsic update loop, such as a game. You can also subscribe to the FrameReady event to get tracking frames through an event delegate.

If the current thread implements a SynchronizationContext that contains a message loop, events are posted to that threads message loop. Otherwise, events are called on an independent thread and applications must perform any needed synchronization or marshalling of data between threads. Note that Unity3D does not create an appropriate SynchronizationContext object. Typically, event handlers cannot access any Unity objects.

Since

1.0

Public Types

enum PolicyFlag

The supported controller policies.

The supported policy flags are:

POLICY_BACKGROUND_FRAMES requests that your application receives frames when it is not the foreground application for user input.

The background frames policy determines whether an application receives frames of tracking data while in the background. By default, the Leap Motion software only sends tracking data to the foreground application. Only applications that need this ability should request the background frames policy. The “Allow Background Apps” checkbox must be enabled in the Leap Motion Control Panel or this policy will be denied.

POLICY_OPTIMIZE_HMD request that the tracking be optimized for head-mounted tracking.

The optimize HMD policy improves tracking in situations where the Leap Motion hardware is attached to a head-mounted display. This policy is not granted for devices that cannot be mounted to an HMD, such as Leap Motion controllers embedded in a laptop or keyboard.

Some policies can be denied if the user has disabled the feature on their Leap Motion control panel.

Since

1.0

Values:

POLICY_DEFAULT

The default policy.

POLICY_BACKGROUND_FRAMES

Receive background frames.

POLICY_IMAGES

Allow streaming images.

POLICY_OPTIMIZE_HMD

Optimize the tracking for head-mounted device.

POLICY_ALLOW_PAUSE_RESUME

Allow pausing and unpausing of the Leap Motion service.

POLICY_MAP_POINTS

Allow streaming map point

POLICY_OPTIMIZE_SCREENTOP

Optimize the tracking for screen-top device.

Since

5.0.0

Public Functions

Controller ()

Constructs a Controller object.

The default constructor uses a connection key of 0.

Since

1.0

Controller (int connectionKey, string serverNamespace = “Leap Service”, bool supportsMultipleDevices = true)

Constructs a Controller object using the specified connection key.

All controller instances using the same key will use the same connection to the service. In general, an application should not use more than one connection for all its controllers. Each connection keeps its own cache of frames and images.

Since

3.0

Param connectionKey

An identifier specifying the connection to use. If a connection with the specified key already exists, that connection is used. Otherwise, a new connection is created.

void StartConnection ()

Starts the connection.

A connection starts automatically when created, but you can use this function to restart the connection after stopping it.

Since

3.0

void StopConnection ()

Stops the connection.

No more frames or other events are received from a stopped connection. You can restart with StartConnection().

Since

3.0

bool CheckRequiredServiceVersion (LEAP_VERSION minServiceVersion)

Checks whether a minimum or required tracking service version is installed. Gets the currently installed service version from the connection and checks whether the argument minServiceVersion is smaller or equal to it

Param minServiceVersion

The minimum service version to check against

Return

True if the version of the running service is equal to or less than the minimum version specified

void SetAndClearPolicy (PolicyFlag set, PolicyFlag clear, Device device = null)

Requests setting and clearing policy flags on a specific device

A request to change a policy is subject to user approval and a policy can be changed by the user at any time (using the Leap Motion settings dialog). The desired policy flags must be set every time an application runs.

Policy changes are completed asynchronously and, because they are subject to user approval or system compatibility checks, may not complete successfully. Call Controller.IsPolicySet() after a suitable interval to test whether the change was accepted.

Since

2.1.6 (5.4.4 for specific device)

void SetPolicy (PolicyFlag policy, Device device = null)

Requests setting a policy on a specific device

A request to change a policy is subject to user approval and a policy can be changed by the user at any time (using the Leap Motion settings dialog). The desired policy flags must be set every time an application runs.

Policy changes are completed asynchronously and, because they are subject to user approval or system compatibility checks, may not complete successfully. Call Controller.IsPolicySet() after a suitable interval to test whether the change was accepted.

Since

2.1.6 (5.4.4 for specific device)

void ClearPolicy (PolicyFlag policy, Device device = null)

Requests clearing a policy on a specific device

Policy changes are completed asynchronously and, because they are subject to user approval or system compatibility checks, may not complete successfully. Call Controller.IsPolicySet() after a suitable interval to test whether the change was accepted.

Since

2.1.6 (5.4.4 for specific device)

bool IsPolicySet (PolicyFlag policy, Device device = null)

Gets the active setting for a specific device.

Keep in mind that setting a policy flag is asynchronous, so changes are not effective immediately after calling setPolicyFlag(). In addition, a policy request can be declined by the user. You should always set the policy flags required by your application at startup and check that the policy change request was successful after an appropriate interval.

If the controller object is not connected to the Leap Motion software, then the default state for the selected policy is returned.

Since

2.1.6 (5.4.4 for specific device)

bool IsDeviceAvailable (Device device = null)

Checks if the specified device is available.

Device availability is determined by checking it has active policy flags set against it via its connection.

void RequestHandTrackingHints (string[] hints, Device device = null)

Send a specific set of hints, if this does not include previously set ones, they will be cleared.

Param hints

The hints you wish to send

Param device

An optional specific Device, otherwise the first found will be used

Frame Frame (int history = 0)

In most cases you should get Frame objects using the LeapProvider.CurrentFrame property. The data in Frame objects taken directly from a Leap.Controller instance is still in the Leap Motion frame of reference and will not match the hands displayed in a Unity scene.

Returns a frame of tracking data from the Leap Motion software. Use the optional history parameter to specify which frame to retrieve. Call frame() or frame(0) to access the most recent frame; call frame(1) to access the previous frame, and so on. If you use a history value greater than the number of stored frames, then the controller returns an empty frame.

Since

1.0

Param history

The age of the frame to return, counting backwards from the most recent frame (0) into the past and up to the maximum age (59).

Return

The specified frame; or, if no history parameter is specified, the newest frame. If a frame is not available at the specified history position, an invalid Frame is returned.

void Frame (Frame toFill, int history = 0)

Identical to Frame(history) but instead of constructing a new frame and returning it, the user provides a frame object to be filled with data instead.

long FrameTimestamp (int history = 0)

Returns the timestamp of a recent tracking frame. Use the optional history parameter to specify how many frames in the past to retrieve the timestamp. Leave the history parameter as it’s default value to return the timestamp of the most recent tracked frame.

Frame GetTransformedFrame (LeapTransform trs, int history = 0)

Returns the frame object with all hands transformed by the specified transform matrix.

Frame GetInterpolatedFrame (Int64 time, Device device = null)

Returns the Frame at the specified time, interpolating the data between existing frames, if necessary.

Frame GetInterpolatedFrame (Int64 time)

Returns the Frame at the specified time, interpolating the data between existing frames, if necessary.

void GetInterpolatedFrame (Frame toFill, Int64 time, Device device = null)

Fills the Frame with data taken at the specified time, interpolating the data between existing frames, if necessary.

LEAP_HEAD_POSE_EVENT GetInterpolatedHeadPose (Int64 time)

Returns the Head pose at the specified time, interpolating the data between existing frames, if necessary.

void SubscribeToDeviceEvents (Device device)

Subscribes to the events coming from an individual device

If this is not called, only the primary device will be subscribed. Will automatically unsubscribe the primary device if this is called on a secondary device, but not a primary one.

Since

4.1

void UnsubscribeFromDeviceEvents (Device device)

Unsubscribes from the events coming from an individual device

This can be called safely, even if the device has not been subscribed.

Since

4.1

void SubscribeToAllDevices ()

Subscribes to the events coming from all devices

Since

4.1

void UnsubscribeFromAllDevices ()

Unsubscribes from the events coming from all devices

Since

4.1

void GetInterpolatedLeftRightTransform (Int64 time, Int64 sourceTime, int leftId, int rightId, Device device, out LeapTransform leftTransform, out LeapTransform rightTransform)

This is a special variant of GetInterpolatedFrameFromTime, for use with special features that only require the position and orientation of the palm positions, and do not care about pose data or any other data.

You must specify the id of the hand that you wish to get a transform for. If you specify an id that is not present in the interpolated frame, the output transform will be the identity transform.

void GetInterpolatedLeftRightTransform (Int64 time, Int64 sourceTime, int leftId, int rightId, out LeapTransform leftTransform, out LeapTransform rightTransform)

This is a special variant of GetInterpolatedFrameFromTime, for use with special features that only require the position and orientation of the palm positions, and do not care about pose data or any other data.

You must specify the id of the hand that you wish to get a transform for. If you specify an id that is not present in the interpolated frame, the output transform will be the identity transform.

long Now ()

Returns a timestamp value as close as possible to the current time. Values are in microseconds, as with all the other timestamp values.

Since

2.2.7

FailedDeviceList FailedDevices ()

A list of any Leap Motion hardware devices that are physically connected to the client computer, but are not functioning correctly. The list contains FailedDevice objects containing the pnpID and the reason for failure. No other device information is available.

Since

3.0

Properties

SynchronizationContext EventContext { get; set; }

The SynchronizationContext used for dispatching events.

By default the synchronization context of the thread creating the controller instance is used. You can change the context if desired.

EventHandler<LeapEventArgs> Init { get; set; }

Dispatched when the connection is initialized (but not necessarily connected).

Can be dispatched more than once, if connection is restarted.

Since

3.0

EventHandler<ConnectionEventArgs> Connect { get; set; }

Dispatched when the connection to the service is established.

Since

3.0

EventHandler<ConnectionLostEventArgs> Disconnect { get; set; }

Dispatched if the connection to the service is lost.

Since

3.0

EventHandler<FrameEventArgs> FrameReady { get; set; }

Dispatched when a tracking frame is ready.

Since

3.0

EventHandler<InternalFrameEventArgs> InternalFrameReady { get; set; }

Dispatched when an internal tracking frame is ready.

Since

3.0

EventHandler<DeviceEventArgs> Device { get; set; }

Dispatched when a Leap Motion device is connected.

Since

3.0

EventHandler<DeviceEventArgs> DeviceLost { get; set; }

Dispatched when a Leap Motion device is disconnected.

Since

3.0

EventHandler<DeviceFailureEventArgs> DeviceFailure { get; set; }

Dispatched when a Leap device fails to initialize.

Since

3.0

EventHandler<LogEventArgs> LogMessage { get; set; }

Dispatched when the system generates a loggable event.

Since

3.0

EventHandler<PolicyEventArgs> PolicyChange { get; set; }

Dispatched when a policy changes.

Since

3.0

EventHandler<ConfigChangeEventArgs> ConfigChange { get; set; }

Dispatched when a configuration setting changes.

Since

3.0

EventHandler<DistortionEventArgs> DistortionChange { get; set; }

Dispatched when the image distortion map changes. The distortion map can change when the Leap device switches orientation, or a new device becomes active.

Since

3.0

EventHandler<DroppedFrameEventArgs> DroppedFrame { get; set; }

Dispatched when the service drops a tracking frame.

EventHandler<ImageEventArgs> ImageReady { get; set; }

Dispatched when an unrequested image is ready.

Since

4.0

Action<BeginProfilingForThreadArgs> BeginProfilingForThread { get; set; }

Dispatched whenever a thread wants to start profiling for a custom thread. The event is always dispatched from the thread itself.

The event data will contain the name of the thread, as well as an array of all possible profiling blocks that could be entered on that thread.

Since

4.0

Action<EndProfilingForThreadArgs> EndProfilingForThread { get; set; }

Dispatched whenever a thread is finished profiling. The event is always dispatched from the thread itself.

Since

4.0

Action<BeginProfilingBlockArgs> BeginProfilingBlock { get; set; }

Dispatched whenever a thread enters a profiling block. The event is always dispatched from the thread itself.

The event data will contain the name of the profiling block.

Since

4.0

Action<EndProfilingBlockArgs> EndProfilingBlock { get; set; }

Dispatched whenever a thread ends a profiling block. The event is always dispatched from the thread itself.

The event data will contain the name of the profiling block.

Since

4.0

EventHandler<PointMappingChangeEventArgs> PointMappingChange { get; set; }

Dispatched when point mapping change events are generated by the service.

Since

4.0

EventHandler<HeadPoseEventArgs> HeadPoseChange { get; set; }

Dispatched when a new HeadPose is available.

EventHandler<FiducialPoseEventArgs> FiducialPose { get; set; }

Dispatched when a Fiducial Marker has been tracked.

bool IsServiceConnected { get; set; }

Reports whether your application has a connection to the Leap Motion daemon/service. Can be true even if the Leap Motion hardware is not available.

Since

1.2

LEAP_VERSION ServiceVersion { get; set; }

Returns the current Leap service version information.

bool IsConnected { get; set; }

Reports whether this Controller is connected to the Leap Motion service and the Leap Motion hardware is plugged in.

When you first create a Controller object, isConnected() returns false. After the controller finishes initializing and connects to the Leap Motion software and if the Leap Motion hardware is plugged in, isConnected() returns true.

You can either handle the onConnect event using a Listener instance or poll the isConnected() function if you need to wait for your application to be connected to the Leap Motion software before performing some other operation.

Since

1.0

Config Config { get; set; }

Returns a Config object, which you can use to query the Leap Motion system for configuration information.

Since

1.0

DeviceList Devices { get; set; }

The list of currently attached and recognized Leap Motion controller devices.

The Device objects in the list describe information such as the range and tracking volume.

Currently, the Leap Motion Controller only allows a single active device at a time, however there may be multiple devices physically attached and listed here. Any active device(s) are guaranteed to be listed first, however order is not determined beyond that.

Since

1.0

Public Static Functions

static bool CheckRequiredServiceVersion (LEAP_VERSION minServiceVersion, Connection connection)

Checks whether a minimum or required tracking service version is installed. Gets the currently installed service version from the connection and checks whether the argument minServiceVersion is smaller or equal to it

Param minServiceVersion

The minimum service version to check against

Param connection

The connection

Return

True if the version of the running service is equal to or less than the minimum version specified