Merge pull request #76373 from MewPurPur/add-AudioStreamGenerator-example

Author: mhilbrunner

doc/classes/AudioStreamGenerator.xml

@@ -1,16 +1,36 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioStreamGenerator" inherits="AudioStream" version="4.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Audio stream that generates sounds procedurally.
+		An audio stream with utilities for procedural sound generation.
 	</brief_description>
 	<description>
-		This audio stream does not play back sounds, but expects a script to generate audio data for it instead. See also [AudioStreamGeneratorPlayback].
+		[AudioStreamGenerator] is a type of audio stream that does not play back sounds on its own; instead, it expects a script to generate audio data for it. See also [AudioStreamGeneratorPlayback].
+		Here's a sample on how to use it to generate a sine wave:
+		[codeblock]
+		var playback # Will hold the AudioStreamGeneratorPlayback.
+		@onready var sample_hz = $AudioStreamPlayer.stream.mix_rate
+		var pulse_hz = 440.0 # The frequency of the sound wave.
+
+		func _ready():
+		    $AudioStreamPlayer.play()
+		    playback = $AudioStreamPlayer.get_stream_playback()
+		    fill_buffer()
+
+		func fill_buffer():
+		    var phase = 0.0
+		    var increment = pulse_hz / sample_hz
+		    var frames_available = playback.get_frames_available()
+
+		    for i in range(frames_available):
+		        playback.push_frame(Vector2.ONE * sin(phase * TAU))
+		        phase = fmod(phase + increment, 1.0)
+		[/codeblock]
+		In the example above, the "AudioStreamPlayer" node must use an [AudioStreamGenerator] as its stream. The [code]fill_buffer[/code] function provides audio data for approximating a sine wave.
 		See also [AudioEffectSpectrumAnalyzer] for performing real-time audio spectrum analysis.
 		[b]Note:[/b] Due to performance constraints, this class is best used from C# or from a compiled language via GDExtension. If you still want to use this class from GDScript, consider using a lower [member mix_rate] such as 11,025 Hz or 22,050 Hz.
 	</description>
 	<tutorials>
 		<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/526</link>
-		<link title="Godot 3.2 will get new audio features">https://godotengine.org/article/godot-32-will-get-new-audio-features</link>
 	</tutorials>
 	<members>
 		<member name="buffer_length" type="float" setter="set_buffer_length" getter="get_buffer_length" default="0.5">