VirtualGamepad

@objc(GSVirtualGamepad)
public protocol VirtualGamepad : Peripheral

Virtual gamepad peripheral for RemoteControl devices.

Through this peripheral, you can receive navigation events when some predefined inputs are triggered on the remote control.

The mapping between physical inputs (buttons, axes, etc.) on the device and received navigation events is specific to the remote control in use: please refer to the remote control documentation for further information. This peripheral is provided by all remote control devices, unless explicitly stated otherwise in the specific remote control documentation.

To start receiving navigation events, the virtual gamepad peripheral must be grabbed and a listener (that will receive all events) must be provided.

When the virtual gamepad is grabbed, the remote control will stop forwarding events associated to its navigation inputs to the connected drone (if any) and instead forward those events to the application-provided listener. To stop receiving events and having the device forward navigation input events back to the connected drone, the virtual gamepad must be ungrabbed.

Most remote control devices also provide a more specialized gamepad interface (please refer to the remote control documentation for further information), which usually allows to listen to finer-grained remote control input events. However, when inputs are grabbed using such a specialized interface, the virtual gamepad is preempted, thus it cannot be used anymore. While preempted, the navigation event won’t be forwarded to the listener anymore, until all inputs on the specialized gamepad interface are released. At that point, the virtual gamepad will grab the navigation inputs again and resume forwarding events to the application listener.

This peripheral is also in charge of notifying application events through the NotificationCenter. Those events are the appAction* values defined in ButtonsMappableAction enum. To subscribe to these notifications, please refer to the GsdkActionGamepadAppAction notification key documentation.

This peripheral can be retrieved by:

drone.getPeripheral(Peripherals.virtualGamepad)
  • Whether othe virtual gamepad is currently grabbed. If this peripheral is grabbed and not preempted, you should receive navigation events through the listener.

    Declaration

    Swift

    var isGrabbed: Bool { get }
  • Whether the virtual gamepad is preempted by the specific gamepad. If this peripheral is grabbed and not preempted, you should receive navigation events through the listener.

    Declaration

    Swift

    var isPreempted: Bool { get }
  • Whether or not the gamepad can be grabbed for navigation.

    Declaration

    Swift

    var canGrab: Bool { get }
  • Grabs the remote control navigation inputs.

    Note

    When grabbed, the remote control will stop forwarding events associated to its navigation inputs to the connected drone (if any) and instead forward those events to the application-provided listener.

    Declaration

    Swift

    func grab(listener: @escaping (_ event: VirtualGamepadEvent, _ state: VirtualGamepadEventState) -> Void) -> Bool

    Parameters

    listener

    the listener to forward navigation events to

    event

    the virtual gamepad event that has been received

    state

    the state corresponding to the event

    Return Value

    true if navigation inputs could be grabbed, false otherwise.

  • Ungrabs the remote control navigation inputs.

    This stops forwarding navigation events to the application listener and resumes forwarding them to the connected drone.

    Note

    Navigation inputs are automatically released, and the application listener is unregistered as soon as the gamepad peripheral disappears.

    Declaration

    Swift

    func ungrab()