Merge pull request #1844 from yunline/sound-position

Add mixer.Channel.set_source_location()

Author: Starbuck5

buildconfig/stubs/pygame/mixer.pyi

@@ -83,6 +83,7 @@ class Channel:
     def unpause(self) -> None: ...
     def fadeout(self, time: int) -> None: ...
     def queue(self, sound: Sound) -> None: ...
+    def set_source_location(self, angle:float, distance:float) -> None: ...
     @overload
     def set_volume(self, value: float) -> None: ...
     @overload

docs/reST/ref/mixer.rst

@@ -480,6 +480,21 @@ change the default buffer by calling :func:`pygame.mixer.pre_init` before
 
       .. ## Channel.fadeout ##
 
+   .. method:: set_source_location
+
+      | :sl:`set the position of a playing channel`
+      | :sg:`set_source_location(angle,distance) -> None`
+
+      Set the position (angle, distance) of a playing channel.
+
+      `angle`: Angle is in degrees.
+      
+      `distance`: Range from 0 to 255.
+      
+      .. versionadded:: 2.3.0
+      
+      .. ## Channel.set_source_location ##
+
    .. method:: set_volume
 
       | :sl:`set the volume of a playing channel`

src_c/doc/mixer_doc.h

@@ -29,6 +29,7 @@
 #define DOC_MIXER_CHANNEL_PAUSE "pause() -> None\ntemporarily stop playback of a channel"
 #define DOC_MIXER_CHANNEL_UNPAUSE "unpause() -> None\nresume pause playback of a channel"
 #define DOC_MIXER_CHANNEL_FADEOUT "fadeout(time) -> None\nstop playback after fading channel out"
+#define DOC_MIXER_CHANNEL_SETSOURCELOCATION "set_source_location(angle,distance) -> None\nset the position of a playing channel"
 #define DOC_MIXER_CHANNEL_SETVOLUME "set_volume(value) -> None\nset_volume(left, right) -> None\nset the volume of a playing channel"
 #define DOC_MIXER_CHANNEL_GETVOLUME "get_volume() -> value\nget the volume of the playing channel"
 #define DOC_MIXER_CHANNEL_GETBUSY "get_busy() -> bool\ncheck if the channel is active"

src_c/mixer.c

@@ -1160,6 +1160,37 @@ chan_unpause(PyObject *self, PyObject *_null)
     Py_RETURN_NONE;
 }
 
+static PyObject *
+chan_set_source_location(PyObject *self, PyObject *args)
+{
+    int channelnum = pgChannel_AsInt(self);
+    Sint16 angle;
+    float angle_f;
+    Uint8 distance;
+    float distance_f;
+    PyThreadState *_save;
+
+    if (!PyArg_ParseTuple(args, "ff", &angle_f, &distance_f))
+        return NULL;
+
+    angle = (Sint16)roundf(fmodf(angle_f, 360));
+    distance_f = roundf(distance_f);
+    if (0 > distance_f || 256 <= distance_f) {
+        return RAISE(PyExc_ValueError,
+                     "distance out of range, expected (0, 255)");
+    }
+    distance = (Uint8)distance_f;
+
+    MIXER_INIT_CHECK();
+    _save = PyEval_SaveThread();
+    if (!Mix_SetPosition(channelnum, angle, distance)) {
+        PyEval_RestoreThread(_save);
+        return RAISE(pgExc_SDLError, Mix_GetError());
+    }
+    PyEval_RestoreThread(_save);
+    Py_RETURN_NONE;
+}
+
 static PyObject *
 chan_set_volume(PyObject *self, PyObject *args)
 {
@@ -1290,6 +1321,8 @@ static PyMethodDef channel_methods[] = {
     {"pause", (PyCFunction)chan_pause, METH_NOARGS, DOC_MIXER_CHANNEL_PAUSE},
     {"unpause", (PyCFunction)chan_unpause, METH_NOARGS,
      DOC_MIXER_CHANNEL_UNPAUSE},
+    {"set_source_location", chan_set_source_location, METH_VARARGS,
+     DOC_MIXER_CHANNEL_SETSOURCELOCATION},
     {"set_volume", chan_set_volume, METH_VARARGS, DOC_MIXER_CHANNEL_SETVOLUME},
     {"get_volume", (PyCFunction)chan_get_volume, METH_NOARGS,
      DOC_MIXER_CHANNEL_GETVOLUME},

test/mixer_test.py

@@ -1,10 +1,11 @@
 import sys
 import os
 import unittest
+import time
 import pathlib
 import platform
 
-from pygame.tests.test_utils import example_path
+from pygame.tests.test_utils import example_path, prompt, question
 
 import pygame
 from pygame import mixer
@@ -897,6 +898,55 @@ def todo_test_unpause(self):
 
         self.fail()
 
+    def test_set_source_location(self):
+        ch = mixer.Channel(0)
+        ch.set_source_location(-3.14, 6.25)
+        self.assertRaises(ValueError, lambda: ch.set_source_location(0, -1))
+        self.assertRaises(ValueError, lambda: ch.set_source_location(0, 256.0))
+        self.assertRaises(TypeError, lambda: ch.set_source_location("", 6.25))
+
+
+class ChannelInteractiveTest(unittest.TestCase):
+    __tags__ = ["interactive"]
+
+    def tearDown(self):
+        mixer.quit()
+        mixer.pre_init(0, 0, 0, 0)
+
+    def setUp(self):
+        mixer.init()
+        filename = example_path(os.path.join("data", "house_lo.mp3"))
+        self.snd = mixer.Sound(filename)
+
+    def test_set_source_location(self):
+        prompt("Please wear earphones before the test for set_source_location() starts")
+        ch = self.snd.play()
+        angle = 0
+        distance = 100
+        while ch.get_busy():
+            ch.set_source_location(angle, distance)
+            angle += 1
+            angle %= 360
+            time.sleep(0.01)
+        ans = question("You heard the sound was running around you. Is that correct?")
+        self.assertTrue(ans)
+
+        ch = self.snd.play()
+        angle = 0
+        distance = 0
+        direction = 0
+        while ch.get_busy():
+            ch.set_source_location(angle, distance)
+            if distance == 0 or distance == 255:
+                direction = 1 - direction
+            distance += 1 if direction else -1
+            time.sleep(0.01)
+
+        ans = question(
+            "You heard the distance of the sound was changing. Is that correct?"
+        )
+        self.assertTrue(ans)
+
 
 ############################### SOUND CLASS TESTS ##############################