diff --git a/docs/reST/ref/mixer.rst b/docs/reST/ref/mixer.rst index 0558fb62fa..6d009b2f47 100644 --- a/docs/reST/ref/mixer.rst +++ b/docs/reST/ref/mixer.rst @@ -438,6 +438,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 @@ -447,6 +466,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 @@ -627,6 +649,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 @@ -640,6 +665,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 diff --git a/docs/reST/ref/music.rst b/docs/reST/ref/music.rst index e49177387b..ad50304595 100644 --- a/docs/reST/ref/music.rst +++ b/docs/reST/ref/music.rst @@ -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()` for more information regarding how the value is stored internally + .. ## pygame.mixer.music.set_volume ## .. function:: get_volume @@ -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()` for more information regarding the returned value + .. ## pygame.mixer.music.get_volume ## .. function:: get_busy