Struct rusty_xinput::XInputHandle

pub struct XInputHandle { /* fields omitted */ }

A handle to a loaded XInput DLL.

Methods

impl XInputHandle

pub fn load_default() -> Result<XInputHandle, XInputLoadingFailure>

Attempts to dynamically load an XInput DLL and get the function pointers.

Failure

This can fail in a few ways, as explained in the XInputLoadingFailure type. The most likely failure case is that the user's system won't have the required DLL, in which case you should probably allow them to play with just a keyboard/mouse instead.

Current DLL Names

Currently the following DLL names are searched for in this order:

• xinput1_4.dll
• xinput1_3.dll
• xinput1_2.dll
• xinput1_1.dll
• xinput9_1_0.dll

pub fn load<S: AsRef<str>>(s: S) -> Result<XInputHandle, XInputLoadingFailure>

Attempt to load a specific XInput DLL and get the function pointers.

impl XInputHandle

pub fn enable(&self, enable: bool)

Enables or disables XInput.

See the MSDN documentation for XInputEnable.

pub fn get_state(
    &self,
    user_index: u32
) -> Result<XInputState, XInputUsageError>

Polls the controller port given for the current controller state.

Notes

It is a persistent problem (since ~2007?) with xinput that polling for the data of a controller that isn't connected will cause a long delay. In the area of 500_000 cpu cycles. That's like 2_000 cache misses in a row.

Once a controller is detected as not being plugged in you are strongly advised to not poll for its data again next frame. Instead, you should probably only poll for one known-missing controller per frame at most.

Alternately, you can register for your app to get plug and play events and then wait for one of them to come in before you ever poll for a missing controller a second time. That's up to you.

Errors

A few things can cause an Err value to come back, as explained by the XInputUsageError type.

Most commonly, a controller will simply not be connected. Most people don't have all four slots plugged in all the time.

impl XInputHandle

pub fn set_state(
    &self,
    user_index: u32,
    left_motor_speed: u16,
    right_motor_speed: u16
) -> Result<(), XInputUsageError>

Allows you to set the rumble speeds of the left and right motors.

Valid motor speeds are across the whole u16 range, and the number is the scale of the motor intensity. In other words, 0 is 0%, and 65,535 is 100%.

On a 360 controller the left motor is low-frequency and the right motor is high-frequency. On other controllers running through xinput this might be the case, or the controller might not even have rumble ability at all. If rumble is missing from the device you'll still get Ok return values, so treat rumble as an extra, not an essential.

Errors

A few things can cause an Err value to come back, as explained by the XInputUsageError type.

Most commonly, a controller will simply not be connected. Most people don't have all four slots plugged in all the time.

impl XInputHandle

pub fn get_capabilities(
    &self,
    user_index: u32
) -> Result<XINPUT_CAPABILITIES, XInputUsageError>

Retrieve the capabilities of a controller.

See the MSDN documentation for XInputGetCapabilities.

pub fn get_keystroke(
    &self,
    user_index: u32
) -> Result<Option<XINPUT_KEYSTROKE>, XInputOptionalFnUsageError>

Retrieve a gamepad input event.

See the MSDN documentation for XInputGetKeystroke.

impl XInputHandle

pub fn get_gamepad_battery_information(
    &self,
    user_index: u32
) -> Result<XInputBatteryInformation, XInputOptionalFnUsageError>

Get battery type and charge level of a gamepad.

See also XInputGetBatteryInformation

pub fn get_headset_battery_information(
    &self,
    user_index: u32
) -> Result<XInputBatteryInformation, XInputOptionalFnUsageError>

Get battery type and charge level of a headset.

See also XInputGetBatteryInformation

Trait Implementations

impl Sync for XInputHandle

impl Clone for XInputHandle

fn clone(&self) -> XInputHandle

Returns a copy of the value.

default fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Send for XInputHandle

impl Debug for XInputHandle

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.