Controller Policies

Controller policies are a mechanism to turn on features that either change how the Leap Motion service/daemon operates or which can use additional computer resources. For example, the Optimize for HMD policy changes the hand recognition algorithms to expect to see the backs of hands more often then the palms of hands. Likewise, the Images policy instructs the service to send image data to your application, which adds a small amount of additional processing time and increases the size of a frame of tracking data.

Most policies can also be denied, typically because the user has disabled the feature in their Leap Motion control panel. For example, if the user has unchecked the “Allow Images” setting, then activating the Images policy in an application will fail.

The current policies available are:

  • Allow Pause and Resume — allows the application to pause and resume tracking.
  • Background Frames — receive tracking data when not the foreground, focused application.
  • Images — receive image data along with the rest of the tracking data.
  • Optimize for HMD — optimizes the tracking algorithm to recognize hands when the Leap Motion device is attached to a head-mounted display.

Allow Pause and Resume

Requesting the Allow Pause and Resume policy enables the setPaused() function, allowing your application to pause and resume the production of tracking data. Most applications should not request this policy. Pausing the service affects all Leap Motion applications. Activate this policy when you control the client computer and need to temporarily reduce resource usage.

Note that users can manually resume and pause the service using the Leap Motion control panel.

bool isPausable = controller.isPolicySet(Leap::Controller::POLICY_ALLOW_PAUSE_RESUME);
controller.setPolicy(Leap::Controller::POLICY_ALLOW_PAUSE_RESUME);

Background Frames

Requesting background frames allows your application to receive tracking data when it is not the foreground, focused application. Ordinarily, the Leap Motion service/daemon only sends tracking data to an application when it has the operating system input focus. When you activate the Background Frames policy, your application will still receive frames when it loses focus to a non-Leap-enabled application — but not when another Leap-enabled application has the focus.

The background frames policy exists to help prevent Leap-enabled applications from conflicting with each other. If the user is actively working in one application — or just moving their hands for another reason — Leap-enabled applications in the background could otherwise receive unintended input. Typically, only mouse control or similar applications that don’t have their own GUI windows should request the Background Frames policy.

The background frames policy is denied when the user has unchecked the Allow Background Frames option in the control panel. Note that you can override the control panel setting using the Config class, but you must always ask the ask the user’s permission before doing so. If the user still denies permission and your application cannot function without it, simply exit, informing the user that background frames are necessary for your application.

bool backgroundModeAllowed = controller.config().getInt32("background_app_mode") == 2;
if (!backgroundModeAllowed) {
    // Show dialog to request permission to allow background mode apps
    if(userPermission){
        controller.config().setInt32("background_app_mode", 2);
        controller.config().save();
    }
}
controller.setPolicy(Leap::Controller::POLICY_BACKGROUND_FRAMES);

Alternate background modes

You can set additional policies for alternate background modes. Most applications should not set these modes. The alternate modes can only be set numerically; no enumeration value is provided (these alternate modes cannot be set using the Java API):

  • (1 << 15) provides background frames, even when another Leap-enabled application has the operating system focus. This policy should be set for visualizer-style applications where there is no danger that unintended interaction will cause problems.
  • (1 << 23) allows background applications (that have set the Background Frames policy) to receive frames even when this applications has the operating system focus. This policy can also be set for visualizer-style applications to ease testing of background applications.
Leap::Controller::PolicyFlag current = controller.policyFlags();
Leap::Controller::PolicyFlag augmented = static_cast<Leap::Controller::PolicyFlag>(current & (1 << 15));
controller.setPolicyFlags(augmented);
augmented = static_cast<Leap::Controller::PolicyFlag>(augmented & (1 << 23));
controller.setPolicyFlags(augmented);

Images

Requesting images enables the Frame::images() and Controller::images() functions, allowing your application to access data from the Leap Motion cameras.

The Images policy is denied if the user has unchecked the Allow Images option in the Leap Motion Control Panel. You can override the setting with the Config class, but you must ask the user’s permission before doing so. If the user still denies permission and your application cannot function without it, simply exit, informing the user that background frames are necessary for your application.

bool imagesAllowed = controller.config().getInt32("tracking_images_mode") == 2;
if (!imagesAllowed) {
    // ask user for permission...
    if (userPermission) {
        controller.config().setInt32("tracking_images_mode", 2);
        controller.config().save();
    }
}
controller.setPolicy(Leap::Controller::POLICY_IMAGES);

Optimize for HMD

Requesting the Optimize for HMD policy tunes the hand recognition logic to better recognize hands when the Leap Motion device is attached to a head-mounted display. This primarily improves the classification of hands as left versus right and the direction of the palm. This policy does not improve tracking when the Leap Motion is mounted in a fixed, downward orientation.

controller.setPolicy(Leap::Controller::POLICY_OPTIMIZE_HMD);