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.

Every time you use Gilrs::poll_events() gamepad state is updated. You can use it to know if some button is pressed or to get axis's value.

use gilrs::{Gilrs, Button, Axis};

let mut gilrs = Gilrs::new();

loop {
    for _ in gilrs.poll_events() {}

    println!("Start: {}, Left Stick X: {}",
             gilrs[0].is_pressed(Button::Start),
             gilrs[0].value(Axis::LeftStickX));
}

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. Always returns false for Button::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. Returns NaN for Axis::Unknown.

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.

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

fn add_ff_effect(&mut self, data: EffectData) -> Result<usize, Error>

Creates and uploads new force feedback effect using data. This function will fail if device doesn't have space for new effect or doesn't support requested effect. Returns effect's index.

use gilrs::ff::EffectData;
use gilrs::Gilrs;

let mut gilrs = Gilrs::new();

let mut effect = EffectData::default();
effect.period = 1000;
effect.magnitude = 20000;
effect.replay.length = 5000;
effect.envelope.attack_length = 1000;
effect.envelope.fade_length = 1000;

let effect_idx = gilrs.gamepad_mut(0).add_ff_effect(effect).unwrap();
gilrs.gamepad_mut(0).ff_effect(effect_idx).unwrap().play(1);

fn drop_ff_effect(&mut self, idx: usize)

Drop effect stopping it. Use this function to make space for new effects.

fn ff_effect(&mut self, idx: usize) -> Option<&mut Effect>

Borrows mutable Effect.

fn max_ff_effects(&self) -> usize

Returns how many force feedback effects device can have.

fn is_ff_supported(&self) -> bool

Returns true if force feedback is supported by device.

fn set_ff_gain(&mut self, gain: u16)

Sets master gain for device.

Trait Implementations

impl Debug for Gamepad

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

Formats the value using the given formatter.