Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2025-02-16 22:18:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

Bevy Input Docs : gamepad.rs (#9469)

Browse source 
# Objective

Complete the documentation of `bevy_input` (#3492).

This PR is part of a triptych of PRs :
- https://github.com/bevyengine/bevy/pull/9467
- https://github.com/bevyengine/bevy/pull/9468

## Solution

Add missing documentation on items in `gamepad.rs`

---------

Co-authored-by: Pascal Hertleif <killercup@gmail.com>
This commit is contained in:
Tristan Guichaoua 2023-08-19 20:19:46 +02:00 • committed by GitHub
parent b9ab17e8b6
commit 5db4a04a76
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 52 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
crates/bevy_input/src/gamepad.rs
View file

@ -27,13 +27,17 @@ pub enum AxisSettingsError {
/// Parameter `livezone_lowerbound` was not less than or equal to parameter `deadzone_lowerbound`.
#[error("invalid parameter values livezone_lowerbound {} deadzone_lowerbound {}, expected livezone_lowerbound <= deadzone_lowerbound", .livezone_lowerbound, .deadzone_lowerbound)]
LiveZoneLowerBoundGreaterThanDeadZoneLowerBound {
/// The value of the `livezone_lowerbound` parameter.
livezone_lowerbound: f32,
/// The value of the `deadzone_lowerbound` parameter.
deadzone_lowerbound: f32,
},
/// Parameter `deadzone_upperbound` was not less than or equal to parameter `livezone_upperbound`.
#[error("invalid parameter values livezone_upperbound {} deadzone_upperbound {}, expected deadzone_upperbound <= livezone_upperbound", .livezone_upperbound, .deadzone_upperbound)]
DeadZoneUpperBoundGreaterThanLiveZoneUpperBound {
/// The value of the `livezone_upperbound` parameter.
livezone_upperbound: f32,
/// The value of the `deadzone_upperbound` parameter.
deadzone_upperbound: f32,
},
/// The given parameter was not in range 0.0..=2.0.
@ -53,7 +57,9 @@ pub enum ButtonSettingsError {
/// Parameter `release_threshold` was not less than or equal to `press_threshold`.
#[error("invalid parameter values release_threshold {} press_threshold {}, expected release_threshold <= press_threshold", .release_threshold, .press_threshold)]
ReleaseThresholdGreaterThanPressThreshold {
/// The value of the `press_threshold` parameter.
press_threshold: f32,
/// The value of the `release_threshold` parameter.
release_threshold: f32,
},
}
@ -100,6 +106,11 @@ impl Gamepad {
reflect(Serialize, Deserialize)
)]
pub struct GamepadInfo {
/// The name of the gamepad.
///
/// This name is generally defined by the OS.
///
/// For example on Windows the name may be "HID-compliant game controller".
pub name: String,
}
@ -130,6 +141,7 @@ impl Gamepads {
self.gamepads.keys().copied()
}
/// The name of the gamepad if this one is connected.
pub fn name(&self, gamepad: Gamepad) -> Option<&str> {
self.gamepads.get(&gamepad).map(|g| g.name.as_str())
}
@ -1025,6 +1037,7 @@ pub fn gamepad_connection_system(
}
}
/// The connection status of a gamepad.
#[derive(Debug, Clone, PartialEq, Reflect)]
#[reflect(Debug, PartialEq)]
#[cfg_attr(
@ -1033,7 +1046,9 @@ pub fn gamepad_connection_system(
reflect(Serialize, Deserialize)
)]
pub enum GamepadConnection {
/// The gamepad is connected.
Connected(GamepadInfo),
/// The gamepad is disconnected.
Disconnected,
}
@ -1054,6 +1069,7 @@ pub struct GamepadConnectionEvent {
}
impl GamepadConnectionEvent {
/// Creates a [`GamepadConnectionEvent`].
pub fn new(gamepad: Gamepad, connection: GamepadConnection) -> Self {
Self {
gamepad,
@ -1061,15 +1077,19 @@ impl GamepadConnectionEvent {
}
}
/// Is the gamepad connected?
pub fn connected(&self) -> bool {
matches!(self.connection, GamepadConnection::Connected(_))
}
/// Is the gamepad disconnected?
pub fn disconnected(&self) -> bool {
!self.connected()
}
}
/// Gamepad event for when the "value" on the axis changes
/// by an amount larger than the threshold defined in [`GamepadSettings`].
#[derive(Event, Debug, Clone, PartialEq, Reflect)]
#[reflect(Debug, PartialEq)]
#[cfg_attr(
@ -1078,12 +1098,16 @@ impl GamepadConnectionEvent {
reflect(Serialize, Deserialize)
)]
pub struct GamepadAxisChangedEvent {
/// The gamepad on which the axis is triggered.
pub gamepad: Gamepad,
/// The type of the triggered axis.
pub axis_type: GamepadAxisType,
/// The value of the axis.
pub value: f32,
}
impl GamepadAxisChangedEvent {
/// Creates a [`GamepadAxisChangedEvent`].
pub fn new(gamepad: Gamepad, axis_type: GamepadAxisType, value: f32) -> Self {
Self {
gamepad,
@ -1103,12 +1127,16 @@ impl GamepadAxisChangedEvent {
reflect(Serialize, Deserialize)
)]
pub struct GamepadButtonChangedEvent {
/// The gamepad on which the button is triggered.
pub gamepad: Gamepad,
/// The type of the triggered button.
pub button_type: GamepadButtonType,
/// The value of the button.
pub value: f32,
}
impl GamepadButtonChangedEvent {
/// Creates a [`GamepadButtonChangedEvent`].
pub fn new(gamepad: Gamepad, button_type: GamepadButtonType, value: f32) -> Self {
Self {
gamepad,
@ -1163,8 +1191,11 @@ pub fn gamepad_button_event_system(
reflect(Serialize, Deserialize)
)]
pub enum GamepadEvent {
/// A gamepad has been connected or disconnected.
Connection(GamepadConnectionEvent),
/// A button of the gamepad has been triggered.
Button(GamepadButtonChangedEvent),
/// An axis of the gamepad has been triggered.
Axis(GamepadAxisChangedEvent),
}
@ -1242,16 +1273,16 @@ const ALL_AXIS_TYPES: [GamepadAxisType; 6] = [
/// The intensity at which a gamepad's force-feedback motors may rumble.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct GamepadRumbleIntensity {
/// The rumble intensity of the strong gamepad motor
/// The rumble intensity of the strong gamepad motor.
///
/// Ranges from 0.0 to 1.0
/// Ranges from `0.0` to `1.0`.
///
/// By convention, this is usually a low-frequency motor on the left-hand
/// side of the gamepad, though it may vary across platforms and hardware.
pub strong_motor: f32,
/// The rumble intensity of the weak gamepad motor
/// The rumble intensity of the weak gamepad motor.
///
/// Ranges from 0.0 to 1.0
/// Ranges from `0.0` to `1.0`.
///
/// By convention, this is usually a high-frequency motor on the right-hand
/// side of the gamepad, though it may vary across platforms and hardware.
@ -1259,27 +1290,27 @@ pub struct GamepadRumbleIntensity {
}
impl GamepadRumbleIntensity {
/// Rumble both gamepad motors at maximum intensity
/// Rumble both gamepad motors at maximum intensity.
pub const MAX: Self = GamepadRumbleIntensity {
strong_motor: 1.0,
weak_motor: 1.0,
};
/// Rumble the weak motor at maximum intensity
/// Rumble the weak motor at maximum intensity.
pub const WEAK_MAX: Self = GamepadRumbleIntensity {
strong_motor: 0.0,
weak_motor: 1.0,
};
/// Rumble the strong motor at maximum intensity
/// Rumble the strong motor at maximum intensity.
pub const STRONG_MAX: Self = GamepadRumbleIntensity {
strong_motor: 1.0,
weak_motor: 0.0,
};
/// Creates a new rumble intensity with weak motor intensity set to the given value
/// Creates a new rumble intensity with weak motor intensity set to the given value.
///
/// Clamped within the 0 to 1 range
/// Clamped within the `0.0` to `1.0` range.
pub const fn weak_motor(intensity: f32) -> Self {
Self {
weak_motor: intensity,
@ -1287,9 +1318,9 @@ impl GamepadRumbleIntensity {
}
}
/// Creates a new rumble intensity with strong motor intensity set to the given value
/// Creates a new rumble intensity with strong motor intensity set to the given value.
///
/// Clamped within the 0 to 1 range
/// Clamped within the `0.0` to `1.0` range.
pub const fn strong_motor(intensity: f32) -> Self {
Self {
strong_motor: intensity,
@ -1298,7 +1329,7 @@ impl GamepadRumbleIntensity {
}
}
/// An event that controls force-feedback rumbling of a [`Gamepad`]
/// An event that controls force-feedback rumbling of a [`Gamepad`].
///
/// # Notes
///
@ -1340,19 +1371,22 @@ pub enum GamepadRumbleRequest {
///
/// To replace an existing rumble, send a [`GamepadRumbleRequest::Stop`] event first.
Add {
/// How long the gamepad should rumble
/// How long the gamepad should rumble.
duration: Duration,
/// How intense the rumble should be
/// How intense the rumble should be.
intensity: GamepadRumbleIntensity,
/// The gamepad to rumble
/// The gamepad to rumble.
gamepad: Gamepad,
},
/// Stop all running rumbles on the given [`Gamepad`].
Stop {
/// The gamepad to stop rumble.
gamepad: Gamepad,
},
/// Stop all running rumbles on the given [`Gamepad`]
Stop { gamepad: Gamepad },
}
impl GamepadRumbleRequest {
/// Get the [`Gamepad`] associated with this request
/// Get the [`Gamepad`] associated with this request.
pub fn gamepad(&self) -> Gamepad {
match self {
Self::Add { gamepad, .. } | Self::Stop { gamepad } => *gamepad,