LeapController

Properties:

Methods:

class LeapController

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

Create an instance of this LeapController class to access frames of tracking data and configuration information. Frame data can be polled at any time using the [LeapController frame:] function. Set the frame: parameter to 0 to get the most recent frame. Set the parameter to a positive integer to access previous frames. For example, [controller frame:10] returns the frame that occurred ten frames ago. 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 add a listener object or delegate to the controller to handle events as they occur. The Leap dispatches events to the listener upon initialization and exiting, on connection changes, and when a new frame of tracking data is available. When these events occur, the controller object invokes the appropriate callback function.

Polling

Create an instance of the LeapController class using the default initializer:

LeapController *controller = [[LeapController alloc] init];

Access the frame data at regular intervals:

LeapFrame *frame = [controller frame:0];

You can check [LeapController isConnected] to determine if the controller is connected to the Leap software.

LeapListener protocol

Implement a class adopting the LeapListener protocol.

Create an instance of the LeapController class and assign your LeapListener object to it:

FrameListener *listener = [[FrameListener alloc] init];
LeapController *controller = [[LeapController alloc] initWithListener:listener];

The controller subscribes the LeapListener instance to the appropriate NSNotifications for the Leap events. When a new frame of data is ready, the controller dispatches an NSNotification on the main application thread, which is handled by your [LeapListener onFrame:] implementation.

LeapDelegate protocol

Implement a class adopting the LeapDelegate protocol.

Create an instance of the LeapController class and assign your LeapListener object to it:

LeapEventDelegate *delegate = [[LeapEventDelegate alloc] init];
LeapController *controller = [[LeapController alloc] init];
[controller addDelegate:delegate];

When a new frame of data is ready, the controller calls the [LeapDelegate onFrame:] method. The Controller object is multithreaded and calls the LeapDelegate functions on its own thread, not on an application thread.

You can handle the other Leap events, onInit, onConnect, onDisconnect, onServiceConnect, onServiceDisconnect, onDeviceChange, and onExit in the same manner.

Since 1.0

Public Functions


- (BOOL) addDelegate:(id< LeapDelegate >) delegate

Adds a delegate to this LeapController.

LeapEventDelegate *delegate = [[LeapEventDelegate alloc] init];
LeapController *controller = [[LeapController alloc] init];
[controller addDelegate:delegate];

Note: You cannot add a delegate when there is already a listener assigned.

Return
BOOL Whether or not the delegate was successfully added.
Since 1.0
Parameters


- (BOOL) addListener:(id< LeapListener >) listener

Adds a listener to this LeapController.

When you add an object adopting the LeapListener protocol to a LeapController, the controller automatically subscribes the listener to NSNotifications dispatched for the Leap events.

[controller addListener:listener];

Note: You cannot add a listener when there is already a delegate assigned.

Return
BOOL Whether or not the listener was successfully added to the list of listeners.
Since 1.0
Parameters


- (void) clearPolicy:(LeapPolicyFlag) policy

Requests clearing a policy.

Policy changes are completed asynchronously and, because they are subject to user approval, may not complete successfully. Call [LeapController isPolicySet:] after a suitable interval to test whether the change was accepted.

[controller clearPolicy:LEAP_POLICY_IMAGES];

Since 2.1.6
Parameters
  • flags -

    A PolicyFlag value indicating the policy to request.


- (void) enableGesture:(LeapGestureType) gestureType enable:(BOOL) enable

Enables or disables reporting of a specified gesture type.

See
[LeapController - isGestureEnabled:]
Parameters
  • enable -

    YES, to enable the specified gesture type; NO, to disable.


- (LeapFrame *) frame:(int) history

Returns a LeapFrame containing a frame of tracking data from the Leap.

