Struct gilrs::Gamepad

pub struct Gamepad { /* fields omitted */ }

Represents game controller.

Using this struct you can access cached gamepad state, informations about gamepad such as name or UUID and manage force feedback effects.

Methods

impl Gamepad

fn name(&self) -> &str

Returns gamepad's name.

fn uuid(&self) -> Uuid

Returns gamepad's UUID.

fn state(&self) -> &GamepadState

Returns cached gamepad state.

fn status(&self) -> Status

Returns current gamepad's status, which can be Connected, Disconnected or NotObserved. Only connected gamepads generate events. Disconnected gamepads retain their name and UUID. Cached state of disconnected and not observed gamepads is 0 (false for buttons and 0.0 for axis) and all actions preformed on such gamepad are no-op.

fn is_connected(&self) -> bool

Returns true if gamepad is connected.

fn is_pressed(&self, btn: Button) -> bool

Examines cached gamepad state to check if given button is pressed. If btn can also be represented by axis returns true if value is not equal to 0.0. Panics if btn is Unknown.

fn value(&self, axis: Axis) -> f32

Examines cached gamepad state to check axis's value. If axis is represented by button on device it value is 0.0 if button is not pressed or 1.0 if is pressed. Panics if axis is Unknown.

fn button_data(&self, btn: Button) -> Option<&ButtonData>

Returns button state and when it changed.

fn axis_data(&self, axis: Axis) -> Option<&AxisData>

Returns axis state and when it changed.

fn power_info(&self) -> PowerInfo

Returns device's power supply state. See PowerInfo for details.

fn mapping_source(&self) -> MappingSource

Returns source of gamepad mapping. Can be used to filter gamepads which do not provide unified controller layout.

use gilrs::MappingSource;

for (_, gamepad) in gilrs.gamepads().filter(
    |gp| gp.1.mapping_source() != MappingSource::None)
{
    println!("{} is ready to use!", gamepad.name());
}

fn set_mapping<'a, O: Into<Option<&'a str>>>(
    &mut self,
    mapping: &MappingData,
    name: O
) -> Result<String, MappingError>

Sets gamepad's mapping and returns SDL2 representation of them. Returned mappings may not be compatible with SDL2 - if it is important, use set_mapping_strict().

The name argument can be a string slice with custom gamepad name or None. If None, gamepad name reported by driver will be used.

Errors

This function return error if name contains comma, mapping have axis and button entry for same element (for example Axis::LetfTrigger and Button::LeftTrigger) or gamepad does not have any element with NativeEvCode used in mapping. Button::Unknown and Axis::Unknown are not allowd as keys to mapping – in this case, MappingError::UnknownElement is returned.

Error is also returned if this function is not implemented or gamepad is not connected.

Example

use gilrs::{Mapping, Button};

let mut data = Mapping::new();
data[Button::South] = 213;
// …

// or `match gilrs[0].set_mapping(&data, None) {`
match gilrs[0].set_mapping(&data, "Custom name") {
    Ok(sdl) => println!("SDL2 mapping: {}", sdl),
    Err(e) => println!("Failed to set mapping: {}", e),
};

Example with MappingError::DuplicatedEntry:

use gilrs::{Mapping, Button, Axis, MappingError};

let mut data = Mapping::new();
data[Button::RightTrigger2] = 2;
data[Axis::RightTrigger2] = 2;

assert_eq!(gilrs[0].set_mapping(&data, None), Err(MappingError::DuplicatedEntry));

See also examples/mapping.rs.

fn set_mapping_strict<'a, O: Into<Option<&'a str>>>(
    &mut self,
    mapping: &MappingData,
    name: O
) -> Result<String, MappingError>

Similar to set_mapping() but returned string should be compatible with SDL2.

Errors

Returns MappingError::NotSdl2Compatible if mapping have an entry for Button::{C, Z} or Axis::{LeftZ, RightZ}.

fn is_ff_supported(&self) -> bool

Returns true if force feedback is supported by device.

fn set_listener_position<Vec3: Into<[f32; 3]>>(
    &self,
    position: Vec3
) -> Result<(), FfError>

Change gamepad position used by force feedback effects.

fn button_name(&self, nec: NativeEvCode) -> Button

Returns Button mapped to nec.

fn axis_name(&self, nec: NativeEvCode) -> Axis

Returns Axis mapped to nec.

fn button_code(&self, btn: Button) -> Option<NativeEvCode>

Returns NativeEvCode associated with btn.

fn axis_code(&self, axis: Axis) -> Option<NativeEvCode>

Returns NativeEvCode associated with axis.

fn deadzone(&self, axis: NativeEvCode) -> f32

Returns area in which axis events should be ignored.

fn id(&self) -> usize

Returns ID of gamepad.

Trait Implementations

impl Debug for Gamepad

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.