# What is it?

This is a rust library that allows you to interface with your Oculus Touch controllers and headset. It is a wrapper for the [auto_oculus_touch](https://github.com/rajetic/auto_oculus_touch/) project.

With it, you can read the current state of the controllers and headset, send button presses to the controller, or move the thumbsticks.

# Installation

```bash
cargo add rust_oculus_touch
```

# Example Usage

Below is a short program that will vibrate both controllers for 1 second whenever the X button is pressed while the headset is being worn.

```rust
use rust_oculus_touch as ot;

fn main() {
    let oculus = ot::OculusTouch::new();
    oculus.InitOculus();

    while true {
        oculus.Poll();
        println!("\n");

        let wearing = oculus.Wearing();
        println!(
            "Headset is {} your head",
            if wearing { "ON" } else { "OFF" }
        );

        let x = oculus.GetPositionX(ot::OculusTouchControllerEnum::Head);
        let y = oculus.GetPositionY(ot::OculusTouchControllerEnum::Head);
        let z = oculus.GetPositionZ(ot::OculusTouchControllerEnum::Head);
        let yaw = oculus.GetYaw(ot::OculusTouchControllerEnum::Head);
        let pitch = oculus.GetPitch(ot::OculusTouchControllerEnum::Head);
        let roll = oculus.GetRoll(ot::OculusTouchControllerEnum::Head);
        println!(
            "Headset Position: ({}, {}, {}), Yaw: {}, Pitch: {}, Roll: {}",
            x, y, z, yaw, pitch, roll
        );

        let buttons_down = oculus.GetButtonsDownList(); // Get a list of buttons that are currently held down
        let sensors_touched = oculus.GetTouchDownList(); // Get a list of capacitive sensors that are currently being touched
        println!("These buttons are down: {:?}", buttons_down);
        println!("These sensors are touched: {:?}", sensors_touched);

        println!("Here's a vibration for fun!"); // Vibrate the controllers
        oculus.Vibrate(
            ot::OculusTouchControllerEnum::Left,
            ot::OculusTouchVibrationFrequencyEnum::Medium,
            128,
            1.0,
        );
        oculus.Vibrate(
            ot::OculusTouchControllerEnum::Right,
            ot::OculusTouchVibrationFrequencyEnum::Medium,
            128,
            1.0,
        );

        oculus.PollAndSleep(1.0 as u64); // Poll and wait 1 second
    }
}
```

This is a smaple output from the above program:

```
Headset is ON your head
Headset Position: (-0.011632837, 0.061689533, 0.34418005), Yaw: 6.269506, Pitch: 37.764984, Roll: 1.5803292
These buttons are down: [RThumb]
These sensors are touched: [RThumb]
Here's a vibration for fun!


Headset is ON your head
Headset Position: (-0.010339707, 0.061480127, 0.34358978), Yaw: 6.575623, Pitch: 37.657368, Roll: 1.8094705
These buttons are down: []
These sensors are touched: [A, B]
Here's a vibration for fun!


Headset is ON your head
Headset Position: (-0.0077772066, 0.06255522, 0.3305807), Yaw: 6.428792, Pitch: 37.119587, Roll: 1.9261029
These buttons are down: []
These sensors are touched: [A, B, RIndexTrigger]
Here's a vibration for fun!


Headset is ON your head
Headset Position: (0.040116116, 0.071848914, 0.05625144), Yaw: 3.89342, Pitch: 28.924469, Roll: 2.6751015
These buttons are down: []
These sensors are touched: []
Here's a vibration for fun!
```

# API Reference

## InitOculus

Initialize the Oculus API.

### Parameters

- `poll: boolean` (Optional): If true, polls the Oculus API after initializing. Defaults to true.

### Returns

- `number`: Return code from the initialization process.

## Poll

Polls the Oculus Touch API for state updates.

### Parameters

_None_

### Returns

_None_

## Sleep

Blocks the runtime and waits for the specified length. Useful for sleeping between polls.

### Parameters

- `length: number` (Optional): Length of time to sleep in seconds. Defaults to 0.1.

### Returns

- `Promise<void>`: A Promise that resolves after the specified length of time.

## PollAndSleep

Combines the `Poll()` and `Sleep()` functions.

### Parameters

- `length: number` (Optional): Length of time to sleep in seconds. Defaults to 0.1.

### Returns

- `Promise<void>`: A Promise that resolves after the specified length of time.

## Wearing

Checks if the user is wearing the headset.

### Parameters

_None_

### Returns

- `boolean`: True if the user is wearing the headset, false otherwise.

## IsPressed

Checks if the specified button was pressed in the current poll. "Pressed" and "Down" are not the same thing.

### Parameters

- `button: OculusTouchButtonEnum`: The button to check.

### Returns

- `boolean`: True if the button was pressed, false otherwise.

## IsReleased

Checks if the specified button was released in the current poll.

### Parameters

- `button: OculusTouchButtonEnum`: The button to check.

### Returns

- `boolean`: True if the button was released, false otherwise.

## IsDown

Checks if the specified button is currently held down. "Pressed" and "Down" are not the same thing.

### Parameters

- `button: OculusTouchButtonEnum`: The button to check.

### Returns

- `boolean`: True if the button is held down, false otherwise.

## IsTouchPressed

Checks if the specified button's capacitor was touched in the current poll. "Pressed" and "Down" are not the same thing.

### Parameters

- `sensor: OculusTouchSensorEnum`: The sensor to check.

### Returns

- `boolean`: True if the button's capacitor was touched, false otherwise.

## IsTouchReleased

Checks if the specified button's capacitor was released in the current poll.

### Parameters

- `sensor: OculusTouchSensorEnum`: The sensor to check.

### Returns

- `boolean`: True if the button's capacitor was released, false otherwise.

## IsTouchDown

Checks if the specified button's capacitor is currently being touched. "Pressed" and "Down" are not the same thing.

### Parameters

- `sensor: OculusTouchSensorEnum`: The sensor to check.

### Returns

- `boolean`: True if the button's capacitor is being touched, false otherwise.

## Reached

Checks whether a specified axis has reached a specified threshold value in between the last poll.

### Parameters

- `axis: OculusTouchAxisEnum`: The axis to check.
- `value: number`: The threshold value to check against.

### Returns

- `number`: Return code indicating if the axis has reached the threshold. 0 if the threshold wasn't crossed. 1 if the threshold was crossed in the positive direction. -1 if it was crossed in the negative direction.

## GetAxis

Returns the value of the specified axis.

### Parameters

- `axis: OculusTouchAxisEnum`: The axis to query.

### Returns

- `number`: The current value of the specified axis.

## GetButtonsDown

Returns a bitmask of all buttons currently held down. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `number`: Bitmask representing buttons currently held down.

## GetButtonsDownList

Returns a list of all buttons currently held down. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `OculusTouchButtonEnum[]`: List of buttons currently held down.

## GetButtonsReleased

Returns a bitmask of all buttons released in the current poll.

### Parameters

_None_

## Returns

- `number`: Bitmask representing buttons released in the current poll.

## GetButtonsReleasedList

Returns a list of all buttons released in the current poll.

### Parameters

_None_

### Returns

- `OculusTouchButtonEnum[]`: List of buttons released in the current poll.

## GetButtonsPressed

Returns a bitmask of all buttons pressed in the current poll. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `number`: Bitmask representing buttons pressed in the current poll.

## GetButtonsPressedList

Returns a list of all buttons pressed in the current poll. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `OculusTouchButtonEnum[]`: List of buttons pressed in the current poll.

## GetTouchDown

Returns a bitmask of all buttons whose capacitors are currently being touched. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `number`: Bitmask representing buttons whose capacitors are currently being touched.

## GetTouchDownList

Returns a list of all buttons whose capacitors are currently being touched. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `OculusTouchSensorEnum[]`: List of buttons whose capacitors are currently being touched.

## GetTouchPressed

Returns a bitmask of all buttons whose capacitors were touched in the current poll. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `number`: Bitmask representing buttons whose capacitors were touched in the current poll.

## GetTouchPressedList

Returns a list of all buttons whose capacitors were touched in the current poll. "Pressed" and "Down" are not the same thing.

### Parameters

_None_

### Returns

- `OculusTouchSensorEnum[]`: List of buttons whose capacitors were touched in the current poll.

## GetTouchReleased

Returns a bitmask of all buttons whose capacitors were released in the current poll.

### Parameters

_None_

### Returns

- `number`: Bitmask representing buttons whose capacitors were released in the current poll.

## GetTouchReleasedList

Returns a list of all buttons whose capacitors were released in the current poll.

### Parameters

_None_

### Returns

- `OculusTouchSensorEnum[]`: List of buttons whose capacitors were released in the current poll.

## GetTrigger

Returns the value of a specified trigger.

### Parameters

- `hand: OculusTouchHandEnum`: The hand (left or right) of the trigger.
- `trigger: OculusTouchTriggerEnum`: The trigger (index or hand) to query.

### Returns

- `number`: The value of the specified trigger.

## GetThumbStick

Returns the value of a specified thumbstick's axis.

### Parameters

- `hand: OculusTouchHandEnum`: The hand (left or right) of the thumbstick.
- `axis: OculusTouchAxisEnum`: The axis (x or y) of the thumbstick to query.

### Returns

- `number`: The value of the specified thumbstick's axis.

## Vibrate

Vibrates a specified controller.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to vibrate.
- `frequency: OculusTouchVibrationFrequencyEnum` (Optional): The vibration frequency. Default is `OculusTouchVibrationFrequencyEnum.Medium`.
- `amplitude: number` (Optional): The amplitude of the vibration, range [0, 255]. Default is 128.
- `length: number` (Optional): The length of the vibration in seconds, 0 for infinite. Default is 1.0.

### Throws

- `Error`: If the amplitude is not in the range [0, 255].

### Returns

_None_

## GetYaw

Returns the yaw of a specified controller. Yaw is rotation around the y-axis.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to query.

### Returns

- `number`: The yaw (rotation around the y-axis) of the specified controller.

## GetPitch

Returns the pitch of a specified controller. Pitch is rotation around the x-axis.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to query.

### Returns

- `number`: The pitch (rotation around the x-axis) of the specified controller.

## GetRoll

Returns the roll of a specified controller. Roll is rotation around the z-axis.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to query.

### Returns

- `number`: The roll (rotation around the z-axis) of the specified controller.

## GetPositionX

Returns the x position of a specified controller.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to query.

### Returns

- `number`: The x position of the specified controller.

## GetPositionY

Returns the y position of a specified controller.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to query.

### Returns

- `number`: The y position of the specified controller.

## GetPositionZ

Returns the z position of a specified controller.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller to query.

### Returns

- `number`: The z position of the specified controller.

## SetTrackingOrigin

Sets the tracking origin of the headset. This is the point in space that the headset will consider to be the origin (0, 0, 0).

### Parameters

- `origin: OculusTouchTrackingOriginEnum`: The tracking origin to set.

### Returns

_None_

## ResetFacing

Resets the yaw of a specified controller. Yaw is rotation around the y-axis.

### Parameters

- `controller: OculusTouchControllerEnum`: The controller for which to reset the yaw.

### Returns

_None_

## InitvJoy

Initializes the vJoy driver. This must be called before any vJoy functions can be used.

### Parameters

- `device: number`: The vJoy device number to initialize.

### Throws

- `Error`: If there is an error during initialization.

### Returns

_None_

## SetvJoyAxis

Sets the value of a specified vJoy axis.

### Parameters

- `axis: OculusTouchvJoyDeviceEnum`: The vJoy axis to set.
- `value: number`: The value to set, range [0.0, 1.0].

### Returns

_None_

## SetvJoyAxisU

Sets the value of a specified vJoy axis using a different range.

### Parameters

- `axis: OculusTouchvJoyDeviceEnum`: The vJoy axis to set.
- `value: number`: The value to set, range [0.0, 1.0], mapped to [-1.0, 1.0].

### Returns

_None_

## SetvJoyButton

Sets the value of a specified vJoy button.

### Parameters

- `button: OculusTouchButtonEnum`: The vJoy button to set.
- `value: number`: The value to set, range [0, 1].

### Returns

_None_

## SendRawMouseMove

Sends a raw mouse move event to the host computer.

### Parameters

- `x: number`: The relative movement in the x direction.
- `y: number`: The relative movement in the y direction.
- `z: number`: The relative movement in the z direction.

### Returns

_None_

## SendRawMouseButtonDown

Sends a raw mouse button down event to the host computer.

### Parameters

- `button: OculusTouchRawMouseButtonEnum`: The button to press.

### Returns

_None_

## SendRawMouseButtonUp

Sends a raw mouse button up event to the host computer.

### Parameters

- `button: OculusTouchRawMouseButtonEnum`: The button to release.

### Returns

_None_