Skip to content

Conversation

@Nintorch
Copy link
Contributor

@Nintorch Nintorch commented Dec 5, 2025

This PR documents the axes values for mobile motion sensor methods: Input.get_accelerometer(), Input.get_gravity() and Input.get_gyroscope() (I don't exactly know how to use Input.get_magnetometer(), and googling it doesn't give the results on what the axes are exactly...)

I decided to document these, because I want to make sure that joypad motion sensors ( #111679 ) have the same axes as these methods, and I think it's better for the developers if the axes are documented.

The wording is partially borrowed from here:

/**
* The different sensors defined by SDL.
*
* Additional sensors may be available, using platform dependent semantics.
*
* Here are the additional Android sensors:
*
* https://developer.android.com/reference/android/hardware/SensorEvent.html#values
*
* Accelerometer sensor notes:
*
* The accelerometer returns the current acceleration in SI meters per second
* squared. This measurement includes the force of gravity, so a device at
* rest will have an value of SDL_STANDARD_GRAVITY away from the center of the
* earth, which is a positive Y value.
*
* - `values[0]`: Acceleration on the x axis
* - `values[1]`: Acceleration on the y axis
* - `values[2]`: Acceleration on the z axis
*
* For phones and tablets held in natural orientation and game controllers
* held in front of you, the axes are defined as follows:
*
* - -X ... +X : left ... right
* - -Y ... +Y : bottom ... top
* - -Z ... +Z : farther ... closer
*
* The accelerometer axis data is not changed when the device is rotated.
*
* Gyroscope sensor notes:
*
* The gyroscope returns the current rate of rotation in radians per second.
* The rotation is positive in the counter-clockwise direction. That is, an
* observer looking from a positive location on one of the axes would see
* positive rotation on that axis when it appeared to be rotating
* counter-clockwise.
*
* - `values[0]`: Angular speed around the x axis (pitch)
* - `values[1]`: Angular speed around the y axis (yaw)
* - `values[2]`: Angular speed around the z axis (roll)
*
* For phones and tablets held in natural orientation and game controllers
* held in front of you, the axes are defined as follows:
*
* - -X ... +X : left ... right
* - -Y ... +Y : bottom ... top
* - -Z ... +Z : farther ... closer
*
* The gyroscope axis data is not changed when the device is rotated.
*
* \since This enum is available since SDL 3.2.0.
*
* \sa SDL_GetCurrentDisplayOrientation
*/

@Nintorch Nintorch force-pushed the mobile-orientation-docs branch from 9930a72 to d069dcb Compare December 6, 2025 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants