Merge pull request #71855 from reduz/audio-stream-polyphonic

Add AudioStreamPolyphonic to simplify sound playback from code

2 files changed, 78 insertions, 0 deletions

diff --git a/doc/classes/AudioStreamPlaybackPolyphonic.xml b/doc/classes/AudioStreamPlaybackPolyphonic.xml
new file mode 100644
index 0000000000..35ab05058a
--- /dev/null
+++ b/doc/classes/AudioStreamPlaybackPolyphonic.xml
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="AudioStreamPlaybackPolyphonic" inherits="AudioStreamPlayback" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Playback instance for [AudioStreamPolyphonic].
+	</brief_description>
+	<description>
+		Playback instance for [AudioStreamPolyphonic]. After setting the [code]stream[/code] property of [AudioStreamPlayer], [AudioStreamPlayer2D], or [AudioStreamPlayer3D], the playback instance can be obtained by calling [method AudioStreamPlayer.get_stream_playback], [method AudioStreamPlayer2D.get_stream_playback] or [method AudioStreamPlayer3D.get_stream_playback] methods.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="is_stream_playing" qualifiers="const">
+			<return type="bool" />
+			<param index="0" name="stream" type="int" />
+			<description>
+				Return true whether the stream associated with an integer ID is still playing. Check [method play_stream] for information on when this ID becomes invalid.
+			</description>
+		</method>
+		<method name="play_stream">
+			<return type="int" />
+			<param index="0" name="stream" type="AudioStream" />
+			<param index="1" name="from_offset" type="float" default="0" />
+			<param index="2" name="volume_db" type="float" default="0" />
+			<param index="3" name="pitch_scale" type="float" default="1.0" />
+			<description>
+				Play an [AudioStream] at a given offset, volume and pitch scale. Playback starts immediately.
+				The return value is an unique integer ID that is associated to this playback stream and which can be used to controll it.
+				This ID becomes invalid when the stream ends (if it does not loop), when the [AudioStreamPlaybackPolyphonic] is stopped, or when [method stop_stream] is called.
+				This function returns [constant INVALID_ID] if the amount of streams currently playing equals [member AudioStreamPolyphonic.polyphony]. If you need a higher amount of maximum polyphony, raise this value.
+			</description>
+		</method>
+		<method name="set_stream_pitch_scale">
+			<return type="void" />
+			<param index="0" name="stream" type="int" />
+			<param index="1" name="pitch_scale" type="float" />
+			<description>
+				Change the stream pitch scale. The [param stream] argument is an integer ID returned by [method play_stream].
+			</description>
+		</method>
+		<method name="set_stream_volume">
+			<return type="void" />
+			<param index="0" name="stream" type="int" />
+			<param index="1" name="volume_db" type="float" />
+			<description>
+				Change the stream volume (in db). The [param stream] argument is an integer ID returned by [method play_stream].
+			</description>
+		</method>
+		<method name="stop_stream">
+			<return type="void" />
+			<param index="0" name="stream" type="int" />
+			<description>
+				Stop a stream. The [param stream] argument is an integer ID returned by [method play_stream], which becomes invalid after calling this function.
+			</description>
+		</method>
+	</methods>
+	<constants>
+		<constant name="INVALID_ID" value="-1">
+			Returned by [method play_stream] in case it could not allocate a stream for playback.
+		</constant>
+	</constants>
+</class>
diff --git a/doc/classes/AudioStreamPolyphonic.xml b/doc/classes/AudioStreamPolyphonic.xml
new file mode 100644
index 0000000000..baa1fc7037
--- /dev/null
+++ b/doc/classes/AudioStreamPolyphonic.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="AudioStreamPolyphonic" inherits="AudioStream" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player.
+	</brief_description>
+	<description>
+		AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player.
+		Playback control is done via the [AudioStreamPlaybackPolyphonic] instance set inside the player, which can be obtained via [method AudioStreamPlayer.get_stream_playback], [method AudioStreamPlayer2D.get_stream_playback] or [method AudioStreamPlayer3D.get_stream_playback] methods. Obtaining the playback instance is only valid after the [code]stream[/code] property is set as an [AudioStreamPolyphonic] in those players.
+	</description>
+	<tutorials>
+	</tutorials>
+	<members>
+		<member name="polyphony" type="int" setter="set_polyphony" getter="get_polyphony" default="32">
+			Maximum amount of simultaneous streams that can be played.
+		</member>
+	</members>
+</class>