Use the optional history parameter to specify which frame to retrieve. Call [controller frame:0] to access the most recent frame; call [controller 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 invalid frame.

LeapFrame *frame = [controller frame:0];

Return
The specified LeapFrame; or, if no history parameter is specified, the newest frame. If a frame is not available at the specified history position, an invalid LeapFrame is returned.
Since 1.0
Parameters
  • history -

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


- (id) init

Initializes a LeapController instance.

LeapController *controller = [[LeapController alloc] init];

Since 1.0


- (id) initWithDelegate:(id< LeapDelegate >) delegate

Initializes a LeapController instance and assigns a delegate.

LeapEventDelegate *delegate = [[LeapEventDelegate alloc] init];
LeapController *controller = [[LeapController alloc] initWithDelegate:delegate];

Since 1.0
Parameters


- (id) initWithListener:(id< LeapListener >) listener

Initializes a LeapController instance and assigns a listener.

FrameListener *listener = [[FrameListener alloc] init];
LeapController *controller = [[LeapController alloc] initWithListener:listener];

Since 1.0
Parameters


- (BOOL) isGestureEnabled:(LeapGestureType) gestureType

Reports whether the specified gesture type is enabled.

if (![controller isGestureEnabled:LEAP_GESTURE_TYPE_KEY_TAP]) {
    [controller enableGesture:LEAP_GESTURE_TYPE_KEY_TAP enable:true];
}

Return
YES, if the specified type is enabled; NO, otherwise.
See
[LeapController - enableGesture:enable:]
Parameters
  • gestureType -

    The type of gesture to check. Must be a member of the LeapGestureType enumeration:


- (BOOL) isPolicySet:(LeapPolicyFlag) policy

Gets the active setting for a specific policy.

Use this function to determine the current policy state. Keep in mind that setting a policy flag is asynchronous, so changes are not effective immediately after calling [LeapController setPolicy:]. 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, then the default policy state is returned.

This method has been deprecated. Use [LeapController isPolicySet:] instead.

bool isImagePolicySet = [controller isPolicySet:LEAP_POLICY_IMAGES];

Return
A boolean indicating whether the specified policy has been set.
Since 2.1.6
Parameters
  • flags -

    A PolicyFlag value indicating the policy to query.


- (int64_t) now

Returns a timestamp value as close as possible to the current time.

Values are in microseconds, as with all the other timestamp values.

LeapFrame *frame = [controller frame:0];
int64_t frameAge = 0;
if(frame.isValid){
    frameAge = [controller now] - frame.timestamp; //microseconds
}

Since
2.3.0


- (LeapPolicyFlag) policyFlags

This method has been deprecated.

Use [LeapController isPolicySet:] instead.

Return
The current policy flags.


- (BOOL) removeDelegate

Removes the delegate assigned to this LeapController.

[controller removeDelegate];

Return
BOOL Whether or not the delegate was successfully removed.
Since 1.0


- (BOOL) removeListener:(id< LeapListener >) listener

Unsubscribes the listener object from receiving Leap NSNotifications.

[controller removeListener:listener];

Return
BOOL Whether or not the listener was successfully removed.
Since 1.0
Parameters
  • listener -

    The listener to unsubscribe.


- (void) setPaused:(BOOL) enable

Pauses or resumes the Leap Motion service.

When the service is paused no applications receive tracking data and the service itself uses minimal CPU time.

Before changing the state of the service, you must set the POLICY_ALLOW_PAUSE_RESUME using the [LeapController setPolicy:] function. Policies must be set every time the application is run.

Since
3.0
Parameters
  • pause -

    Set true to pause the service; false to resume.


- (void) setPolicy:(LeapPolicyFlag) 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 settings window). 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, may not complete successfully. Call [LeapController isPolicySet:] after a suitable interval to test whether the change was accepted.

The current policies are:

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

LEAP_POLICY_IMAGES request that your application receives images from the device cameras. The “Allow Images” checkbox must be enabled in the Leap Motion Control Panel or this policy will be denied. The images policy determines whether an application receives image data from the Leap Motion sensors which each frame of data. By default, this data is not sent. Only applications that use the image data should request this policy.LEAP_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.

