Struct TargetBuilder 

pub struct TargetBuilder<'a, T> { /* private fields */ }

A builder for creating and plugging in a new virtual target.

Obtain a TargetBuilder from Client::new_x360_target() or Client::new_ds4_target().

Implementations

impl<'a, T> TargetBuilder<'a, T>

pub fn with_vid(self, vid: u16) -> Self

Sets a custom Vendor ID (VID) for this virtual device.

If not set, the default VID for the controller type will be used.

pub fn with_pid(self, pid: u16) -> Self

Sets a custom Product ID (PID) for this virtual device.

If not set, the default PID for the controller type will be used.

impl<'a> TargetBuilder<'a, Xbox360>

pub fn plugin(self) -> Result<TargetHandle<Xbox360>, ClientError>

Plugs the configured target into the ViGEm bus.

WARNING: The virtual controller may not be immediately ready for input updates (e.g., update() calls) upon the return of this function. Windows and the ViGEm driver require time to fully enumerate the device.

For reliable operation, especially when sending updates immediately after plugging in, it is highly recommended to call TargetHandle<T>::wait_for_ready and wait for it to return successfully before sending the first report.

On success, this consumes the builder and returns a TargetHandle which can be used to control the virtual device.

Examples found in repository

examples/x360.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let x360 = client.new_x360_target().plugin()?;
    println!("Plugged in virtual Xbox 360 controller");

    // Wait for the controller to be ready
    // The virtual controller needs a moment to be recognized
    // by the system before it can receive updates.
    x360.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = x360.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!("  - LED Number/Player Index: {}", notification.led_number);
        }
    });

    // Here, we'll send reports to the controller to simulate input.
    let mut report = X360Report::default();
    let mut angle: f64 = 0.0;
    let mut step = 0;

    loop {
        // Animate the left thumbstick in a circle
        angle += 0.1;
        let (sin, cos) = angle.sin_cos();
        report.thumb_lx = (sin * 32767.0) as i16;
        report.thumb_ly = (cos * 32767.0) as i16;

        // Alternate pressing A and B buttons
        if step % 2 == 0 {
            report.buttons = X360Button::A;
        } else {
            report.buttons = X360Button::B;
        }

        // Send the updated report to the controller
        x360.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        step += 1;
    }
}

impl<'a> TargetBuilder<'a, DualShock4>

pub fn plugin(self) -> Result<TargetHandle<DualShock4>, ClientError>

Plugs the configured target into the ViGEm bus.

WARNING: The virtual controller may not be immediately ready for input updates (e.g., update() calls) upon the return of this function. Windows and the ViGEm driver require time to fully enumerate the device.

For reliable operation, especially when sending updates immediately after plugging in, it is highly recommended to call TargetHandle<T>::wait_for_ready and wait for it to return successfully before sending the first report.

On success, this consumes the builder and returns a TargetHandle which can be used to control the virtual device.

Examples found in repository

examples/ds4.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Here, we'll send reports to the controller to simulate input.

    let mut report = Ds4Report::default();

    // Hold the right D-pad button
    report.set_dpad(Ds4Dpad::East);
    // Hold the Cross button
    report.buttons |= Ds4Button::CROSS.bits();
    // Fully press the right trigger
    report.trigger_r = 255;

    let mut angle: f64 = 0.0;

    loop {
        // Animate the right thumbstick in a circle
        let (sin, cos) = angle.sin_cos();

        // DS4 thumbsticks are 0-255, with 128 as the center.
        report.thumb_rx = (128.0 + sin * 127.0) as u8;
        report.thumb_ry = (128.0 + cos * 127.0) as u8;

        // Send the updated report to the controller
        ds4.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        angle += 0.05;
    }
}

examples/ds4_ex.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Main input loop for extended reports
    let mut report_ex = Ds4ReportEx::default();

    // Variables to animate the touch point
    let mut packet_counter: u8 = 0;
    let mut touch_x: i32 = 0;
    let mut direction: i32 = 12;

    loop {
        // Move the touch point back and forth horizontally.
        if touch_x <= 0 {
            direction = 12;
        }
        if touch_x >= 1919 {
            direction = -12;
        }
        touch_x += direction;

        report_ex.touch_packets_n = 1;

        // Get a mut reference to the touch data struct inside the report.
        let touch = &mut report_ex.current_touch;

        // This counter should increment for each new packet of touch data (not sure if necessary for functionality).
        touch.packet_counter = packet_counter;
        packet_counter = packet_counter.wrapping_add(1);

        touch.set_touch_1(true, 1, touch_x as u16, 471); // Finger 1 is down, centered vertically.
        touch.set_touch_2(false, 0, 0, 0); // Finger 2 is up (inactive).

        // Send the updated report to the controller
        ds4.update_ex(&report_ex)?;

        thread::sleep(Duration::from_millis(16));
    }
}