Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document how volume is stored internally for (get|set)_volume functions and methods #3091

Merged
merged 3 commits into from
Jan 1, 2025
Merged

Document how volume is stored internally for (get|set)_volume functions and methods #3091

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
42f9239
document the internal state of sound/music volume
Matiiss Nov 20, 2024
9d48dbf
Merge branch 'main' of https://github.com/pygame-community/pygame-ce …
Matiiss Nov 20, 2024
f442ea1
formatting (of course)
Matiiss Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions docs/reST/ref/mixer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,25 @@ The following file formats are supported
| If value < 0.0, the volume will not be changed
| If value > 1.0, the volume will be set to 1.0

.. note::
The values are internally converted and kept as integer values in range [0, 128], which means
that ``get_volume()`` may return a different volume than it was set to. For example,

>>> sound.set_volume(0.1)
>>> sound.get_volume()
0.09375

This is because when you ``set_volume(0.1)``, the volume is internally calculated like so

>>> int(0.1 * 128)
12

This means that some of the precision is lost, so when you retrieve it again using ``get_volume()``,
it is converted back to a ``float`` using that integer

>>> 12 / 128
0.09375

.. ## Sound.set_volume ##

.. method:: get_volume
Expand All @@ -451,6 +470,9 @@ The following file formats are supported

Return a value from 0.0 to 1.0 (inclusive) representing the volume for this Sound.

.. note::
See :func:`Sound.set_volume` for more information regarding the returned value

.. ## Sound.get_volume ##

.. method:: get_num_channels
Expand Down Expand Up @@ -631,6 +653,9 @@ The following file formats are supported
sound.set_volume(0.6) # Now plays at 60% (previous value replaced).
channel.set_volume(0.5) # Now plays at 30% (0.6 * 0.5).

.. note::
See :func:`Sound.set_volume` for more information regarding how the value is stored internally

.. ## Channel.set_volume ##

.. method:: get_volume
Expand All @@ -644,6 +669,9 @@ The following file formats are supported
:meth:`Channel.set_volume`. The Sound object also has its own volume
which is mixed with the channel.

.. note::
See :func:`Sound.set_volume` for more information regarding the returned value

.. ## Channel.get_volume ##

.. method:: get_busy
Expand Down
6 changes: 6 additions & 0 deletions docs/reST/ref/music.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,9 @@ For a complete list of supported file formats, see the :mod:`pygame.mixer` doc p
volume will remain set at the current level. If the ``volume`` argument
is greater than ``1.0``, the volume will be set to ``1.0``.

.. note::
See :func:`mixer.Sound.set_volume()<pygame.mixer.Sound.set_volume>` for more information regarding how the value is stored internally

.. ## pygame.mixer.music.set_volume ##

.. function:: get_volume
Expand All @@ -168,6 +171,9 @@ For a complete list of supported file formats, see the :mod:`pygame.mixer` doc p
Returns the current volume for the mixer. The value will be between ``0.0``
and ``1.0``.

.. note::
See :func:`mixer.Sound.set_volume()<pygame.mixer.Sound.set_volume>` for more information regarding the returned value

.. ## pygame.mixer.music.get_volume ##

.. function:: get_busy
Expand Down