A device's sensor resolution and report rate can be configured per profile, with each profile reporting a number of resolution modes (see ratbag_resolution). More...
Data Structures | |
struct | ratbag_resolution |
Represents a resolution setting on the device. More... | |
Functions | |
struct ratbag_resolution * | ratbag_resolution_ref (struct ratbag_resolution *resolution) |
Add a reference to the resolution. More... | |
struct ratbag_resolution * | ratbag_resolution_unref (struct ratbag_resolution *resolution) |
Dereference the ratbag resolution. More... | |
void | ratbag_resolution_set_user_data (struct ratbag_resolution *resolution, void *userdata) |
Set caller-specific data associated with this resolution. More... | |
void * | ratbag_resolution_get_user_data (const struct ratbag_resolution *resolution) |
Get the caller-specific data associated with this resolution, if any. More... | |
int | ratbag_resolution_has_capability (struct ratbag_resolution *resolution, enum ratbag_resolution_capability cap) |
Check if a resolution has a specific capability. More... | |
enum ratbag_error_code | ratbag_resolution_set_dpi (struct ratbag_resolution *resolution, unsigned int dpi) |
Set the resolution in DPI for the resolution mode. More... | |
enum ratbag_error_code | ratbag_resolution_set_dpi_xy (struct ratbag_resolution *resolution, unsigned int x, unsigned int y) |
Set the x and y resolution in DPI for the resolution mode. More... | |
int | ratbag_resolution_get_dpi (struct ratbag_resolution *resolution) |
Get the resolution in DPI for the resolution mode. More... | |
int | ratbag_resolution_get_dpi_x (struct ratbag_resolution *resolution) |
Get the x resolution in DPI for the resolution mode. More... | |
int | ratbag_resolution_get_dpi_y (struct ratbag_resolution *resolution) |
Get the y resolution in DPI for the resolution mode. More... | |
enum ratbag_error_code | ratbag_resolution_set_report_rate (struct ratbag_resolution *resolution, unsigned int hz) |
Set the the report rate in Hz for the resolution mode. More... | |
int | ratbag_resolution_get_report_rate (struct ratbag_resolution *resolution) |
Get the the report rate in Hz for the resolution mode. More... | |
enum ratbag_error_code | ratbag_resolution_set_active (struct ratbag_resolution *resolution) |
Activate the given resolution mode. More... | |
int | ratbag_resolution_is_active (const struct ratbag_resolution *resolution) |
Check if the resolution mode is the currently active one. More... | |
enum ratbag_error_code | ratbag_resolution_set_default (struct ratbag_resolution *resolution) |
Set the default resolution mode for the associated profile. More... | |
int | ratbag_resolution_is_default (const struct ratbag_resolution *resolution) |
Check if the resolution mode is the default one in this profile. More... | |
Detailed Description
A device's sensor resolution and report rate can be configured per profile, with each profile reporting a number of resolution modes (see ratbag_resolution).
The number depends on the hardware, but at least one is provided by libratbag.
Each resolution mode is a tuple of a resolution and report rate and represents the modes that the mouse can switch through, usually with the use of a button on the mouse to cycle through the preconfigured resolutions.
The resolutions have a default resolution and a currently active resolution. The currently active one is the one used by the device now and only applies if the profile is currently active too. The default resolution is the one the device will chose when the profile is selected next.
Function Documentation
§ ratbag_resolution_get_dpi()
int ratbag_resolution_get_dpi | ( | struct ratbag_resolution * | resolution | ) |
Get the resolution in DPI for the resolution mode.
If the resolution has the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability, this function returns the x resolution, see ratbag_resolution_get_dpi_x().
A value of 0 for dpi indicates the mode is disabled.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- The resolution in dpi
§ ratbag_resolution_get_dpi_x()
int ratbag_resolution_get_dpi_x | ( | struct ratbag_resolution * | resolution | ) |
Get the x resolution in DPI for the resolution mode.
If the resolution does not have the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability, this function is identical to ratbag_resolution_get_dpi().
A value of 0 for dpi indicates the mode is disabled.
- Parameters
-
resolution A previously initialized ratbag resolution with the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability
- Returns
- The resolution in dpi
§ ratbag_resolution_get_dpi_y()
int ratbag_resolution_get_dpi_y | ( | struct ratbag_resolution * | resolution | ) |
Get the y resolution in DPI for the resolution mode.
If the resolution does not have the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability, this function is identical to ratbag_resolution_get_dpi().
A value of 0 for dpi indicates the mode is disabled.
- Parameters
-
resolution A previously initialized ratbag resolution with the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability
- Returns
- The resolution in dpi
§ ratbag_resolution_get_report_rate()
int ratbag_resolution_get_report_rate | ( | struct ratbag_resolution * | resolution | ) |
Get the the report rate in Hz for the resolution mode.
A value of 0 hz indicates the mode is disabled.
If the resolution does not have the RATBAG_RESOLUTION_CAP_INDIVIDUAL_REPORT_RATE capability, changing the report rate on one resolution changes the report rate for all resolutions in this profile.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- The report rate for this resolution in Hz
§ ratbag_resolution_get_user_data()
void* ratbag_resolution_get_user_data | ( | const struct ratbag_resolution * | resolution | ) |
Get the caller-specific data associated with this resolution, if any.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- The caller-specific data previously assigned in ratbag_resolution_set_user_data().
§ ratbag_resolution_has_capability()
int ratbag_resolution_has_capability | ( | struct ratbag_resolution * | resolution, |
enum ratbag_resolution_capability | cap | ||
) |
Check if a resolution has a specific capability.
- Returns
- non-zero if the capability is available, zero otherwise.
§ ratbag_resolution_is_active()
int ratbag_resolution_is_active | ( | const struct ratbag_resolution * | resolution | ) |
Check if the resolution mode is the currently active one.
If the profile is the currently active profile, the mode is the one currently active. For profiles not currently active, this always returns 0.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- Non-zero if the resolution mode is the active one, zero otherwise.
§ ratbag_resolution_is_default()
int ratbag_resolution_is_default | ( | const struct ratbag_resolution * | resolution | ) |
Check if the resolution mode is the default one in this profile.
The default resolution is the one the device selects when switching to the corresponding profile. It may not be the currently active resolution, use ratbag_resolution_is_active() instead.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- Non-zero if the resolution mode is the default one, zero otherwise.
§ ratbag_resolution_ref()
struct ratbag_resolution* ratbag_resolution_ref | ( | struct ratbag_resolution * | resolution | ) |
Add a reference to the resolution.
A resolution is destroyed whenever the reference count reaches 0. See ratbag_resolution_unref.
- Parameters
-
resolution A previously initialized valid ratbag resolution
- Returns
- The passed ratbag resolution
§ ratbag_resolution_set_active()
enum ratbag_error_code ratbag_resolution_set_active | ( | struct ratbag_resolution * | resolution | ) |
Activate the given resolution mode.
If the mode is not configured, this function returns an error and the result is undefined.
The mode must be one of the current profile, otherwise an error is returned.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- zero on success or an error code on failure
§ ratbag_resolution_set_default()
enum ratbag_error_code ratbag_resolution_set_default | ( | struct ratbag_resolution * | resolution | ) |
Set the default resolution mode for the associated profile.
When the device switches to the profile next, this mode will be the active resolution. If the mode is not configured, this function returns an error and the result is undefined.
This only switches the default resolution, not the currently active resolution. Use ratbag_resolution_set_active() instead.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- zero on success or an error code on failure
§ ratbag_resolution_set_dpi()
enum ratbag_error_code ratbag_resolution_set_dpi | ( | struct ratbag_resolution * | resolution, |
unsigned int | dpi | ||
) |
Set the resolution in DPI for the resolution mode.
If the resolution has the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability, this function sets both x and y resolution to the given value.
A value of 0 for dpi disables the mode.
If the resolution mode is the currently active mode and the profile is the currently active profile, the change takes effect immediately.
- Parameters
-
resolution A previously initialized ratbag resolution dpi Set to the resolution in dpi, 0 to disable
- Returns
- zero on success or an error code on failure
§ ratbag_resolution_set_dpi_xy()
enum ratbag_error_code ratbag_resolution_set_dpi_xy | ( | struct ratbag_resolution * | resolution, |
unsigned int | x, | ||
unsigned int | y | ||
) |
Set the x and y resolution in DPI for the resolution mode.
If the resolution does not have the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability, this function returns an error and does nothing.
A value of 0 for both x and y disables the mode. If either value is 0 and the other value is non-zero, this function returns an error and does nothing.
If the resolution mode is the currently active mode and the profile is the currently active profile, the change takes effect immediately.
- Parameters
-
resolution A previously initialized ratbag resolution with the RATBAG_RESOLUTION_CAP_SEPARATE_XY_RESOLUTION capability x The x resolution in dpi y The y resolution in dpi
- Returns
- zero on success or an error code on failure
§ ratbag_resolution_set_report_rate()
enum ratbag_error_code ratbag_resolution_set_report_rate | ( | struct ratbag_resolution * | resolution, |
unsigned int | hz | ||
) |
Set the the report rate in Hz for the resolution mode.
A value of 0 hz disables the mode.
If the resolution mode is the currently active mode and the profile is the currently active profile, the change takes effect immediately.
- Parameters
-
resolution A previously initialized ratbag resolution hz Set to the report rate in Hz, may be 0
- Returns
- zero on success or an error code on failure
§ ratbag_resolution_set_user_data()
void ratbag_resolution_set_user_data | ( | struct ratbag_resolution * | resolution, |
void * | userdata | ||
) |
Set caller-specific data associated with this resolution.
libratbag does not manage, look at, or modify this data. The caller must ensure the data is valid.
- Parameters
-
resolution A previously initialized resolution userdata Caller-specific data passed to the various callback interfaces.
§ ratbag_resolution_unref()
struct ratbag_resolution* ratbag_resolution_unref | ( | struct ratbag_resolution * | resolution | ) |
Dereference the ratbag resolution.
When the internal refcount reaches zero, all resources associated with this object are released. The object must be considered invalid once unref is called.
- Parameters
-
resolution A previously initialized ratbag resolution
- Returns
- Always NULL