207 lines
7.0 KiB
Python
207 lines
7.0 KiB
Python
"""Pygame module to provide additional context about the system.
|
|
|
|
.. versionadded:: 2.2.0
|
|
"""
|
|
|
|
from typing import TypedDict
|
|
|
|
from pygame._data_classes import PowerState
|
|
|
|
class _InstructionSets(TypedDict):
|
|
ALTIVEC: bool
|
|
MMX: bool
|
|
SSE: bool
|
|
SSE2: bool
|
|
SSE3: bool
|
|
SSE41: bool
|
|
SSE42: bool
|
|
AVX: bool
|
|
AVX2: bool
|
|
AVX512F: bool
|
|
NEON: bool
|
|
ARMSIMD: bool
|
|
LSX: bool
|
|
LASX: bool
|
|
|
|
class _Locale(TypedDict):
|
|
language: str
|
|
country: str | None
|
|
|
|
def get_cpu_instruction_sets() -> _InstructionSets:
|
|
"""Get the information of CPU instruction sets.
|
|
|
|
Returns a dict of the information of CPU instruction sets. The keys of
|
|
the dict are the names of instruction sets and the values determine
|
|
whether the instruction set is available.
|
|
|
|
Some of functions like ``Surface.blit`` can be accelerated by SIMD
|
|
instruction sets like SSE2 or AVX2. By checking the availability of
|
|
instruction sets, you can check if these accelerations are available.
|
|
|
|
Here is an example of the returned dict
|
|
::
|
|
|
|
{
|
|
'ALTIVEC': False,
|
|
'MMX': True,
|
|
'SSE': True,
|
|
'SSE2': True,
|
|
'SSE3': True,
|
|
'SSE41': True,
|
|
'SSE42': True,
|
|
'AVX': True,
|
|
'AVX2': True,
|
|
'AVX512F': False,
|
|
'NEON': False,
|
|
'ARMSIMD': False,
|
|
'LSX': False,
|
|
'LASX': False
|
|
}
|
|
|
|
.. note:: The values of ``LSX`` and ``LASX`` will be always False if
|
|
SDL version < 2.24.0.
|
|
|
|
.. versionadded:: 2.3.1
|
|
|
|
.. versionchanged:: 2.4.0 removed ``RDTSC`` key,
|
|
as it has been removed in pre-release SDL3
|
|
"""
|
|
|
|
def get_total_ram() -> int:
|
|
"""Get the amount of RAM configured in the system.
|
|
|
|
Returns the amount of RAM configured in the system in MiB.
|
|
|
|
.. versionadded:: 2.3.1
|
|
"""
|
|
|
|
def get_pref_path(org: str, app: str) -> str:
|
|
"""Get a writeable folder for your app.
|
|
|
|
When distributing apps, it's helpful to have a way to get a writeable path,
|
|
because it's what apps are expected to do, and because sometimes the local
|
|
space around the app isn't writeable to the app.
|
|
|
|
This function returns a platform specific path for your app to store
|
|
savegames, settings, and the like. This path is unique per user and
|
|
per app name.
|
|
|
|
It takes two strings, ``org`` and ``app``, referring to the "organization"
|
|
and "application name." For example, the organization could be "Valve,"
|
|
and the application name could be "Half Life 2." It then will figure out the
|
|
preferred path, **creating the folders referenced by the path if necessary**,
|
|
and return a string containing the absolute path.
|
|
|
|
For example::
|
|
|
|
On Windows, it would resemble
|
|
C:\\Users\\bob\\AppData\\Roaming\\My Company\\My Program Name\\
|
|
|
|
On macOS, it would resemble
|
|
/Users/bob/Library/Application Support/My Company/My Program Name/
|
|
|
|
And on Linux it would resemble
|
|
/home/bob/.local/share/My Company/My Program Name/
|
|
|
|
.. note::
|
|
Since the organization and app names can potentially be used as
|
|
a folder name, it is highly encouraged to avoid punctuation.
|
|
Instead stick to letters, numbers, and spaces.
|
|
|
|
.. note::
|
|
The ``appdirs`` library has similar functionality for this use case,
|
|
but has more "folder types" to choose from.
|
|
|
|
.. versionadded:: 2.2.0
|
|
"""
|
|
|
|
def get_pref_locales() -> list[_Locale]:
|
|
"""Get preferred locales set on the system.
|
|
|
|
Returns a list of "locale" dicts, sorted in descending order of preference
|
|
set on the host OS (the most preferred locale is the first element). May
|
|
also be an empty list if pygame could not find this information.
|
|
|
|
Each "locale" dict contains the language code which can be accessed by the
|
|
key ``"language"``. This language code is an ISO-639 language specifier
|
|
(such as "en" for English, "de" for German, etc).
|
|
A "locale" dict may also optionally contain a ``"country"`` field, whose
|
|
value is an ISO-3166 country code (such as "US" for the United States,
|
|
"CA" for Canada, etc). If this field is not set or undetermined, it is
|
|
``None``.
|
|
A "locale" dict which looks like ``{'language': 'en', 'country': 'US'}``
|
|
indicates the user prefers American English, while
|
|
``{'language': 'en', 'country': None}`` indicates that the user prefers
|
|
English, generically.
|
|
|
|
This might be a bit of an expensive call because it has to query the OS. So
|
|
this function must not be called in a game loop, instead it's best to ask
|
|
for this once and save the results. However, this list can change when the
|
|
user changes a system preference outside of your program. pygame will send
|
|
a ``LOCALECHANGED`` event in this case, if possible, and you can call this
|
|
function again to get an updated copy of preferred locales.
|
|
|
|
.. versionadded:: 2.2.0
|
|
"""
|
|
|
|
def get_power_state() -> PowerState | None:
|
|
"""Get the current power supply state.
|
|
|
|
**Experimental:** feature available for testing and feedback.
|
|
We don't anticipate it changing, but it might if something important
|
|
is brought up. `Please leave get_power_state feedback with
|
|
authors <https://github.com/pygame-community/pygame-ce/pull/2257>`_
|
|
|
|
Returns a ``PowerState`` object representing the power supply state.
|
|
|
|
Returns ``None`` if the power state is unknown.
|
|
|
|
The PowerState object has several attributes:
|
|
|
|
.. code-block:: text
|
|
|
|
battery_percent:
|
|
An integer between 0 and 100, representing the percentage of
|
|
battery life left.
|
|
|
|
battery_seconds:
|
|
An integer, representing the seconds of battery life left.
|
|
Could be None if the value is unknown.
|
|
|
|
on_battery:
|
|
True if the device is running on the battery (not plugged in).
|
|
|
|
no_battery:
|
|
True if the device has no battery available (plugged in).
|
|
|
|
charging:
|
|
True if the device is charging battery (plugged in).
|
|
|
|
charged:
|
|
True if the battery of the device is fully charged (plugged in).
|
|
|
|
plugged_in:
|
|
True if the device is plugged in.
|
|
Equivalent to `not on_battery`.
|
|
|
|
has_battery:
|
|
True if the device has battery.
|
|
Equivalent to `on_battery or not no_battery`.
|
|
|
|
|
|
You should never take a battery status as absolute truth. Batteries
|
|
(especially failing batteries) are delicate hardware, and the values
|
|
reported here are best estimates based on what that hardware reports. It's
|
|
not uncommon for older batteries to lose stored power much faster than it
|
|
reports, or completely drain when reporting it has 20 percent left, etc.
|
|
|
|
Battery status can change at any time; if you are concerned with power
|
|
state, you should call this function frequently, and perhaps ignore changes
|
|
until they seem to be stable for a few seconds.
|
|
|
|
It's possible a platform can only report battery percentage or time left
|
|
but not both.
|
|
|
|
.. versionadded:: 2.4.0
|
|
"""
|