[controller setPolicy:LEAP_POLICY_BACKGROUND_FRAMES];
[controller setPolicy:LEAP_POLICY_IMAGES];

LEAP_POLICY_BACKGROUND_FRAMES

Parameters
  • flags -

    A PolicyFlag value indicating the policy to request. Must be a member of the LeapPolicyFlags enumeration:

LEAP_POLICY_IMAGES

LEAP_POLICY_OPTIMIZE_HMD

Since 2.1.6


- (void) setPolicyFlags:(LeapPolicyFlag) flags

This method has been deprecated.

Use [LeapController setPolicy:] and [LeapController clearPolicy:] instead.

Return
The current policy flags.

Property


- (LeapConfig *) config
config

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

LeapConfig *config = controller.config;

Since 1.0


- (NSArray *) devices
devices

Returns a list of currently attached devices.

Devices can be queried for device-specific information such as field of view.

Currently the Leap controller only recognizes a single device at a time.

NSArray *deviceList = controller.devices;

Since 1.0


- (NSArray *) failedDevices
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 LeapFailedDevice objects containing the pnpID and the reason for failure. No other device information is available.

Since
3.0


- (BOOL) hasFocus
hasFocus

Reports whether this application is the focused, foreground application.

Only the foreground application receives tracking information from the Leap Motion Controller.

if(!controller.hasFocus){
    //Pause app
}

Return
True, if application has focus; false otherwise.
Since 1.0


- (NSArray *) images
images

The most recent set of images from the Leap Motion cameras.

Depending on timing and the current processing frame rate, the images obtained with this function can be newer than images obtained from the current frame of tracking data.

NSArray *images = controller.images;

//image latency:
LeapImage * image = [images objectAtIndex:0];
int64_t imageAge = [controller now] - image.timestamp;

Return
An NSArray object containing the most recent camera images.
Since
2.2.1


- (BOOL) isConnected
isConnected

Reports whether this LeapController is connected to the Leap device.

When you first create a LeapController object, isConnected returns false. After the controller finishes initializing and connects to the Leap, isConnected will return true.

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

if(controller.isConnected){
    LeapFrame *frame = [controller frame:0];
}

Return
True, if connected; false otherwise.
Since 1.0


- (BOOL) isPaused
isPaused

Reports whether the Leap Motion service is currently paused.

Return
True, if the service is paused; false, otherwise.
Since
3.0


- (BOOL) isServiceConnected
isServiceConnected

Reports whether this LeapService is in communication with the client API.

When you first create a LeapController object, isServiceConnected returns false. After the controller finishes initializing and makes contact with the LeapService, isServiceConnected will return true.

You can either handle the onServiceConnect event using a LeapListener or LeapDelegate instance or poll the isServiceConnected function if you need to wait for your application to be connected to the Leap Service before performing some other operation.

if(controller.isServiceConnected){
    LeapFrame *frame = [controller frame:0];
}

Return
True, if connected; false otherwise.
Since 1.2

LeapPolicyFlags

LeapPolicyFlag enum

The supported controller policies.

Since 1.0

Values:

  • LEAP_POLICY_DEFAULT = = 0 -

    The default policy.

    Since 1.0

  • LEAP_POLICY_BACKGROUND_FRAMES = = (1 << 0) -

    Receive background frames.

    Since 1.0

  • LEAP_POLICY_IMAGES = = (1 << 1) -

    Receive raw images from sensor cameras.

    Since 2.0.5

  • LEAP_POLICY_OPTIMIZE_HMD = = (1 << 2) -

    Optimize the tracking for head-mounted device.

    Since 2.1.3

  • LEAP_POLICY_ALLOW_PAUSE_RESUME = = (1 << 3) -

    Allow pausing and unpausing of the Leap Motion service.

    Since 2.2.0