vigem_client/
lib.rs

1/*!
2ViGEm client in Rust
3====================
4
5[ViGEm](https://vigem.org/) is the Virtual Gamepad Emulation Framework.
6This crate implements a client for the [ViGEmBus Driver](https://github.com/ViGEm/ViGEmBus).
7The driver must be installed for this library to have any use.
8
9The [`Client`] contains the connection to the ViGEmBus driver.
10Start by connecting to the service:
11
12```
13let client = vigem_client::Client::connect().unwrap();
14```
15
16With a client instance virtual controllers (targets) can be created (eg. [`Xbox360Wired::new`] and [`DualShock4Wired::new`]).
17These targets are constructed from a client and a [`TargetId`].
18
19```
20let client = vigem_client::Client::connect().unwrap();
21
22# let id = vigem_client::TargetId::XBOX360_WIRED;
23// Creates a new virtual Xbox360 wired controller
24// It is not yet plugged in
25let target = vigem_client::Xbox360Wired::new(client, id);
26```
27
28A client can be used by multiple targets by passing a shared borrow of the client:
29
30```
31let client = vigem_client::Client::connect().unwrap();
32
33# let id = vigem_client::TargetId::XBOX360_WIRED;
34let target1 = vigem_client::Xbox360Wired::new(&client, id);
35let target2 = vigem_client::Xbox360Wired::new(&client, id);
36```
37
38For memory management reasons you can also pass `Rc` or `Arc` clients:
39
40```
41use std::rc::Rc;
42let client = Rc::new(vigem_client::Client::connect().unwrap());
43
44# let id = vigem_client::TargetId::XBOX360_WIRED;
45let target1 = vigem_client::Xbox360Wired::new(client.clone(), id);
46let target2 = vigem_client::Xbox360Wired::new(client.clone(), id);
47```
48
49Newly created targets are not plugged in by default, many methods will return [`Error::NotPluggedIn`] except `plugin`:
50
51```no_run
52let client = vigem_client::Client::connect().unwrap();
53# let id = vigem_client::TargetId::XBOX360_WIRED;
54let mut target = vigem_client::Xbox360Wired::new(client, id);
55
56// Plugin the virtual controller
57target.plugin().unwrap();
58```
59
60When a target is plugged in Windows plays the 'Device Connect' sound.
61You can see your virtual controller in the 'Set up USB game controllers' section of Control Panel.
62
63When a target is unplugged (or dropped, which unplugs the target) Windows plays the 'Device Disconnect' sound.
64If a target is dropped without running its destructor (eg. process is killed) then the virtual controller will remain stuck.
65Under Control Panel's 'Devices and Printers' section you can manually remove the stuck controller devices.
66
67It may take some time before the target is ready to accept updates, see `wait_ready`.
68If a target is updated before it is ready it may return [`Error::TargetNotReady`] errors:
69
70```no_run
71let client = vigem_client::Client::connect().unwrap();
72# let id = vigem_client::TargetId::XBOX360_WIRED;
73let mut target = vigem_client::Xbox360Wired::new(client, id);
74
75// Plugin the virtual controller
76target.plugin().unwrap();
77
78// Wait until the target is ready to accept updates
79target.wait_ready().unwrap();
80```
81
82Finally the target is ready to update its input states
83(note that `Xbox360Wired` and `DualShock4Wired` targets each have their own input states):
84
85```no_run
86let client = vigem_client::Client::connect().unwrap();
87# let id = vigem_client::TargetId::XBOX360_WIRED;
88let mut target = vigem_client::Xbox360Wired::new(client, id);
89
90// Plugin the virtual controller
91target.plugin().unwrap();
92
93// Wait until the target is ready to accept updates
94target.wait_ready().unwrap();
95
96// Configure the gamepad pressing nothing but A and X buttons
97let gamepad = vigem_client::XGamepad {
98	buttons: vigem_client::XButtons!(A | X),
99	..Default::default()
100};
101
102// Update the target
103let _ = target.update(&gamepad);
104```
105
106The DualShock4Wired target is under development.
107*/
108
109mod bus;
110mod event;
111mod error;
112mod client;
113mod x360;
114mod ds4;
115
116use self::event::*;
117pub use self::error::Error;
118pub use self::client::*;
119pub use self::x360::*;
120pub use self::ds4::*;
121
122/// Vendor and product ids.
123#[derive(Copy, Clone, Debug, Default, Eq, PartialEq, Hash)]
124#[repr(C)]
125pub struct TargetId {
126	pub vendor: u16,
127	pub product: u16,
128}
129impl TargetId {
130	/// Default vender and product ids for a wired Xbox360 target.
131	pub const XBOX360_WIRED: TargetId = TargetId { vendor: 0x045E, product: 0x028E };
132	/// Default vender and product ids for a wired DualShock4 target.
133	#[cfg(feature = "unstable_ds4")]
134	pub const DUALSHOCK4_WIRED: TargetId = TargetId { vendor: 0x054C, product: 0x05C4 };
135}
vigem_client/lib.rs

vigem_client/
lib.rs
