The Controller class is your main interface to the Leap Motion Controller. More...
Inherits IController.
Public Types | |
| enum | PolicyFlag |
| The supported controller policies. More... | |
Public Member Functions | |
| void | ClearPolicy (Controller.PolicyFlag policy) |
| Requests clearing a policy. More... | |
| Controller () | |
| Constructs a Controller object. More... | |
| Controller (int connectionKey) | |
| Constructs a Controller object using the specified connection key. More... | |
| FailedDeviceList | FailedDevices () |
| A list of any Leap Motion hardware devices that are physically connected to the client computer, but are not functioning correctly. More... | |
| Frame | Frame (int history) |
| Returns a frame of tracking data from the Leap Motion software. More... | |
| void | Frame (Frame toFill, int history) |
| 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. More... | |
| Frame | Frame () |
| Returns the most recent frame of tracking data. More... | |
| void | Frame (Frame toFill) |
| Fills a frame object with the most recent tracking data. More... | |
| long | FrameTimestamp (int history=0) |
| Returns the timestamp of a recent tracking frame. More... | |
| Frame | GetInterpolatedFrame (Int64 time) |
| Returns the Frame at the specified time, interpolating the data between existing frames, if necessary. More... | |
| 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. More... | |
| Frame | GetTransformedFrame (LeapTransform trs, int history=0) |
| Returns the frame object with all hands transformed by the specified transform matrix. More... | |
| bool | IsPolicySet (Controller.PolicyFlag policy) |
| Gets the active setting for a specific policy. More... | |
| long | Now () |
| Returns a timestamp value as close as possible to the current time. More... | |
| Image | RequestImages (Int64 frameId, Image.ImageType type) |
| Requests an image pair from the service. More... | |
| Image | RequestImages (Int64 frameId, Image.ImageType type, byte[] imageBuffer) |
| Requests an image from the service. More... | |
| void | SetPolicy (Controller.PolicyFlag policy) |
| Requests setting a policy. More... | |
| void | StartConnection () |
| Starts the connection. More... | |
| void | StopConnection () |
| Stops the connection. More... | |
Properties | |
| Config | Config [get] |
| Returns a Config object, which you can use to query the Leap Motion system for configuration information. More... | |
| EventHandler< ConfigChangeEventArgs > | ConfigChange |
| Dispatched when a configuration seting changes. More... | |
| EventHandler< ConnectionEventArgs > | Connect |
| Dispatched when the connection to the service is established. More... | |
| EventHandler< DeviceEventArgs > | Device |
| Dispatched when a Leap Motion device is connected. More... | |
| EventHandler< DeviceFailureEventArgs > | DeviceFailure |
| Dispatched when a Leap device fails to initialize. More... | |
| EventHandler< DeviceEventArgs > | DeviceLost |
| Dispatched when when a Leap Motion device is disconnected. More... | |
| DeviceList | Devices [get] |
| The list of currently attached and recognized Leap Motion controller devices. More... | |
| EventHandler< ConnectionLostEventArgs > | Disconnect |
| Dispatched if the connection to the service is lost. More... | |
| EventHandler< DistortionEventArgs > | DistortionChange |
| Dispatched when the image distortion map changes. More... | |
| SynchronizationContext | EventContext [get, set] |
| The SynchronizationContext used for dispatching events. More... | |
| EventHandler< FrameEventArgs > | FrameReady |
| Dispatched when a tracking frame is ready. More... | |
| EventHandler< ImageEventArgs > | ImageReady |
| Dispatched when an image is ready. More... | |
| EventHandler< ImageRequestFailedEventArgs > | ImageRequestFailed |
| Dispatched when a requested image cannot be sent. More... | |
| EventHandler< LeapEventArgs > | Init |
| Dispatched when the connection is initialized (but not necessarily connected). More... | |
| EventHandler< InternalFrameEventArgs > | InternalFrameReady |
| Dispatched when an internal tracking frame is ready. More... | |
| bool | IsConnected [get] |
| Reports whether this Controller is connected to the Leap Motion service and the Leap Motion hardware is plugged in. More... | |
| bool | IsServiceConnected [get] |
| Reports whether your application has a connection to the Leap Motion daemon/service. More... | |
| EventHandler< LogEventArgs > | LogMessage |
| Dispatched when the system generates a loggable event. More... | |
| EventHandler< PolicyEventArgs > | PolicyChange |
| Dispatched when a policy changes. More... | |
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.
|
strong |
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.
| Enumerator | |
|---|---|
| POLICY_DEFAULT |
The default policy.
|
| POLICY_BACKGROUND_FRAMES |
Receive background frames.
|
| POLICY_OPTIMIZE_HMD |
Optimize the tracking for head-mounted device.
|
| POLICY_ALLOW_PAUSE_RESUME |
Allow pausing and unpausing of the Leap Motion service.
|
| Controller | ( | ) |
| Controller | ( | int | connectionKey | ) |
Constructs a Controller object using the specified connection key.
All controller instances using the same key will use the same connection to the serivce. 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.
| 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 ClearPolicy | ( | Controller.PolicyFlag | policy | ) |
Requests clearing a policy.
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.
| flags | A PolicyFlag value indicating the policy to request. |
| 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.
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.
| 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). |
Implements IController.
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.
| toFill | The frame object to fill with tracking data. |
| history | The age of the frame to return. |
Fills a frame object with the most recent tracking data.
| toFill | The frame object to fill with tracking data. |
| 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.
| history | the age of the timestamp to return, |
| Frame GetInterpolatedFrame | ( | Int64 | time | ) |
Returns the Frame at the specified time, interpolating the data between existing frames, if necessary.
Implements IController.
| 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.
| Frame GetTransformedFrame | ( | LeapTransform | trs, |
| int | history = 0 |
||
| ) |
Returns the frame object with all hands transformed by the specified transform matrix.
| trs | a LeapTransform containing translation, rotation, and scale. |
| 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). |
Implements IController.
| bool IsPolicySet | ( | Controller.PolicyFlag | policy | ) |
Gets the active setting for a specific policy.
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.
| flags | A PolicyFlag value indicating the policy to query. |
| 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.
Implements IController.
| Image RequestImages | ( | Int64 | frameId, |
| Image.ImageType | type | ||
| ) |
Requests an image pair from the service.
Image data is stacked in a single byte array, with the left camera image first, followed by the right camera image. Two types of image are supported. ImageType.TYPE_DEFAULT is the normal, IR format image. ImageType.RAW is the unmodified, raw sensor pixels. The format of this image type depends on the device. For the publically available Leap Motion devices, the raw image type is also IR and is identical to the default image type except when in robust mode. In robust mode, the default image type is processed to subtract the unilluminated background; the raw image is not.
Images are not sent automatically. You must request each image. This function returns an Image object. However, that object does not contain image data until its IsComplete property becomes true.
Image requests will fail if the request is made after the image has been disposed by the service. The service only keeps images for a few frames, so applications that use images must make the image request as soon as possible after a tracking frame is received.
The controller dispatches an ImageReady event when a requested image is recevied from the service and is ready for use. The controller dispatches an ImageRequestFailed event if the request does not succeed.
Image requests can fail for the following reasons:
In addition, if the returned image is invalid, then the request call itself failed. Typically this will occur when the connection itself is not running. Such errors are reported in a LogEvent event.
| frameId | The Id value of the tracking frame. |
| type | The type of image desired. A member of the Image.ImageType enumeration. |
| Image RequestImages | ( | Int64 | frameId, |
| Image.ImageType | type, | ||
| byte[] | imageBuffer | ||
| ) |
Requests an image from the service.
The pixels of the image are written to the specified byte array.
If the specified byte array is too small, an ImageRequestFailed event is dispatched. The arguments of this event include the required buffer size. For the publically available Leap device, the buffer size must be: width * height * bytes-per-pixel * #cameras, i.e: 640 * 240 * 1 * 2 = 307,200 bytes.
The Image object returned by this function contains a reference to the supplied buffer. When the service sets the IsComplete property to true when the buffer is filled in. An ImageReady event is also dispatched.
| frameId | The Id value of the tracking frame. |
| type | The type of image desired. A member of the Image.ImageType enumeration. |
| imageBuffer | A byte array large enough to hold the requested image pair. |
| void SetPolicy | ( | Controller.PolicyFlag | policy | ) |
Requests setting a policy.
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.
| policy | A PolicyFlag value indicating the policy to request. |
| void StartConnection | ( | ) |
Starts the connection.
A connection starts automatically when created, but you can use this function to restart the connection after stopping it.
| void StopConnection | ( | ) |
Stops the connection.
No more frames or other events are received from a stopped connection. You can restart with StartConnection().
Returns a Config object, which you can use to query the Leap Motion system for configuration information.
|
addremove |
Dispatched when a configuration seting changes.
|
addremove |
Dispatched when the connection to the service is established.
|
addremove |
Dispatched when a Leap Motion device is connected.
|
addremove |
Dispatched when a Leap device fails to initialize.
|
addremove |
Dispatched when when a Leap Motion device is disconnected.
|
get |
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.
|
addremove |
Dispatched if the connection to the service is lost.
|
addremove |
Dispatched when the image distortion map changes.
The distortion map can change when the Leap device switches orientation, or a new device becomes active.
|
getset |
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.
|
addremove |
Dispatched when a tracking frame is ready.
|
addremove |
Dispatched when an image is ready.
Call Controller.RequestImage() to request that an image be sent to your application.
|
addremove |
Dispatched when a requested image cannot be sent.
|
addremove |
Dispatched when the connection is initialized (but not necessarily connected).
Can be dispatched more than once, if connection is restarted.
|
addremove |
Dispatched when an internal tracking frame is ready.
|
get |
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.
|
get |
|
addremove |
Dispatched when the system generates a loggable event.
|
addremove |
Dispatched when a policy changes.