/******************************************************************************
 * Copyright (C) Leap Motion, Inc. 2011-2017.                                 *
 * Leap Motion proprietary and  confidential.                                 *
 *                                                                            *
 * Use subject to the terms of the Leap Motion SDK Agreement available at     *
 * https://developer.leapmotion.com/sdk_agreement, or another agreement       *
 * between Leap Motion and you, your company or other organization.           *
 ******************************************************************************/

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

namespace Leap.Unity.Interaction {

  /// <summary>
  /// An IGraspedPoseHandler specifies where an object grasped by a Leap hand or
  /// controller (or multiple hands/controllers) should move as the grasping
  /// controllers(s) move. The default implementation provided by the Interaction Engine
  /// is the KabschGraspedPose, which produces a physically-intuitive following motion
  /// for the object no matter how a grasping hand moves.
  /// 
  /// IGraspedPoseHandlers do not actually move an object; they only calculate where
  /// an object should be moved. Actually moving the object is the concern of an
  /// IGraspedMovementHandler.
  /// </summary>
  public interface IGraspedPoseHandler {

    /// <summary>
    /// Called when a new InteractionController begins grasping a certain object.
    /// The controller or Leap hand should be included in the held pose calculation.
    /// </summary>
    void AddController(InteractionController controller);

    /// <summary>
    /// Called when an InteractionController stops grasping a certain object; the
    /// controller should no longer be included in the held pose calculation.
    /// </summary>
    void RemoveController(InteractionController controller);

    /// <summary>
    /// Called e.g. if the InteractionBehaviour is set not to move while being grasped;
    /// this should clear any hands to be included in the grasping position calculation.
    /// </summary>
    void ClearControllers();

    /// <summary>
    /// Calculate the best holding position and orientation given the current state of
    /// all InteractionControllers (added via AddController()).
    /// </summary>
    void GetGraspedPosition(out Vector3 position, out Quaternion rotation);

  }

}
