Struct rusty_xinput::XInputHandle

pub struct XInputHandle { /* private fields */ }

A handle to a loaded XInput DLL.

Implementations

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.

This cannot detect the “Guide” button. Use get_state_ex for that.

Notes

It is a persistent problem with xinput (since ~2007?) that polling for the data of a controller that isn’t connected will cause a long stall. 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.

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

Works like get_state, but can detect the “Guide” button as well.

Failure

• This function is technically an undocumented API. It was introduced in XInput 1.3, but may not be present in the currently loaded XInput. If it’s not available then XInputNotLoaded is returned as an Err, even when other XInput functions may be available.

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_capabilities_ex( &self, user_index: u32 ) -> Result<XINPUT_CAPABILITIES_EX, XInputUsageError>

Retrieve the Extended capabilities of a controller.

Undocumented!! This isn’t part of the official XInput API, but is often available.

Failure

• This function is technically an undocumented API. If it’s not available then XInputNotLoaded is returned as an Err, even when other XInput functions may be available.

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 Clone for XInputHandle

fn clone(&self) -> XInputHandle

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for XInputHandle

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

Formats the value using the given formatter.

impl Send for XInputHandle

impl Sync for XInputHandle